KCGL/inventory-backend at a25201357382f005a8ebba7caaa05fcfecaf90ee - KCGL

Files

yueli dda6e4c787 feat(return): 退回、回库、报废与在管台账接口

打通逆向物流的全部后端入口。

新增接口（app/api/v1/inbound/stock.py）：
- POST /stock/<id>/change-status      库存状态变更（在库/冻结/不良品）
- POST /stock/return-from-outbound    通用原单退回
- POST /stock/defective/<id>/restock  不良品修好回库（支持部分回库）
- POST /stock/defective/<id>/scrap    不良品报废销毁
- GET  /stock/defective               在管台账分页查询

设计要点：
- 良品退回加回原库存行；不良品退回则库存表分毫不动，只写独立在管台账。
  这样坏件从根上不会混进可分配池
- 全链路 Fail-Closed 守卫：良品退回到非「在库」行会被拒（status 是行级
  属性，加回已冻结/不良品的行会让良品被连带隔离）；原库存行已不存在会被
  拒（入库模块会物理删除库存行，实测 1077 条出库记录中已有 7 条悬空）
- 三个写接口均加 with_for_update 行锁 + prevent_double_submit 幂等锁。
  装饰器顺序为 permission_required → prevent_double_submit，顺序颠倒会因
  JWT 未验证而抛错、被自身 except 捕获后 fail-open 降级
- 报废同时写 trans_scrap 台账（source_table 用 trans_defective_goods 并
  存台账自身主键，与 trans_borrow/trans_repair 作来源时的约定一致），
  成本按原库存行 best-effort 取价，取不到记 0 而不中断报废

报废报表集成（app/api/v1/scrap.py）：
- _resolve_materials 补 trans_defective_goods 分支。物料名已在台账冗余存储，
  不联表——坏件的原库存行可能已被删除，联表取名称会得到空值
- 公司隔离补 defective_subq 分支。原先按 source_table 逐个构造子查询，
  未知来源会被整体过滤，导致这类记录对普通用户静默消失
- 无审批单号的分组前缀按来源分流：不良品直报不再套用 LEGACY-（它是新业务
  记录，不是历史脏数据）。分组键同步带上来源标记，且 _order_key_pred 的
  SQL 谓词改为同口径，否则页面分组与「按单筛选」结果会对不上

2026-09-16 15:45:31 +08:00