增量质量报告 · huanyan/web v0.1.52

对比区间：ded04ef（base）→ 6ba2469（head，v0.1.52） 数据来源：codescan_issues_diff（修复/新增问题，真实数据）+ git diff 精读 + 关键文件人工复核 变更规模：新增 5 个测试文件 + 1 个共享判据模块 + 1 个抽屉组件，改造依赖 mock/order/records/settle/workbench 等核心链路

---

一、版本变更概览

本版本围绕 D61「拆单 + 服务单状态机 + 建单意向」，交付四块能力：

1. 服务单状态推进（start/finish）

   • 新增 src/pages/shared/orderActions.ts：状态维度（showServiceAdvance / serviceAdvanceStatusReason）+ 权限维度（canOperateService）+ 错误文案（serviceActionErrorText）统一判据，列表行与详情抽屉共用。
   • api/order.ts 新增 startService / finishService 及响应类型；order.mock.ts 补齐同契约 mock（权限 2003、状态 1005 优先序与 server 一致）。
   • OrderRecordDrawer、pos/records/index.tsx 接入按钮、二次确认与灰显 tooltip。

2. 员工微信绑定（残留批 2）

   • api/org.ts 新增 StaffWxBinding / fetchStaffWxBinding / unbindStaffWx，org.mock.ts 补 mock（openid 脱敏、越域 2004、未绑定 1005）。
   • 新增 WxBindingDrawer.tsx，org/staffs/index.tsx 行操作「微信绑定」接入；解绑走统一带遮罩 Modal。

3. 建单意向「看得见」（D61 §七）

   • order.ts 详情适配 draftAllocs/draftPayIntent；model.ts 新增 ratioPctText / draftIntentOf。
   • AllocPanel 增加只读意向条；SettleOrderModal 组装意向并在待收款链路透传 pay_intent。

4. 测试基建：新增 5 个用例文件（mock 契约、抽屉动作、开单记录推进、意向可读化、微信绑定）；testTimeout 20s→60s、asyncUtilTimeout→20s。

总体评价：功能实现规范，边界（权限/状态/错误码）有明确契约且被新用例覆盖，未见影响主流程的功能性缺陷。主要问题集中在新增代码的复杂度膨胀与少量健壮性/分层细节。

---

二、修复的问题（base 有 → head 无，共 15 条）

均为历史存量质量项在重构中被动消除，主要来自 adaptOrderDetail、OrderRecordDrawer、pos/records、SettleOrderModal 的改写。

说明：其中 OrderRecordDrawer.tsx:493、pos/records/index.tsx:33 等为「同函数被改动后行号变化」，与第三节「新增」中同位置的条目互为同一处代码的位置迁移，非功能回归。

---

三、新增的问题（base 无 → head 有，共 29 条）

3.1 真实新增的复杂度/维护性债（集中于本次新增代码）

3.2 「新增」中属于行号位移的伪新增（同一处代码，非新债）

• OrderRecordDrawer.tsx:598（VoidOrderModal 圈复杂度/嵌套/函数过长，3 条）↔ base 的 :493，因上方插入 start/finish 代码而下移。
• SettleOrderModal.tsx:291（行过长）↔ base 的 :270。
• order.ts:464、records/index.tsx:56 虽亦为位置迁移，但对应函数确有真实增长（新逻辑并入），计入真实新债。

3.3 测试文件内的维护性项

• orderDrawerActions.test.tsx:99、serviceAdvance.test.tsx:117：重复代码块（测试 setup 重复，可抽 helper）。

建议：新增复杂度集中在「列表页推进逻辑」和「详情适配层」，下一迭代优先把 PosRecordsPage 的行操作、adaptOrderDetail 的子结构适配抽离，可同时消掉多条 Medium。

---

四、人工复核发现的真实风险（自动化未覆盖）

以下为精读变更代码后识别的问题，按严重度排序；均为新增/改造代码引入。

4.1【Medium】微信绑定抽屉加载失败无错误态，永久转圈

src/pages/org/staffs/WxBindingDrawer.tsx 渲染分支只以 !binding（data 是否存在）区分，loading 与 error 共用同一 Spin 占位：

{binding ? (…内容…) : (<div style={{padding:60,textAlign:'center'}}><Spin /></div>)}

当 GET /staffs/{id}/wx-binding 失败（网络异常，或 2003/2004/1002 越权/越域），bindingQuery.data 恒为 undefined，抽屉一直停留在 Spin，用户既看不到失败原因也无法重试。 建议：增加 bindingQuery.isError 分支，展示 errorMessage(bindingQuery.error) + 「重试」按钮（复用项目统一错误展示）。

4.2【Medium】API（mock）层反向依赖状态层

src/api/order.mock.ts 新增 import { useAuthStore } from '@/stores/auth'，让 API 层（含 mock）依赖 zustand store，用于在 ensureServiceStaff 中读取当前登录人。

• 现状核查：stores/auth → api/auth|api/client|queryClient|menu|storeSelection，当前无循环依赖，运行时不报错。
• 风险：破坏「api 层零业务/零 store 依赖」的分层约定，且 orderServiceFlow.mock.test.ts 等契约测试需先初始化 store 才能跑通，耦合上升。 建议：把「操作人」作为参数显式传入 mock 动作（startService(orderId, operator)），或在更底层注入当前 staff，保持 api 层不感知 store。

4.3【Low】org.mock 新增 wxBindings 缺版本迁移，存量会话丢种子绑定态

src/api/order.mock.ts 有 MOCK_VERSION 强校验（不足版本重播种），但 src/api/org.mock.ts 的 load() 命中 sessionStorage 即 return JSON.parse(raw)，不校验版本、不合并新增字段：

• 同标签页内跨版本热更新/重载时，旧 state 无 wxBindings，state.wxBindings?.[id] 恒 undefined → 种子已绑定的员工（张小明/周晓芸）显示「未绑定」，unbindStaffWx 直接判定 1005 无需解绑。
• 仅影响 mock 演示/本地走查（真实通道走接口），故定 Low。 建议：org.mock 加 MOCK_VERSION（或在 load 中对缺失的 wxBindings 兜底合并 seed() 的默认值）。

4.4【Low】确认弹窗 onOk 返回可能 reject 的链式 Promise，失败后弹窗不关闭 + console 噪音

OrderRecordDrawer.confirmFinish/confirmCancel 与 pos/records.runAdvance 的完成分支：

onOk: () => mutation.mutateAsync().then(() => undefined)

失败时 mutateAsync reject，虽 onError 已弹错误文案，但 antd Modal.confirm 会保留弹窗并 console.error，用户可能重复点确认。 建议：onOk 内 try/await/catch 后返回 resolved（失败即由 onError 提示并关闭），或显式 .catch(() => undefined)。

4.5【Low】建单意向只读条渲染不完整（信息缺失，非错误）

src/pages/pos/workbench/AllocPanel.tsx 的 draftIntentBanner 在销售单分支与常规服务单分支渲染，但服务单「无购买行（全划卡/空行）」的早退分支未渲染，此时收款面板会看不到「下单时已排/支付意向」。属展示一致性问题。

4.6【Low】测试基建以上调超时替代根因

vitest.config.ts 将 testTimeout 由 20s 提到 60s，src/test/setup.ts 将 asyncUtilTimeout 提到 20s。注释称「不改断言口径」，但可用性上是在放大等待上限以吸收大 DOM（PosRecordsPage/OrderRecordDrawer 巨型组件）与 jsdom 可访问名计算开销。这会掩盖页面级性能退化。 建议：结合 3.1 的组件拆分降低单页 DOM 规模，逐步回退超时阈值；而非持续上调。

---

五、结论与建议

1. 无阻断级缺陷：本版本核心链路（服务单推进、权限/状态灰显、意向展示、微信绑定）逻辑自洽，错误码映射与 server 契约一致，且有契约/组件级用例兜底。
2. 需要跟进：4.1（微信绑定失败无错误态）与 4.2（api 依赖 store）建议本迭代内修正；4.3/4.4/4.5 可在下一次清理批处理。
3. 技术债治理：新增 Medium 复杂度集中于 PosRecordsPage 与 adaptOrderDetail，建议下一迭代优先抽取「行操作 hook」与「详情子结构适配器」，可批量消除复杂度/扇出告警，并配合回退测试超时（4.6）。