# 提示词：工单 / 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。

## 字典投影

- EXACT_ONLY，禁止模糊。
- 空运包装缺省可投影 `packageType=1`（全部），并保留 raw。
- 失败要返回智能体能区分的 `source=TMS_DICTIONARY_PROJECTION` 与明确错误码，不要装成「无报价」。

## 不要

- 不要让 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 与迁移同一提交。