636 lines
22 KiB
Markdown
636 lines
22 KiB
Markdown
# AI 工具箱(WMS)
|
||
|
||
本文件用于统一 AI 协助开发/调试时可直接使用的方法,减少重复沟通成本。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×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` 完整
|
||
- 公共头部声明与实际鉴权逻辑一致
|
||
|
||
## 10. 远程发布与回退工具
|
||
|
||
发布配置文件:
|
||
|
||
- 模板:`config/deploy.config.example.cjs`
|
||
- 本地真实配置:`config/deploy.config.local.cjs`
|
||
|
||
说明:
|
||
|
||
- 生产目录固定为 `/www/wwwroot/qimen`
|
||
- `config/deploy.config.local.cjs` 已加入 git ignore,避免 SSH 配置误提交
|
||
- 发布前会自动备份远端当前目录到 `/www/wwwroot/qimen/.deploy/backups/`
|
||
- 回退默认使用最近一次发布前备份
|
||
- 发布包按 Egg.js 最小运行集自动裁剪(默认 `app.js`、`app/**`、`methods/**`、`native/addons/**`、`package*.json`)
|
||
- 发布与回退均保留远端 `config/`,不做覆盖
|
||
- 发布与回退的停服务逻辑仅匹配当前 `deployRoot` 对应的 Egg 进程,不再用全局 `egg-scripts stop` 扫整机
|
||
|
||
### 10.1 固定命令入口(仅 npm script)
|
||
|
||
执行要求:
|
||
|
||
- 远程发布与回退只允许通过 `npm run` 执行。
|
||
- 禁止直接运行 `node ./script/deploy-remote.cjs ...` 与 `node ./script/rollback-remote.cjs ...`。
|
||
- `npm stop` 已改为仅停止当前目录对应的 Egg 进程,不再直接调用全局 `egg-scripts stop`。
|
||
|
||
标准格式:
|
||
|
||
```powershell
|
||
# 启用仓库级 pre-commit 保护
|
||
npm run setup:hooks
|
||
|
||
# 只读预检(不改远端文件)
|
||
npm run deploy:precheck
|
||
|
||
# 查询当前线上版本号
|
||
npm run deploy:version
|
||
|
||
# 查询最近 20 次线上版本历史
|
||
npm run deploy:version:history
|
||
|
||
# 查看远端 state 与备份清单
|
||
npm run deploy:inspect
|
||
|
||
# 对关键路由做最小连通冒烟
|
||
npm run deploy:smoke
|
||
|
||
# 组合执行 inspect + smoke
|
||
npm run deploy:verify
|
||
|
||
# 按文件名清理远端失败备份
|
||
npm run deploy:cleanup-backups -- backup-20260324202526.tar.gz backup-20260324204750.tar.gz
|
||
|
||
# 调用 internal gateway 做 method 连通探针
|
||
npm run deploy:gateway-probe -- releaseProbe.ping "{}"
|
||
|
||
# 手动记录一次本地包版本快照
|
||
npm run version:record
|
||
|
||
# 查询本地版本历史
|
||
npm run version:history
|
||
|
||
# 检查暂存区是否包含禁止提交文件
|
||
npm run guard:git
|
||
|
||
# 发布生产环境
|
||
npm run deploy:prod
|
||
|
||
# 发布生产环境(短命令别名)
|
||
npm run deploy
|
||
|
||
# 回退到最近一次备份
|
||
npm run rollback:prod
|
||
|
||
# 回退到最近一次备份(短命令别名)
|
||
npm run rollback
|
||
|
||
# 指定备份包回退
|
||
npm run rollback:prod -- --backup=backup-20260324123045.tar.gz
|
||
```
|
||
|
||
### 10.2 SSH 配置字段
|
||
|
||
- `host`:生产服务器 IP 或域名
|
||
- `port`:SSH 端口,默认 `22`
|
||
- `username`:SSH 登录用户
|
||
- `privateKeyPath`:本机私钥路径
|
||
- `deployRoot`:固定为 `/www/wwwroot/qimen`
|
||
- `sharedDirs`:发布时保留目录,默认 `logs/run/temp`
|
||
- `postDeployCommands`:发布后执行命令;发布链路会强制确保包含 `npm install --production`,并自动剥离其中的通用 stop 命令,改为按当前部署目录定点停进程
|
||
|
||
最小发布相关可选字段:
|
||
|
||
- `deployIncludePaths`:最小发布白名单路径(不填则使用默认最小集)
|
||
- `deployExcludePaths`:发布排除路径(默认包含 `config/**`)
|
||
- `preserveDirs`:远端覆盖时额外保留目录(默认包含 `config`)
|
||
|
||
### 10.5 线上版本号规则与查询
|
||
|
||
- 版本号自动生成时机:每次执行 `npm run deploy:prod`。
|
||
- 版本号格式:`v{package.version}-{yyyyMMddHHmmss}-{gitShortCommit}`。
|
||
- 远端保存位置:
|
||
- 当前版本:`/www/wwwroot/qimen/.deploy/state/current-release.json`
|
||
- 历史版本:`/www/wwwroot/qimen/.deploy/state/release-history.jsonl`
|
||
- 查询命令(固定 npm script):
|
||
- 当前版本:`npm run deploy:version`
|
||
- 历史版本:`npm run deploy:version:history`
|
||
|
||
### 10.6 本地版本管理目录(回退辅助)
|
||
|
||
- 目录:`versioning/`
|
||
- 记录目标:每次更新的包版本号、提交号、分支、时间。
|
||
- 自动记录:每次 `npm run deploy:prod` 成功后自动写入本地记录。
|
||
- 手动记录:`npm run version:record`
|
||
- 本地历史查询:`npm run version:history`
|
||
- 文件:
|
||
- `versioning/package-version-current.json`
|
||
- `versioning/package-version-history.jsonl`
|
||
- git 规则:`versioning/` 的记录文件默认不提交,仅保留目录占位。
|
||
|
||
### 10.3 安全约束
|
||
|
||
- pre-commit 会阻止以下内容进入 git:
|
||
- `config/config.local.js`
|
||
- `config/deploy.config.local.cjs`
|
||
- `database/config.json`
|
||
- `temp/`、`logs/`、`run/`
|
||
- `.env*`、`.pem`、`.key`
|
||
- 真实 SSH 信息只写入本地配置文件,不写入 README、脚本或示例文件
|
||
- 在补齐 SSH 配置前,不执行发布/回退测试
|
||
|
||
### 10.4 AI 安全红线(强制)
|
||
|
||
- 明文规则:AI 禁止读取 SSH 本地配置文件 `config/deploy.config.local.cjs`。
|
||
- AI 禁止通过任何方式展示、提取、复述该文件中的 `host`、`username`、`privateKeyPath` 等敏感内容。
|
||
- AI 禁止把 SSH 配置写入文档、日志、日报、提交信息或任意可提交文件。
|
||
- 如需发布/回退协助,AI 仅可提示用户“自行填写或核对该文件”,不可主动读取文件内容。
|
||
|
||
执行规则:接口代码与 `methods/*.json` 不一致时,以“必须补齐文档”为完成标准。
|
||
|
||
## 11. App 能力地图(优先定位)
|
||
|
||
能力入口文件:
|
||
|
||
- `app.js`
|
||
- `app/extend/application.js`
|
||
|
||
### 11.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')`
|
||
|
||
### 11.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`)
|
||
|
||
### 11.3 AI 调试优先顺序
|
||
|
||
- 遇到“方法不存在/映射异常”优先检查 `app/extend/application.js` 是否包含对应能力。
|
||
- 遇到“动态分表模型不可用”优先检查 `app.js` 的工厂初始化是否执行成功。
|
||
- 遇到“缓存读写异常”优先检查 Redis client `cache` 配置及 `setCacheAsync/getCacheAsync` 调用链。
|
||
|
||
### 11.4 AI 快速回复定义
|
||
- 回复0时默认拒绝
|
||
- 回复1时默认接收
|
||
|
||
## 12. 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. 若仍为空,检查账号角色授权与当前激活角色是否存在
|
||
|
||
## 13. setting.account 接口说明(system)
|
||
|
||
适用入口:`POST /system?method=setting.account.xxx`
|
||
|
||
### 13.1 setting.account.list
|
||
|
||
用途:查询当前主体下工号列表(默认只返回启用工号)。
|
||
|
||
入参(body):
|
||
- `status`(number,可选):状态筛选,默认 `1`
|
||
- `includeDisabled`(boolean,可选):`true` 时包含停用工号
|
||
|
||
返回(`data[]` 关键字段):
|
||
- `employee_id`:工号 ID
|
||
- `account_id`:账号 ID
|
||
- `store_id`:主体 ID
|
||
- `real_name`:工号姓名
|
||
- `status`:工号状态(`1` 启用 / `0` 停用)
|
||
- `username` / `phone` / `email`:账号基础信息
|
||
- `avatar_file_id` / `avatar_url`:头像信息
|
||
|
||
### 13.2 setting.account.add
|
||
|
||
用途:新增工号;手机号存在则复用账号,不存在则创建账号并绑定工号。
|
||
|
||
入参(body):
|
||
- `phone`(string,必填):11 位手机号
|
||
- `real_name`(string,必填):工号姓名
|
||
- `role_id`(number,可选):不传时继承当前操作人工号角色
|
||
- `username`(string,可选):仅新建账号时生效
|
||
- `password`(string,可选):仅新建账号时生效,默认 `111111`
|
||
- `email`(string,可选):仅新建账号时生效
|
||
|
||
返回(`data` 关键字段):
|
||
- `employee_id` / `account_id` / `role_id`
|
||
- `is_new_account`:是否本次新建账号
|
||
- `phone` / `username`
|
||
|
||
错误码:
|
||
- `400`:参数错误、手机号格式错误、保留名称限制
|
||
- `409`:账号禁用、重复绑定、用户名冲突
|
||
|
||
### 13.3 setting.account.delete
|
||
|
||
用途:停用工号绑定,不删除底层账号。
|
||
|
||
入参(body):
|
||
- `employee_id`(number,必填)
|
||
|
||
返回(`data`):
|
||
- `employee_id` / `account_id`
|
||
- `status`:固定 `deleted`
|
||
- `already_deleted`(可选):原本已是停用状态
|
||
|
||
### 13.4 setting.account.update
|
||
|
||
用途:更新工号姓名和/或头像引用。
|
||
|
||
入参(body):
|
||
- `employee_id`(number,必填)
|
||
- `real_name`(string,可选)
|
||
- `file_id`(number,可选):头像文件 ID
|
||
|
||
约束:`real_name` 与 `file_id` 至少传一个。
|
||
|
||
返回(`data`):
|
||
- 更新后的工号完整信息(同 list 列表项结构)
|
||
|
||
### 13.5 代码分层约定
|
||
|
||
- 对外 method 包装层:`app/service/systemMethods/setting/account.js`
|
||
- 业务实现层:`app/service/systems/setting/account.js`
|
||
- 约定:非暴露辅助函数与业务逻辑统一下沉到 `systems`,`systemMethods` 只保留出口包装。
|
||
|
||
## 14. where 参数统一规范(强制)
|
||
|
||
适用范围:所有包含 `where` 筛选条件的 `/system` 接口。
|
||
|
||
### 14.1 标准结构
|
||
|
||
`where` 必须使用统一条件对象格式:
|
||
|
||
```json
|
||
{
|
||
"where": {
|
||
"item_code": { "operator": "like", "value": "SKU" },
|
||
"status": { "operator": "eq", "value": "created" },
|
||
"quantity": { "operator": "ge", "type": "number", "value": "10" },
|
||
"create_at": { "operator": "between", "type": "date", "value": ["2026-03-01", "2026-03-31"] },
|
||
"quickWhere": { "operator": "like", "type": "text", "value": "关键字" }
|
||
}
|
||
}
|
||
```
|
||
|
||
### 14.2 统一处理入口
|
||
|
||
- `where` 统一在 `app/service/main.js` 中处理:`prepareWhereContext(data, options)`。
|
||
- 处理后上下文约定:
|
||
- `ctx.where`:标准化后的 where 条件对象(含 `operator/value/type`)
|
||
- `ctx.whereValue`:仅提取 value 的兼容对象(给旧逻辑渐进兼容)
|
||
- `ctx.whereParsed`:基于 `app/lib/query_condition_parser.js` 解析后的动态条件结构
|
||
|
||
### 14.3 实施规则
|
||
|
||
- 所有 method 层(`systemMethods`)收到 `where` 后,必须先调用 `prepareWhereContext`。
|
||
- 所有 systems 层查询逻辑优先读取 `ctx.where` / `ctx.whereParsed`,不得重复定义另一套 where 规则。
|
||
- 历史简写结构(如 `where: { status: 1 }`)允许输入,但会在 main 层自动标准化为条件对象。
|
||
|
||
### 14.4 回归覆盖建议
|
||
|
||
- 至少验证:空 where、eq、like、in、between、quickWhere。
|
||
- 对日志中高频接口优先回归:
|
||
- `print.getList`
|
||
- `storage.entry.list`
|
||
- `stock.warehouse.list`
|
||
|
||
## 15. system API 权限映射规则(wms_permission)
|
||
|
||
适用范围:`/system` 入口,权限类型为 `type=api`。
|
||
|
||
### 15.1 映射规则
|
||
|
||
- `wms_permission.path` 作为 system method 的权限标识(例如:`setting.account.list`)。
|
||
- 同步来源以 `methods/system.json` 为准:`isNeedAuth=true` 的 method 必须存在对应 `wms_permission(type=api,path=method)`。
|
||
- 角色权限不再以 `wms_role_permission` 作为主存储,统一写入 `wms_role.permissions`。
|
||
- `wms_role.permissions` 支持两种值:
|
||
- JSON 数组:如 `[1,2,3]`
|
||
- `"*"`:表示拥有所有权限
|
||
- 新增 API 权限后,`role_id=2` 的授权应同步更新其 `permissions` 字段;若该字段为 `"*"` 则无需额外追加。
|
||
|
||
### 15.2 外部脚本(批量补齐)
|
||
|
||
固定命令:
|
||
|
||
```powershell
|
||
# 预览差异(不写库)
|
||
npm run permission:sync:system-api -- --dry-run
|
||
|
||
# 执行补齐(写库)
|
||
npm run permission:sync:system-api
|
||
```
|
||
|
||
可选参数:
|
||
|
||
- `--role-id=2`:绑定角色 ID(默认 `2`)
|
||
- `--db-client=wms`:数据库客户端名(默认 `wms`)
|
||
- `--config-path=./config/config.local.js`:配置文件路径
|
||
- `--method-doc=./methods/system.json`:method 文档路径
|
||
|
||
### 15.3 运行时兜底(仅 debug)
|
||
|
||
- 入口:`app/service/main.js` 的 `checkApiPermission`。
|
||
- 逻辑:当用户权限列表不包含目标 method 时,若 `app.config.debug === true`,自动:
|
||
1. 参考现有 `type=api` 权限行构建缺失权限行;
|
||
2. 更新 `wms_role(id=2).permissions`,将新权限 ID 追加到 JSON 数组;若该字段为 `"*"` 则保持不变。
|
||
- 生产建议:保持 `app.config.debug=false`,避免运行时自动写库。
|
||
|
||
|