34 KiB
34 KiB
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') StoreWarehouseinclude/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_stockinclude 在 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语义不变
- StoreWarehouse 新增
- 验证方式:
- 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使用)
- app/model/**/*.js(association
- 上游入口:
- 无直接 system/qimen 行为变更
- 更新的 API 文档:
- 无
- 返回结构变化: 无
- 扫描方法:
- 全量检索 model association 与 service include 的 alias 使用
- 执行自动差集比对(service alias - model alias)
- 扫描结果:
- model alias 总数: 48
- 差集可疑项: 0
- 结论: 未发现 include alias 不一致问题
- 验证方式:
- 通过一次性 Node 差集脚本执行
service alias - model alias自动比对(临时脚本未入库)
- 通过一次性 Node 差集脚本执行
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
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
- 验证方式:
- 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
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
- 验证方式:
- 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: 7 passing
- tests: 15 passing
2026-03-23 模型能力治理执行(第二十批:阶段 5.2 P1 第三组迁移)
- 修改范围: 将 Role / RolePermission 的权限编排方法迁移到 service,收敛 model 职责
- 涉及 service/model:
- app/service/systems/auth/role_permission.js
- app/model/role.js
- app/model/role_permission.js
- 上游入口:
- 无直接新增 system/qimen method;属于内部服务能力收敛
- 更新的 API 文档:
- 无(对外接口参数与返回结构未变化)
- 返回结构变化: 无
- 兼容处理:
- 迁移 Role.assignPermissions/getPermissionTree/getPermissionIds
- 迁移 RolePermission.bulkAssign/clearRolePermissions/getRolePermissions/hasPermission
- 验证方式:
- 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: 7 passing
- tests: 15 passing
2026-03-23 模型能力治理执行(第二十一批:阶段 5.2 P1 第四组迁移)
- 修改范围: 将 Store 的校验与查询助手方法迁移到 service,收敛 model 职责
- 涉及 service/model:
- app/service/systems/store.js
- app/model/store.js
- 上游入口:
- 无直接新增 system/qimen method;属于内部服务能力收敛
- 更新的 API 文档:
- 无(对外接口参数与返回结构未变化)
- 返回结构变化: 无
- 兼容处理:
- 迁移 Store.validateStoreData/checkCompanyNameExists/findByAccountId/findAllEnabled/findAllWarehouses
- 验证方式:
- 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: 7 passing
- tests: 15 passing
2026-03-23 系统接口兼容修复(第二十二批:project 请求头校验)
- 修改范围: 修复 system 请求上下文校验对历史 project=wms 请求头的误拒绝
- 涉及 service:
- app/service/system.js
- 变更内容:
ALLOWED_PROJECTS增加wms/scm/other,保持与历史调用兼容
- 触发原因:
- generated regression 与 smoke 在无业务代码变更时统一出现 400(
project 不支持: wms)
- generated regression 与 smoke 在无业务代码变更时统一出现 400(
- 验证方式:
- 直接调用
user.login(platform=web, project=wms)回归 - compare + generated regression + smoke 全量重跑
- 直接调用
- 回归结果:
- login: HTTP 200
- compare: total=8, mismatch=0
- generated regression: 8 passing
- smoke: 7 passing
- tests: 15 passing