170 lines
4.9 KiB
Markdown
170 lines
4.9 KiB
Markdown
# 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×tamp=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` 不一致时,以“必须补齐文档”为完成标准。
|
||
|
||
|
||
|