docs(test): archive 2026-09-08 HTTP API and SSE context integration test report
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
WeiCHEN
committed by
weichen
weichen
co-authored by
Cursor
Cursor
parent
44ebafd946
commit
ae9d2f1fea
@@ -0,0 +1,131 @@
|
||||
# 多级上下文与受控文档治理 HTTP RESTful / SSE 流式接口集成测试报告
|
||||
|
||||
## 一、 测试背景 (Background)
|
||||
在医疗器械研发与商务协同场景中，系统具备多层级上下文管理（单用户私有上下文、项目协同黑板事实与偏好记忆）以及受控文档治理引擎（编制、审核、批准生命周期、认领机制及变更提案拦截）。
|
||||
根据用户产品交互指导思想：
|
||||
1. **轻量推送与低认知负荷**：用户不关心过于繁琐的后端底层推演草稿或内部步骤细节，过量杂乱信息会严重降低用户体验，前端应优先聚合展示阶段性任务进度、核心摘要（Summary）以及决策锦囊（Briefing）；
|
||||
2. **受控文档治理前端闭环**：当已认领文档因外部输入变化被智能体小队拦截时，需通过高亮流式事件（`governance` 与 `summary`）实时向前端触达告警，编制人可通过 RESTful 接口直接完成提案拍板、章节批注、送审、审核与批准操作；
|
||||
3. **HTTP RESTful 与 SSE 协议双轨互通**：支持外部 Web 前端、桌面端及多端系统基于统一标准化协议发起阻塞/流式调用。
|
||||
|
||||
本报告对刚刚完成研发的 **HTTP RESTful API 路由套件** 与 **分层 SSE 流式长连接协议** 进行端到端回归验证。
|
||||
|
||||
---
|
||||
|
||||
## 二、 测试目标 (Test Objectives)
|
||||
1. **多级上下文与偏好画像 RESTful 接口验证**：
|
||||
- 验证 `GET /api/v1/context/user` 正确获取单用户偏好、会话记录及时间衰减后的活动流；
|
||||
- 验证 `PUT /api/v1/context/user/preference` 能够动态持久化用户的工作习惯、沟通风格与定制指令；
|
||||
- 验证 `GET /api/v1/context/project` 能够聚合项目协同事实黑板、里程碑决策与团队文件。
|
||||
2. **受控文档治理生命周期 RESTful 接口闭环**：
|
||||
- 验证 `GET /api/v1/docgov/document` 查询文档责任人、生命周期状态与锁定标志；
|
||||
- 验证 `POST /api/v1/docgov/claim` 查阅触发认领；
|
||||
- 验证 `POST /api/v1/docgov/proposal/decide` 编制人拍板同意/拒绝变更提案；
|
||||
- 验证 `POST /api/v1/docgov/submit-review` 送审与自动加锁；
|
||||
- 验证 `POST /api/v1/docgov/review-decision` 审核驳回（强制非空原因并退回草稿解锁）与审核通过；
|
||||
- 验证 `POST /api/v1/docgov/approver-decision` 终态批准归档；
|
||||
- 验证 `GET/POST /api/v1/docgov/comments` 与 `GET /api/v1/docgov/audit-logs` 批注与全生命周期审计轨迹。
|
||||
3. **SSE 流式传输与轻量化过滤验证**：
|
||||
- 验证 `POST /api/v1/tasks/run/stream` 在文档未认领时发射 `phase`、`deliverable` 与 `done`；
|
||||
- 验证在文档已认领再次触发任务时，SSE 流中精准捕获 `governance` 拦截通知与 `summary` 核心提炼事件，默认阻断冗长推演细节；
|
||||
- 验证 `POST /api/v1/chat/stream` 连续对话流中低延迟逐字推送与意图状态更新。
|
||||
|
||||
---
|
||||
|
||||
## 三、 测试方案与环境 (Test Plan & Environment)
|
||||
- **操作系统**：Darwin (macOS 15.6.0 arm64)
|
||||
- **Go 运行环境**：Go 1.24
|
||||
- **测试模型模式**：Stub 高保真模拟器（按既定约束快速验证网络协议与状态机，无多余网络延迟）
|
||||
- **测试端点与端口**：`internal/server` 内存级 HTTP Test Server
|
||||
- **自动化测试用例矩阵**：
|
||||
1. `TestServer_Health`：基础自检与环境变量
|
||||
2. `TestServer_ChatBlocking`：标准 JSON 阻塞式会话
|
||||
3. `TestServer_ChatSSEStream`：对话长连接 SSE 流事件时序
|
||||
4. `TestServer_ContextAndDocGovAPIs`：涵盖上下文、用户偏好更新、文档认领、提案拍板、送审、审核驳回/通过、批准及审计日志的 14 步完整 RESTful 闭环
|
||||
5. `TestE2E_ChatSSEStreamPipeline`：端到端对话流解析
|
||||
6. `TestE2E_TasksRunStreamPipeline`：端到端独立任务监控流
|
||||
7. `TestE2E_ClaimedDocument_SSE_Interception`：已认领文档通过 SSE 执行的流式拦截事件专项验证
|
||||
|
||||
---
|
||||
|
||||
## 四、 预期结果 (Expected Results)
|
||||
1. **RESTful 状态码与协议格式**：所有接口均返回标准 `application/json; charset=utf-8`，参数错误返回 400，资源不存在返回 404，执行成功返回 200；
|
||||
2. **驳回校验**：审核驳回缺少原因时直接返回 400，并提示 `reject_reason required`；
|
||||
3. **提案拍板**：编制人授权通过后，提案状态跃迁为 `approved_by_author`；
|
||||
4. **SSE 事件流协议**：遵循 `event: <type>\ndata: <json>\n\n` 规范，事件流中包含 `phase`、`summary`、`governance`、`deliverable`、`done` 等关键类型，且不包含未经允许的底层巨量推演杂音。
|
||||
|
||||
---
|
||||
|
||||
## 五、 实际测试结果与判定 (Actual Results & Evaluation)
|
||||
|
||||
### 1. RESTful 核心接口交互验证 (TestServer_ContextAndDocGovAPIs)
|
||||
- **步骤 1 (偏好更新)**: `PUT /api/v1/context/user/preference` -> HTTP 200 `{"status": "ok", "user_id": 101}` [PASS]
|
||||
- **步骤 2 (用户上下文)**: `GET /api/v1/context/user?user_id=101&project_id=1` -> HTTP 200 包含偏好画像与活动流 [PASS]
|
||||
- **步骤 3 (项目黑板)**: `GET /api/v1/context/project?project_id=1` -> HTTP 200 包含黑板事实与里程碑决策 [PASS]
|
||||
- **步骤 4 (任务生成)**: `POST /api/v1/tasks/run` -> HTTP 200 生成注册可行性报告与受控文档记录 [PASS]
|
||||
- **步骤 5 (文档详情)**: `GET /api/v1/docgov/document?doc_id=doc_api_test_001` -> HTTP 200 `current_state="drafting"`, `is_locked=false` [PASS]
|
||||
- **步骤 6 (查阅认领)**: `POST /api/v1/docgov/claim` -> HTTP 200 `author_claimed=true` [PASS]
|
||||
- **步骤 7 (已认领拦截)**: `POST /api/v1/tasks/run` (输入变更) -> HTTP 200 `RequiresAuthorApproval=true`, 成功返回 `PendingProposal` [PASS]
|
||||
- **步骤 8 (提案拍板)**: `POST /api/v1/docgov/proposal/decide` -> HTTP 200 提案状态更新为 `approved_by_author` [PASS]
|
||||
- **步骤 9 (发表批注)**: `POST /api/v1/docgov/comments` -> HTTP 200 成功持久化审核修改建议 [PASS]
|
||||
- **步骤 10 (编制送审)**: `POST /api/v1/docgov/submit-review` -> HTTP 200 状态流转为 `reviewing`，`is_locked=true` 锁定文档 [PASS]
|
||||
- **步骤 11 (空原因驳回拦截)**: `POST /api/v1/docgov/review-decision` (action=reject, reason="") -> HTTP 400 校验拒绝 [PASS]
|
||||
- **步骤 12 (审核通过)**: `POST /api/v1/docgov/review-decision` (action=approve) -> HTTP 200 状态流转为 `approving` [PASS]
|
||||
- **步骤 13 (终态批准)**: `POST /api/v1/docgov/approver-decision` (action=approve) -> HTTP 200 状态流转为 `approved` 终态归档 [PASS]
|
||||
- **步骤 14 (审计追踪)**: `GET /api/v1/docgov/audit-logs?doc_id=doc_api_test_001` -> HTTP 200 返回全流程审计事件链 [PASS]
|
||||
|
||||
### 2. 已认领文档 SSE 流式拦截专项验证 (TestE2E_ClaimedDocument_SSE_Interception)
|
||||
真实测试控制台取样：
|
||||
```
|
||||
=== RUN TestE2E_ClaimedDocument_SSE_Interception
|
||||
e2e_test.go:275: ✓ SSE 流中成功捕获文档治理拦截事件: proposal_id=prop_feasibility_reg_1788843975773822000, 简报=文档【注册路径可行性评估报告】已被认领，变更已拦截
|
||||
e2e_test.go:281: ✓ SSE 流中成功捕获轻量级摘要事件: 标题=⚠️ 文档【注册路径可行性评估报告】变更拦截, 内容=该文档已由编制负责人认领。本次调整需拍板提案 [prop_feasibility_reg_1788843975773822000]，确认后方可覆写更新。
|
||||
--- PASS: TestE2E_ClaimedDocument_SSE_Interception (0.01s)
|
||||
```
|
||||
- **判定**：PASS。文档认领后上游发生变化时，SSE 管道未发生静默覆写，而是向客户端主动发射了 `governance` 事件与 `summary` 进展摘要，完美契合低认知负荷要求。
|
||||
|
||||
### 3. 会话流式长连接 (TestE2E_ChatSSEStreamPipeline)
|
||||
```
|
||||
=== RUN TestE2E_ChatSSEStreamPipeline
|
||||
--- PASS: TestE2E_ChatSSEStreamPipeline (0.01s)
|
||||
```
|
||||
- **判定**：PASS。成功验证了包含 `phase`（组建小队）、`status`（意图识别）、`done` 等核心事件的正确顺序与响应头。
|
||||
|
||||
---
|
||||
|
||||
## 六、 自动化测试套件汇总 (Test Suite Execution)
|
||||
|
||||
运行全量回归测试命令：`go test -v ./...`
|
||||
```
|
||||
ok chat-agent-system/cmd/bizdev-cli (cached)
|
||||
ok chat-agent-system/internal/agent (cached)
|
||||
ok chat-agent-system/internal/bizdev 4.400s
|
||||
ok chat-agent-system/internal/chat 1.832s
|
||||
ok chat-agent-system/internal/config (cached)
|
||||
ok chat-agent-system/internal/coordinator 3.721s
|
||||
ok chat-agent-system/internal/ctxmgr (cached)
|
||||
ok chat-agent-system/internal/docgov (cached)
|
||||
ok chat-agent-system/internal/intent (cached)
|
||||
ok chat-agent-system/internal/kb (cached)
|
||||
ok chat-agent-system/internal/quote (cached)
|
||||
ok chat-agent-system/internal/server 0.474s
|
||||
ok chat-agent-system/internal/squad 2.901s
|
||||
ok chat-agent-system/internal/storage (cached)
|
||||
ok chat-agent-system/internal/stream 1.261s
|
||||
ok chat-agent-system/internal/template (cached)
|
||||
```
|
||||
- **总包通过率**：16 / 16 (100% 通过)
|
||||
- **编译检查**：`go build ./cmd/server` 零警告零错误顺利产出可执行文件
|
||||
|
||||
---
|
||||
|
||||
## 七、 测试结论与后续优化建议 (Conclusion & Next Steps)
|
||||
|
||||
### 1. 测试结论
|
||||
本轮测试全面覆盖了 **选项一（HTTP API 与 SSE 流式长连接多级上下文集成）** 与 **受控文档治理生命周期** 的端到端协同。
|
||||
1. **API 接口健全完整**：新增的 9 个 RESTful 端点涵盖上下文偏好画像管理、受控文档状态查询、非模板查阅认领、提案拍板、驳回退回与全生命周期审计流；
|
||||
2. **SSE 体验低负荷**：流式推送精简高效，剔除冗长内部推演杂音，核心突出阶段推进与任务摘要；在文档拦截时以高亮事件通知前端，闭环交互顺畅；
|
||||
3. **质量指标全面达标**：全量单元与端到端集成测试通过率达到 100%，具备部署到测试环境或供 Web 前端联调的标准。
|
||||
|
||||
### 2. 后续规划建议
|
||||
- **演进方向 A**：为 Web 前端提供标准化 TypeScript SDK / React Hook，便于极速接入 SSE 事件总线与文档治理卡片组件；
|
||||
- **演进方向 B（选项三）**：开启全流程业务成熟度贯通演练（V0.1 意图沟通 -> V0.5 可行性与型检 -> V1.0 研发立项与 CDO 商务报价），结合刚落地的轻量 SSE 进度摘要与文档治理闭环，进行全局自动化贯通。
|
||||
Reference in New Issue
Block a user