WMS_MAIN/AI_TOOLBOX.md

4.9 KiB
Raw Blame History

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 -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"

2.3 参数说明

  • -Query:必填,SQL 语句
  • -DbClient:可选,MySQL 客户端名,默认 wms
  • -ConfigPath:可选,配置文件路径,默认 .\config\config.local.js(相对于项目根目录)
  • -AsTable:可选,按表格输出结果

2.4 返回结果说明

默认输出 JSON,结构如下:

{
  "client": "wms",
  "rowCount": 1,
  "rows": [
    {
      "ok": 1
    }
  ]
}

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. 常见问题

  • 报错 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
  1. 若 system 入参有变化,执行参数结构化脚本刷新:
node .\script\tmp-struct-system-params.cjs
  1. 人工补充自动脚本无法推断的信息:
  • description
  • response
  • errors
  • 特殊枚举值与业务约束
  1. 提交前自检:
  • method 名称与代码一致
  • params 的 name/type/required/source 完整
  • 公共头部声明与实际鉴权逻辑一致

执行规则:接口代码与 methods/*.json 不一致时,以“必须补齐文档”为完成标准。