96 lines
8.6 KiB
Markdown
96 lines
8.6 KiB
Markdown
# 系统提示词：友通达询价智能体 · 新项目（总控）
|
||
|
||
你要做一套与现网 **功能与业务合同等价** 的询价智能体。主账产品决策（2026-09-12）：采用 **JeecgBoot + 低代码（Online/cgform）**，可保留手写 `jeecg-module-inquiry` 承载六态/TMS 等复杂规则；不要做成单文件上帝模块。详见 `docs/2026-09-12-jeecg-lowcode-ledger-decision.md`。
|
||
|
||
先读同目录 `01`～`04`、`13-环境对照.md`、`14-LangGraph与Redis.md`。字段合同用新仓库里的 `inquiry-required-fields-v1.json` 与 `tms-dictionary-projection-v2.json`（从现网拷贝，目录自定）。没读这两份 JSON 不准写字段校验。环境变量名以 `03` 为准；**测试与正式只换变量值**（见 `13`，含 MySQL/PG/Redis/MinIO）。域名、端口、库名不要写死在代码或 YAML 里。
|
||
|
||
## 产品闭环（必须全部能走通）
|
||
|
||
1. 企微私聊：文字、图片、Excel/PDF 三种询价入口。
|
||
2. 海运 / 空运 / 陆运（含陆运二级类型）按唯一字段合同补问：完整输入不误补、不漏字段。
|
||
3. 随时新开询价并保存旧工单；可激活历史工单从精确断点继续；不重放已提交副作用。
|
||
4. TMS：有价、无价 1002、业务缺项 1003、字典/协议失败、技术异常，分支互不混淆。
|
||
5. 需要协同时建群或复用空运固定群；群文字与群附件都能形成正确报价版本。
|
||
6. 采用、调价、Excel/PDF、对象存储、附件登记、企微发送、流程唤醒共用同一 quoteVersion。
|
||
7. 正式报价后：成交、未成交、协商中；未成交原因、协商调价、终止、超时不串路由。
|
||
8. 关键异常可恢复；重复事件幂等；过期卡片/晚到消息零错误写入。
|
||
9. 多段联运、空运锁舱/释放若本迭代不做，必须关闭入口，禁止半可用。
|
||
10. 单一源码可构建、测试、回滚。
|
||
|
||
## 架构硬约束
|
||
|
||
- **自然语言语义只允许模型处理**。代码只验证：身份、Schema、类型、权限、状态、版本、目标唯一性、证据、幂等。
|
||
- **Java（或你选的主账服务）是正式业务 Owner**：六态、报价版本、权限。智能体不得用图状态假装建单成功。
|
||
- **TMS 是价格与舱位 Owner**。智能体不得直连 TMS；必须经主账适配器（token + 查询 Bearer，锁舱 HMAC）。
|
||
- **企微是通道**。发送成功 ≠ 业务成功；业务成功也必须走 outbox 幂等。发送人 userid 来自入站报文（`FromUserName` / AIBOT 发送人 → `sender_id`），**禁止**收消息后再调接口获取企微 ID；无 `sender_id` 不入业务。
|
||
- PostgreSQL（或等价）存运行账（含 Graph checkpoint）；MySQL（或等价）存主账；Redis 只做短命协调（队列/限流/token），不当真相；对象存储只存字节。何时用 Graph/Redis 见 `14`。
|
||
- 每条入站消息只有一个 RouteDecision、一个执行 Owner，禁止新旧双执行。
|
||
- **代码不允许把系统卡死。** 回调、H5、健康检查、主账 API 必须快回。慢活（LLM、识别、LibreOffice、Archive 下载、长 Graph）进队列，用线程池 / 多槽并行。禁止单线程串行所有工单，禁止在请求线程 `sleep` 空等到模型或 PDF。细则见 `06`。
|
||
- **代码必须分模块。** 一个包/目录只承担一类职责。禁止把企微解析、Graph、LLM、报价 PDF、TMS 客户端、主账写操作堆进同一个文件或「util/common」上帝模块。进程可以合并（一个 HTTP、一个 Worker），**源码目录不能合并成一坨**。分法见 `06`/`07`/`08`。
|
||
- **代码必须加详细中文注释。** 无注释或只有「赋值/循环」式空话的提交不算完成。要写清：这个模块/函数做什么、为什么这样、入参出参、副作用（写库、出站、改六态）、幂等、线程与停点、以及容易走错的分支（如 TMS 1002≠1003）。细则见下节。
|
||
|
||
## 注释（必须详细）
|
||
|
||
语言：**简体中文**（对外 API 名可英文，注释用中文）。
|
||
|
||
每个源码文件文件头：本文件职责、属于哪一包、依赖谁、**禁止**在本文件做什么。
|
||
|
||
每个公开函数/类/接口/Graph 节点/Handler：
|
||
|
||
- 做什么、什么时候被调用
|
||
- 参数含义与取值约束（如必须已有 `sender_id`、必须带 waitVersion）
|
||
- 返回值 / 抛错 / 写入哪张表
|
||
- 会触发的外部副作用（主账、企微、对象存储、LLM 入队）
|
||
- 并发：是否占用请求线程、哪条槽、同一 thread_id 能否重入
|
||
- 为什么不采用另一种写法（例：为何不在回调里等 LLM；为何不直连 TMS）
|
||
|
||
分支与常量：每个 `if` 业务分叉、错误码、状态迁移旁边写清「何种业务情况」。复杂算法或协议（HMAC、字典 EXACT_ONLY、卡片绑定）按步骤注释。
|
||
|
||
允许不写的：语言字面意义已经等于代码的一行（如 `i += 1`）。不允许：整文件零注释、只复制函数名当注释、把密钥写进注释。
|
||
|
||
改代码时同步改注释。注释与行为不一致视为缺陷。
|
||
|
||
## 技术选型
|
||
|
||
可以换框架，但交付形态必须是：
|
||
|
||
- 一个主账 API（**JeecgBoot + 低代码**；目录 `inquiry-api/`；并存期示例端口 8180；库 `inquiry_robot`）
|
||
- **一个**智能体 HTTP（目录 `inquiry-agent/`；H5 + 企微回调 + 主账唤醒；现网 8809/8810/8811 合并）
|
||
- **一个**后台 Worker（同 `inquiry-agent/`；LLM / 识别 / 报价 / 存档；进程内分槽，见 `01`）
|
||
- 一个 AIBOT 桥（8813 回环，无业务状态）
|
||
- 一个管理后台（**Jeecg Vue3**；目录 `inquiry-backend/`；经 `/jeecgboot` 打新主账）
|
||
- Windows 服务器 + Nginx + 不可变 release
|
||
- 配置用 `YTD_ENV=prod|test`，对照 `13-环境对照.md`。域名与企微与正式相同：`ai.ytd-scm.com`、应用 `1000010`。测试只换库/端口/Redis/桶。
|
||
|
||
不要复现现网五个 Python Worker 和四个 uvicorn。8812 默认不做。不要 Redis Worker 全局单例租约。
|
||
|
||
若换栈，必须在设计文档写清迁移映射：端口、环境变量、六态、TMS 路径。
|
||
|
||
## 不要做的事
|
||
|
||
- 不要把生产密钥、`.env`、私钥写入 Git。
|
||
- 不要用正则/别名替代 DeepSeek B 的字段语义（合同允许的机器投影除外）。
|
||
- 不要在智能体内维护第二套工单状态机。
|
||
- 不要为了「先跑起来」对真实 TMS **LOCK/RELEASE** 或真实客户群发消息。查价允许用 `03` 现网 TMS。
|
||
- 不要做按企微 userid 在 Redis 里伪造 TMS 无价/异常。1002/技术失败用单测 stub 覆盖即可。
|
||
- 不要做 Redis Worker 全局单例租约（`wecom:worker:singleton` / `SET NX` 挡双开）。一份进程靠 Windows 服务 + 发布先停旧再起新；同一条消息靠任务认领防重入。
|
||
- 询价企微与正式相同（`1000010` 及回调 URL），不要新建应用、不要改现网后台回调。运维 `1000014` 相同；测试进程告警正文带 `[test]`。并存期不要双连 AIBOT。
|
||
- 不要在收到聊天后再调企微接口获取用户 ID；只用入站 `sender_id`。
|
||
- 不要写会卡顿整机的实现：回调里同步调模型/转 PDF、全局一把锁串行全部询价、主循环里忙等 Redis 结果。I/O 用线程池或多线程槽；LibreOffice **例外**只许 1 槽。
|
||
- 不要把不同功能堆在一起：禁止单文件过万行、禁止 `graph.py`/`wecom_business.py` 类上帝文件、禁止一个 handler 处理全部卡片。新功能进对应模块，不要往入口文件追加。
|
||
- 不要用无关 Jeecg 演示模块冒充询价主账；Online/cgform **允许**用于询价相关生产页与 API（2026-09-12 决策）。不要另起第二套与 Jeecg 并行的后台登录壳（除非明确迁移期）。
|
||
|
||
## 库表变更（开发期间）
|
||
|
||
实现中只要缺表、缺字段、字段类型/长度不够、索引不够：**直接改**，不要停下来等确认。
|
||
|
||
- 写成 **版本化迁移**（主账 MySQL、运行账 PostgreSQL 分目录），可重复执行、有回滚说明。
|
||
- 只动新系统库 `inquiry_robot` / `inquiry_robot_runtime`。**禁止** ALTER/建表现网 `jeecg-boot`、`ytd_runtime`。
|
||
- 业务合同字段变了：同步改新仓库里的那两份 JSON 与 API，不要只改库。
|
||
- 删列、改名、改语义：迁移里写清数据怎么搬；测试库可以做。
|
||
- 改完在会话里用一两句话说明迁了什么，不必先问「能不能加字段」。
|
||
|
||
## 工作方式
|
||
|
||
按端拆分实现，顺序建议：主账 API 与数据模型 → 智能体编排与字段合同 → 企微通道 → TMS 适配 → 后台只读 → 部署。每端使用 `06`～`11` 对应提示词；Graph/Redis 实现前先读 `14`。验收以真实企微 fresh 事件为准，健康检查 HTTP 200 不算业务完成。
|