17 KiB
AI 工具箱(WMS)
本文件用于统一 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×tamp=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:
- 新增接口(新增 method)
- 修改接口入参(新增/删除/重命名/必填变化)
- 修改公共请求头(如
platform、project、Authorization) - 修改响应结构或错误码
执行步骤:
- 先改代码(controller/service/model)
- 更新对应文档文件:
- system 入口改
methods/system.json - qimen 入口改
methods/qimen.json
- 若 system 入参有变化,执行参数结构化脚本刷新:
node .\script\tmp-struct-system-params.cjs
- 人工补充自动脚本无法推断的信息:
descriptionresponseerrors- 特殊枚举值与业务约束
- 提交前自检:
- 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 端口,默认22username:SSH 登录用户privateKeyPath:本机私钥路径deployRoot:固定为/www/wwwroot/qimensharedDirs:发布时保留目录,默认logs/run/temppostDeployCommands:发布后执行命令;发布链路会强制确保包含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.jsonversioning/package-version-history.jsonl
- git 规则:
versioning/的记录文件默认不提交,仅保留目录占位。
10.3 安全约束
- pre-commit 会阻止以下内容进入 git:
config/config.local.jsconfig/deploy.config.local.cjsdatabase/config.jsontemp/、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.jsapp/extend/application.js
11.1 启动与初始化能力(app.js)
- 设置应用根路径:
global.APP_ROOT、app.appRoot - 启动前初始化动态工厂:
OrderDeliveryFactoryOrderItemsFactory
- 启动时能力自检:
app.setCacheAsync/app.getCacheAsyncapp.Message
- 全局日期格式化扩展:
Date.prototype.format('YYYY-MM-DD HH:mm:ss')
11.2 Application 扩展能力(app/extend/application.js)
- 业务字典访问:
businessDictgetBusinessTypeName(code)getOperationCodeName(code)getPlatformName(code)getExternalLogTypeName(type)
- 外部 SOAP 调用:
wsdl(methodName, args)
- Redis 缓存(cache client):
setCacheAsync(cacheKey, data, expireSeconds = 300)getCacheAsync(cacheKey)
- Message 扩展:
Messagegetter(返回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
建议排查顺序(当返回菜单/权限为空时):
- 先查
user.info返回中的employees_id、store_id、platform_code - 确认请求头是否为
platform=web、project=all - 若仍为空,检查账号角色授权与当前激活角色是否存在