# NebulaKB Reliability Acceptance Plan

本计划用于把 NebulaKB 从“能用”推进到“可靠”。执行优先级是：先锁定最小验收闭环，再用四层测试体系覆盖高风险模块，最后用 CI、发布清单和非功能测试让风险在发布前可见。

## 1. 最小验收闭环

每次发布至少要跑通这条链路：

登录 -> 知识库 -> 上传 -> 检索 -> 应用 -> 权限 -> API Key

| 环节 | 必测结果 | 阻断条件 |
| --- | --- | --- |
| 登录 | 正确账号可登录并生成 token；错误账号拒绝；失败次数、验证码、锁定策略生效 | 登录绕过、弱 token、退出后 token 仍可用 |
| 知识库 | 可创建知识库并绑定模型/向量配置；跨工作空间数据不可见 | 知识库越权读取或删除 |
| 上传 | 支持文件可上传、解析、切片并进入异步任务；非法类型和超限文件被拒绝 | 文件上传导致 500、路径穿越、任务永久卡住 |
| 检索 | embedding/keywords/blend 检索返回正确知识范围；空知识库返回可解释结果 | 检索泄露其他知识库段落 |
| 应用 | 应用可绑定知识库并执行默认工作流；失败时有可追踪错误 | 工作流吞错、循环失控、错误无日志 |
| 权限 | 普通用户只能访问授权资源；管理员可管理工作空间资源 | 未授权用户可查看/修改/删除资源 |
| API Key | 可创建、禁用、过期、撤销；公开接口正确校验 Key 与权限 | 过期/撤销 Key 仍可调用，或无权限调用成功 |

## 2. 四层测试体系

| 层级 | 目标 | 当前入口 | 第一阶段重点 |
| --- | --- | --- | --- |
| 单元测试 | 快速验证纯逻辑、序列化器、权限判断、token 生成、文件校验 | `python apps/manage.py test apps.users apps.tools` | 认证、token、MCP 工具配置、文件校验 |
| 集成测试 | 验证数据库、缓存、向量检索、异步任务、模型/知识库组合 | `python apps/manage.py test apps.users.tests.LoginSerializerTests apps.knowledge.tests.KnowledgeRetrievalTests apps.tools.tests.ToolConnectionTests` | 登录缓存、知识检索、工具连接 |
| API 回归 | 固定公开接口契约、状态码、错误体、鉴权头、API Key 调用方式 | `python apps/manage.py test apps.chat apps.application` | chat、应用访问 token、API Key |
| E2E | 覆盖真实用户路径和浏览器状态 | 待接入 Playwright | 登录 -> 上传知识 -> 检索 -> 创建应用 -> 用 API Key 调用 |

测试用例必须遵循 AAA：Arrange 准备数据，Act 执行动作，Assert 验证结果。CSV 只记录执行状态，测试步骤以本文档和后续测试用例文档为准。

## 3. 高风险模块优先级

| 优先级 | 模块 | 风险 | 必补测试 |
| --- | --- | --- | --- |
| P0 | 认证与登录 | 登录绕过、弱锁定、token 未失效 | 成功/失败登录、锁定、验证码、退出失效 |
| P0 | 权限体系 | 工作空间/资源越权 | 不同角色读取、编辑、删除、跨空间访问 |
| P0 | API Key / Access Token | 公开接口被滥用 | 创建、禁用、过期、撤销、无权限调用 |
| P0 | 文件上传 | 大文件、恶意文件、路径穿越 | 类型、大小、解析失败、重复上传、任务状态 |
| P1 | 知识检索 | 命中错误、跨知识库泄露 | embedding/keywords/blend、空结果、排除文档 |
| P1 | 工作流执行 | 循环、节点异常、外部工具失败 | 默认工作流、工具节点、异常节点、超时 |
| P1 | 公开接口 | 状态码/错误体漂移 | OpenAPI 契约、鉴权头、限流、错误结构 |

## 4. 覆盖率推进

采用 ratchet 模式，只升不降：

| 阶段 | CI 门槛 | 范围 | 进入下一阶段条件 |
| --- | --- | --- | --- |
| Stage 1 | 50% | 已进入质量门禁的核心风险模块 | smoke、API 回归、auth、permission 均可稳定通过 |
| Stage 2 | 60% | 增加应用、API Key、文件上传、工作流执行 | 新增关键路径测试不少于 20 个，P0/P1 缺陷清零 |
| Stage 3 | 核心模块 70%+ | 认证、权限、token、上传、公开接口、工作流 | 发布前质量报告可预测主要风险 |

规则：

- 新增高风险代码必须同时新增测试或在 PR 中说明不能自动化的原因。
- 核心模块覆盖率不能比主分支下降。
- 覆盖率不替代关键路径测试；登录到 API Key 的闭环必须显式跑通。

## 5. 非功能测试

| 类型 | 场景 | 通过标准 |
| --- | --- | --- |
| 并发压测 | 登录、上传、chat/API Key 调用、检索同时发生 | p95 延迟和错误率在发布阈值内，无连接池耗尽 |
| 大文件 | 50MB、100MB、500MB 文件上传和解析 | 超限明确拒绝，允许范围内任务可完成或可重试 |
| 长文本 | 超长段落、超长问题、模型上下文边界 | 切片稳定，token 计算不崩溃，错误可解释 |
| 异步队列积压 | 批量上传/解析、工作流任务堆积 | 任务状态可观察，可恢复，无永久 running |
| 越权攻击 | 跨 workspace、跨资源 ID、伪造 token/API Key | 返回 401/403，不泄露资源存在性和敏感数据 |

## 6. 发布质量门禁

每次发布必须执行：

1. smoke：Django 配置检查、基础仓库 smoke。
2. API regression：chat/application/public API 契约回归。
3. auth：登录、token、退出、失败锁定。
4. permission：角色、工作空间、资源权限、越权拒绝。
5. rollback：确认镜像、数据库迁移、配置变更都有回滚路径。

推荐命令：

```bash
bash scripts/quality-gate.sh release
```

## 7. 验收标准

一个版本满足以下条件才算“可靠可发布”：

- 登录 -> 知识库 -> 上传 -> 检索 -> 应用 -> 权限 -> API Key 关键路径全覆盖。
- CI 至少能拦截认证、权限、token、上传、公开接口、工作流执行的 P0/P1 问题。
- 覆盖率进入当前阶段门槛，并且核心模块覆盖率趋势不下降。
- 发布前清单完成，有明确 rollback 方案。
- 非功能风险有结论：已通过、已豁免、或已登记为阻断缺陷。
