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

341 lines
12 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 协助开发/调试时可直接使用的方法,减少重复沟通成本。
## 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` 完整
- 公共头部声明与实际鉴权逻辑一致
执行规则:接口代码与 `methods/*.json` 不一致时,以“必须补齐文档”为完成标准。
## 10. App 能力地图(优先定位)
能力入口文件:
- `app.js`
- `app/extend/application.js`
### 10.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')`
### 10.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`)
### 10.3 AI 调试优先顺序
- 遇到“方法不存在/映射异常”优先检查 `app/extend/application.js` 是否包含对应能力。
- 遇到“动态分表模型不可用”优先检查 `app.js` 的工厂初始化是否执行成功。
- 遇到“缓存读写异常”优先检查 Redis client `cache` 配置及 `setCacheAsync/getCacheAsync` 调用链。
### 10.4 AI 快速回复定义
- 回复0时默认拒绝
- 回复1时默认接收
## 11. 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. 若仍为空,检查账号角色授权与当前激活角色是否存在