WMS_MAIN/AI_TOOLBOX.md

22 KiB
Raw Blame History

AI 工具箱(WMS)

本文件用于统一 AI 协助开发/调试时可直接使用的方法,减少重复沟通成本。AI每次应答文尾加喵~以判断是否丢失上下文

1. 适用范围

  • 项目根目录:D:\wms
  • 主要用途:本地调试、数据库取数、问题定位
  • 默认环境:PowerShell + Node.js

2. 数据库调试脚本

临时文件规则(强制):

  • 所有临时产物统一生成到 temp/ 目录。
  • temp/ 目录不提交到 git。

项目已提供数据库查询脚本:script/db-query.ps1

脚本能力:

  • 自动读取 config/config.local.js 中的 config.mysql.clients.<clientName> 配置
  • 支持通过 -DbClient 显式切换 mysql client(如 wms、ye4s),默认 wms
  • 执行传入 SQL 并返回 JSON
  • 可选表格输出,便于命令行快速查看

2.1 基本用法

powershell -ExecutionPolicy Bypass -File .\script\db-query.ps1 -Query "SELECT 1 AS ok"

2.2 常用示例

# 查询最近 10 条账号
powershell -ExecutionPolicy Bypass -File .\script\db-query.ps1 -Query "SELECT * FROM account ORDER BY id DESC LIMIT 10"

# 表格输出
powershell -ExecutionPolicy Bypass -File .\script\db-query.ps1 -Query "SELECT id, name FROM store LIMIT 20" -AsTable

# 指定 mysql client(默认是 wms)
powershell -ExecutionPolicy Bypass -File .\script\db-query.ps1 -DbClient wms -Query "SHOW TABLES"

# 切换到 ye4s client
powershell -ExecutionPolicy Bypass -File .\script\db-query.ps1 -DbClient ye4s -Query "SHOW TABLES"

# 快速确认当前连接到哪个库/账号
powershell -ExecutionPolicy Bypass -File .\script\db-query.ps1 -Query "SELECT DATABASE() AS db, USER() AS loginUser"
powershell -ExecutionPolicy Bypass -File .\script\db-query.ps1 -DbClient ye4s -Query "SELECT DATABASE() AS db, USER() AS loginUser"

2.3 参数说明

  • -Query:必填,SQL 语句
  • -DbClient:可选,MySQL 客户端名(例如 wms、ye4s),默认 wms
  • -ConfigPath:可选,配置文件路径,默认 .\config\config.local.js(相对于项目根目录)
  • -AsTable:可选,按表格输出结果

2.4 返回结果说明

默认输出 JSON,结构如下:

{
  "client": "wms",
  "rowCount": 1,
  "rows": [
    {
      "ok": 1
    }
  ]
}

2.5 区分 wms 与 ye4s(快速自检)

  • 步骤 1:不传 -DbClient 执行一次 SELECT DATABASE() AS db, USER() AS loginUser
  • 步骤 2:传 -DbClient ye4s 再执行同一条 SQL
  • 期望结果:
    • 默认执行返回 client = wms 且 db = wms
    • 指定 ye4s 返回 client = ye4s 且 db = ye4s

说明:脚本会从 config.mysql.clients.<clientName> 读取连接参数,返回体中的 client 字段可直接用于确认当前路由。

3. AI 协助时建议使用的提问模板

3.1 只读查询(推荐)

请在项目根目录执行 script/db-query.ps1,查询 SQL:
SELECT * FROM account LIMIT 20;
并把结果按表格给我,同时解释关键字段含义。

3.2 先分析再查询

请先阅读 app/model 下与 store 相关的模型,再使用 script/db-query.ps1 查询最近 50 条门店数据,
最后输出:1) 字段映射说明 2) 异常数据判断规则 3) 建议补充索引。

3.3 联合排障

请帮我排查某接口返回为空:
1) 找到对应 controller 和 service
2) 给出需要执行的 SQL
3) 使用 script/db-query.ps1 验证每一步
4) 输出最终根因和修复建议

4. Redis 缓存调试脚本

项目已提供 Redis 调试脚本:script/redis-cache.ps1

脚本能力:

  • 自动读取 config/config.local.js(可切换 -ConfigPath)中的 config.redis.clients.<clientName> 配置连接 Redis
  • 支持缓存读取与修改:get/set/del/exists/ttl/expire/keys/hget/hset/hdel/hgetall/incr/decr
  • 可选表格输出(-AsTable)

4.1 基本用法

powershell -ExecutionPolicy Bypass -File .\script\redis-cache.ps1 -Action get -RedisClient cache -Key "system"

4.2 常用示例

# 列出 key(使用 SCAN,不直接 KEYS 阻塞)
powershell -ExecutionPolicy Bypass -File .\script\redis-cache.ps1 -Action keys -RedisClient cache -Pattern "user:*" -AsTable

# 读取/写入字符串缓存
powershell -ExecutionPolicy Bypass -File .\script\redis-cache.ps1 -Action get -RedisClient cache -Key "system"
powershell -ExecutionPolicy Bypass -File .\script\redis-cache.ps1 -Action set -RedisClient cache -Key "system" -Value "{\"ok\":1}" -ExpireSeconds 600

# 删除缓存
powershell -ExecutionPolicy Bypass -File .\script\redis-cache.ps1 -Action del -RedisClient cache -Key "system"

# Hash 结构读写
powershell -ExecutionPolicy Bypass -File .\script\redis-cache.ps1 -Action hgetall -RedisClient cache -Key "session:123" -AsTable
powershell -ExecutionPolicy Bypass -File .\script\redis-cache.ps1 -Action hset -RedisClient cache -Key "session:123" -Field "status" -Value "active"

# 自增/自减计数器
powershell -ExecutionPolicy Bypass -File .\script\redis-cache.ps1 -Action incr -RedisClient cache -Key "counter:order"
powershell -ExecutionPolicy Bypass -File .\script\redis-cache.ps1 -Action decr -RedisClient cache -Key "counter:order" -Value 2

4.3 参数说明

  • -Action:必填,操作类型(get/set/del/exists/ttl/expire/keys/hget/hset/hdel/hgetall/incr/decr)
  • -RedisClient:可选,Redis 客户端名,默认 cache
  • -Key:按操作需要传入
  • -Value:set/hset/incr/decr 等操作使用
  • -Field:hget/hset/hdel 必填
  • -ExpireSeconds:set(可选)和 expire(必填)
  • -Pattern:keys 操作匹配模式,默认 *
  • -ConfigPath:可选,默认 .\config\config.local.js
  • -AsTable:可选,表格输出

4.4 AI 调用模板(缓存读改)

请在项目根目录执行 script/redis-cache.ps1:
1) 用 Action=keys, Pattern="user:*" 列出目标缓存键
2) 读取 key=xxx 的当前值(Action=get)
3) 按我提供的新值执行 Action=set 并设置过期时间 600 秒
4) 回读一次确认变更生效,并输出变更前后对比

5. 常见问题

  • 报错 Cannot find module 'mysql2/promise'

    • 先执行 npm install,确认依赖完整
  • 报错 Cannot find module 'ioredis'

    • 先执行 npm install,确认依赖完整
  • 报错 MySQL client "xxx" not found in config.mysql.clients

    • 检查 config/config.local.js 中 config.mysql.clients 是否包含对应 client
  • SQL 语法报错且定位到 current_user

    • 避免使用 current_user 作为别名,建议改成 loginUser 等非保留字名称
  • 报错 Redis client "xxx" not found in config.redis.clients

    • 检查 config/config.local.js 中 config.redis.clients 是否包含对应 client
  • 报错连接失败(超时/拒绝访问)

    • 检查数据库 IP、端口、用户名密码、网络白名单
  • 报错 Redis 连接失败(超时/认证失败)

    • 检查 Redis host/port/password/db 与网络连通性
  • PowerShell 执行策略限制

    • 使用命令中的 -ExecutionPolicy Bypass(仅本次命令生效)

6. 安全约束

  • 默认只执行 SELECT/SHOW 等只读 SQL
  • 执行 UPDATE/DELETE 前必须先让 AI 生成影响范围确认 SQL(COUNT + WHERE 条件)
  • 涉及生产数据时,优先在测试环境验证
  • Redis 写操作(set/del/hset/hdel/incr/decr/expire)前,先执行一次读取并确认影响 key 范围

7. 接口入口与 Method 指向

  • 入口风格:

    • /qimen:奇门开发接口(POST)
    • /system:Web 端与 PDA 端统一接口(POST)
  • 外部请求示例:

    • http://127.0.0.1:6060/system?method=print.getComputerPrinter&v=1.0&timestamp=1773386721
  • Method 指向说明文档:

    • 见 AI_METHOD_ROUTING.md
    • 文档记录了 method 到 app/service/systemMethods、app/service/qimenMethods 的映射规则与示例。

8. methods 目录地图

目录:methods/

  • methods/system.json

    • 作用:维护 /system(及 system 风格 method)的接口说明。
    • 覆盖内容:公共请求头、method 分组、params、response、errors。
  • methods/qimen.json

    • 作用:维护 /qimen 接口说明。
    • 覆盖内容:奇门 method、请求格式、响应格式、错误码。

建议将 methods/*.json 视为“接口文档单一事实来源(SSOT)”。

9. 接口变更联动工作流(强制)

当出现以下任一变更时,必须同步更新 methods 目录下对应 JSON:

  1. 新增接口(新增 method)
  2. 修改接口入参(新增/删除/重命名/必填变化)
  3. 修改公共请求头(如 platform、project、Authorization)
  4. 修改响应结构或错误码

执行步骤:

  1. 先改代码(controller/service/model)
  2. 更新对应文档文件:
  • system 入口改 methods/system.json
  • qimen 入口改 methods/qimen.json
  1. 若 system 入参有变化,执行参数结构化脚本刷新:
node .\script\tmp-struct-system-params.cjs
  1. 人工补充自动脚本无法推断的信息:
  • description
  • response
  • errors
  • 特殊枚举值与业务约束
  1. 提交前自检:
  • method 名称与代码一致
  • params 的 name/type/required/source 完整
  • 公共头部声明与实际鉴权逻辑一致

10. 远程发布与回退工具

发布配置文件:

  • 模板:config/deploy.config.example.cjs
  • 本地真实配置:config/deploy.config.local.cjs

说明:

  • 生产目录固定为 /www/wwwroot/qimen
  • config/deploy.config.local.cjs 已加入 git ignore,避免 SSH 配置误提交
  • 发布前会自动备份远端当前目录到 /www/wwwroot/qimen/.deploy/backups/
  • 回退默认使用最近一次发布前备份
  • 发布包按 Egg.js 最小运行集自动裁剪(默认 app.js、app/**、methods/**、native/addons/**、package*.json)
  • 发布与回退均保留远端 config/,不做覆盖
  • 发布与回退的停服务逻辑仅匹配当前 deployRoot 对应的 Egg 进程,不再用全局 egg-scripts stop 扫整机

10.1 固定命令入口(仅 npm script)

执行要求:

  • 远程发布与回退只允许通过 npm run 执行。
  • 禁止直接运行 node ./script/deploy-remote.cjs ... 与 node ./script/rollback-remote.cjs ...。
  • npm stop 已改为仅停止当前目录对应的 Egg 进程,不再直接调用全局 egg-scripts stop。

标准格式:

# 启用仓库级 pre-commit 保护
npm run setup:hooks

# 只读预检(不改远端文件)
npm run deploy:precheck

# 查询当前线上版本号
npm run deploy:version

# 查询最近 20 次线上版本历史
npm run deploy:version:history

# 查看远端 state 与备份清单
npm run deploy:inspect

# 对关键路由做最小连通冒烟
npm run deploy:smoke

# 组合执行 inspect + smoke
npm run deploy:verify

# 按文件名清理远端失败备份
npm run deploy:cleanup-backups -- backup-20260324202526.tar.gz backup-20260324204750.tar.gz

# 调用 internal gateway 做 method 连通探针
npm run deploy:gateway-probe -- releaseProbe.ping "{}"

# 手动记录一次本地包版本快照
npm run version:record

# 查询本地版本历史
npm run version:history

# 检查暂存区是否包含禁止提交文件
npm run guard:git

# 发布生产环境
npm run deploy:prod

# 发布生产环境(短命令别名)
npm run deploy

# 回退到最近一次备份
npm run rollback:prod

# 回退到最近一次备份(短命令别名)
npm run rollback

# 指定备份包回退
npm run rollback:prod -- --backup=backup-20260324123045.tar.gz

10.2 SSH 配置字段

  • host:生产服务器 IP 或域名
  • port:SSH 端口,默认 22
  • username:SSH 登录用户
  • privateKeyPath:本机私钥路径
  • deployRoot:固定为 /www/wwwroot/qimen
  • sharedDirs:发布时保留目录,默认 logs/run/temp
  • postDeployCommands:发布后执行命令;发布链路会强制确保包含 npm install --production,并自动剥离其中的通用 stop 命令,改为按当前部署目录定点停进程

最小发布相关可选字段:

  • deployIncludePaths:最小发布白名单路径(不填则使用默认最小集)
  • deployExcludePaths:发布排除路径(默认包含 config/**)
  • preserveDirs:远端覆盖时额外保留目录(默认包含 config)

10.5 线上版本号规则与查询

  • 版本号自动生成时机:每次执行 npm run deploy:prod。
  • 版本号格式:v{package.version}-{yyyyMMddHHmmss}-{gitShortCommit}。
  • 远端保存位置:
    • 当前版本:/www/wwwroot/qimen/.deploy/state/current-release.json
    • 历史版本:/www/wwwroot/qimen/.deploy/state/release-history.jsonl
  • 查询命令(固定 npm script):
    • 当前版本:npm run deploy:version
    • 历史版本:npm run deploy:version:history

10.6 本地版本管理目录(回退辅助)

  • 目录:versioning/
  • 记录目标:每次更新的包版本号、提交号、分支、时间。
  • 自动记录:每次 npm run deploy:prod 成功后自动写入本地记录。
  • 手动记录:npm run version:record
  • 本地历史查询:npm run version:history
  • 文件:
    • versioning/package-version-current.json
    • versioning/package-version-history.jsonl
  • git 规则:versioning/ 的记录文件默认不提交,仅保留目录占位。

10.3 安全约束

  • pre-commit 会阻止以下内容进入 git:
    • config/config.local.js
    • config/deploy.config.local.cjs
    • database/config.json
    • temp/、logs/、run/
    • .env*、.pem、.key
  • 真实 SSH 信息只写入本地配置文件,不写入 README、脚本或示例文件
  • 在补齐 SSH 配置前,不执行发布/回退测试

10.4 AI 安全红线(强制)

  • 明文规则:AI 禁止读取 SSH 本地配置文件 config/deploy.config.local.cjs。
  • AI 禁止通过任何方式展示、提取、复述该文件中的 host、username、privateKeyPath 等敏感内容。
  • AI 禁止把 SSH 配置写入文档、日志、日报、提交信息或任意可提交文件。
  • 如需发布/回退协助,AI 仅可提示用户“自行填写或核对该文件”,不可主动读取文件内容。

执行规则:接口代码与 methods/*.json 不一致时,以“必须补齐文档”为完成标准。

11. App 能力地图(优先定位)

能力入口文件:

  • app.js
  • app/extend/application.js

11.1 启动与初始化能力(app.js)

  • 设置应用根路径:global.APP_ROOT、app.appRoot
  • 启动前初始化动态工厂:
    • OrderDeliveryFactory
    • OrderItemsFactory
  • 启动时能力自检:
    • app.setCacheAsync / app.getCacheAsync
    • app.Message
  • 全局日期格式化扩展:Date.prototype.format('YYYY-MM-DD HH:mm:ss')

11.2 Application 扩展能力(app/extend/application.js)

  • 业务字典访问:
    • businessDict
    • getBusinessTypeName(code)
    • getOperationCodeName(code)
    • getPlatformName(code)
    • getExternalLogTypeName(type)
  • 外部 SOAP 调用:
    • wsdl(methodName, args)
  • Redis 缓存(cache client):
    • setCacheAsync(cacheKey, data, expireSeconds = 300)
    • getCacheAsync(cacheKey)
  • Message 扩展:
    • Message getter(返回 MessageClass)

11.3 AI 调试优先顺序

  • 遇到“方法不存在/映射异常”优先检查 app/extend/application.js 是否包含对应能力。
  • 遇到“动态分表模型不可用”优先检查 app.js 的工厂初始化是否执行成功。
  • 遇到“缓存读写异常”优先检查 Redis client cache 配置及 setCacheAsync/getCacheAsync 调用链。

11.4 AI 快速回复定义

  • 回复0时默认拒绝
  • 回复1时默认接收

12. Web 用户信息与切换角色测试(已验证)

目标:

  • 使用 /system 入口验证 Web 端用户信息获取与角色切换链路。
  • 固定请求头:platform=web、project=all。
  • 将接口返回暂存到 test/.runtime/ 便于回放与比对。

测试文件:

  • test/app/controller/system.user.info.web.test.js

    • 调用 user.info
    • 断言 status=200、flag=success、code=200
    • 断言返回 platform_code=web
    • 落盘:test/.runtime/system_user_info_web_all.json
  • test/app/controller/system.user.changeRole.test.js

    • 先调用 user.info 读取当前角色与可切换角色
    • 调用 user.changeRole(roleId 取可用候选角色)
    • 使用返回的新 token 再调 user.info 验证 employees_id 已切换
    • 落盘:test/.runtime/system_user_change_role_web_all.json
    • 末尾自动切回原角色,降低对其他测试影响

一键执行:

npx egg-bin test test/app/controller/system.user.info.web.test.js test/app/controller/system.user.changeRole.test.js

本地验证结果:

  • 2 passing

建议排查顺序(当返回菜单/权限为空时):

  1. 先查 user.info 返回中的 employees_id、store_id、platform_code
  2. 确认请求头是否为 platform=web、project=all
  3. 若仍为空,检查账号角色授权与当前激活角色是否存在

13. setting.account 接口说明(system)

适用入口:POST /system?method=setting.account.xxx

13.1 setting.account.list

用途:查询当前主体下工号列表(默认只返回启用工号)。

入参(body):

  • status(number,可选):状态筛选,默认 1
  • includeDisabled(boolean,可选):true 时包含停用工号

返回(data[] 关键字段):

  • employee_id:工号 ID
  • account_id:账号 ID
  • store_id:主体 ID
  • real_name:工号姓名
  • status:工号状态(1 启用 / 0 停用)
  • username / phone / email:账号基础信息
  • avatar_file_id / avatar_url:头像信息

13.2 setting.account.add

用途:新增工号;手机号存在则复用账号,不存在则创建账号并绑定工号。

入参(body):

  • phone(string,必填):11 位手机号
  • real_name(string,必填):工号姓名
  • role_id(number,可选):不传时继承当前操作人工号角色
  • username(string,可选):仅新建账号时生效
  • password(string,可选):仅新建账号时生效,默认 111111
  • email(string,可选):仅新建账号时生效

返回(data 关键字段):

  • employee_id / account_id / role_id
  • is_new_account:是否本次新建账号
  • phone / username

错误码:

  • 400:参数错误、手机号格式错误、保留名称限制
  • 409:账号禁用、重复绑定、用户名冲突

13.3 setting.account.delete

用途:停用工号绑定,不删除底层账号。

入参(body):

  • employee_id(number,必填)

返回(data):

  • employee_id / account_id
  • status:固定 deleted
  • already_deleted(可选):原本已是停用状态

13.4 setting.account.update

用途:更新工号姓名和/或头像引用。

入参(body):

  • employee_id(number,必填)
  • real_name(string,可选)
  • file_id(number,可选):头像文件 ID

约束:real_name 与 file_id 至少传一个。

返回(data):

  • 更新后的工号完整信息(同 list 列表项结构)

13.5 代码分层约定

  • 对外 method 包装层:app/service/systemMethods/setting/account.js
  • 业务实现层:app/service/systems/setting/account.js
  • 约定:非暴露辅助函数与业务逻辑统一下沉到 systems,systemMethods 只保留出口包装。

14. where 参数统一规范(强制)

适用范围:所有包含 where 筛选条件的 /system 接口。

14.1 标准结构

where 必须使用统一条件对象格式:

{
  "where": {
    "item_code": { "operator": "like", "value": "SKU" },
    "status": { "operator": "eq", "value": "created" },
    "quantity": { "operator": "ge", "type": "number", "value": "10" },
    "create_at": { "operator": "between", "type": "date", "value": ["2026-03-01", "2026-03-31"] },
    "quickWhere": { "operator": "like", "type": "text", "value": "关键字" }
  }
}

14.2 统一处理入口

  • where 统一在 app/service/main.js 中处理:prepareWhereContext(data, options)。
  • 处理后上下文约定:
    • ctx.where:标准化后的 where 条件对象(含 operator/value/type)
    • ctx.whereValue:仅提取 value 的兼容对象(给旧逻辑渐进兼容)
    • ctx.whereParsed:基于 app/lib/query_condition_parser.js 解析后的动态条件结构

14.3 实施规则

  • 所有 method 层(systemMethods)收到 where 后,必须先调用 prepareWhereContext。
  • 所有 systems 层查询逻辑优先读取 ctx.where / ctx.whereParsed,不得重复定义另一套 where 规则。
  • 历史简写结构(如 where: { status: 1 })允许输入,但会在 main 层自动标准化为条件对象。

14.4 回归覆盖建议

  • 至少验证:空 where、eq、like、in、between、quickWhere。
  • 对日志中高频接口优先回归:
    • print.getList
    • storage.entry.list
    • stock.warehouse.list

15. system API 权限映射规则(wms_permission)

适用范围:/system 入口,权限类型为 type=api。

15.1 映射规则

  • wms_permission.path 作为 system method 的权限标识(例如:setting.account.list)。
  • 同步来源以 methods/system.json 为准:isNeedAuth=true 的 method 必须存在对应 wms_permission(type=api,path=method)。
  • 角色权限不再以 wms_role_permission 作为主存储,统一写入 wms_role.permissions。
  • wms_role.permissions 支持两种值:
    • JSON 数组:如 [1,2,3]
    • "*":表示拥有所有权限
  • 新增 API 权限后,role_id=2 的授权应同步更新其 permissions 字段;若该字段为 "*" 则无需额外追加。

15.2 外部脚本(批量补齐)

固定命令:

# 预览差异(不写库)
npm run permission:sync:system-api -- --dry-run

# 执行补齐(写库)
npm run permission:sync:system-api

可选参数:

  • --role-id=2:绑定角色 ID(默认 2)
  • --db-client=wms:数据库客户端名(默认 wms)
  • --config-path=./config/config.local.js:配置文件路径
  • --method-doc=./methods/system.json:method 文档路径

15.3 运行时兜底(仅 debug)

  • 入口:app/service/main.js 的 checkApiPermission。
  • 逻辑:当用户权限列表不包含目标 method 时,若 app.config.debug === true,自动:
    1. 参考现有 type=api 权限行构建缺失权限行;
    2. 更新 wms_role(id=2).permissions,将新权限 ID 追加到 JSON 数组;若该字段为 "*" 则保持不变。
  • 生产建议:保持 app.config.debug=false,避免运行时自动写库。