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

2026-04-19 21:47:08 +08:00
parent 3ab6fe6504
commit 34346be862
202 changed files with 23544 additions and 0 deletions
@@ -0,0 +1,142 @@
+# API 契约
+
+**文档版本**: 1.0.0
+**最后更新**: 2026-04-19
+
+---
+
+## 1. 通用规范
+
+| 规范项 | 规则 |
+|--------|------|
+| **基础路径** | `/api/v1` |
+| **协议** | HTTPS（所有接口强制 HTTPS） |
+| **时间格式** | ISO 8601（示例：`2026-04-15T14:30:00Z`） |
+| **字符编码** | UTF-8 |
+| **分页参数** | `?page=1&per_page=50`（默认 50，最大 200） |
+
+### 1.1 认证方式
+
+| 接口类别 | 认证方式 | 说明 |
+|----------|----------|------|
+| <!-- 类别1 --> | <!-- 方式 --> | <!-- 说明 --> |
+| <!-- 类别2 --> | <!-- 方式 --> | <!-- 说明 --> |
+
+---
+
+## 2. 通用响应格式
+
+### 2.1 成功响应
+
+```json
+{
+    "data": {
+        "key": "value"
+    },
+    "meta": {
+        "request_id": "550e8400-e29b-41d4-a716-446655440000"
+    }
+}
+```
+
+### 2.2 错误响应
+
+```json
+{
+    "error": {
+        "code": "ERROR_CODE",
+        "message": "用户可读的错误描述"
+    },
+    "meta": {
+        "request_id": "550e8400-e29b-41d4-a716-446655440000"
+    }
+}
+```
+
+### 2.3 分页响应
+
+```json
+{
+    "data": [],
+    "meta": {
+        "total": 100,
+        "page": 1,
+        "per_page": 50,
+        "request_id": "550e8400-e29b-41d4-a716-446655440000"
+    }
+}
+```
+
+---
+
+## 3. HTTP 状态码
+
+| 状态码 | 场景 |
+|--------|------|
+| 200 | 成功 |
+| 201 | 创建成功 |
+| 204 | 删除成功（无响应体） |
+| 400 | 请求参数错误 |
+| 401 | 未认证 |
+| 403 | 未授权 |
+| 404 | 资源不存在 |
+| 409 | 冲突 |
+| 429 | 请求过于频繁 |
+| 500 | 服务端内部错误 |
+
+---
+
+## 4. 错误码规范
+
+| 范围 | 错误码 | 说明 |
+|------|--------|------|
+| `AUTH_*` | <!-- 错误码 --> | 认证相关 |
+| `VALIDATION_*` | <!-- 错误码 --> | 验证相关 |
+| <!-- 范围 --> | <!-- 错误码 --> | <!-- 说明 --> |
+
+---
+
+## 5. 接口定义
+
+<!-- 按以下模板为每个接口编写定义 -->
+
+### 5.1 <!-- HTTP方法 --> <!-- 路径 --> -- <!-- 接口说明 -->
+
+**请求：**
+
+```json
+{
+    "field": "value"
+}
+```
+
+**响应 <!-- 状态码 -->：**
+
+```json
+{
+    "data": {},
+    "meta": {
+        "request_id": "550e8400-e29b-41d4-a716-446655440000"
+    }
+}
+```
+
+**错误响应：**
+
+| 状态码 | 错误码 | 说明 |
+|--------|--------|------|
+| <!-- 状态码 --> | <!-- 错误码 --> | <!-- 说明 --> |
+
+---
+
+## 6. FR 映射表
+
+| FR 编号 | 功能 | 对应 API 接口 |
+|---------|------|---------------|
+| FR-001 | <!-- 功能 --> | <!-- 接口 --> |
+| FR-002 | <!-- 功能 --> | <!-- 接口 --> |
+
+---
+
+**版本历史**:
+- v1.0.0 (2026-04-19): 初始化模板