Files

T

zhanghongyu_0626 f87e11f104 feat(merge): 完成 AL-09 合并接线，整合风控模块与宿主 Wave 0

- 合并 `risk-control-agent` 分支至 `merger`，实现 JWT 统一与模块 API 恢复。
- 更新 `auth_service` 和 `auth_adapter`，确保对外登录/token 统一。
- 增强 chat 模块，支持会话管理与流式对话（SSE）。
- 测试基线更新至 502 passed, 1 skipped，确保系统稳定性。

此更新标志着风控模块的成功集成，提升了系统的整体功能与可维护性。

2026-09-08 20:00:39 +08:00

7.9 KiB

Raw Blame History

从需求到公共 API 开发方法

路径：docs/项目管理/04-从需求到公共API开发方法.md
性质：方法论文档 / 项目产出（非会议纪要）
适用：统筹（P1）搭公共底座与 Platform API；各 Agent 负责人联调接入
制定：2026-09-08
关联：02-项目开发计划.md · 03-表设计文档.md · ../需求拆解/数据交互矩阵.md · ../memory/REQUIREMENTS.md

0. 一句话

先定需求 → 做数据交互矩阵 → 矩阵推出公共存储层 → 封装公共 Service/Repository → 暴露公共 API → 四个 Agent 按契约接入。
公共 API 不可能一次满足全部 Agent 脑洞；第一批只覆盖 Core L0 公共底座 与 P0 场景。

1. 主流程（标准顺序）

① 定需求（场景 ID、验收、禁止项）
        ↓
② 数据交互矩阵（谁采集 / 谁使用 / 读写 / 优先级）
        ↓
③ 公共数据底座 · 存储层（Core + agent 库 + Redis/Milvus/Neo4j）
        ↓
④ 公共底座函数（Repository / Platform Service，如 core_ro）
        ↓
⑤ 公共 API（REST + JWT + 归属；仪表盘与 Agent Tool 共用底层 Service）
        ↓
⑥ 四个 Agent（LangGraph + Tool；编排与 L1/L2/L3 enrich）

1.1 本仓库对应文档

步骤	产出 / 文档
① 定需求	`docs/需求拆解/业务场景优先级清单.md` · `docs/memory/REQUIREMENTS.md`
合规约束	`docs/需求拆解/Agent风险与合规约束汇总.md`
② 数据交互矩阵	`docs/需求拆解/数据交互矩阵.md`
③ 存储层	`jinrong_core` / `jinrong_agent` · `docs/项目框架设计/表设计/` · Core 模拟底座
④ 公共函数	`app/repository/core_ro.py` · `app/model/suitability.py` · `scripts/sync/`
⑤ 公共 API	`app/api/auth.py` · `app/api/chat.py` · 规划中的 `app/api/platform/`
⑥ Agent	各负责人 `app/service/agent_service.py` 及 Tool

2. 两个门闸（矩阵之后、写 API 之前）

门闸 A · 合规 / 架构硬规则

在搭接口前必须固定，避免各 Agent 各写一套：

规则	说明
L0 权威	Core 正式 C1~C5、持仓/交易真账；Agent 只读
画像边界	L1/L2/L3 enrich 不得覆盖 L0 风评
唯一阻断	仅 R-02 适当性可阻断进入交易流程
Agent 隔离	四 Agent 不互调 LLM；跨 Agent 走画像表与预警表
审计	`audit_log` 等只 INSERT
合规	不代客交易、不营销式推荐、代理人草稿不自动外发

门闸 B · Wave / P0 裁剪

矩阵是全量的；公共 API 只做 P0 + Core 已有能力，其余联调驱动补充：

矩阵（全量） → 筛 P0 场景 → 映射 core_ro 已有方法 → API v0.1
P1/P2        → 联调提需求 → 补 Repository → 升 API v0.2+

3. 分层定义（避免「数据底座」与「公共服务」概念打架）

层	叫什么	干什么	谁调用
存储层	Core / agent 库 / Redis / Milvus / Neo4j	存数据；不对外讲业务	仅 Service / Repository
公共 Service	Platform Service · 公共底座函数	封装 L0 查询、R-02 规则、归属校验	Agent Tool、REST 控制器
公共 API	Platform REST	HTTP 契约；三类仪表盘 + Agent 可复用	前端、Agent（HTTP 或同进程 Service）
Agent 层	四 Agent	意图理解、Tool 编排、写 L1/L2/L3	调公共 Service/API，禁止直连 Core SQL

概念合并（下个项目可沿用）：

旧称「数据底座」→ 现称 存储层 + 公共 Service（Core RO 是 Service 的实现细节，不是独立业务层）
Agent 与前端 共享公共 API/Service，而不是「共享一套各自理解的底座」

4. 矩阵如何推出「公共存储层」

数据交互矩阵回答三件事：

哪些是 L0 权威（多 Agent 只读、口径唯一）→ 进 jinrong_core
哪些是 Agent enrich（谁写谁读）→ 进 jinrong_agent 画像/会话/审计表
哪些是跨 Agent 交换（适当性结果、预警台账）→ agent 库 + 事件

凡矩阵中「四 Agent 只读 + 事实口径唯一」的对象，都属于公共底座（Core L0），由统筹封装 API。

典型 L0 对象：客户主档、正式风评、归属、产品、持仓、申赎转流水、净值、C×R 矩阵。

5. 公共 API 的分批策略（现实做法）

5.1 不能一次做全的原因

各 Agent 的 Tool 命名、多步编排、RAG、NL→SQL 属于 Agent 层，开工时无法全部预知
仪表盘聚合、产品写 Milvus、工单等属于 业务公共服务，可与 Agent P0 并行、分 Wave 交付

5.2 三批交付（统筹侧）

批次	范围	说明
Phase A · API v0.1	Core L0 + P0；对齐现有 `core_ro.py`	现在优先；不依赖 Agent 脑洞
Phase B · 联调驱动	Agent 提缺的 Core 查询/聚合	加 Repository 方法后再暴露 API
Phase C · 业务公共服务	仪表盘 KPI、产品 CRUD+Milvus、清算模拟	与 Agent 并行，不阻塞 P0 联调

5.3 Phase A 清单（与 `core_ro.py` 对齐）

Repository 方法	建议 REST（草案）	主要场景
`get_customer_l0`	`GET /api/customers/{id}`	C-01、A-01、仪表盘
`list_customers_by_advisor`	`GET /api/advisors/{id}/customers`	F-01、代理人仪表盘
`is_advisor_assigned`	归属中间件 / 内 Service	F-01
`get_product`	`GET /api/products/{id}`	C-02、A-02
`get_latest_nav`	`GET /api/products/{id}/nav`	C-05
`list_holdings`	`GET /api/customers/{id}/holdings`	C-01、A-01
`list_trades`	`GET /api/customers/{id}/trades`	C-01、D-01、R-01
`list_products_for_customer`	`GET /api/customers/{id}/products`	C-11
`check_suitability`	`POST /api/compliance/suitability-check`	R-02
`get_staff`	`GET /api/staff/{id}` 或鉴权上下文	F-01

正式字段、错误码、归属规则见后续 《接口契约 v0.1》（待 P1 单独出稿）。

6. 角色分工

角色	负责
统筹（P1）	需求/矩阵维护、Core 存储与灌库、公共 Service/API v0.1、接口契约、Review 禁止直连 Core
Agent 负责人	本 Agent 场景 Tool/编排/L1~L3；按契约调 Platform；缺 Core 能力提 Issue
前端	登录 + chat + 仪表盘；调公共 API，不直连库

团队硬规则（联调前宣贯）

Agent Tool 只允许调 Platform Service / Platform API。
禁止各 Agent 直连 jinrong_core 写 SQL。
缺 L0 查询能力 → 向统筹提需求 → 补 core_ro + API → 再接入。

7. 与国内代销模块的关系

纵向 公共业务模块（账户、产品、交易、清算、报表、系统管理、L0 画像）的 读路径 应全部收敛到本流程第 ④⑤ 步；
Agent 对话能力走第 ⑥ 步，不重复实现 L0 查数逻辑。

国内模块映射详见：C:\Users\Windows\Downloads\国内代销模块与需求映射表.md（项目外备份；后续可迁入 docs/项目管理/）。

8. 验收对照（统筹自查）

P0 场景 ID 与矩阵中 L0 对象一一能映射到 core_ro 或已登记「Phase B 待补」
core_ro.py 每个 public 方法有对应 Service 封装计划
Phase A REST 清单有 JWT + 归属规则说明
Agent 负责人已收到「禁止直连 Core」与 Issue 提需求流程
接口契约 v0.1 发群后，各 Agent Tool 名称可各异，但底层调同一 Service

9. 修订记录

日期	说明
2026-09-08	首版：固化「需求→矩阵→存储→Service→API→Agent」主线及分批策略
2026-09-08	AL-09 合并完成：`merger` 分支 502 绿；下一步统筹 Phase A Core REST API v0.1

7.9 KiB Raw Blame History Unescape Escape