diff --git a/.doc/test-reports/2026-09-08-http-api-sse-context-integration-test-report.md b/.doc/test-reports/2026-09-08-http-api-sse-context-integration-test-report.md new file mode 100644 index 00000000..8ae6a19a --- /dev/null +++ b/.doc/test-reports/2026-09-08-http-api-sse-context-integration-test-report.md @@ -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: \ndata: \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 进度摘要与文档治理闭环，进行全局自动化贯通。