jillion886andCursor
99da1faf30
查到价后把币种、单位、数量、单价、备注写入报价单，避免销售只看到光秃秃的金额。 Co-authored-by: Cursor <cursoragent@cursor.com>
82 lines
5.5 KiB
Markdown
82 lines
5.5 KiB
Markdown
# 提示词：工单 / TMS 主账 API
|
||
|
||
你负责新系统的 **业务主账**。产品决策（2026-09-12）：主账以 **JeecgBoot + 低代码（Online / cgform / 代码生成器）** 为正式方式；库与端口走新系统（`inquiry_robot`、并存期 **8180**），禁止写现网 `jeecg-boot`。
|
||
|
||
决策说明见 `docs/2026-09-12-jeecg-lowcode-ledger-decision.md`。正式主账工程目录为 **`inquiry-api/`**（JeecgBoot）。
|
||
|
||
## 正式方式（已定 · 低代码）
|
||
|
||
- **主账工程 = JeecgBoot**（工程目录 `inquiry-api/`，保留手写 `jeecg-module-inquiry`）。
|
||
- **允许** Online / cgform / 积木报表 / 代码生成器配置询价相关表单、列表、简单 CRUD 与菜单。
|
||
- 登录、用户、角色、菜单走 Jeecg `/sys/*` + 低代码权限模型。
|
||
- 复杂领域（六态 transition、TMS 适配、报价版本采用/调价、智能体唤醒）可继续用手写 `jeecg-module-inquiry`（低代码 + 手写模块混合）；路径风格仍如 `/inquiry/workOrder/...`、`/inquiry/quotes/...`。
|
||
- 后台以 Jeecg Vue3 为正式入口（本仓库 `inquiry-backend/`）；`defHttp` + `X-Access-Token`；Nginx `/jeecgboot` → 新主账端口（`inquiry-api/`）。
|
||
|
||
## 模块划分
|
||
|
||
| 包 / 能力 | 职责 |
|
||
|---|---|
|
||
| Jeecg `/sys/*` + Online | 登录、菜单、字典、低代码表单/列表 |
|
||
| `jeecg-module-inquiry`（或等价） | 工单六态、报价版本、TMS、群门禁、智能体集成等复杂规则 |
|
||
| TMS 适配 | 密钥不出业务乱写；智能体不直连 TMS |
|
||
|
||
手写部分仍按领域拆分（工单 / 报价 / TMS / 人员 / 群 / 附件），不要一个上帝 Service。禁止把智能体 Graph 逻辑写进 Java。
|
||
|
||
类、公开方法、六态迁移、TMS 签名与投影：**详细中文 JavaDoc/块注释**。见 `05` 注释节。无注释不验收。
|
||
|
||
## 领域模型
|
||
|
||
- 工单：单号、销售企微身份、客户、业务线 SEA/AIR/LAND、陆运二级类型、六态、版本。
|
||
- 运输段 segment：多段预留但可关闭入口。
|
||
- 源报价（TMS 绑定）、客户报价、quoteVersion、费用行、附件元数据。
|
||
- 群绑定：chatId、角色、与工单/段/报价版本三门禁。
|
||
- 人员角色：wecom_id ↔ 销售/产品/运营。
|
||
- 时间线 / 异常单 / 重试状态。
|
||
- TMS 字典投影表：按 `tms-dictionary-projection-v2.json`。
|
||
|
||
## API 能力（与智能体、后台对齐）
|
||
|
||
- 工单：创建、校验、查询、聚合视图、六态 transition、异常 handle/retry。智能体每次出询价确认都新开一单，相同需求不复用未关闭工单。
|
||
- TMS：query、template-fields、detail、health、字典 sync。lock/release 接口可留，**与现网共用 TMS 密钥期间默认关闭出站**。
|
||
- 报价决策：采用、调价、成本/售价基线（空运与海陆规则不同，与合同语义对齐）。
|
||
- 模板、识别任务、生成任务的查询接口（任务执行可在智能体，主账存结果指针）。
|
||
- 智能体回调：唤醒 Graph 的事件要鉴权 `agentCallbackToken`，打到智能体**唯一 HTTP**（不要假设还存在 8809 `bridge_api`）。
|
||
- 人员：按入站已有的 `wecom_id` 查角色；**不负责**替智能体向企微换 userid。
|
||
|
||
## TMS 适配器（本端独占密钥）
|
||
|
||
主账 HTTP **不许卡死线程池**：TMS / DB 必须有超时；接口用容器线程池处理并发请求。禁止全局锁串行所有工单。智能体唤醒回调失败要可重试，不要在 Tomcat 线程里同步等 Python Graph 跑完。
|
||
|
||
实现现网 TMS 网关语义：
|
||
|
||
- Token：`POST {base}{tokenPath}`，Basic(clientId:clientSecret)，body `grantType=client_credentials`，业务码 1，缓存 accessToken。
|
||
- 查询类：Bearer。
|
||
- 锁舱/释放：`X-Signature` HMAC，canonical `timestamp + "\n" + nonce + "\n" + rawBody`。
|
||
- 审计日志脱敏：token/signature/password/secret 字段打码。
|
||
- 熔断、超时、最多 3 次、query 对 code 1/1002 短缓存。
|
||
- `tmsEnabled=false` 时不得出站。生产现网为 `YTD_TMS_V2_ENABLED=true`。
|
||
|
||
路径默认：`/quote/v2/query`、`/quote/v2/detail`、`/quote/template-fields`、`/air/cabin/lock`、`/air/cabin/release`、`/auth/token`。地址与 Client 三件套、字典 Token **直接用 `03` 现网值**，不要另要一套 TMS。智能体仍只打**新主账**，不直连 TMS、不打现网 Java 8080。
|
||
|
||
## 查价（不做字典对应）
|
||
|
||
- 询价必填齐了就出站查 TMS，本地不把「珠海」对成机场码、不因对不上而拒绝查价。
|
||
- 有价返回报价；TMS 无匹配或未出价格则「暂无报价」。
|
||
- 技术失败（超时/熔断/未配置）单独分类，禁止 fixture 假价。
|
||
|
||
## 不要
|
||
|
||
- 不要让 Python 写 MySQL 工单表。
|
||
- 不要在主账里做自然语言抽取。
|
||
- 不要把 Jeecg `signatureSecret` 默认值当生产密钥。
|
||
- 后台登录与智能体服务账号分离。
|
||
- 不要连接或 ALTER 现网 `jeecg-boot`；新系统只用 `inquiry_robot`。
|
||
- 不要在并存期占用现网 8080；新主账用 8180（或合同约定的测试端口）。
|
||
- 不要把无关 Jeecg 演示业务当询价主账；演示模块可删可关，Online 只配询价相关。
|
||
|
||
## 数据
|
||
|
||
MySQL 8、UTF8MB4、Asia/Shanghai。库名/用户/JDBC **全部环境变量**（`MYSQL_DB`、`MYSQL_USER`、`YTD_MYSQL_URL` 等），对照 `13`。新系统连 `inquiry_robot`，禁止连现网 `jeecg-boot`。禁止在 yml 写死库名。Redis 前缀、MinIO 桶同样走环境变量。
|
||
|
||
开发期间缺表、缺列、要改列：**直接写迁移并执行到当前 `MYSQL_DB`（新系统即 `inquiry_robot`）**，不要等批准。禁止动现网 `jeecg-boot`。实体/Mapper/API 与迁移同一提交。
|