# 现状总览：语言、技术、框架、数据库、部署、域名

## 产品是什么

货代询价智能体：销售在企业微信私聊/群聊发文字、图片、Excel/PDF；系统抽字段、补问、建工单、查 TMS 报价、需要时建协同群、生成 Excel/PDF 报价、成交闭环。管理后台查看工单、报价、人员、模板、异常。

当前不是单体，而是多进程组合。

## 开发语言

| 语言 | 版本（建议/源码） | 用在哪 |
|---|---|---|
| Python | 3.12 | 智能体、企微 Worker、LangGraph、LLM/识别/报价/存档 |
| Java | 1.8（JDK 8） | JeecgBoot 工单/TMS 主账 |
| TypeScript / JavaScript | Node 18 或 20 | Vue3 管理后台；企微 AIBOT 长连接是 Node `.cjs` |
| PowerShell | 7（本机开发建议） | 环境导入、累计部署、远程运维 |
| SQL | MySQL / PostgreSQL 方言 | Java 业务库、Python 运行账迁移 |

## 主要框架与库

### Python（现网）

- FastAPI 0.137 + Uvicorn：HTTP 入口
- LangGraph 1.2.5 + `langgraph-checkpoint-postgres`：业务流程编排与 checkpoint（何时用、怎么用见 `14`）
- httpx：出站 HTTP
- psycopg / psycopg2：PostgreSQL
- redis：队列、限流、token 缓存；现网还有 Worker **全局单例锁**（新系统不要）。何时用见 `14`
- openpyxl / PyMuPDF / pypdf：Excel、PDF
- cryptography / python-dotenv
- PyMySQL：仅 metrics 等旁路读 MySQL（正式写走 Java）

### Java（现网主账）

- JeecgBoot 3.5.3
- Spring Boot 2.7.10
- Spring Cloud / Alibaba 组件在仓库里有，**生产活动形态是单体** `jeecg-system-start`，不是必开微服务
- MyBatis-Plus 3.5.1、Druid、Shiro、JWT
- MinIO Java SDK、Hutool、Fastjson、Knife4j
- 询价业务在 Jeecg 的 inquiry 模块

### 前端（现网管理后台）

- JeecgBoot Vue3 3.5.3
- Vue 3.2、Vite 3、Ant Design Vue 3、Pinia、TypeScript
- pnpm 7.33.x（锁文件 `pnpm-lock v5.4`，不要用 pnpm 11 重新生成锁文件）
- Axios、ECharts 等 Jeecg 全家桶

### 其它运行时

- Node.js：AIBOT 长连接脚本（只做传输）
- Nginx 1.18.0：`C:\nginx-1.18.0`，反代前端与 Java
- LibreOffice：报价 Excel → PDF（默认 `C:\Program Files\LibreOffice\program\soffice.exe`）

## 数据库与存储

| 组件 | 角色 | 谁写 |
|---|---|---|
| **MySQL** | 正式业务主账：工单六态、运输段、源报价/客户报价/版本、费用、附件元数据、人员角色、时间线、Jeecg 系统表。库名源码默认 `jeecg-boot` | **仅 Java** |
| **PostgreSQL** | 运行账：企微 inbox/outbox、Graph checkpoint、conversation session、suspend、clarification/卡片绑定、LLM/识别/报价任务 | **仅 Python** |
| **Redis** | 缓存、LLM 队列、限流。**不能当业务真相** | Python + Java |
| **MinIO / S3 兼容** | 报价文件、附件对象；元数据仍在 Java/任务账 | Python `object_storage` + Jeecg 上传配置 |
| 本地磁盘 | 企微 spool、release 目录、Nginx 静态、上传目录 | 运维/进程 |

现网 Redis 另有两样，**新系统都不要**：`wecom:worker:singleton`（全机只准一个 Worker 的锁）；按销售 UserID 伪造 TMS 无价/异常。并发靠「一条任务认领 + 超时回收」和「服务只起一份」。

### 新系统库名（同机 `10.206.0.14`，空库待建，口令新开）

| | 现网（禁止新系统连接） | 新系统 |
|---|---|---|
| MySQL 主账 | `jeecg-boot` / 用户 `ytd_jeecg` | 库 `inquiry_robot` / 用户 `inquiry_robot` |
| PostgreSQL 运行账 | `ytd_runtime` / 用户 `ytd_runtime` | 库 `inquiry_robot_runtime` / 用户 `inquiry_robot_runtime` |
| Redis | db0 前缀 `ytd:prod:node01-07` | **db1**，前缀 `inquiry_robot:` |
| MinIO 桶 | `ytd-inquiry` | `inquiry_robot` |

仍用现网端口 3306 / 5432 / 6379 / 9000。账号口令不要抄现网，由甲方新建。变量名与正式/测试取值见 `13`。

## 外部系统（非本仓库）

| 系统 | 职责 |
|---|---|
| 企业微信 | 私聊、群聊、模板卡、应用消息、AIBOT |
| 微盛会话存档 `open.wshoto.com` | 群/会话 Archive、附件下载 |
| TMS（友商/自有 TMS V2） | 报价查询、详情、字典、空运锁舱/释放；外部报价与舱位事实 Owner |
| DeepSeek API | 意图路由（A）+ 字段语义（B） |
| 阿里云百炼/DashScope 千问 | 附件/图片、报价表映射等 |
| 现网 Git | 对照地址见 `03`；本仓库用自己的远程 |

## 部署环境

| 项 | 值 |
|---|---|
| 形态 | 甲方 Windows 服务器，不可变 release 目录 |
| 公网 IP | `129.211.181.80`（SSH 22） |
| 主机名 | `10_206_0_15` |
| 运行根 | `C:\yutongda` |
| 版本目录 | `C:\yutongda\releases\` |
| 运维指针 | `C:\yutongda\ops\`（active-release*.json） |
| SSH 账号 | `ytd_extdev_0903`，仅 Ed25519 公钥 |
| 允许出口 | `38.175.103.103`、`113.119.172.108`、`115.159.76.75` |
| 部署方式 | 固定脚本 `Deploy-YtdCumulativeRelease.ps1`，禁止手工覆盖活动目录 |
| OS 本机开发 | Windows 10/11 + PowerShell 7 |

新系统与现网 **同机并存**：不占用上表 `C:\yutongda` 活动指针；TMS、**域名 `ai.ytd-scm.com`、询价企微 `1000010`、AIBOT Bot 与正式相同**。库、Redis 前缀、监听端口另起。运维通知 `1000014` 也相同。并存期不要改 Nginx 回调、不要双连 AIBOT。

## 公开域名与路径

| 地址 | 用途 |
|---|---|
| `https://ai.ytd-scm.com` | 正式站点（Nginx `ai.conf`）。测试环境域名配置与此相同，切流前公网仍进现网 |
| `https://ai.ytd-scm.com/inquiry-form` | H5（测试 `.env` 也填这一条） |
| `https://ai.ytd-scm.com/inquiry-form/upload` | H5 询价附件上传 |
| `/jeecgboot`（生产前端 `VITE_GLOB_API_URL`） | 浏览器到 Java 的反代前缀 |
| Java context-path | `/jeecg-boot`（服务端口 8080） |
| 现网 Git | 地址见 `03`；本仓库用新远程 |
| `https://work.weixin.qq.com/` | 企微卡片跳转占位 |
| `https://open.wshoto.com` | 微盛 Archive API 默认基址 |
| `https://api.deepseek.com` / `/beta` | DeepSeek |
| DashScope 兼容基址（环境变量 `QWEN_BASE_URL`） | 千问 |

源码里的 `minio.jeecg.com`、`fileview.jeecg.com`、`cas.test.com` 是 Jeecg 模板默认值，**不等于生产**。生产对象存储与域名以服务器环境文件为准。

## 监听端口

公网对外只需 **443**（Nginx）。下面多数是本机回环或数据机，不是都要映射到公网。

### 现网应用口（拆得过细）

| 端口 | 现网进程 | 新系统 |
|---|---|---|
| 8080 | Java JeecgBoot | **保留**（主账，本机，Nginx 反代） |
| 8810 | Python `agent_api` | **保留**，并承接原 8809/8811 |
| 8809 | Python `bridge_api` | **砍**，并进 8810 |
| 8811 | Python `wecom_callback` | **砍**，并进 8810 |
| 8812 | Python `wecom_robot` | **砍**，现网基本空配置 |
| 8813 | AIBOT Bridge | **保留**，仅 127.0.0.1 |
| 3100 | Vite 开发服 | **生产不要开** |

### 基础设施（不是询价业务端口）

数据在 `10.206.0.14`：MySQL `3306`、PostgreSQL `5432`、Redis `6379`。本机还有 MinIO `9000`。Worker **不占**对外端口。

新系统并存期应用口：**8180 + 8910 + 8913**，外加 Nginx 80/443。切流前不要占用现网 8080/8810/8813。

## 目标进程（不要复现现网拆法）

现网 Python 拆成多个 uvicorn + 五个 Worker，是发布/隔离习惯，**不是业务必需**。新系统交付形态：

| 进程 | 端口（可沿用） | 职责 |
|---|---|---|
| Nginx | 443 / 80 | TLS、静态后台、反代 |
| 主账 API | 并存时不要用 8080（示例 8180） | 工单、权限、TMS、后台 API |
| 智能体 HTTP | 并存时不要用 8810（示例 8910） | H5、企微 HTTP 回调、主账唤醒；**只入队、快回** |
| AIBOT 桥 | 并存时不要用 8813（示例 8913）仅回环 | 长连接转发，无业务状态 |
| 后台 Worker **一个进程** | 无对外端口 | LLM、识别、报价（LibreOffice）、存档；进程内分并发槽 |

Worker 并发约定（**不允许系统卡顿，尽量多线程**）：

- **1 个槽专跑 LibreOffice**（避免本机两台 soffice 互抢）。不是整进程单线程。
- **2～3 个线程槽跑 HTTP 类**（模型、识别、存档下载、主账）。不同工单并行。
- inbox / outbox **独立线程**，禁止和转 PDF 串在一条阻塞线上。
- 回调 / H5 **只入队快回**；禁止在请求线程转 PDF、等完整 LLM、忙等 Redis 结果。
- 禁止全局大锁把所有询价排成单行。同一任务认领即可。

不要：群机器人独立 8812（现网空配置）；五个 NSSM Worker；把慢活塞回回调请求。

## 业务六态（Java 唯一）

询价中、已报价、协商中、已成交、未成交、已关闭。

补字段、附件识别中、生成文件、异常、人工协同 **不是第七态**，属于 Graph/任务/异常正交状态。