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

31 KiB
Raw Blame History

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