增量代码审查报告（incremental_report）

• 项目：huanyan/web
• 分支：v0.1.51
• 对比区间：520a427b → ded04ef8
• 审查方式：git diff 全量变更面 + 逐文件源码核对 + 质量工具 issues diff（修复/新增问题均为工具真实数据）
• 变更规模：约 26 个文件（含 6 个新增测试文件、3 个新增源码文件 + 1 个新增契约测试）

---

一、变更概览（按模块）

本增量属于「库存域残留批 1b」+「D61 §5.5 续开」两块能力的收口，主线是把服务端已定稿的口径搬到前端与 mock：

---

二、修复的问题（工具 issues diff 真实数据，14 条）

口径：base 有、head 无（已修复/已收敛）。

• [Medium/Complexity] 圈复杂度过高 @ src/api/stock.mock.ts:552
• [Medium/Complexity] 嵌套深度过高 @ src/api/stock.mock.ts:552
• [Medium/Complexity] 圈复杂度过高 @ src/api/stock.mock.ts:597
• [Medium/Complexity] 圈复杂度过高 @ src/api/stock.mock.ts:820
• [Medium/Complexity] 圈复杂度过高 @ src/api/stock.mock.ts:893
• [Low/Maintainability] 重复代码块 @ src/api/stock.ts:179
• [Low/Maintainability] 行过长 @ src/api/stock.ts:232
• [Low/Maintainability] 重复代码块 @ src/pages/pos/workbench/index.tsx:1055（结果页 JSX 抽出为 OrderResultPanel 后消除）
• [Low/Maintainability] 行过长 @ src/pages/stock/out/index.tsx:323
• [Medium/Complexity] 圈复杂度过高 @ src/pages/stock/out/index.tsx:404
• [Medium/Complexity] 嵌套深度过高 @ src/pages/stock/out/index.tsx:404
• [Medium/Complexity] 函数过长 @ src/pages/stock/out/index.tsx:404
• [Low/Naming] 命名不规范 @ src/pages/stock/out/index.tsx:404
• [Medium/Complexity] 嵌套深度过高 @ src/pages/stock/shared.tsx:424

---

三、新增的问题（工具 issues diff 真实数据，25 条）

口径：head 有、base 无（本次新增/由拆分造成）。多数为复杂度与重复代码类，不影响功能，但建议在下个批次收敛。

3.1 复杂度 / 函数过长（建议拆分）

• [Medium/Complexity] 圈复杂度过高 @ src/api/stock.mock.ts:574（count=19）
• [Medium/Complexity] 嵌套深度过高 @ src/api/stock.mock.ts:574
• [Medium/Complexity] 圈复杂度过高 @ src/api/stock.mock.ts:623（count=19）
• [Medium/Complexity] 圈复杂度过高 @ src/api/stock.mock.ts:846（count=39）
• [Medium/Complexity] 圈复杂度过高 @ src/api/stock.mock.ts:989（count=20）
• [Medium/Complexity] 圈复杂度过高 @ src/pages/stock/out/index.tsx:452（CreateStockOutButton，count=17）
• [Medium/Complexity] 嵌套深度过高 @ src/pages/stock/out/index.tsx:452
• [Medium/Complexity] 函数过长 @ src/pages/stock/out/index.tsx:452（CreateStockOutButton 159 行）
• [Medium/Complexity] 圈复杂度过高 @ src/pages/stock/photoGrid.tsx:68（StockInPhotoGrid，count=24）
• [Medium/Complexity] 嵌套深度过高 @ src/pages/stock/photoGrid.tsx:68
• [Medium/Complexity] 函数过长 @ src/pages/stock/photoGrid.tsx:68（196 行）
• [Medium/Complexity] 嵌套深度过高 @ src/pages/pos/workbench/__tests__/continueSales.test.tsx:119

3.2 耦合 / 扇出

• [Medium/Dependency] 高耦合 @ src/api/__tests__/stock.contract.test.ts:1（直接依赖 11 个函数）
• [Low/Dependency] 扇入扇出异常 @ src/pages/stock/photoGrid.tsx:68（StockInPhotoGrid fan-out 22）
• [Medium/Dependency] 高耦合 @ src/pages/stock/photoGrid.tsx:68（直接依赖 22 个函数）

3.3 重复代码 / 长行 / 命名（可维护性）

• [Low/Maintainability] 重复代码块 @ src/api/stock.ts:213（3 处重复）
• [Low/Maintainability] 行过长 @ src/api/stock.ts:323
• [Low/Maintainability] 行过长 @ src/pages/pos/workbench/OrderResultPanel.tsx:57
• [Low/Maintainability] 重复代码块 @ src/pages/pos/workbench/__tests__/continueSales.test.tsx:33
• [Low/Maintainability] 行过长 @ src/pages/pos/workbench/__tests__/continueSales.test.tsx:153
• [Low/Maintainability] 重复代码块 @ src/pages/pos/workbench/__tests__/continueSales.test.tsx:184
• [Low/Maintainability] 重复代码块 @ src/pages/pos/workbench/index.tsx:1001
• [Low/Maintainability] 重复代码块 @ src/pages/shared/orderStatus.ts:34
• [Low/Naming] 命名不规范 @ src/pages/stock/out/index.tsx:452（私有函数用了导出名风格）

点评：StockInPhotoGrid（196 行 / 复杂度 24 / 依赖 22）与 mock 中 fetchStocks/fetchStockOuts 的复杂度抬升，主要来自把「上传 + 预览 + 删除 + 只读」四态塞进一个组件、以及 mock 里不断叠加聚合逻辑。功能正确，但建议下批把上传逻辑抽 useStockInPhotoUpload hook、把只读渲染拆为 StockInPhotoGridReadOnly。

---

四、人工深度核对（逐文件）——发现的功能/一致性问题

以下是人工阅读变更代码后的补充发现（非工具 issues）。已按影响面从高到低排列。

P1｜中｜mock「在途显示串」复用 wholeDisplay，数量 ≥ 整件换算量时输出包装单位，违背 D6b「耗材＝次」契约

• 位置：src/api/stock.mock.ts:894-896（transit_out_display / transit_in_display）调用 wholeDisplay（src/api/stock.mock.ts:386-395）
• 现象：wholeDisplay(200, 耗材 product#1 base_unit_qty=100) 返回 "2 支"（余数为 0 时整件段独占），wholeDisplay(150, ...) 返回 "1 支 50 次"。而 StockRow.transit_*_display 的契约注释、库存列表 Tooltip 明确写「数量按基本单位显示（耗材＝次，服务端下发显示串）」，恰好是要避免「把 200 次写成 2 支」的误导。
• 影响：mock 是 VITE_AUTH_MOCK=1 下的前端联调/演示数据源，QA 与演示会看到包装单位，与真实 server 口径不一致；契约测试只用了 50/10（< base_unit_qty）所以未暴露。
• 建议：mock 在途显示串改用「基本单位」格式化（耗材固定 N 次；零售/仪器 N unit），并为「在途数量 ≥ base_unit_qty」补一条契约断言。

P1｜中｜useResolvedPhotoUrls 用 Promise.all，单张预签名失败会让整组缩略图退化为占位

• 位置：src/pages/stock/photoGrid.tsx:46-62
• 现象：Promise.all(keys.map(fetchFileDownloadUrl)) 任一张抛错即整体 reject → query.data 为 undefined → resolved = {}，所有已有照片都显示 FileImageOutlined 占位。而同一处注释承诺「单张失败只回退占位（不阻塞其余照片展示）」。
• 影响：详情抽屉/九宫格里只要一张照片的下载地址换取失败，其余照片全部不可见，用户会误以为单据缺失凭证。
• 建议：改为 Promise.allSettled 或逐张 try/catch，失败项不写入结果 map（保留占位），成功项照常展示。

P2｜低｜stockInPhotoUrls 对空数组不回落（?? 只处理 null/undefined）

• 位置：src/api/stock.ts:116-124
• 现象：const list = row.imageUrls ?? row.image_urls。若详情接口下发 imageUrls: []（空数组而非 null），同时列表字段 image_urls 有值，?? 不会回落到 image_urls，导致照片被误判为「无照片」。
• 影响：接口字段兼容期（驼峰/下划线两套并存）可能偶发丢图。当前 StockDocDrawer 传的是列表行（imageUrls 为 undefined），暂不触发，属潜在隐患。
• 建议：改为「取第一个非空数组」：const list = (row.imageUrls?.length ? row.imageUrls : row.image_urls)。

P2｜低｜九宫格上传过程中可删除既有照片，上传完成用旧闭包 value 覆盖，可能把已删照片加回

• 位置：src/pages/stock/photoGrid.tsx handleFiles（约 L94-145）与 removeAt（约 L147-160）
• 现象：上传时仅禁用了「添加」按钮，每张缩略图的删除按钮仍可点。handleFiles 在开始时快照 const nextKeys = [...value]，await 上传完成后再 onChange(nextKeys)。若期间用户删除了一张既有照片，父级 photoKeys 已变短，但完成回调会写回「旧列表 + 新上传」，已删的照片被重新加回（且 remain 也按旧 value 计算）。
• 影响：多图上传（网络较慢）时的并发编辑错乱，属边界竞态。
• 建议：上传期间禁用删除按钮（editable && !uploading 才渲染删除入口），或在完成回调里用 setState(prev => merge(prev, addedKeys)) 的函数式更新而非闭包快照。

P2｜低｜期初库存导入向导仍走单图 image_url，未适配入库凭证 1–9 张数组化

• 位置：src/components/import/ImportWizard.tsx:345（TransferPhotoUpload bizType="stock-in" 单图）+ 约 L262 createImportBatch({ ... image_url: isStockInitial ? photoKey! : undefined })
• 现象：本次把「入库单新建」页面改成 1–9 张 image_urls，但「期初库存导入」生成的「期初导入」入库单仍只带一张 legacy image_url；TransferPhotoUpload 头注释也仍写「入库页同样复用」（实际入库页已改用 StockInPhotoGrid）。
• 影响：服务端声明「旧单图 image_url 仍兼容」，功能不阻断；但产品口径不统一（期初导入只能 1 张），且注释已过期，易误导后续维护。
• 建议：明确期初导入是否纳入 1–9 张口径；若纳入则复用 StockInPhotoGrid 并把 image_urls 透传到 createImportBatch；若暂不纳入，至少在注释与页面上写明「导入路径暂用单图」，并清理 transfer/photo.tsx 的过期注释。

P3｜低｜工作台客户预选的一次性守卫，同 kind 下切换不同 customerId 不会重新预选

• 位置：src/pages/pos/workbench/index.tsx presetAppliedRef（约 L564-577）
• 现象：presetAppliedRef.current 一旦置 true 就不再应用 URL 客户参数。这是为了「更换客户后不被带参查询顶回来」的正确取舍；但副作用是：若停留在同一 kind 的工作台（WorkbenchInner key={kind} 未重挂载）时再次通过带参 URL 导航到另一个 customerId（如先后从两张服务单详情点「继续开销售单」），新的客户不会被预选。
• 影响：边界场景下续开入口带错客户（仍显示上一次预选客户），需用户手动更换。
• 建议：把「已应用的 customerId」记录为 useRef<number | null>，变化时才重置；或让 ContinueSalesOrderButton 导航时追加一个非 kind 的 key（如 x=<timestamp>）触发重挂载，或在 WorkbenchInner 的 key 中加入 customerId。

P3｜信息｜只读态仍渲染隐藏 file input

• 位置：src/pages/stock/photoGrid.tsx（隐藏 <input type="file"> 无条件渲染）
• 现象：详情抽屉只读态虽无上传/删除按钮，但 DOM 仍存在 aria-label="入库凭证照片文件选择" 的 input（onChange 因 !onChange 直接 return）。
• 影响：功能无碍，仅无障碍/测试选择器噪音。
• 建议：{editable && <input ... />}。

---

五、正确性确认（已核对，无需改动）

• stockOutQueryParams：store_id → store、空筛选项不下发、excludeAuto 仅 true 时下发，与契约测试断言一致。
• mock fetchStockOuts：type 用归一化类型（手动/自动/期初）、excludeAuto 排除自动出库、total 与过滤同口径；purpose 与 type 组合过滤逻辑正确。
• transitDisplay：显示串优先 → 裸数字降级 → 无在途 —；未拼 unit，符合「不二次拼包装单位」要求。
• transferTransitText：transit_text 优先且原样展示、空串降级本地时长、非开放态且无串返回 null；列表/详情/widget 三处共用，口径一致。
• canContinueSalesOrder：仅「服务单」且状态 ∈ {待服务, 服务中, 已完成}；销售单/待支付不出现，符合 D61 §5.5（销售单不出反向入口）。
• 结果页 if (result && customer)：doSubmit 保证有 customer 才会 setResult，guard 不会造成结果页丢失。
• StockInPhotoGrid：满 9 张硬拦、超选只取剩余额度、删除可重拍、只读态无操作入口，与新增单测一致。
• photoGrid 上传链路使用 uploadFileViaPresign({name,size,mime,blob,biz_type:'stock-in'})，与 files.ts 签名一致；失败逐张提示且不落 value。

---

六、回归测试建议（按风险排序）

1. 入库凭证（高）：新建入库选 1/9/10 张、混入非图片、单张上传失败重试；详情抽屉对「新单 image_urls / 详情 imageUrls / 历史单图 image_url / 无照片」四种数据源的展示。
2. 出库筛选（高）：type 三值 + excludeAuto 开关 + purpose 组合；确认 total 与列表同口径；确认「产品」Tab 不受筛选影响；「重置」恢复全量。
3. 在途显示（中）：耗材在途数量 ≥ 整件换算量时的显示（对应 P1）；旧 server 无 display 字段时降级裸数字。
4. 调拨在途时长（中）：开放态/终态、transit_text 缺失降级、超时标注「（超时）」。
5. 续开（中）：服务单结果页/详情抽屉（待服务/服务中/已完成）出现入口，待支付/销售单不出现；?kind=销售单&customerId= 进入工作台客户已预选；同 kind 二次带参导航（对应 P3）。
6. 期初库存导入（低）：单图凭证路径在 array 化后仍能成功建单（对应 P2）。

---

七、结论

• 本次增量功能实现完整、契约与单测覆盖到位，核心口径（在途显示串、transit_text、type/excludeAuto、续开显隐、凭证数组化和历史回退）与 PRD 一致，未发现阻断级缺陷。
• 需要跟进的关键点：P1 mock 在途显示串不符合基本单位口径（会误导联调/演示）与 P1 单张预签名失败拖垮整组缩略图（违背注释承诺）；其余为边界竞态与口径一致性建议。
• 代码健康度：新增的 StockInPhotoGrid 与 mock 聚合函数复杂度偏高，建议下批拆分；同时清理 transfer/photo.tsx 过期注释、统一 imageUrls/image_urls 回落策略。