WMS_MAIN/SERVICE_API_CHANGE_AUDIT_20260322.md
2026-03-23 17:10:07 +08:00

719 lines
31 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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