Develop/AIclinicalresearch
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(aia): Complete AIA V2.0 with universal streaming capabilities

Browse Source 
Major Changes:
- Add StreamingService with OpenAI Compatible format
- Upgrade Chat component V2 with Ant Design X integration
- Implement AIA module with 12 intelligent agents
- Update API routes to unified /api/v1 prefix
- Update system documentation

Backend (~1300 lines):
- common/streaming: OpenAI Compatible adapter
- modules/aia: 12 agents, conversation service, streaming integration
- Update route versions (RVW, PKB to v1)

Frontend (~3500 lines):
- modules/aia: AgentHub + ChatWorkspace (100% prototype restoration)
- shared/Chat: AIStreamChat, ThinkingBlock, useAIStream Hook
- Update API endpoints to v1

Documentation:
- AIA module status guide
- Universal capabilities catalog
- System overview updates
- All module documentation sync

Tested: Stream response verified, authentication working
Status: AIA V2.0 core completed (85%)
This commit is contained in:
HaHafeng
2026-01-14 19:15:01 +08:00
parent 3d35e9c58b
commit 1b53ab9d52
386 changed files with 52096 additions and 65238 deletions
Download Patch File Download Diff File Expand all files Collapse all files

194
docs/04-开发规范/02-API设计规范.md
View File

@@ -1,32 +1,32 @@
# API霈曇恣閫<E681A3><E996AB>
> **版本：** v2.0
> **<EFBFBD><EFBFBD>𧋦嚗?* v2.0
> **<2A><><EFBFBD>擧凒<E693A7>堆<EFBFBD>** 2025-11-06
> **API风格：** RESTful API
> **基础URL：** `http://localhost:3001/api/v1`
> **适用范围：** 平台层 + 能力层 + 业务模块层
> **API憌擧聢嚗?* RESTful API
> **<EFBFBD>箇<EFBFBD>URL嚗?* `http://localhost:3001/api/v1`
> **<EFBFBD><EFBFBD>鍂<EFBFBD><EFBFBD>凒嚗?* 撟喳蝱撅?+ <20>賢<EFBFBD>撅?+ 銝𡁜𦛚璅∪<E79285>撅?
---
## <20><> 霈曇恣<E69B87>笔<EFBFBD>
### API First<73>笔<EFBFBD>
- ✅ 先设计API，再实现功能
- ✅ API是前后端的契约
- ✅ API变更需要版本控制
- ✅ 所有API都要有文档
- <EFBFBD>?<3F><>挽霈，PI嚗<49><E59A97>摰䂿緵<E482BF>蠘<EFBFBD>
- <EFBFBD>?API<EFBFBD>臬<EFBFBD><EFBFBD>𡒊垢<EFBFBD><EFBFBD><EFBFBD>蝥?
- <EFBFBD>?API<EFBFBD>䀹凒<EFBFBD><EFBFBD>閬<EFBFBD><EFBFBD><EFBFBD>祆綉<EFBFBD>?
- <EFBFBD>?<3F><><EFBFBD>𡅅PI<50>質<EFBFBD><E8B3AA>㗇<EFBFBD>獢?
### RESTful霈曇恣
- ✅ 使用HTTP动词表示操作（GET、POST、PUT、DELETE）
- ✅ URL表示资源，不表示动作
- ✅ 使用复数名词表示资源集合
- ✅ 嵌套资源不超过2层
- ✅ 使用HTTP状态码表示结果
- <EFBFBD>?雿輻鍂HTTP<54>刻<EFBFBD>銵函內<E587BD>滢<EFBFBD>嚗𠃑ET<45><54>OST<53><54>UT<55><54>ELETE嚗?
- <EFBFBD>?URL銵函內韏<EFBFBD><EFBFBD>嚗䔶<EFBFBD>銵函內<EFBFBD>其<EFBFBD>
- <EFBFBD>?雿輻鍂憭齿㺭<E9BDBF>滩<EFBFBD>銵函內韏<E585A7><E99F8F><EFBFBD><EFBFBD><EFBFBD>
- <EFBFBD>?撋<><E6928B>韏<EFBFBD><E99F8F>銝滩<E98A9D>餈?撅?
- <EFBFBD>?雿輻鍂HTTP<54>嗆<EFBFBD><E59786><EFBFBD>銵函內蝏𤘪<E89D8F>
### <20>賢<EFBFBD>閫<EFBFBD><E996AB>
- ✅ URL使用小写字母和连字符（kebab-case）
- ✅ 查询参数使用驼峰命名（camelCase）
- ✅ JSON字段使用驼峰命名（camelCase）
- <EFBFBD>?URL雿輻鍂撠誩<EFBFBD>摮埈<EFBFBD><EFBFBD>諹<EFBFBD>摮㛖泵嚗ɑebab-case嚗?
- <EFBFBD>?<3F>亥砭<E4BAA5><E7A0AD>㺭雿輻鍂撽澆陸<E6BE86>賢<EFBFBD>嚗ẾamelCase嚗?
- <EFBFBD>?JSON摮埈挾雿輻鍂撽澆陸<EFBFBD>賢<EFBFBD>嚗ẾamelCase嚗?
---
@@ -37,9 +37,9 @@
```
/api/v{version}/{module}/{resource}/{id?}/{action?}
示例：
蝷箔<EFBFBD>嚗?
/api/v1/literature/projects # <20>瑕<EFBFBD><E79195><EFBFBD>讃憿寧𤌍<E5AFA7>𡑒”
/api/v1/literature/projects/123 # 获取ID=123的项目
/api/v1/literature/projects/123 # <EFBFBD>瑕<EFBFBD>ID=123<EFBFBD><EFBFBD>★<EFBFBD>?
/api/v1/literature/projects/123/export # 撖澆枂憿寧𤌍嚗<F0A48C8D>𢆡雿頣<E99BBF>
```
@@ -50,19 +50,19 @@
| 霈方<E99C88> | `/auth` | `/api/v1/auth/login` |
| <20>冽<EFBFBD> | `/users` | `/api/v1/users/me` |
| AI<41>桃<EFBFBD> | `/chat` | `/api/v1/chat/conversations` |
| 智能体 | `/agents` | `/api/v1/agents` |
| <EFBFBD>箄<EFBFBD>雿?| `/agents` | `/api/v1/agents` |
| AI<41><49>讃 | `/literature` | `/api/v1/literature/projects` |
| 知识库 | `/knowledge-bases` | `/api/v1/knowledge-bases` |
| <EFBFBD>亥<EFBFBD>摨?| `/knowledge-bases` | `/api/v1/knowledge-bases` |
| <20>唳旿皜<E697BF><E79A9C> | `/data-cleaning` | `/api/v1/data-cleaning/projects` |
| 蝏蠘恣<E8A098><E681A3><EFBFBD> | `/analysis` | `/api/v1/analysis/projects` |
| 蝏蠘恣撌亙<E6928C> | `/tools` | `/api/v1/tools` |
| 蝔蹂辣摰⊥䰻 | `/review` | `/api/v1/review/tasks` |
| LLM蝵穃<E89DB5> | `/llm` | `/api/v1/llm/chat` |
| 管理端 | `/admin` | `/api/v1/admin/users` |
| 蝞∠<EFBFBD>蝡?| `/admin` | `/api/v1/admin/users` |
### 韏<><E99F8F><EFBFBD>賢<EFBFBD>
**✅ 正确示例：**
**<EFBFBD>?甇<>＆蝷箔<E89DB7>嚗?*
```
GET /api/v1/literature/projects # <20>瑕<EFBFBD><E79195>𡑒”
GET /api/v1/literature/projects/:id # <20>瑕<EFBFBD>霂行<E99C82>
@@ -72,10 +72,10 @@ DELETE /api/v1/literature/projects/:id # 删除
GET /api/v1/literature/projects/:id/items # <20>瑕<EFBFBD>憿寧𤌍銝讠<E98A9D><E8AEA0><EFBFBD>讃
POST /api/v1/literature/projects/:id/items/import # 撖澆<E69296><E6BE86><EFBFBD>讃
POST /api/v1/literature/projects/:id/screening/execute # 执行筛选
POST /api/v1/literature/projects/:id/screening/execute # <EFBFBD>扯<EFBFBD>蝑偦<EFBFBD>?
```
**❌ 错误示例：**
**<EFBFBD>?<3F>躰秤蝷箔<E89DB7>嚗?*
```
POST /api/v1/literature/getProjects # 雿輻鍂<E8BCBB>刻<EFBFBD>
POST /api/v1/literature/createProject # 雿輻鍂<E8BCBB>刻<EFBFBD>
@@ -89,13 +89,13 @@ GET /api/v1/literatureProjectList # 驼峰命名
### <20>寞<EFBFBD>雿輻鍂
| 方法 | 用途 | 是否幂等 | 是否安全 |
| <EFBFBD>寞<EFBFBD> | <20>券<EFBFBD>?| <20>臬炏撟<E7828F><E6929F> | <20>臬炏摰匧<E691B0> |
|------|------|---------|---------|
| **GET** | 获取资源 | ✅ | ✅ |
| **POST** | 创建资源 | ❌ | ❌ |
| **PUT** | 完整更新资源 | ✅ | ❌ |
| **PATCH** | 部分更新资源 | ❌ | ❌ |
| **DELETE** | 删除资源 | ✅ | ❌ |
| **GET** | <EFBFBD>瑕<EFBFBD>韏<EFBFBD><EFBFBD> | <20>?| <20>?|
| **POST** | <EFBFBD>𥕦遣韏<EFBFBD><EFBFBD> | <20>?| <20>?|
| **PUT** | 摰峕㟲<EFBFBD>湔鰵韏<EFBFBD><EFBFBD> | <20>?| <20>?|
| **PATCH** | <EFBFBD>典<EFBFBD><EFBFBD>湔鰵韏<EFBFBD><EFBFBD> | <20>?| <20>?|
| **DELETE** | <EFBFBD>𣳇膄韏<EFBFBD><EFBFBD> | <20>?| <20>?|
### <20>寞<EFBFBD>蝷箔<E89DB7>
@@ -109,7 +109,7 @@ GET /api/v1/literature/projects/123
# <EFBFBD>𥕦遣韏<EFBFBD><EFBFBD>
POST /api/v1/literature/projects
Content-Type: application/json
{ "name": "新项目", "description": "..." }
{ "name": "<EFBFBD>圈★<EFBFBD>?, "description": "..." }
# 摰峕㟲<EFBFBD>湔鰵韏<EFBFBD><EFBFBD>嚗<EFBFBD><EFBFBD><EFBFBD>匧<EFBFBD>畾蛛<EFBFBD>
PUT /api/v1/literature/projects/123
@@ -119,7 +119,7 @@ Content-Type: application/json
# <EFBFBD>典<EFBFBD><EFBFBD>湔鰵韏<EFBFBD><EFBFBD>嚗<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>畾蛛<EFBFBD>
PATCH /api/v1/literature/projects/123
Content-Type: application/json
{ "name": "只更新名称" }
{ "name": "<EFBFBD>芣凒<EFBFBD>啣<EFBFBD>蝘? }
# <EFBFBD>𣳇膄韏<EFBFBD><EFBFBD>
DELETE /api/v1/literature/projects/123
@@ -135,15 +135,15 @@ DELETE /api/v1/literature/projects/123
|--------|------|---------|
| **200** | OK | <20>𣂼<EFBFBD>餈𥪜<E9A488><F0A5AA9C>唳旿 |
| **201** | Created | <20>𣂼<EFBFBD><F0A382BC>𥕦遣韏<E981A3><E99F8F> |
| **204** | No Content | 成功但无返回数据（如删除） |
| **204** | No Content | <EFBFBD>𣂼<EFBFBD>雿<EFBFBD><EFBFBD>餈𥪜<EFBFBD><EFBFBD>唳旿嚗<EFBFBD><EFBFBD><EFBFBD>𣳇膄嚗?|
| **400** | Bad Request | 霂瑟<E99C82><E7919F><EFBFBD>㺭<EFBFBD>躰秤 |
| **401** | Unauthorized | 未认证（没有Token或Token过期） |
| **403** | Forbidden | 无权限（已认证但权限不足） |
| **404** | Not Found | 资源不存在 |
| **409** | Conflict | 资源冲突（如重复创建） |
| **422** | Unprocessable Entity | 语义错误（如验证失败） |
| **401** | Unauthorized | <EFBFBD>芾恕霂<EFBFBD><EFBFBD>瘝⊥<EFBFBD>Token<EFBFBD>巁oken餈<EFBFBD><EFBFBD>嚗?|
| **403** | Forbidden | <EFBFBD>䭾<EFBFBD><EFBFBD>琜<EFBFBD>撌脰恕霂<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>銝滩雲嚗?|
| **404** | Not Found | 韏<EFBFBD><EFBFBD>銝滚<EFBFBD><EFBFBD>?|
| **409** | Conflict | 韏<EFBFBD><EFBFBD><EFBFBD>脩<EFBFBD>嚗<EFBFBD><EFBFBD><EFBFBD>滚<EFBFBD><EFBFBD>𥕦遣嚗?|
| **422** | Unprocessable Entity | 霂凋<EFBFBD><EFBFBD>躰秤嚗<EFBFBD><EFBFBD>撉諹<EFBFBD>憭梯揖嚗?|
| **429** | Too Many Requests | 霂瑟<E99C82>餈<EFBFBD><E9A488>憸𤑳<E686B8>嚗<EFBFBD><E59A97>瘚<EFBFBD><E7989A> |
| **500** | Internal Server Error | 服务器错误 |
| **500** | Internal Server Error | <EFBFBD>滚𦛚<EFBFBD>券<EFBFBD>霂?|
### <20>嗆<EFBFBD><E59786><EFBFBD>雿輻鍂蝷箔<E89DB7>
@@ -154,7 +154,7 @@ res.status(200).json({ success: true, data: projects });
// 201 Created - <20>𣂼<EFBFBD><F0A382BC>𥕦遣韏<E981A3><E99F8F>
res.status(201).json({ success: true, data: newProject });
// 204 No Content - 成功删除（无内容返回）
// 204 No Content - <EFBFBD>𣂼<EFBFBD><EFBFBD>𣳇膄嚗<EFBFBD><EFBFBD><EFBFBD><EFBFBD>捆餈𥪜<EFBFBD>嚗?
res.status(204).send();
// 400 Bad Request - <20><>㺭<EFBFBD>躰秤
@@ -163,22 +163,22 @@ res.status(400).json({
error: { code: 'INVALID_PARAMS', message: '<27><>㺭<EFBFBD>躰秤' }
});
// 401 Unauthorized - 未认证
// 401 Unauthorized - <EFBFBD>芾恕霂?
res.status(401).json({
success: false,
error: { code: 'UNAUTHORIZED', message: '霂瑕<E99C82><E79195>餃<EFBFBD>' }
});
// 403 Forbidden - 无权限
// 403 Forbidden - <EFBFBD>䭾<EFBFBD><EFBFBD>?
res.status(403).json({
success: false,
error: { code: 'FORBIDDEN', message: '<27>䭾<EFBFBD>霈輸䔮' }
});
// 404 Not Found - 资源不存在
// 404 Not Found - 韏<EFBFBD><EFBFBD>銝滚<EFBFBD><EFBFBD>?
res.status(404).json({
success: false,
error: { code: 'NOT_FOUND', message: '资源不存在' }
error: { code: 'NOT_FOUND', message: '韏<EFBFBD><EFBFBD>銝滚<EFBFBD><EFBFBD>? }
});
// 422 Unprocessable Entity - 撉諹<E69289>憭梯揖
@@ -196,9 +196,9 @@ res.status(422).json({
## <20><> <20>滚<EFBFBD><E6BB9A>澆<EFBFBD>閫<EFBFBD><E996AB>
### 统一响应格式 ⭐ 必须遵守
### 蝏煺<EFBFBD><EFBFBD>滚<EFBFBD><EFBFBD>澆<EFBFBD> 潃?敹<>◆<EFBFBD>萄<EFBFBD>
**成功响应：**
**<EFBFBD>𣂼<EFBFBD><EFBFBD>滚<EFBFBD>嚗?*
```json
{
"success": true,
@@ -209,7 +209,7 @@ res.status(422).json({
}
```
**错误响应：**
**<EFBFBD>躰秤<EFBFBD>滚<EFBFBD>嚗?*
```json
{
"success": false,
@@ -255,11 +255,11 @@ res.status(422).json({
"details": [
{
"field": "email",
"message": "邮箱格式不正确"
"message": "<EFBFBD>桃拳<EFBFBD>澆<EFBFBD>銝齿迤蝖?
},
{
"field": "password",
"message": "密码长度必须大于6位"
"message": "撖<EFBFBD><EFBFBD><EFBFBD>踹漲敹<EFBFBD>◆憭找<EFBFBD>6雿?
}
]
}
@@ -268,7 +268,7 @@ res.status(422).json({
---
## 🔑 认证与授权规范
## <EFBFBD><EFBFBD> 霈方<E99C88>銝擧<E98A9D><E693A7><EFBFBD><EFBFBD><EFBFBD>?
### JWT霈方<E99C88>
@@ -307,12 +307,12 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
**3. Token餈<6E><E9A488>憭<EFBFBD><E686AD>**
```http
# Token过期，返回401
# Token餈<EFBFBD><EFBFBD>嚗諹<EFBFBD><EFBFBD>?01
{
"success": false,
"error": {
"code": "TOKEN_EXPIRED",
"message": "Token已过期，请重新登录"
"message": "Token撌脰<EFBFBD><EFBFBD><EFBFBD><EFBFBD>霂琿<EFBFBD><EFBFBD>啁蒈敶?
}
}
@@ -327,23 +327,23 @@ Content-Type: application/json
### <20><><EFBFBD><EFBFBD>批<EFBFBD>
| 端点类型 | 需要认证 | 角色要求 |
| 蝡舐<EFBFBD>蝐餃<EFBFBD> | <20><>閬<EFBFBD>恕霂?| 閫坿𠧧閬<F0A0A7A7><E996AC> |
|---------|---------|---------|
| 公开端点 | ❌ | 无 |
| 用户端点 | ✅ | user |
| 管理端点 | ✅ | admin |
| <EFBFBD>砍<EFBFBD>蝡舐<EFBFBD> | <20>?| <20>?|
| <EFBFBD>冽<EFBFBD>蝡舐<EFBFBD> | <EFBFBD>?| user |
| 蝞∠<EFBFBD>蝡舐<EFBFBD> | <EFBFBD>?| admin |
**示例：**
**蝷箔<EFBFBD>嚗?*
```typescript
// 公开端点（无需认证）
// <EFBFBD>砍<EFBFBD>蝡舐<EFBFBD>嚗<EFBFBD><EFBFBD><EFBFBD><EFBFBD>霈方<EFBFBD>嚗?
POST /api/v1/auth/login
POST /api/v1/auth/register
// 用户端点（需要认证，user角色）
// <EFBFBD>冽<EFBFBD>蝡舐<EFBFBD>嚗<EFBFBD><EFBFBD>閬<EFBFBD>恕霂<EFBFBD><EFBFBD>user閫坿𠧧嚗?
GET /api/v1/literature/projects
POST /api/v1/literature/projects
// 管理端点（需要认证，admin角色）
// 蝞∠<EFBFBD>蝡舐<EFBFBD>嚗<EFBFBD><EFBFBD>閬<EFBFBD>恕霂<EFBFBD><EFBFBD>admin閫坿𠧧嚗?
GET /api/v1/admin/users
POST /api/v1/admin/users/:id/disable
```
@@ -357,11 +357,11 @@ POST /api/v1/admin/users/:id/disable
```
GET /api/v1/literature/projects?page=1&pageSize=20&sortBy=createdAt&sortOrder=desc
Query参数：
- page: 页码（默认1）
- pageSize: 每页数量（默认10，最大100）
- sortBy: 排序字段（默认createdAt）
- sortOrder: 排序方向（asc/desc，默认desc）
Query<EFBFBD><EFBFBD>㺭嚗?
- page: 憿萇<EFBFBD>嚗<EFBFBD><EFBFBD>霈?嚗?
- pageSize: 瘥誯△<EFBFBD>圈<EFBFBD>嚗<EFBFBD><EFBFBD>霈?0嚗峕<E59A97>憭?00嚗?
- sortBy: <EFBFBD>鍦<EFBFBD>摮埈挾嚗<EFBFBD><EFBFBD>霈勺reatedAt嚗?
- sortOrder: <EFBFBD>鍦<EFBFBD><EFBFBD>孵<EFBFBD>嚗Òsc/desc嚗屸<EFBFBD>霈千esc嚗?
```
### <20>滚<EFBFBD><E6BB9A>澆<EFBFBD>
@@ -387,16 +387,16 @@ Query参数：
## <20><> 蝑偦<E89D91>劐<EFBFBD><E58A90>𦦵揣閫<E68FA3><E996AB>
### 筛选参数
### 蝑偦<EFBFBD>匧<EFBFBD><EFBFBD>?
```
GET /api/v1/literature/projects?status=active&keyword=撉刻捶<E588BB>𤩺𠹭
Query参数：
- status: 状态筛选（active/inactive）
- keyword: 关键词搜索（搜索name和description字段）
Query<EFBFBD><EFBFBD>㺭嚗?
- status: <EFBFBD>嗆<EFBFBD><EFBFBD><EFBFBD><EFBFBD>㚁<EFBFBD>active/inactive嚗?
- keyword: <EFBFBD>喲睸霂齿<EFBFBD>蝝ｇ<EFBFBD><EFBFBD>𦦵揣name<EFBFBD>𩥇escription摮埈挾嚗?
- userId: <20>冽<EFBFBD>ID蝑偦<E89D91>㚁<EFBFBD>蝞∠<E89D9E>蝡荔<E89DA1>
- startDate/endDate: 日期范围筛选
- startDate/endDate: <EFBFBD>交<EFBFBD><EFBFBD><EFBFBD>凒蝑偦<EFBFBD>?
```
### <20>𦦵揣<F0A6A6B5>滚<EFBFBD>
@@ -417,29 +417,29 @@ Query参数：
---
## ⚠️ 错误码设计
## <EFBFBD>𩤃<EFBFBD> <20>躰秤<E8BAB0><E7A7A4>挽霈?
### 标准错误码
### <EFBFBD><EFBFBD><EFBFBD><EFBFBD>躰秤<EFBFBD>?
| 错误码 | HTTP状态 | 说明 |
| <EFBFBD>躰秤<EFBFBD>?| HTTP<EFBFBD>嗆<EFBFBD>?| 霂湔<E99C82> |
|--------|---------|------|
| `VALIDATION_ERROR` | 422 | <20><>㺭撉諹<E69289>憭梯揖 |
| `UNAUTHORIZED` | 401 | 未认证 |
| `UNAUTHORIZED` | 401 | <EFBFBD>芾恕霂?|
| `TOKEN_EXPIRED` | 401 | Token餈<6E><E9A488> |
| `FORBIDDEN` | 403 | 无权限 |
| `NOT_FOUND` | 404 | 资源不存在 |
| `ALREADY_EXISTS` | 409 | 资源已存在 |
| `FORBIDDEN` | 403 | <EFBFBD>䭾<EFBFBD><EFBFBD>?|
| `NOT_FOUND` | 404 | 韏<EFBFBD><EFBFBD>銝滚<EFBFBD><EFBFBD>?|
| `ALREADY_EXISTS` | 409 | 韏<EFBFBD><EFBFBD>撌脣<EFBFBD><EFBFBD>?|
| `QUOTA_EXCEEDED` | 429 | <20>漤<EFBFBD>頞<EFBFBD><E9A09E> |
| `INTERNAL_ERROR` | 500 | 服务器错误 |
| `INTERNAL_ERROR` | 500 | <EFBFBD>滚𦛚<EFBFBD>券<EFBFBD>霂?|
### 业务错误码
### 銝𡁜𦛚<EFBFBD>躰秤<EFBFBD>?
```typescript
// 模块特定错误码（前缀区分）
ASL_IMPORT_FAILED // AI文献：导入失败
// 璅∪<EFBFBD><EFBFBD>孵<EFBFBD><EFBFBD>躰秤<EFBFBD><EFBFBD><EFBFBD><EFBFBD>滨<EFBFBD><EFBFBD>箏<EFBFBD>嚗?
ASL_IMPORT_FAILED // AI<EFBFBD><EFBFBD>讃嚗𡁜紡<EFBFBD>亙仃韐?
ASL_SCREENING_IN_PROGRESS // AI<41><49>讃嚗𡁶<E59A97><F0A181B6>㕑<EFBFBD>銵䔶葉
PKB_QUOTA_EXCEEDED // <20>亥<EFBFBD>摨橒<E691A8><E6A992>漤<EFBFBD>頞<EFBFBD><E9A09E>
LLM_QUOTA_EXCEEDED // LLM：配额超限
LLM_QUOTA_EXCEEDED // LLM嚗𡁻<EFBFBD>憸肽<EFBFBD><EFBFBD>?
```
---
@@ -452,7 +452,7 @@ LLM_QUOTA_EXCEEDED // LLM：配额超限
<EFBFBD><EFBFBD><EFBFBD>匧<EFBFBD>銵冽𦻖<EFBFBD><EFBFBD><EFBFBD>憿餅𣈲<EFBFBD><EFBFBD><EFBFBD>憿蛛<EFBFBD>
- 暺䁅恕pageSize=10
- <20><>憭吠ageSize=100
- 禁止一次性返回全部数据
- 蝳<EFBFBD>迫銝<EFBFBD>甈⊥<EFBFBD>扯<EFBFBD><EFBFBD>𧼮<EFBFBD><EFBFBD>冽㺭<EFBFBD>?
```
### 2. 摮埈挾餈<E68CBE>誘
@@ -460,13 +460,13 @@ LLM_QUOTA_EXCEEDED // LLM：配额超限
```
GET /api/v1/users/me?fields=id,name,email
只返回需要的字段，减少数据传输
<EFBFBD>芾<EFBFBD><EFBFBD>鮋<EFBFBD>閬<EFBFBD><EFBFBD>摮埈挾嚗<EFBFBD><EFBFBD>撠烐㺭<EFBFBD>桐<EFBFBD>颲?
```
### 3. 蝻枏<E89DBB>蝑𣇉裦
```http
# 设置缓存头
# 霈曄蔭蝻枏<EFBFBD>憭?
Cache-Control: public, max-age=300
# 雿輻鍂ETag
@@ -477,40 +477,40 @@ If-None-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"
---
## ✅ 检查清单
## <EFBFBD>?璉<><E79289>交<EFBFBD><E4BAA4>?
**霈曇恣<E69B87>蚊PI<50>嗅<EFBFBD>憿餅<E686BF><E9A485>伐<EFBFBD>**
- [ ] URL符合RESTful规范（使用名词+复数）
- [ ] 使用正确的HTTP方法（GET/POST/PUT/DELETE）
- [ ] URL蝚血<EFBFBD>RESTful閫<EFBFBD><EFBFBD>嚗<EFBFBD>蝙<EFBFBD>典<EFBFBD>霂?憭齿㺭嚗?
- [ ] 雿輻鍂甇<EFBFBD>＆<EFBFBD><EFBFBD>TTP<EFBFBD>寞<EFBFBD>嚗𠃑ET/POST/PUT/DELETE嚗?
- [ ] 雿輻鍂甇<E98D82>＆<EFBFBD><EFBC86>TTP<54>嗆<EFBFBD><E59786><EFBFBD>
- [ ] 响应格式符合统一规范（success + data/error）
- [ ] <EFBFBD>滚<EFBFBD><EFBFBD>澆<EFBFBD>蝚血<EFBFBD>蝏煺<EFBFBD>閫<EFBFBD><EFBFBD>嚗ìuccess + data/error嚗?
- [ ] <20><>閬<EFBFBD>恕霂<E68195><E99C82><EFBFBD>亙藁璉<E89781><E79289>仔WT Token
- [ ] 需要权限的接口检查用户角色
- [ ] <EFBFBD><EFBFBD>閬<EFBFBD><EFBFBD><EFBFBD>鞟<EFBFBD><EFBFBD>亙藁璉<EFBFBD><EFBFBD>亦鍂<EFBFBD>瑁<EFBFBD><EFBFBD>?
- [ ] <20>𡑒”<F0A19192>亙藁<E4BA99>舀<EFBFBD><E88880><EFBFBD>△
- [ ] <20>𡑒”<F0A19192>亙藁<E4BA99>舀<EFBFBD><E88880>鍦<EFBFBD>
- [ ] 错误响应包含明确的错误码和错误信息
- [ ] <EFBFBD>躰秤<EFBFBD>滚<EFBFBD><EFBFBD><EFBFBD>鉄<EFBFBD>𡒊＆<EFBFBD><EFBFBD><EFBFBD>霂舐<EFBFBD><EFBFBD>屸<EFBFBD>霂臭縑<EFBFBD>?
- [ ] <20><><EFBFBD>𡅅PI<50>賣<EFBFBD><E8B3A3><EFBFBD>﹝霂湔<E99C82>
---
## <20><> <20>詨<EFBFBD><E8A9A8><EFBFBD>﹝
**总览：**
- [API路由总览](./04-API路由总览.md) ⭐ 查看所有API端点
**<EFBFBD>餉<EFBFBD>嚗?*
- [API頝舐眏<EFBFBD>餉<EFBFBD>](./04-API頝舐眏<EFBFBD>餉<EFBFBD>.md) 潃?<3F>亦<EFBFBD><E4BAA6><EFBFBD><EFBFBD>𡅅PI蝡舐<E89DA1>
**模板：**
**璅⊥踎嚗?*
- [API霈曇恣璅⊥踎](../_templates/API霈曇恣-璅⊥踎.md)
**<EFBFBD><EFBFBD>芋<EFBFBD>𡑒挽霈∴<EFBFBD>**
- [平台基础层](../01-平台基础层/README.md)
- [通用能力层](../02-通用能力层/README.md)
- [撟喳蝱<EFBFBD>箇<EFBFBD>撅<EFBFBD>(../01-撟喳蝱<E596B3>箇<EFBFBD>撅?README.md)
- [<EFBFBD>𡁶鍂<EFBFBD>賢<EFBFBD>撅<EFBFBD>(../02-<2D>𡁶鍂<F0A181B6>賢<EFBFBD>撅?README.md)
- [銝𡁜𦛚璅∪<E79285>撅<EFBFBD>(../03-銝𡁜𦛚璅∪<E79285>/README.md)
---
**<EFBFBD><EFBFBD><EFBFBD>擧凒<EFBFBD>堆<EFBFBD>** 2025-11-06
**蝏湔擪鈭綽<E988AD>** <20><><EFBFBD>舀沲<E88880><E6B2B2><EFBFBD>
**版本：** v2.0
**<EFBFBD><EFBFBD>𧋦嚗?* v2.0