配置: 初始化 ISOS Agent Teams 软件研发模板

docs/测试-接口.md

@@ -0,0 +1,92 @@
+# 接口测试规范
+
+**文档版本**: 1.0.0
+**最后更新**: 2026-04-19
+
+---
+
+## 1. 概述
+
+本文档定义项目所有 API 接口的测试规范。测试按接口分组组织，与 [09-API契约.md](./09-API契约.md) 章节结构一致。
+
+### 1.1 测试目标
+
+| 目标 | 说明 |
+|------|------|
+| **契约一致性** | 验证所有接口的请求/响应格式与 API 契约完全一致 |
+| **状态码正确性** | 验证每个接口在各种场景下返回正确的 HTTP 状态码 |
+| **错误码准确性** | 验证错误响应中的 code 和 message 符合错误码规范 |
+| **安全性** | 验证认证机制、权限控制和注入防护 |
+| **边界条件** | 验证空值、超长输入、特殊字符等边界场景 |
+| **性能基准** | 验证接口响应时间满足非功能性需求 |
+
+### 1.2 测试工具
+
+| 工具 | 用途 | 适用范围 |
+|------|------|----------|
+| **pytest** | 测试框架 | 全部 |
+| **httpx** | HTTP 客户端 | 全部 |
+| **faker** | 测试数据生成 | 全部 |
+
+### 1.3 HTTP 状态码速查
+
+| 状态码 | 场景 |
+|--------|------|
+| 200 | 成功 |
+| 201 | 创建成功 |
+| 204 | 删除成功（无响应体） |
+| 400 | 请求参数错误 |
+| 401 | 未认证 |
+| 403 | 权限不足 |
+| 404 | 资源不存在 |
+| 409 | 冲突 |
+| 500 | 服务端内部错误 |
+
+---
+
+## 2. 通用响应格式验证
+
+### 2.1 成功响应结构
+
+**验证点**：
+- 响应体必须包含 `data` 和 `meta` 两个顶层字段
+- `meta` 必须包含 `request_id`
+
+### 2.2 错误响应结构
+
+**验证点**：
+- 响应体必须包含 `error` 和 `meta` 两个顶层字段
+- `error` 必须包含 `code` 和 `message`
+
+### 2.3 分页响应结构
+
+**验证点**：
+- `meta` 必须包含 `total`、`page`、`per_page`
+- `data` 为数组类型
+
+---
+
+## 3. 接口测试文档索引
+
+<!-- 按接口分组拆分为独立文件后在此列出索引 -->
+
+| 文件 | 内容 | 章节来源 |
+|------|------|----------|
+| [测试-接口-分类.md](./测试-接口-分类.md) | 分类接口测试用例模板 | §3+ |
+
+---
+
+## 4. 测试文件组织结构
+
+```
+apps/<!-- 模块 -->/
+└── tests/
+    └── api/
+        ├── conftest.py          # API 公共 fixtures
+        └── <!-- test_*.py -->   # 接口测试文件
+```
+
+---
+
+**版本历史**:
+- v1.0.0 (2026-04-19): 初始化模板