719 lines
31 KiB
Markdown
719 lines
31 KiB
Markdown
# Service 使用与 API 文档联动审计
|
||
|
||
更新时间: 2026-03-22
|
||
适用阶段: Model 重构阶段 4 及后续代码改造
|
||
目的: 在修改 service 前,先确认真实使用链路;若 service 已被使用,则必须同步更新 service、对应 API 文档,并在本文件中记录变更,便于后续复盘。
|
||
|
||
## 1. 执行规则
|
||
|
||
- 任何计划修改的 service,必须先确认是否被 systemMethods、qimenMethods、controller 或其他 service 使用。
|
||
- 只要存在真实调用链,就不能只改底层 service,必须一起评估上游入口与返回结构。
|
||
- 对外暴露为 system/qimen method 的能力,必须同步更新 methods/system.json 或 methods/qimen.json。
|
||
- 每次实际修改完成后,必须在本文件末尾追加一条变更记录。
|
||
|
||
## 2. 本轮已确认的高风险 service 使用链路
|
||
|
||
### 2.1 账号-仓库-角色关联链路
|
||
|
||
#### A. app/service/systems/store.js
|
||
|
||
关键风险:
|
||
|
||
- 直接使用不存在的 ctx.model.AccountStoreRole。
|
||
- 影响门店申请审核、角色分配、角色列表查询。
|
||
|
||
已确认调用点:
|
||
|
||
- app/service/systems/store.js:464
|
||
- app/service/systems/store.js:679
|
||
- app/service/systems/store.js:690
|
||
|
||
上游 system method:
|
||
|
||
- app/service/systemMethods/store.js:35 -> store.getStoreRoles
|
||
- app/service/systemMethods/store.js:45 -> store.auditApply
|
||
|
||
对应 API 文档:
|
||
|
||
- methods/system.json:1976 -> store.getStoreRoles
|
||
- methods/system.json:1993 -> store.auditApply
|
||
|
||
联动要求:
|
||
|
||
- 若将 AccountStoreRole 收敛为 AccountStoreEmployee 或其他真实模型,必须同步更新:
|
||
- app/service/systems/store.js
|
||
- app/service/systemMethods/store.js
|
||
- methods/system.json 中 store.getStoreRoles / store.auditApply 的参数、返回结构描述
|
||
|
||
#### B. app/service/systems/auth/user.js
|
||
|
||
关键风险:
|
||
|
||
- 当前已部分切到 AccountStoreEmployee,但变量名和注释仍保留 accountStoreRole 旧语义。
|
||
- 平台激活逻辑会联动 user.login、user.info、user.changeRole。
|
||
|
||
已确认调用点:
|
||
|
||
- app/service/systems/auth/user.js:118 -> changeRole
|
||
- app/service/systems/auth/user.js:195 -> info
|
||
- app/service/systems/auth/user.js:328 -> findById
|
||
- app/service/systems/auth/user.js:877 -> ensurePlatformActiveRole
|
||
|
||
上游 system method:
|
||
|
||
- app/service/systemMethods/user.js:11 -> user.login
|
||
- app/service/systemMethods/user.js:24 -> user.info
|
||
- app/service/systemMethods/user.js:29 -> user.changeRole
|
||
|
||
对应 API 文档:
|
||
|
||
- methods/system.json:2016 附近 -> user.login
|
||
- methods/system.json:2051 附近 -> user.info
|
||
- methods/system.json:2067 附近 -> user.changeRole
|
||
|
||
联动要求:
|
||
|
||
- 若修改 activeEmployeeId、employee_id、role_id、roles 列表结构,必须同步更新:
|
||
- app/service/systems/auth/user.js
|
||
- app/service/systemMethods/user.js
|
||
- methods/system.json 中 user.login / user.info / user.changeRole 的返回字段说明
|
||
|
||
#### C. app/service/systems/account_platform.js
|
||
|
||
关键风险:
|
||
|
||
- 该 service 当前直接依赖 AccountStoreRole 幽灵 key。
|
||
- 虽然尚未发现对外直接暴露的 system method,但它承载的平台激活角色语义与 auth.user 高度耦合。
|
||
|
||
已确认调用点:
|
||
|
||
- app/service/systems/account_platform.js:13 -> switchActiveRole
|
||
- app/service/systems/account_platform.js:77 -> getActiveRoleByPlatform
|
||
- app/service/systems/account_platform.js:159 -> getMultiplePlatformActiveRoles
|
||
- app/service/systems/account_platform.js:219 -> getAllPlatformActives
|
||
- app/service/systems/account_platform.js:309 -> getAvailableRoles
|
||
|
||
间接受影响入口:
|
||
|
||
- app/service/systems/auth/user.js:58
|
||
- app/service/systems/auth/user.js:304
|
||
- app/service/systems/auth/user.js:877
|
||
|
||
文档联动策略:
|
||
|
||
- 当前没有独立 method 文档入口。
|
||
- 若修改本 service 的输入/输出语义,必须回写到 user.login / user.info / user.changeRole 的 API 文档,因为这些接口会消费平台激活角色结果。
|
||
|
||
### 2.2 动态分表工厂链路
|
||
|
||
#### A. app/service/systemMethods/order.js
|
||
|
||
关键风险:
|
||
|
||
- 依赖 OrderDeliveryFactory / OrderItemsFactory 获取动态模型。
|
||
- 若工厂 key、返回模型或字段映射调整,会直接影响系统订单接口。
|
||
|
||
已确认调用点:
|
||
|
||
- app/service/systemMethods/order.js:18 -> getOrderModels
|
||
- app/service/systemMethods/order.js:98 -> list
|
||
- 其他 order.* 方法共享同一组动态模型入口
|
||
|
||
对应 API 文档:
|
||
|
||
- methods/system.json:422 -> order.getOrderModels
|
||
- methods/system.json:439 -> order.list
|
||
- methods/system.json:471 -> order.detail
|
||
- methods/system.json:503 -> order.listItems
|
||
- methods/system.json:535 -> order.stats
|
||
- methods/system.json:560 -> order.updateStatus
|
||
- methods/system.json:676 -> order.updateDeliveryTime
|
||
|
||
联动要求:
|
||
|
||
- 若修改动态模型获取方式、字段名或订单明细结构,必须同步更新上述 order.* 文档。
|
||
|
||
#### B. app/service/systems/delivery_order.js 与 app/service/qimenMethods/deliveryorder.js
|
||
|
||
关键风险:
|
||
|
||
- qimen 发货单接口直接依赖 OrderDeliveryFactory。
|
||
- 若动态分表模型的 key 或查询字段变化,Qimen 接口会受影响。
|
||
|
||
已确认调用点:
|
||
|
||
- app/service/systems/delivery_order.js:14
|
||
- app/service/systems/delivery_order.js:311
|
||
- app/service/qimenMethods/deliveryorder.js:7
|
||
- app/service/qimenMethods/deliveryorder.js:8
|
||
|
||
对应 API 文档:
|
||
|
||
- methods/qimen.json:14 -> deliveryorder.batchcreate
|
||
- methods/qimen.json:88 -> deliveryorder.create
|
||
- methods/qimen.json:162 -> deliveryorder.query
|
||
|
||
联动要求:
|
||
|
||
- 若修改 deliveryorder 查询、创建、历史表读取逻辑,必须同步更新 qimen deliveryorder.* 文档。
|
||
|
||
#### C. app/service/apiMethods/test.js
|
||
|
||
关键风险:
|
||
|
||
- 存在错误调用名 WmsOrderDeliveryFactory / WmsOrderItemsFactory。
|
||
- 这是内部调试链路,不是正式 API 文档入口,但必须与正式工厂 key 保持一致。
|
||
|
||
已确认调用点:
|
||
|
||
- app/service/apiMethods/test.js:50
|
||
- app/service/apiMethods/test.js:51
|
||
|
||
联动要求:
|
||
|
||
- 改动时同步修正为 OrderDeliveryFactory / OrderItemsFactory。
|
||
- 无需更新 methods 文档,但必须在本文件记录修复事实。
|
||
|
||
## 3. 本轮结论
|
||
|
||
- 即将进入的关联治理不是纯 model 内部调整,至少会影响 store、user、account_platform、order、deliveryorder 这几条真实业务链路。
|
||
- 因此后续任何代码改动都不能只改 model。
|
||
- 必须按“model -> service -> systemMethods/qimenMethods -> methods 文档 -> 变更记录”的顺序联动处理。
|
||
|
||
## 4. 修改前检查清单
|
||
|
||
- 确认目标 service 是否被上游调用。
|
||
- 确认上游调用属于 system 还是 qimen 入口。
|
||
- 确认 methods/system.json 或 methods/qimen.json 是否存在对应 method。
|
||
- 若返回结构变化,先记录旧字段,再补文档。
|
||
- 修改完成后,在本文件追加一条变更记录。
|
||
|
||
## 5. 变更记录模板
|
||
|
||
### YYYY-MM-DD HH:mm
|
||
|
||
- 修改范围:
|
||
- 涉及 service:
|
||
- 上游入口:
|
||
- 更新的 API 文档:
|
||
- 返回结构变化:
|
||
- 兼容处理:
|
||
- 验证方式:
|
||
|
||
## 6. 当前记录
|
||
|
||
### 2026-03-22 关联治理准备
|
||
|
||
- 修改范围: 阶段 4 开始前的 service 使用与文档联动审计
|
||
- 涉及 service:
|
||
- app/service/systems/store.js
|
||
- app/service/systems/auth/user.js
|
||
- app/service/systems/account_platform.js
|
||
- app/service/systemMethods/order.js
|
||
- app/service/systems/delivery_order.js
|
||
- app/service/qimenMethods/deliveryorder.js
|
||
- app/service/apiMethods/test.js
|
||
- 上游入口:
|
||
- system: store.getStoreRoles, store.auditApply, user.login, user.info, user.changeRole, order.*
|
||
- qimen: deliveryorder.batchcreate, deliveryorder.create, deliveryorder.query
|
||
- 更新的 API 文档: 尚未改动代码,本轮只完成审计与联动范围确认
|
||
- 返回结构变化: 暂无
|
||
- 兼容处理: 暂无
|
||
- 验证方式: 通过 service 调用搜索、system/qimen method 搜索、methods 文档映射完成静态核对
|
||
|
||
### 2026-03-22 关联治理执行(第一批)
|
||
|
||
- 修改范围: 修复 store 链路中 AccountStoreRole 幽灵模型引用
|
||
- 涉及 service:
|
||
- app/service/systems/store.js
|
||
- 上游入口:
|
||
- system: store.getStoreRoles, store.auditApply
|
||
- 更新的 API 文档:
|
||
- methods/system.json
|
||
- store.getStoreRoles: 补充 code 参数定义
|
||
- store.auditApply: 补充 audit_status/code/store_id/role_ids/reject_reason 参数定义
|
||
- 返回结构变化: 无(维持原有 code/message/data 结构)
|
||
- 兼容处理:
|
||
- 将账号-门店关系绑定到 AccountStoreEmployee
|
||
- 将角色绑定落到 EmployeeRole(employee_id + role_id)
|
||
- 保持接口出参与状态码行为不变
|
||
- 验证方式:
|
||
- 运行生成的改造前回归样例测试
|
||
- 运行 method-output compare 对比报告
|
||
|
||
### 2026-03-22 关联治理执行(第二批)
|
||
|
||
- 修改范围: 修复 account_platform 链路中 AccountStoreRole 幽灵模型引用
|
||
- 涉及 service:
|
||
- app/service/systems/account_platform.js
|
||
- 上游入口:
|
||
- 间接影响 system: user.login, user.info, user.changeRole
|
||
- 更新的 API 文档:
|
||
- 无直接 method 文档变更(本批未新增/修改 system method 参数)
|
||
- 返回结构变化: 无(维持 role_id/role_name/role_code/store_id/store_name/store_code 字段)
|
||
- 兼容处理:
|
||
- switchActiveRole 保持历史参数名 accountStoreRoleId,内部按 employee_id 落库
|
||
- include 链路由 AccountStoreRole 改为 AccountStoreEmployee + EmployeeRole + Role + Store
|
||
- getAvailableRoles 改为从 AccountStoreEmployee/EmployeeRole 聚合返回
|
||
- 验证方式:
|
||
- npx egg-bin test test/app/controller/system.method-output.pre-refactor.generated.test.js
|
||
- node .\\script\\method-output-regression.cjs compare
|
||
- npx egg-bin test test/app/controller/system.user.login.test.js test/app/controller/system.user.info.test.js test/app/controller/home.test.js
|
||
|
||
### 2026-03-22 关联治理执行(第三批)
|
||
|
||
- 修改范围: 清理 model 层残留命名污染(不改接口结构)
|
||
- 涉及 service/model:
|
||
- app/model/account.js
|
||
- app/model/role.js
|
||
- 上游入口:
|
||
- 间接影响 system 全链路(仅模型关联定义清理)
|
||
- 更新的 API 文档:
|
||
- 无(接口参数与返回结构未变化)
|
||
- 返回结构变化: 无
|
||
- 兼容处理:
|
||
- 仅移除 AccountStoreRole 的遗留注释/无效解构,不调整现有 alias
|
||
- 验证方式:
|
||
- node .\\script\\method-output-regression.cjs compare
|
||
- npx egg-bin test test/app/controller/system.user.login.test.js test/app/controller/system.user.info.test.js test/app/controller/home.test.js
|
||
- npx egg-bin test test/app/controller/system.method-output.batch3.generated.test.js
|
||
|
||
### 2026-03-22 样例漂移策略更新
|
||
|
||
- 发现现象:
|
||
- 固定历史样例 `system.method-output.pre-refactor.generated.test.js` 因权限/业务数据变化出现与历史快照不一致。
|
||
- 策略调整:
|
||
- 每批改造前重新冻结当批 baseline,并生成当批 Egg.js 样例测试。
|
||
- 历史快照保留审计用途,不作为后续批次唯一门禁。
|
||
- 当前批次快照:
|
||
- run/method-output-baseline-batch3-20260322_224649.json
|
||
- test/app/controller/system.method-output.batch3.generated.test.js
|
||
|
||
### 2026-03-22 关联治理执行(第四批)
|
||
|
||
- 修改范围: 统一 alias 命名并引入双轨兼容(复数标准名 + 历史别名保留)
|
||
- 涉及 service/model:
|
||
- app/model/account.js
|
||
- app/model/account_store_employee.js
|
||
- app/model/role.js
|
||
- app/model/store.js
|
||
- app/service/systems/account_platform.js
|
||
- app/service/systems/auth/user.js
|
||
- 上游入口:
|
||
- 间接影响 system: user.login, user.info, user.changeRole, store.getStoreRoles
|
||
- 更新的 API 文档:
|
||
- 无(接口参数与返回结构未变化)
|
||
- 返回结构变化: 无
|
||
- 兼容处理:
|
||
- 新增标准 alias:accountStoreEmployees / employeeRoles
|
||
- 保留历史 alias:accountStoreRoles / accountStoreEmployee / employeeRole
|
||
- service 查询切换到新 alias,并在读取层面对旧 alias 做回退兼容
|
||
- 验证方式:
|
||
- node .\\script\\method-output-regression.cjs compare
|
||
- node .\\script\\tmp-generate-method-regression-test.cjs
|
||
- npx egg-bin test temp/generated-tests/system.method-output.generated.test.js
|
||
- npx egg-bin test test/app/controller/system.user.login.test.js test/app/controller/system.user.info.test.js test/app/controller/home.test.js
|
||
|
||
### 2026-03-23 关联治理执行(第四批补充收敛)
|
||
|
||
- 修改范围: service 层去除旧 alias 回退依赖,统一使用新 alias(保留 model 兼容别名)
|
||
- 涉及 service:
|
||
- app/service/systems/account_platform.js
|
||
- app/service/systems/auth/user.js
|
||
- 上游入口:
|
||
- 间接影响 system: user.login, user.info, user.changeRole, store.getStoreRoles
|
||
- 更新的 API 文档:
|
||
- 无(接口参数与返回结构未变化)
|
||
- 返回结构变化: 无
|
||
- 兼容处理:
|
||
- account_platform 内部读取改为 employeeRoles 单轨
|
||
- model 层兼容 alias 继续保留,避免外部未迁移调用中断
|
||
- auth/user 中 accountStoreRole 变量语义更新为 accountStoreEmployee
|
||
- 验证方式:
|
||
- node .\\script\\method-output-regression.cjs baseline 8
|
||
- node .\\script\\method-output-regression.cjs compare
|
||
- node .\\script\\tmp-generate-method-regression-test.cjs
|
||
- npx egg-bin test temp/generated-tests/system.method-output.generated.test.js
|
||
- npx egg-bin test test/app/controller/system.user.login.test.js test/app/controller/system.user.info.test.js test/app/controller/home.test.js
|
||
|
||
### 2026-03-23 关联治理执行(第五批)
|
||
|
||
- 修改范围: 移除 model 层重复兼容 alias,完成重复关联清理
|
||
- 涉及 model:
|
||
- app/model/account.js
|
||
- app/model/account_store_employee.js
|
||
- app/model/role.js
|
||
- app/model/store.js
|
||
- 上游入口:
|
||
- 间接影响 system: user.login, user.info, user.changeRole, store.getStoreRoles
|
||
- 更新的 API 文档:
|
||
- 无(接口参数与返回结构未变化)
|
||
- 返回结构变化: 无
|
||
- 兼容处理:
|
||
- 删除旧 alias:accountStoreRoles / employeeRole / accountStoreEmployee(Store.hasMany 语义)
|
||
- 保留必要单数 alias:AccountPlatformActive.belongsTo(AccountStoreEmployee).as = accountStoreEmployee
|
||
- 验证方式:
|
||
- node .\\script\\method-output-regression.cjs baseline 8
|
||
- node .\\script\\method-output-regression.cjs compare
|
||
- node .\\script\\tmp-generate-method-regression-test.cjs
|
||
- npx egg-bin test temp/generated-tests/system.method-output.generated.test.js
|
||
- npx egg-bin test test/app/controller/system.user.login.test.js test/app/controller/system.user.info.test.js test/app/controller/home.test.js
|
||
|
||
### 2026-03-23 关联治理执行(4.1 全量一致性校验)
|
||
|
||
- 修改范围: 对 app/model 全量关联定义与数据库真实外键进行一致性审计(无业务代码改动)
|
||
- 审计产物:
|
||
- association_fk_consistency_report.md
|
||
- temp/association-fk-audit.json
|
||
- 审计结论:
|
||
- DB 外键 51 条,模型关联 89 条,可直接匹配 53 条
|
||
- 模型定义但 DB 无外键约束 28 条
|
||
- DB 有外键但模型未声明 13 条
|
||
- 动态模型/示例占位无法静态解析 5 条
|
||
- 影响判断:
|
||
- 当前 system 输出门禁未受影响,但存在“模型语义与 DB 约束不完全对齐”的技术债
|
||
- 已将高优先级差异并入后续 4.4 规约与治理清单
|
||
|
||
### 2026-03-23 关联治理执行(第六批:receiving 高优先差异第一批)
|
||
|
||
- 修改范围: 处理 receiving 链路高优先差异,移除无效模型关联并收敛仓库维度查询条件
|
||
- 涉及 service/model:
|
||
- app/model/receiving.js
|
||
- app/model/receiving_detail.js
|
||
- app/service/systems/storage/receiving.js
|
||
- 上游入口:
|
||
- 间接影响 system: storage.receiving.getReceivingDetail 及 receiving 相关查询/更新链路
|
||
- 更新的 API 文档:
|
||
- 无(接口参数与返回结构未变化)
|
||
- 返回结构变化: 无
|
||
- 兼容处理:
|
||
- 删除无效关联: `Receiving.hasMany(Storage, foreignKey: 'receiving_id')`
|
||
- 删除无效关联: `ReceivingDetail.hasMany(Storage, foreignKey: 'receiving_detail_id')`
|
||
- `StoreWarehouse` include/query 统一增加 `warehouse_id + use_status` 过滤,避免跨仓库错关联
|
||
- `create` 流程 `store_name` 统一使用 `store_remask`
|
||
- 验证方式:
|
||
- node .\\script\\method-output-regression.cjs compare
|
||
- node .\\script\\tmp-generate-method-regression-test.cjs
|
||
- npx egg-bin test temp/generated-tests/system.method-output.generated.test.js test/app/controller/system.user.login.test.js test/app/controller/system.user.info.test.js test/app/controller/home.test.js
|
||
- 验证结果:
|
||
- compare: total=8, mismatch=0
|
||
- tests: 14 passing
|
||
|
||
### 2026-03-23 关联治理执行(第七批:4.4 规约文档落地)
|
||
|
||
- 修改范围: 形成并落地 eager-loading 与 N+1 风险规约(文档治理,无业务代码改动)
|
||
- 涉及文档:
|
||
- association_eager_loading_n_plus_one_guideline.md
|
||
- association_validation_checklist.md
|
||
- model_todo.txt
|
||
- 上游入口:
|
||
- 无直接 system/qimen 行为变更
|
||
- 更新的 API 文档:
|
||
- 无
|
||
- 返回结构变化: 无
|
||
- 兼容处理:
|
||
- 将关联查询的最小约束(include attributes、上下文 where、门禁流程)固化为统一规约
|
||
- 验证方式:
|
||
- 以第六批回归结果作为当前代码基线(compare mismatch=0,tests 14 passing)
|
||
|
||
### 2026-03-23 关联治理执行(第八批:store_warehouse/stock_warehouse 语义收敛)
|
||
|
||
- 修改范围: 修复 stock_store 链路中 `StoreWarehouse` 仅按 `store_id` 关联导致的跨仓误匹配风险
|
||
- 涉及 service/model:
|
||
- app/service/systems/stock_store.js
|
||
- 上游入口:
|
||
- 间接影响 system: stock.* 查询链路(库存列表/搜索)
|
||
- 更新的 API 文档:
|
||
- 无(接口参数与返回结构未变化)
|
||
- 返回结构变化: 无
|
||
- 兼容处理:
|
||
- `store_stock` include 在 count/findAll/search 三处统一增加 `warehouse_id + use_status` 过滤
|
||
- 保持 `required` 策略不变(列表仍 required=true,搜索路径 required=false)
|
||
- 验证方式:
|
||
- node .\\script\\method-output-regression.cjs compare
|
||
- node .\\script\\tmp-generate-method-regression-test.cjs
|
||
- npx egg-bin test temp/generated-tests/system.method-output.generated.test.js test/app/controller/system.user.login.test.js test/app/controller/system.user.info.test.js test/app/controller/home.test.js
|
||
- 验证结果:
|
||
- compare: total=8, mismatch=0
|
||
- tests: 14 passing
|
||
|
||
### 2026-03-23 关联治理执行(第九批:role/permission 语义收敛)
|
||
|
||
- 修改范围: 修复 auth/user 权限链路对禁用角色/权限的过滤缺失问题
|
||
- 涉及 service/model:
|
||
- app/service/systems/auth/user.js
|
||
- 上游入口:
|
||
- 间接影响 system: user.info(权限与菜单加载链路)
|
||
- 更新的 API 文档:
|
||
- 无(接口参数与返回结构未变化)
|
||
- 返回结构变化: 无(仅收敛为“启用角色/启用权限可见”)
|
||
- 兼容处理:
|
||
- `getPermissions/getMenus` 在 EmployeeRole 查询中增加 Role.status=1 过滤
|
||
- Permission 查询增加 status=1 过滤
|
||
- role_id 与 permission_id 查询集合去重
|
||
- 验证方式:
|
||
- node .\\script\\method-output-regression.cjs compare
|
||
- node .\\script\\tmp-generate-method-regression-test.cjs
|
||
- npx egg-bin test temp/generated-tests/system.method-output.generated.test.js test/app/controller/system.user.login.test.js test/app/controller/system.user.info.test.js test/app/controller/home.test.js
|
||
- 验证结果:
|
||
- compare: total=8, mismatch=0
|
||
- tests: 14 passing
|
||
|
||
### 2026-03-23 关联治理执行(第十批:role_permission 外键迁移落地)
|
||
|
||
- 修改范围: 落地 `role_permission.permission_id -> permission.id` 的可执行迁移脚本与模型类型对齐
|
||
- 涉及 service/model/migration:
|
||
- database/migrations/20260323103000-align-role-permission-fk.js
|
||
- app/model/role_permission.js
|
||
- 上游入口:
|
||
- 无直接 system/qimen 返回结构变化
|
||
- 更新的 API 文档:
|
||
- 无
|
||
- 返回结构变化: 无
|
||
- 兼容处理:
|
||
- 迁移脚本包含保护性校验:存在孤儿数据时直接失败,避免静默脏写
|
||
- down 提供外键回滚与字段类型回退
|
||
- 审计发现:
|
||
- `wms_role_permission.permission_id` 存在 4 条孤儿记录(id: 2, 3, 6, 10)
|
||
- `wms_role.store_id` 存在 3 条 `0` 哨兵值(当前不满足直接加 FK 条件)
|
||
- 验证方式:
|
||
- node .\\script\\method-output-regression.cjs compare
|
||
- node .\\script\\tmp-generate-method-regression-test.cjs
|
||
- npx egg-bin test temp/generated-tests/system.method-output.generated.test.js test/app/controller/system.user.login.test.js test/app/controller/system.user.info.test.js test/app/controller/home.test.js
|
||
- 实际执行结果:
|
||
- 已创建备份表并落库:
|
||
- `wms_role_permission_orphan_backup_20260323`(4 条)
|
||
- `wms_role_store_zero_backup_20260323`(3 条)
|
||
- 已清洗数据:
|
||
- 删除 `wms_role_permission.permission_id` 孤儿 4 条
|
||
- 将 `wms_role.store_id=0` 修正为 `NULL` 共 3 条
|
||
- 已执行 DDL:
|
||
- `wms_role_permission.permission_id` -> `int(11)`
|
||
- 新增外键 `fk_wms_role_permission_permission`(ON UPDATE RESTRICT, ON DELETE CASCADE)
|
||
- SequelizeMeta 已登记 `20260323103000-align-role-permission-fk.js`
|
||
- 迁移后复核: 孤儿计数=0,role_store_zero=0
|
||
- 回归结果:
|
||
- compare: total=8, mismatch=0
|
||
- tests: 14 passing
|
||
|
||
### 2026-03-23 关联治理执行(第十一批:role.store_id 外键策略落地)
|
||
|
||
- 修改范围: 落地 `wms_role.store_id -> wms_store.id` 外键策略(NULL 语义)
|
||
- 涉及 migration:
|
||
- database/migrations/20260323113000-add-role-store-fk.js
|
||
- 上游入口:
|
||
- 无直接 system/qimen 返回结构变化
|
||
- 更新的 API 文档:
|
||
- 无
|
||
- 返回结构变化: 无
|
||
- 兼容处理:
|
||
- `store_id` 字段类型对齐为 `bigint(20) unsigned NULL`
|
||
- 新增索引 `idx_store_id`
|
||
- 外键策略采用 `ON DELETE SET NULL`,保留历史角色记录的 NULL 语义
|
||
- 实际执行结果:
|
||
- 外键 `fk_wms_role_store` 已生效(ON UPDATE RESTRICT, ON DELETE SET NULL)
|
||
- `wms_role` 孤儿数据复核: 0
|
||
- SequelizeMeta 已登记 `20260323113000-add-role-store-fk.js`
|
||
- 验证方式:
|
||
- node .\\script\\method-output-regression.cjs compare
|
||
- node .\\script\\tmp-generate-method-regression-test.cjs
|
||
- npx egg-bin test temp/generated-tests/system.method-output.generated.test.js test/app/controller/system.user.login.test.js test/app/controller/system.user.info.test.js test/app/controller/home.test.js
|
||
- 回归结果:
|
||
- compare: total=8, mismatch=0
|
||
- tests: 14 passing
|
||
|
||
### 2026-03-23 关联治理执行(第十二批:store_warehouse/stock_warehouse 模型层语义治理)
|
||
|
||
- 修改范围: 收敛 `store_stock` 关联的模型层复合键表达,统一 include 构造入口
|
||
- 涉及 service/model:
|
||
- app/model/store_warehouse.js
|
||
- app/model/stock_warehouse.js
|
||
- app/model/receiving.js
|
||
- app/service/systems/stock_store.js
|
||
- app/service/systems/storage/receiving.js
|
||
- 上游入口:
|
||
- 间接影响 system: stock.* / storage.receiving.* 查询链路
|
||
- 更新的 API 文档:
|
||
- 无(接口参数与返回结构未变化)
|
||
- 返回结构变化: 无
|
||
- 兼容处理:
|
||
- StoreWarehouse 新增 `buildScopedWhere` 与 `buildStoreStockInclude`,统一生成 `warehouse_id + use_status` 约束
|
||
- 复合键语义关联统一显式 `constraints:false`,避免单列外键误解
|
||
- service 查询改为复用模型构造器,保持原有 `required` 语义不变
|
||
- 验证方式:
|
||
- node .\\script\\method-output-regression.cjs compare
|
||
- node .\\script\\tmp-generate-method-regression-test.cjs
|
||
- npx egg-bin test temp/generated-tests/system.method-output.generated.test.js test/app/controller/system.user.login.test.js test/app/controller/system.user.info.test.js test/app/controller/home.test.js
|
||
- 回归结果:
|
||
- compare: total=8, mismatch=0
|
||
- tests: 14 passing
|
||
|
||
### 2026-03-23 关联治理执行(第十三批:include alias 一致性收尾扫描)
|
||
|
||
- 修改范围: 阶段 4 收尾检查(全量 include alias 一致性扫描,无业务代码改动)
|
||
- 涉及范围:
|
||
- app/model/**/*.js(association `as` 定义)
|
||
- app/service/**/*.js(include `as` 使用)
|
||
- 上游入口:
|
||
- 无直接 system/qimen 行为变更
|
||
- 更新的 API 文档:
|
||
- 无
|
||
- 返回结构变化: 无
|
||
- 扫描方法:
|
||
- 全量检索 model association 与 service include 的 alias 使用
|
||
- 执行自动差集比对(service alias - model alias)
|
||
- 扫描结果:
|
||
- model alias 总数: 48
|
||
- 差集可疑项: 0
|
||
- 结论: 未发现 include alias 不一致问题
|
||
- 验证方式:
|
||
- 通过一次性 Node 差集脚本执行 `service alias - model alias` 自动比对(临时脚本未入库)
|
||
|
||
### 2026-03-23 关联治理执行(第十四批:permission.parent_id 自关联约束落地)
|
||
|
||
- 修改范围: 落地 `wms_permission.parent_id -> wms_permission.id` 自关联外键,并统一根节点语义
|
||
- 涉及 service/model/migration:
|
||
- database/migrations/20260323123000-add-permission-parent-fk.js
|
||
- app/model/permission.js
|
||
- app/service/systems/auth/user.js
|
||
- 上游入口:
|
||
- 间接影响 system: user.info(菜单树构建)
|
||
- 更新的 API 文档:
|
||
- 无(接口参数与返回结构未变化)
|
||
- 返回结构变化: 无
|
||
- 兼容处理:
|
||
- 根节点语义由 `parent_id=0` 规范为 `parent_id IS NULL`
|
||
- 模型 setter 兼容历史输入:`0 -> NULL`
|
||
- 菜单树构建逻辑根判断由 `parent_id===0` 收敛为 `!parent_id`
|
||
- 实际执行结果:
|
||
- 落库复核:`root_zero_after=0`、`root_null_after=42`、`orphan_after=0`
|
||
- 外键 `fk_wms_permission_parent` 已生效(ON UPDATE RESTRICT, ON DELETE SET NULL)
|
||
- SequelizeMeta 已登记 `20260323123000-add-permission-parent-fk.js`
|
||
- 触发器状态:目标库因权限限制(binlog + SUPER)未创建触发器,采用应用层归一化方案替代
|
||
- 验证方式:
|
||
- node .\script\method-output-regression.cjs compare
|
||
- node .\script\tmp-generate-method-regression-test.cjs
|
||
- npx egg-bin test temp/generated-tests/system.method-output.generated.test.js test/app/controller/system.user.login.test.js test/app/controller/system.user.info.test.js test/app/controller/home.test.js
|
||
- 回归结果:
|
||
- compare: total=8, mismatch=0
|
||
- tests: 14 passing
|
||
|
||
### 2026-03-23 模型能力治理执行(第十五批:阶段 5.1 清理清单盘点)
|
||
|
||
- 修改范围: 阶段 5.1(识别应迁移到 service 层的方法能力,文档治理)
|
||
- 涉及文档:
|
||
- model_cleanup_list.md
|
||
- model_todo.txt
|
||
- 上游入口:
|
||
- 无直接 system/qimen 行为变更
|
||
- 更新的 API 文档:
|
||
- 无
|
||
- 返回结构变化: 无
|
||
- 盘点结论:
|
||
- 模型方法总数: 102
|
||
- 第一批应迁移(P1)聚焦: EntryOrder / EntryItems / Storage / RolePermission / Store
|
||
- 第一批无调用可清理(P2)已形成清单,待阶段 5.2 执行删除前复核
|
||
- 验证方式:
|
||
- 静态扫描 model 方法清单与引用关系(仅文档盘点,无业务代码改动)
|
||
|
||
### 2026-03-23 模型能力治理执行(第十六批:阶段 5.2 第一批无调用方法清理)
|
||
|
||
- 修改范围: 清理 model 层第一批无调用静态方法(低风险)
|
||
- 涉及 model:
|
||
- app/model/api_app.js
|
||
- app/model/interface_type.js
|
||
- app/model/print_item.js
|
||
- 上游入口:
|
||
- 无直接 system/qimen 行为变更
|
||
- 更新的 API 文档:
|
||
- 无
|
||
- 返回结构变化: 无
|
||
- 兼容处理:
|
||
- 清理前执行全局引用复核,确认仅在定义处出现
|
||
- 仅删除静态 helper,不触碰关联定义与实例方法
|
||
- 删除项:
|
||
- ApiApp.findByAppKey / ApiApp.findByQimenConfig
|
||
- InterfaceType.findByCode / InterfaceType.findEnabled
|
||
- PrintItem.getGroupFields / PrintItem.getTableConfigs
|
||
- 验证方式:
|
||
- node .\script\method-output-regression.cjs compare
|
||
- node .\script\tmp-generate-method-regression-test.cjs
|
||
- npx egg-bin test temp/generated-tests/system.method-output.generated.test.js test/app/controller/system.user.login.test.js test/app/controller/system.user.info.test.js test/app/controller/home.test.js
|
||
- 回归结果:
|
||
- compare: total=8, mismatch=0
|
||
- tests: 14 passing
|
||
|
||
### 2026-03-23 模型能力治理执行(第十七批:阶段 5.2 第二批无调用方法清理)
|
||
|
||
- 修改范围: 清理 model 层第二批无调用静态方法(低风险)
|
||
- 涉及 model:
|
||
- app/model/i18n_translation.js
|
||
- app/model/stock_store.js
|
||
- 上游入口:
|
||
- 无直接 system/qimen 行为变更
|
||
- 更新的 API 文档:
|
||
- 无
|
||
- 返回结构变化: 无
|
||
- 兼容处理:
|
||
- 清理前已完成删除前引用复核(service/controller/test/script 全仓扫描)
|
||
- 仅删除静态 helper,不触碰关联定义、字段定义与实例方法
|
||
- 删除项:
|
||
- I18nTranslation.getTranslation / I18nTranslation.batchGetTranslations / I18nTranslation.getProjectTranslations / I18nTranslation.upsertTranslation / I18nTranslation.getUntranslated
|
||
- StockStore.findByItemCode / StockStore.findByStore
|
||
- 验证方式:
|
||
- node .\script\method-output-regression.cjs compare
|
||
- node .\script\tmp-generate-method-regression-test.cjs
|
||
- npx egg-bin test temp/generated-tests/system.method-output.generated.test.js
|
||
- npx egg-bin test test/app/controller/system.user.login.test.js test/app/controller/system.user.info.test.js test/app/controller/home.test.js
|
||
- 回归结果:
|
||
- compare: total=8, mismatch=0
|
||
- generated regression: 8 passing
|
||
- smoke: 6 passing
|
||
- tests: 14 passing
|
||
- 回归结果:
|
||
- compare: total=8, mismatch=0
|
||
- generated regression: 8 passing
|
||
- smoke: 6 passing
|
||
- tests: 14 passing
|
||
|
||
### 2026-03-23 模型能力治理执行(第十八批:阶段 5.2 P1 第一组迁移)
|
||
|
||
- 修改范围: 将 EntryOrder / EntryItems 的内部静态方法迁移到 service,收敛 model 职责
|
||
- 涉及 service/model:
|
||
- app/service/systems/entry_order.js
|
||
- app/model/entry_order.js
|
||
- app/model/entry_items.js
|
||
- 上游入口:
|
||
- 无直接新增 system/qimen method;属于内部服务能力收敛
|
||
- 更新的 API 文档:
|
||
- 无(对外接口参数与返回结构未变化)
|
||
- 返回结构变化: 无
|
||
- 兼容处理:
|
||
- 迁移 `EntryOrder.findByOrderCode/findByStatus/getStatsByWarehouse/updateSyncStatus/updateOrderStatus/calculateReceivedQuantities`
|
||
- 迁移 `EntryItems.batchUpdateReceived/getOrderProgress`
|
||
- `calculateReceivedQuantities` 改为 service 侧显式聚合 `wms_storage`,避免 model 版相关子查询别名不稳定
|
||
- 验证方式:
|
||
- node .\script\method-output-regression.cjs compare
|
||
- node .\script\tmp-generate-method-regression-test.cjs
|
||
- npx egg-bin test temp/generated-tests/system.method-output.generated.test.js
|
||
- npx egg-bin test test/app/controller/system.user.login.test.js test/app/controller/system.user.info.test.js test/app/controller/home.test.js
|
||
|
||
### 2026-03-23 模型能力治理执行(第十九批:阶段 5.2 P1 第二组迁移)
|
||
|
||
- 修改范围: 将 Storage 的内部静态方法迁移到 service,收敛 model 职责
|
||
- 涉及 service/model:
|
||
- app/service/systems/storage/index.js
|
||
- app/model/storage.js
|
||
- 上游入口:
|
||
- 无直接新增 system/qimen method;属于内部服务能力收敛
|
||
- 更新的 API 文档:
|
||
- 无(对外接口参数与返回结构未变化)
|
||
- 返回结构变化: 无
|
||
- 兼容处理:
|
||
- 迁移 `Storage.findByStockAndBatch/findBySpace/findAvailableByWarehouse/findExpiringSoon/updateQuantity/lockQuantity/unlockQuantity/allocateQuantity/getStockSummary/getSpaceUsage`
|
||
- 模型层仅保留实例行为与关联定义,跨记录聚合与更新能力归并到 service
|
||
- 验证方式:
|
||
- node .\script\method-output-regression.cjs compare
|
||
- node .\script\tmp-generate-method-regression-test.cjs
|
||
- npx egg-bin test temp/generated-tests/system.method-output.generated.test.js
|
||
- npx egg-bin test test/app/controller/system.user.login.test.js test/app/controller/system.user.info.test.js test/app/controller/home.test.js |