WMS_MAIN/AI_TOOLBOX.md

636 lines
22 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.

# 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
powershell -ExecutionPolicy Bypass -File .\script\db-query.ps1 -Query "SELECT 1 AS ok"
```
### 2.2 常用示例
```powershell
# 查询最近 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,结构如下:
```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 只读查询(推荐)
```text
请在项目根目录执行 script/db-query.ps1,查询 SQL:
SELECT * FROM account LIMIT 20;
并把结果按表格给我,同时解释关键字段含义。
```
### 3.2 先分析再查询
```text
请先阅读 app/model 下与 store 相关的模型,再使用 script/db-query.ps1 查询最近 50 条门店数据,
最后输出:1) 字段映射说明 2) 异常数据判断规则 3) 建议补充索引。
```
### 3.3 联合排障
```text
请帮我排查某接口返回为空:
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
powershell -ExecutionPolicy Bypass -File .\script\redis-cache.ps1 -Action get -RedisClient cache -Key "system"
```
### 4.2 常用示例
```powershell
# 列出 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 调用模板(缓存读改)
```text
请在项目根目录执行 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`
3. 若 system 入参有变化,执行参数结构化脚本刷新:
```powershell
node .\script\tmp-struct-system-params.cjs
```
4. 人工补充自动脚本无法推断的信息:
- `description`
- `response`
- `errors`
- 特殊枚举值与业务约束
5. 提交前自检:
- 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`。
标准格式:
```powershell
# 启用仓库级 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`
- 末尾自动切回原角色,降低对其他测试影响
一键执行:
```powershell
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` 必须使用统一条件对象格式:
```json
{
"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 外部脚本(批量补齐)
固定命令:
```powershell
# 预览差异(不写库)
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`,避免运行时自动写库。