# AI 工具箱(WMS) 本文件用于统一 AI 协助开发/调试时可直接使用的方法,减少重复沟通成本。 ## 1. 适用范围 - 项目根目录:D:\\wms - 主要用途:本地调试、数据库取数、问题定位 - 默认环境:PowerShell + Node.js ## 2. 数据库调试脚本 临时文件规则(强制): - 所有临时产物统一生成到 `temp/` 目录。 - `temp/` 目录不提交到 git。 项目已提供数据库查询脚本:`script/db-query.ps1` 脚本能力: - 自动读取 `config/config.local.js` 中的 `config.mysql.clients.` 配置 - 支持通过 `-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.` 读取连接参数,返回体中的 `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.` 配置连接 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×tamp=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. 若仍为空,检查账号角色授权与当前激活角色是否存在