WMS_MAIN/AI_TOOLBOX.md

170 lines
4.9 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. 数据库调试脚本
项目已提供数据库查询脚本:`script/db-query.ps1`
脚本能力:
- 自动读取 `config/config.local.js` 中的 `config.mysql.clients.<clientName>` 配置
- 执行传入 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"
```
### 2.3 参数说明
- `-Query`:必填,SQL 语句
- `-DbClient`:可选,MySQL 客户端名,默认 `wms`
- `-ConfigPath`:可选,配置文件路径,默认 `.\config\config.local.js`(相对于项目根目录)
- `-AsTable`:可选,按表格输出结果
### 2.4 返回结果说明
默认输出 JSON,结构如下:
```json
{
"client": "wms",
"rowCount": 1,
"rows": [
{
"ok": 1
}
]
}
```
## 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. 常见问题
- 报错 `Cannot find module 'mysql2/promise'`
- 先执行 `npm install`,确认依赖完整
- 报错 `MySQL client "xxx" not found in config.mysql.clients`
- 检查 `config/config.local.js` 中 `config.mysql.clients` 是否包含对应 client
- 报错连接失败(超时/拒绝访问)
- 检查数据库 IP、端口、用户名密码、网络白名单
- PowerShell 执行策略限制
- 使用命令中的 `-ExecutionPolicy Bypass`(仅本次命令生效)
## 5. 安全约束
- 默认只执行 SELECT/SHOW 等只读 SQL
- 执行 UPDATE/DELETE 前必须先让 AI 生成影响范围确认 SQL(COUNT + WHERE 条件)
- 涉及生产数据时,优先在测试环境验证
## 6. 接口入口与 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` 的映射规则与示例。
## 7. methods 目录地图
目录:`methods/`
- `methods/system.json`
- 作用:维护 `/system`(及 system 风格 method)的接口说明。
- 覆盖内容:公共请求头、method 分组、params、response、errors。
- `methods/qimen.json`
- 作用:维护 `/qimen` 接口说明。
- 覆盖内容:奇门 method、请求格式、响应格式、错误码。
建议将 `methods/*.json` 视为“接口文档单一事实来源(SSOT)”。
## 8. 接口变更联动工作流(强制)
当出现以下任一变更时,必须同步更新 `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` 不一致时,以“必须补齐文档”为完成标准。