WPS多维表格效率插件：批量出入库与商品卡片管理

WPS 多维表格效率工具 —— 项目说明 一、项目定位 这是一个面向盲盒直播电商业务的 WPS 多维表格（kdocs.cn）浏览器扩展，通过调用 WPS 官方 window.WPSOpenApi.Application SDK，把大量繁琐、重复、易出错的手工表格操作，封装成一键式批量动作。它本质上是「业务工作流 + 多维表格 SDK 自动化」的结合体，解决的是真实电商团队在日常数据录入/流转中的效率痛点。

技术形态：Chrome/Edge 浏览器扩展（Manifest V3），侧边栏（Side Panel）作为交互入口，核心业务逻辑运行在 WPS 页面的主世界脚本中。

二、核心功能清单 项目按「入库 / 出库 / 商品 / 其他」四个模块组织，功能如下：

1. 出库模块（核心） 预出库批量插入：按指定行数批量插入，自动填充「店铺名称 / 直播场次 / 出库类型 / 出库时间」；支持用 分组:数量|分组:数量 语法（如 15P:6|14P:3）一次性生成不同编号分组的记录，并自动生成递增商品编号。 直播出库批量插入：与预出库类似，但出库类型为「直播出库」。 复制选中直播场次：把某店铺某个直播场次的预出库记录，一键复制到新的直播场次（含关联字段「出库商品选择」），避免重复录入。 UP 组 / 常规组出库展示：把当前店铺、场次的商品以卡片墙形式弹出展示，支持选中、填写补偿积分、提交订单编号后一次性生成直播出库记录。 保底积分处理：把订单编号 + 折算保底积分写入「02直播保底登录表」。
2. 入库模块 入库记录批量插入：支持粘贴多行条形码按条码数生成，或按行数生成；自动填充仓库、类型、时间。 更新调拨入库：根据「01调拨表」选中的记录，自动为「01入库表」补齐缺失的调拨入库占位记录（跨表去重、比对已有条形码）。
3. 商品模块 商品批量生成：按行数生成商品记录，自动生成批次与条形码（可手动粘贴部分条形码补足）。 商品查找窗体：读取「01仓库库存结存表」，弹窗展示库存商品卡片（含图片、成本、库存数），支持按名称/成本/库存区间筛选，双击可把条形码写回 WPS 表格当前单元格，多选后可批量复制条形码。 商品角色查询：选中表格中的条形码单元格后，自动匹配「00商品表」中的商品，展示对应商品卡片（含图片），双击即可把「条形码含角色」写回单元格，支持撤销上次写入。
4. 其他辅助工具 批量切换复选框：选中的复选框列单元格统一切换状态。 删除空记录：按「店铺 + 选中字段」维度，删除该列为空的记录（有二次确认 + 防误删约束）。 SDK 批量写入自检：内置一套真实的矩阵写入测试（普通字段 + 关联字段），用于验证 SDK 行为变化。 三、架构与技术亮点 三层消息桥接：sidepanel（扩展侧） attach.js（隔离世界） page-bridge.js（主世界）。巧妙绕开浏览器内容脚本无法直接访问页面 window.WPSOpenApi 的限制，是 WPS/飞书等在线表格 SDK 自动化的标准解法。 桥接版本校验：响应携带 bridgeVersion，页面若运行旧版桥接会明确提示用户刷新，避免「改了代码页面还在跑旧脚本」的隐蔽 bug。 请求串行化 + 超时保护：WPS SDK 的异步代理不支持并发，所有请求统一排队串行执行；每个可能挂起的 Promise 都带步骤级超时（withTimeout），并记录分步耗时，便于定位「数据读取慢还是写入慢还是筛选慢」。 异步代理的深刻理解：清楚区分「属性 setter 不能 await 确认写入」vs「方法调用需 await」，并总结出 Condition 与 Filters.Add 对 Criteria 是否 await 的相反要求——这些是踩坑后的经验沉淀。 四、特别值得借鉴的几点
5. 《WPS-SDK页面筛选与批量写入规范.md》是宝藏 这份文档不是泛泛的 API 罗列，而是真实实测得出的工程结论，几个极具参考价值的点：

**「SDK 返回成功 页面已重绘」**的产品口径：明确告知用户「如页面未同步请手动刷新」，并给出排障顺序——先确认数据是否落表，禁止重复点击，这是防误操作的核心纪律。 关联字段批量写入的空值坑：实测确认 DBCellValue([]) 或原始 [] 会把整列关联清空，必须用 null 表示空关联——这类「一行代码踩一天坑」的经验非常有价值。 二维矩阵 vs 一维数组：一维数组会被首值广播到全部记录。 「禁止再次采用的方案」清单：明确列出 10 条已验证无效/有害的做法，避免后人重蹈覆辙。 2. 防误操作的产品设计 删除空记录强制「只选中一个单元格 + 必须有店铺名称 + 二次确认」三重防线。 写操作不自动重放、选区地址变化自动取消写入。 大量「如果页面没更新，先查数据别重复插」的提示。 3. 可复用的自动化范式 跨表数据联动（调拨表 入库表自动补齐、商品表 出库表复制）展示了「用 Condition 定位源数据 固化快照 批量写入」的稳定流程，这套流程可迁移到任何「按条件复制/同步数据」的场景。 卡片化 UI + 双击回写的商品选择体验，把「在多维表格里翻找」变成「可视化点选」，交互设计值得借鉴。 4. 可观测性 内置诊断日志（可复制、分级着色）、分步耗时埋点、以及 diagnose-product-query 这类专门的诊断接口，让「线上偶发卡顿/失败」有据可查。

五、可能值得改进/注意的点 README 与实际功能已明显脱节：README 只描述了「批量插入行 + 填店铺名」这一最初功能，实际早已扩展为入库/出库/商品/其他四大模块，建议同步更新 README。 业务耦合较强：代码里硬编码了大量表名（00商品表、01入库表、02直播保底登录表）和字段名，通用性受限，换一套表结构需要改代码。 sidepanel.js 单文件已 800+ 行、page-bridge.js 1500+ 行，缺乏模块拆分，后续维护成本会上升。 依赖特定 WPS 页面版本与 SDK 行为，已有专门的「SDK 批量写入自检」工具应对，但整体仍是「高度依赖未公开/不稳定 API」的方案。