版本增量报告 · huanyan/web v0.1.54（f4dc29b → bdb7f33）

一、结论摘要

---

二、变更清单与逐项评审

1) src/pages/pos/workbench/model.ts（−7/+2）— ✅ 改善

defaultAllocRows 由「round2(1/n) + 末位补尾差」简化为一句话调用 evenAllocRatios(n)，消除了 0.3333 型浮点尾差特判，与 salesAllocRows 共用同一口径（整数百分比）。这是本次唯一真实的可维护性改善（工具未计入“修复”）。

⚠ 业务口径变化（不是纯展示变化）：3 人分摊由 0.3333/0.3333/0.3334 变为 0.34/0.33/0.33，分摊金额随 ratio 由服务端计算 → 首位恒多 1%（每单约 0.67% 相对偏差，随单量累积）。与销售单既有口径一致，可接受，但建议在版本说明中标注。

2) src/pages/pos/workbench/AllocPanel.tsx（+6）

新增 resizeLineRows，把服务单行内「添加分摊人 / 移除」改为按人数重新平分（原先新增行 ratio: null 留白待手填）。逻辑正确（setRows 为闭包内当前渲染值，事件回调内调用无 TDZ/陈旧值问题）。

3) src/pages/pos/workbench/SettleOrderModal.tsx（+33）— ⚠ 见 §3

新增「有建单意向即预填成可编辑行」的 useEffect（131–154），走 详情 → draftAllocs → AllocRow[] 映射：

• 销售单：order_item_index 全缺失才按整单多人预填（判断正确）；
• 服务单：lines.forEach((line, ix) 的 ix 与 detail.items 下标严格 1:1（detailToLines 对 items 是 map，不放缩、不展开），索引映射正确；划卡行显式跳过，正确。

4) src/pages/pos/workbench/__tests__/allocAutoFill.test.tsx（+126，新增）

3 个用例覆盖：整数百分比默认值、服务单加人 1→2→3 人平分、销售单加人平分（含受控组件 Harness 写法，正确）。与既有 allocMulti.test.tsx（已断言 34/33/33）口径一致，不会打破既有断言（已确认无测试依赖 0.3333 浮点值）。

---

三、人工发现的问题（重点）

3.1 【Medium·确认缺陷】seededRef 未随 reset() 复位 → 关闭后重开同一张单，预填消失

• 位置：SettleOrderModal.tsx:131（const seededRef = useRef('')）、:135（if (seededRef.current === sig) return）、:209-219（reset() 清 allocs 但不清 seededRef）
• 复现路径（已核对父组件）：src/pages/pos/pending/index.tsx:142-147 是常驻无 koşul渲染 <SettleOrderModal orderId={settleRow?.order_id ?? null} .../>，关闭只 setSettleRow(null)，组件不卸载，<Modal> 无 destroyOnClose。
  1. 打开待收款单 601（有意向 张 50% / 李 50%）→ 分摊区出现两行预填 50/50；
  2. 点「取消」→ close() → reset() 把 allocs 清空，seededRef.current 仍为 "601:销售单"；
  3. 再次点开同一张单 601 → useQuery(['pos-pending-order', 601]) 命中缓存立即有 detail → effect 命中 seededRef 守卫直接 return → allocs 保持 []，预填行消失。
• 影响：注释承诺的“收银员看得见、可当场改”变成时有时无（首次有、二次无），同一单两次打开 UI 不一致，易被当成“系统丢了我的分摊”。金额结果不变（空分摊仍回落意向），故非资损。
• 修复（1 行）：

3.2 【Medium·需服务端确认】“预填值即提交值”把宽松的“留空=沿用意向”升级成硬校验，可能直接把收款按钮锁死

• 位置：SettleOrderModal.tsx:139-152（预填不做 Σ 校验）、:167-180（salesPending / servicePending 只看 rows.length > 0）、:378（disabled={!detail || allocBlocked}）
• 机理：改造前 allocs 为空 → intentFallback 豁免 → 提交放行、服务端回落 draft_allocs；改造后只要意向非空就一定预填，一旦意向数据本身不平，salesAllocPending/lineAllocPending 即判「待分摊」→ 提交按钮被禁用。触发数据包括：
  • draft_allocs 中 ratio 非数值 → parseDraftAllocs 兜底 ratio: 0（src/api/order.ts:343-347）→ 预填 ratio:0 → 命中 (a.ratio ?? 0) <= 0 → pending；
  • 历史/脏数据 Σ ≠ 100%（如 0.6+0.3；容差仅 0.01）；
  • 只有部分人被排（0.5+0.3）。
• 影响：同等数据在 v0.1.53 可正常收款，v0.1.54 反而被前端拦住，且红色提示“分摊不平”是收银员没有操作过就出现的，需要她手工改比例才能继续 —— 这是本次最值得关注的行为回归方向。
• 建议（二选一）：
  1. 预填前先校验 Math.abs(Σratio − 1) <= 0.01 且所有人 ratio > 0，不满足则不预填（退回空=fallback 的旧行为），并保留横幅告知“下单意向不平，留空将沿用服务端处理”；
  2. 或在面板给「按人数重算平分」一键按钮（复用 evenAllocRatios），把纠正成本降到 1 次点击。

3.3 【Low-Medium·待确认】服务单“部分行预填”会让提交从“整单回落”变成“部分行显式指定”

• 位置：:144-151（只为有意向的行生成行）+ 提交分支 allocs.length > 0（约 :299-312）
• 场景：服务单 3 行，意向只排了第 0 行 → 预填后 allocs.length > 0 → 提交带 [{order_item_index:0,...}]，不再进入“空分摊=整单回落”分支。若服务端 settle.rs 对“传了 allocs”按整单以传入为准处理，其余行的意向归属将丢失。
• 说明：本仓库仅为 web，无法验证服务端回落粒度，故列为待确认；若服务端是“按行 merge/缺行回落”，则无风险。

3.4 【Low】effect 依赖与首帧闪烁

• :154 依赖数组含未被使用的 me（effect 体内引用的 isSalesKind/vals 均来自模块或 detail），会触发 react-hooks/exhaustive-deps 的 “unnecessary dependency” 警告，且让人误以为预填与当前用户相关（注释恰恰强调“不预填当前收银员”）。
• 用 useEffect 写“初始值派生”导致首帧先渲染空分摊、再跳成预填（一次多余渲染 + 视觉跳动）；建议改为 useState(() => ...) 不行（detail 异步），可用 useMemo 派生 seededAllocs + 一次 useEffect 仅在 !allocs.length 时接管。

3.5 【Low】AllocPanel.resizeLineRows 会无提示覆盖手工比例

• AllocPanel.tsx:101-105，用于 :362（移除）与 :374（添加）。
• 用户手工调成 70% / 30% 后点「添加分摊人」→ 三行被整体重置为 34/33/33，手工结果丢失且无提示（与销售单既有行为一致，但服务单此前是“留白待填”，用户对手工值更敏感）。建议：加人时保留已填比例、仅把剩余比例给新行；或给一次 message.info('已按人数重新平分') 提示。

3.6 【Low】测试缺口

新增测试覆盖了“面板平分”，但没有覆盖本次真正新增的 SettleOrderModal 预填逻辑：draftIntent.test.tsx 只断言了顶部横幅文案与“不出现待分摊”，未断言预填行出现（例如 getAllByRole('spinbutton') 值 ['50','50']），也未覆盖 §3.1 的“关闭重开”路径。建议补 2 个断言/用例。

---

四、工具问题对比复核（codescan_issues_diff 实数据）

4.1 “修复 2 条” → 实测为伪修复（行号位移）

4.2 “新增 3 条”

4.3 既存复杂度债务（本次未引入、但被加重）

SettleOrderModal 507 行 / 圈复杂度 100 / 直接依赖 64 个函数；AllocPanel 320 行 / 复杂度 51 / 扇出 41 —— 均为既存问题，本次 +33 行与 +6 行使其更差。建议后续把「分摊预填 + 分摊校验」抽为 useAllocSeed(detail) hook，可同时解决 §3.1/§3.4 并显著降低两处复杂度。

---

五、验证建议（发布前手测清单）

1. 意向预填（主路径）：mp 下单排 张50/李50 → 前台「待收款」打开 → 分摊区应出现两行 50/50 且可直接改 → 收款成功，账本业绩 50/50。
2. §3.1 回归：同一单打开 → 「取消」→ 再打开 → 预填行是否仍在（当前会消失）。
3. §3.2 回归：构造 draft_allocs 比例不全的单（或 ratio 缺失）→ 观察「收款完成」按钮是否被禁用（本应可留空走服务端回落）。
4. §3.3 回归：服务单多行、意向只排 1 行 → 收款后核对未预填行的业绩归属是否仍按下单意向。
5. 口径确认：3 人单核对应分金额为 34/33/33（而非三等分），确认业务侧接受 §2.1 的 1% 偏差。

---

六、局限说明

• 本次分析仅基于 web 仓库源码与工具数据；settle.rs 等服务端回落粒度、draft_allocs 真实数据质量无法验证，故 §3.2/§3.3 标注为“需确认”。
• 工具问题表中 “修复/新增” 的匹配受行号位移影响较大，已逐行比对 base/head 源码纠正，引用时请以本报告 §4 为准。