2026-09-09 21:55:37 +08:00
|
|
|
|
# 项目级开发约束
|
|
|
|
|
|
|
|
|
|
|
|
以下规则对人工开发者和编码 Agent 均为强制约束：
|
|
|
|
|
|
|
|
|
|
|
|
1. 数据库以 `docs/00-新数据库基线设计.md` 为不可变业务基线。
|
|
|
|
|
|
2. 允许创建新表，允许在已有表中增加新字段。
|
|
|
|
|
|
3. 禁止重命名或删除已有表。
|
|
|
|
|
|
4. 禁止重命名、删除、复用已有字段，禁止改变已有字段的类型、可空性和既有业务含义。
|
|
|
|
|
|
5. 历史结构无法满足新需求时，使用新增字段、新表、兼容视图或应用双读解决。
|
|
|
|
|
|
6. 架构固定使用 MVC+S；Agent 属于 Service 层。
|
|
|
|
|
|
7. 业务 Agent 必须继承公共 `BaseAgent` 并由 `AgentFactory` 创建，不得绕过公共鉴权、记忆、模型路由、工具、合规、审计和事件流程。
|
|
|
|
|
|
8. 当前系统业务功能只针对场内基金模拟交易；场外基金运营流程独立，不得写入场内交易表。
|
|
|
|
|
|
|
|
|
|
|
|
修改数据库文档或迁移前，必须对比基线并证明没有改变任何已有表名和已有字段定义。
|
2026-09-11 14:37:20 +08:00
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 📖 接手先读（按此顺序，只读这些就够）
|
|
|
|
|
|
|
|
|
|
|
|
> **⭐ 第 0 步先读这个**：`docs/superpowers/handoff/2026-09-11-交接文档-客服Agent与RAG收尾.md`
|
2026-09-11 15:41:49 +08:00
|
|
|
|
> —— 客服 Agent + RAG 这条线的交接文档（**含合并完成后的第二次更新**）：环境口径、交付内容与
|
|
|
|
|
|
> **可复现验证证据**、合并后修掉的 3 个真机故障、**已知问题清单（逐条标注当前状态）**、Git/PR 状态。
|
|
|
|
|
|
> 当前工作分支是 **`NL_develop`**（个人分支 → PR 合回 `qyqy_develop`），**不要再用 `6516ccb`**。
|
2026-09-11 14:37:20 +08:00
|
|
|
|
> 它是对"当前状态"最准确的一份，读完它再读下面这些。
|
|
|
|
|
|
>
|
2026-09-11 18:42:46 +08:00
|
|
|
|
> **⚠️ 文档现状（2026-09-11 第二次修订）**：本文件原先声明"已删除 5 份编号文档"，
|
|
|
|
|
|
> 那条**已作废** —— 经评审，`docs/04`/`06`/`10`/`13`/`99` **全部保留**（架构师明确要求保留：
|
|
|
|
|
|
> 删除收益为零，而保留成本同样为零）。它们的内容**未被核对过、可能过期**，
|
|
|
|
|
|
> 因此**列在下面的 D 类"不要用来判断当前进度"**里，只作历史参考。
|
|
|
|
|
|
> 被删除的只有 10 份**过程产物**，理由与清单见 `docs/superpowers/ARCHIVE-2026-09-11-文档清理归档.md`。
|
2026-09-11 14:37:20 +08:00
|
|
|
|
|
|
|
|
|
|
### A. 核心 7 份（无论接手哪条线都必读）
|
|
|
|
|
|
|
|
|
|
|
|
| 序 | 文档 | 承载的唯一权威内容 |
|
|
|
|
|
|
|---|---|---|
|
|
|
|
|
|
| 1 | `docs/00-新数据库基线设计.md` | **不可变业务基线**：表/字段业务语义的唯一来源 |
|
|
|
|
|
|
| 2 | `docs/05-接口文档.md` | **接口唯一权威**：信封/错误码/幂等/SSE、§8.3 知识库管理三端点、§8.4 四个只读工具索引与两段式白名单 |
|
|
|
|
|
|
| 3 | `docs/01-通用Agent平台开发设计.md` | MVC+S 分层约束、`BaseAgent` 执行骨架、`AgentFactory` |
|
|
|
|
|
|
| 4 | `docs/02-数据库建表设计.md` | 51 张业务表总览 + DDL + §8 幂等与 Outbox 语义 |
|
|
|
|
|
|
| 5 | `docs/03-平台端到端流程文档.md` | 一次请求从受理→Worker→审计→事件的全链路与降级矩阵 |
|
|
|
|
|
|
| 6 | `docs/08-数据库结构审计基线.md` | 三个审计工具 + `migration_state_check` 的职责；"证明未改基线"的证据出处 |
|
|
|
|
|
|
| 7 | `docs/07-测试问题修复记录.md` | **无替代**：P0-1/2/3 鉴权与 Worker 租约闭环、P1-1~P1-5（含 `api_request_receipt` 事务幂等） |
|
|
|
|
|
|
|
|
|
|
|
|
### B. 按角色补充
|
|
|
|
|
|
|
|
|
|
|
|
| 你接手的是 | 再读这些 |
|
|
|
|
|
|
|---|---|
|
|
|
|
|
|
| **客服 Agent + RAG 这条线** | `docs/14`（接入入口）→ `docs/18`（RAG 三集合路由方案）→ `docs/19`（可运行示例）→ `docs/09`（底座用法与四工具） |
|
|
|
|
|
|
| **整个底座** | 补 `docs/20`（第一版→当前的破坏性改动 + §5 四条尚未修复的偏差 + "跑验收前先停常驻 Worker"） |
|
|
|
|
|
|
| **只改某个业务域** | `docs/00` → `docs/05` → `docs/02` → `docs/14` → `docs/19`；行情加 `docs/12`，前端/联调加 `docs/17` |
|
|
|
|
|
|
| **看"现在做到哪了"** | `docs/验收与审计/phase1-acceptance-report.md`（Phase 1 七条验收标准的逐条可复现证据）+ 同目录 `phase1-acceptance-criteria.md`（老师验收标准原文摘录） |
|
|
|
|
|
|
|
|
|
|
|
|
> 注：完整的过程台账（`progress.md`、各 Task 报告、审计报告）在 **`.superpowers/sdd/2026-09-10-客服Agent与RAG-qyqy版/`**，
|
|
|
|
|
|
> 但该目录**被 `.gitignore` 忽略**（属工作区过程产物）—— 因此**结论性文档已复制到 `docs/验收与审计/`** 以保证 git 可见。
|
|
|
|
|
|
> 若要查过程细节再去看 `.superpowers/`；日常接手**只需读本文档列出的这些**。
|
|
|
|
|
|
|
|
|
|
|
|
### C. 同主题的重复文档（读一份即可，避免信息冲突）
|
|
|
|
|
|
|
|
|
|
|
|
| 主题 | 唯一权威 | 重复品（仅历史参考） |
|
|
|
|
|
|
|---|---|---|
|
|
|
|
|
|
| Agent 组员接入 | **`docs/14`** | `docs/11`（旧版说明书）、`docs/15`（详细手册）、`docs/16`（入门易懂版）—— 三份已各自在开头标注"以 `14` 为准" |
|
|
|
|
|
|
| 接口说明 | **`docs/05`** | `docs/17`（易懂版，自述"不替代 05"） |
|
|
|
|
|
|
|
|
|
|
|
|
### D. ⚠️ 不要用来判断"当前进度"
|
|
|
|
|
|
|
|
|
|
|
|
| 文件 | 为什么 |
|
|
|
|
|
|
|---|---|
|
|
|
|
|
|
| `TODO.md` | **自 2026-09-09 起未随 Phase 1 更新**：5 处"49 张表"（实为 51 张业务表）、T8.1 客服 Agent 整节未勾选但**已交付**、多处标"进行中"其实已完成。**当前进度一律以 `phase1-acceptance-report.md` 为准。** |
|
2026-09-11 18:42:46 +08:00
|
|
|
|
| `docs/04` / `06` / `10` / `13` / `99` | 内容**未核对过、可能过期**（自相矛盾 / 结论失效 / 清单不全）。经 2026-09-11 评审**保留**（不再删除），仅作历史参考。**不要用它们判断现状** |
|
2026-09-11 14:37:20 +08:00
|
|
|
|
|
|
|
|
|
|
### E. 环境与命令口径（易错点）
|
|
|
|
|
|
|
2026-09-11 18:42:46 +08:00
|
|
|
|
- 解释器：本机用 **`.\.venv\Scripts\python.exe`**；架构师环境用 `D:\conda\envs\jr_py313\python.exe`。
|
|
|
|
|
|
两者等价，**各用本机可用的那个**（`.venv` 被 `.gitignore` 忽略、不进仓库，不存在"需要统一"的问题）。
|
2026-09-12 11:27:28 +08:00
|
|
|
|
- 数据库现为 **90 张表**（含 `alembic_version`）＝ **89 张业务表** =
|
|
|
|
|
|
**场内 51 + 场外/推广 17 + 投顾 21**。
|
|
|
|
|
|
后 38 张（`offsite_*` / `promotion_*` / `advisor_*`）**不进 `docs/00` 基线**（规则 8）：
|
|
|
|
|
|
场外/推广那 17 张逐表登记见 `docs/28-场外与推广域数据表登记.md`；
|
|
|
|
|
|
**投顾那 21 张的登记文档待补**（按同样口径另立一份）。
|
|
|
|
|
|
核验命令：`python tools/audit_schema.py`（若报 `unexpected` 先分清是"库里多表"还是"迁移没进来"）。
|
2026-09-11 15:41:49 +08:00
|
|
|
|
- 已注册业务 Agent：`FundQueryDemoAgent`、`CustomerServiceAgent`、`RiskAgent`、`PlatformProbeAgent`（见 `app/service/agent/bootstrap.py`）。
|
|
|
|
|
|
- 已注册公共只读工具：`search_knowledge`（客服知识检索）、`check_suitability`、`query_customer_profile`（画像）、`query_fund_quote`；
|
|
|
|
|
|
**工具可用范围 = 代码上限 ∩ 当前 active `config_release` 的发布白名单**，缺发布配置则失败关闭。
|
2026-09-11 18:42:46 +08:00
|
|
|
|
- ⚠️ **`config_release` 是环境数据，不随代码合并**：本机 active 版本 id 与架构师环境**不同**
|
|
|
|
|
|
（本机是我方发布的客服白名单；他那边还有风控的 9 条白名单）。**"白名单已发布"必须带环境限定**，换环境要重发。
|
|
|
|
|
|
发布脚本 `tools/publish_customer_service_config.py`（**同 key 的继承项必须被本次定义覆盖**，否则旧值会被子集校验 422 拦下整次发布）。
|
|
|
|
|
|
- ⚠️ **Milvus 集合 schema 也因环境而异**：本机是 `knowledge_id`/`snippet`（无 `visibility`），
|
|
|
|
|
|
架构师环境是 `doc_id`/`content`/`visibility`/`chapter`…。**检索层已改为运行时探测字段名**
|
|
|
|
|
|
（`app/core/knowledge_schema.py`）——**不要在任何地方硬编码字段名**，那会把另一套环境打挂。
|
|
|
|
|
|
- ⚠️ **Docker Desktop 不会常驻**：它没运行时 Milvus 不可用（`docker` CLI 报连不上守护进程）。
|
|
|
|
|
|
跑真机验证前先确认 Docker Desktop 在运行。
|
2026-09-12 11:27:28 +08:00
|
|
|
|
- ⚠️ **`MILVUS_LOCAL_URI` 配了就会"看着正常、查的是另一个库"**：一旦在 `.env` 里设置它，
|
|
|
|
|
|
健康检查与部分检索链路会指向本地 **Milvus Lite 文件**。团队/生产环境请**保持该变量为空**。
|
|
|
|
|
|
对应的 `milvus-lite` 属**本地开发依赖**，应放在 `pyproject.toml` 的
|
|
|
|
|
|
`optional-dependencies`，**不要进主 `dependencies`**。
|
|
|
|
|
|
- 测试基线（2026-09-11 架构师环境实测）：`ruff` 干净 / `mypy app` **228 个文件 0 错** /
|
|
|
|
|
|
`pytest tests/unit tests/contract` → **1207 passed, 2 skipped, 0 failed** /
|
|
|
|
|
|
`pytest tests/integration` → **99 passed**。完整口径与联调清单见
|
|
|
|
|
|
`docs/32-平台侧交接与联调准备.md`。
|
|
|
|
|
|
- ⚠️ **mypy 与测试数必须带环境读**：出现"一边上百个错、另一边 0 错"时先对版本，别当代码质量问题。
|
|
|
|
|
|
已知根因是某一侧的虚拟环境没满足 `pyproject.toml` 的 `sqlalchemy>=2.0,<3` / `mypy>=1.14,<2`。
|
|
|
|
|
|
**不要装 `sqlalchemy2-stubs`** —— 那是给 SQLAlchemy 1.4 的，2.0 自带 `py.typed`，
|
|
|
|
|
|
装了反而按 1.4 的 API 报一批新错（`mapped_column` / `DeclarativeBase` 不存在）。
|
