Develop/AIclinicalresearch
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1b53ab9d52f6dff1d1c6c4320b5b9a12dc423141
AIclinicalresearch/docs/_templates/API设计-模板.md
HaHafeng 1b53ab9d52 feat(aia): Complete AIA V2.0 with universal streaming capabilities 
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%)
2026-01-14 19:15:01 +08:00

488 lines
8.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# [璅∪<E79285><E288AA>滨妍] - API霈曇恣
> **<2A>箇<EFBFBD>頝臬<E9A09D>嚗?* `/api/v1/璅∪<E79285><E288AA>崾
> **蝡舐<E89DA1><E88890>圈<EFBFBD>嚗?* X銝?
> **霈方<E99C88>閬<EFBFBD><E996AC>嚗?* JWT Token
> **<2A><><EFBFBD>擧凒<E693A7>堆<EFBFBD>** YYYY-MM-DD
---
## <20><> API璁<49><E79281>
| 蝡舐<E89DA1> | <20>寞<EFBFBD> | 霂湔<E99C82> | 霈方<E99C88> |
|------|------|------|------|
| `/api/v1/xxx/resources` | GET | <20>瑕<EFBFBD>韏<EFBFBD><E99F8F><EFBFBD>𡑒” | <20>?|
| `/api/v1/xxx/resources/:id` | GET | <20>瑕<EFBFBD>韏<EFBFBD><E99F8F>霂行<E99C82> | <20>?|
| `/api/v1/xxx/resources` | POST | <20>𥕦遣韏<E981A3><E99F8F> | <20>?|
| `/api/v1/xxx/resources/:id` | PUT | <20>湔鰵韏<E9B0B5><E99F8F> | <20>?|
| `/api/v1/xxx/resources/:id` | DELETE | <20>𣳇膄韏<E88684><E99F8F> | <20>?|
---
## <20><> API霂衣<E99C82>霈曇恣
### 1. <20>瑕<EFBFBD>韏<EFBFBD><E99F8F><EFBFBD>𡑒”
**蝡舐<E89DA1>嚗?* `GET /api/v1/xxx/resources`
**<EFBFBD>券<EFBFBD>䈑<EFBFBD>** <20>瑕<EFBFBD>敶枏<E695B6><E69E8F>冽<EFBFBD><E586BD><EFBFBD><EFBFBD>皞𣂼<E79A9E>銵剁<E98AB5><E58981><EFBFBD>△嚗?
**霂瑟<E99C82><E7919F><EFBFBD>㺭嚗?*
**Query<72><79>㺭嚗?*
```typescript
{
page?: number; // 憿萇<E686BF>嚗屸<E59A97>霈?
pageSize?: number; // 瘥誯△<E8AAAF>圈<EFBFBD>嚗屸<E59A97>霈?0嚗峕<E59A97>憭?00
status?: string; // 蝑偦<E89D91>㚁<EFBFBD><E39A81>嗆<EFBFBD><E59786><EFBFBD>active/inactive嚗?
keyword?: string; // <20>𦦵揣<F0A6A6B5>喲睸霂?
sortBy?: string; // <20>鍦<EFBFBD>摮埈挾嚗ẾreatedAt/updatedAt嚗?
sortOrder?: 'asc' | 'desc'; // <20>鍦<EFBFBD><E98DA6>孵<EFBFBD>嚗屸<E59A97>霈千esc
}
```
**霂瑟<E99C82>蝷箔<E89DB7>嚗?*
```bash
GET /api/v1/xxx/resources?page=1&pageSize=10&status=active
Authorization: Bearer <token>
```
**<EFBFBD>𣂼<EFBFBD><EFBFBD>滚<EFBFBD>嚗?* `200 OK`
```json
{
"success": true,
"data": {
"items": [
{
"id": 1,
"userId": 123,
"fieldName": "蝷箔<E89DB7>",
"description": "<22>讛膩",
"status": "active",
"createdAt": "2025-11-06T10:00:00.000Z",
"updatedAt": "2025-11-06T10:00:00.000Z"
}
],
"pagination": {
"page": 1,
"pageSize": 10,
"total": 100,
"totalPages": 10
}
},
"message": "<22>瑕<EFBFBD><E79195>𣂼<EFBFBD>"
}
```
**<EFBFBD>躰秤<EFBFBD>滚<EFBFBD>嚗?*
```json
// 401 Unauthorized
{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "<22>芣<EFBFBD><E88AA3><EFBFBD><EFBFBD>霂瑕<E99C82><E79195>餃<EFBFBD>"
}
}
// 400 Bad Request
{
"success": false,
"error": {
"code": "INVALID_PARAMS",
"message": "<22><>㺭<EFBFBD>躰秤",
"details": [
{ "field": "pageSize", "message": "<22><>憭找<E686AD><E689BE>質<EFBFBD>餈?00" }
]
}
}
```
---
### 2. <20>瑕<EFBFBD>韏<EFBFBD><E99F8F>霂行<E99C82>
**蝡舐<E89DA1>嚗?* `GET /api/v1/xxx/resources/:id`
**<EFBFBD>券<EFBFBD>䈑<EFBFBD>** <20>瑕<EFBFBD><E79195><EFBFBD><EFBFBD>韏<EFBFBD><E99F8F><EFBFBD><EFBFBD>祕蝏<E7A595>縑<EFBFBD>?
**頝臬<E9A09D><E887AC><EFBFBD>㺭嚗?*
- `id` (敹<>‵): 韏<><E99F8F>ID
**霂瑟<E99C82>蝷箔<E89DB7>嚗?*
```bash
GET /api/v1/xxx/resources/123
Authorization: Bearer <token>
```
**<EFBFBD>𣂼<EFBFBD><EFBFBD>滚<EFBFBD>嚗?* `200 OK`
```json
{
"success": true,
"data": {
"id": 123,
"userId": 456,
"fieldName": "蝷箔<E89DB7>",
"description": "霂衣<E99C82><E8A1A3>讛膩",
"status": "active",
"createdAt": "2025-11-06T10:00:00.000Z",
"updatedAt": "2025-11-06T10:00:00.000Z",
// 憸嘥<E686B8><E598A5><EFBFBD><EFBFBD><EFBFBD>娍㺭<E5A88D>?
"user": {
"id": 456,
"name": "<22>冽<EFBFBD><E586BD>?
}
},
"message": "<EFBFBD>瑕<EFBFBD><EFBFBD>𣂼<EFBFBD>"
}
```
**<EFBFBD>躰秤<EFBFBD>滚<EFBFBD>嚗?*
```json
// 404 Not Found
{
"success": false,
"error": {
"code": "NOT_FOUND",
"message": "韏<><E99F8F>銝滚<E98A9D><E6BB9A>?
}
}
// 403 Forbidden
{
"success": false,
"error": {
"code": "FORBIDDEN",
"message": "<EFBFBD>䭾<EFBFBD>霈輸䔮甇方<EFBFBD>皞?
}
}
```
---
### 3. <20>𥕦遣韏<E981A3><E99F8F>
**蝡舐<E89DA1>嚗?* `POST /api/v1/xxx/resources`
**<EFBFBD>券<EFBFBD>䈑<EFBFBD>** <20>𥕦遣<F0A595A6>啗<EFBFBD>皞?
**霂瑟<E99C82>雿橒<E99BBF>**
```json
{
"fieldName": "韏<><E99F8F><EFBFBD>滨妍", // 敹<>‵嚗屸鵭摨?-200
"description": "<22>讛膩", // <20>舫<EFBFBD>㚁<EFBFBD><E39A81><EFBFBD>憭?000摮?
"status": "active" // <20>舫<EFBFBD>㚁<EFBFBD>暺䁅恕active
}
```
**撉諹<E69289>閫<EFBFBD><E996AB>嚗?*
- `fieldName`: 敹<>‵嚗?-200摮㛖泵嚗䔶<E59A97><E494B6>賢<EFBFBD><E8B3A2>怎鸌畾𠰴<E795BE>蝚?
- `description`: <20>舫<EFBFBD>㚁<EFBFBD><E39A81><EFBFBD>憭?000摮㛖泵
- `status`: <20>舫<EFBFBD>㚁<EFBFBD><E39A81>㗇<EFBFBD><E39787>潘<EFBFBD>active, inactive
**霂瑟<E99C82>蝷箔<E89DB7>嚗?*
```bash
POST /api/v1/xxx/resources
Authorization: Bearer <token>
Content-Type: application/json
{
"fieldName": "<22>啗<EFBFBD>皞?,
"description": "餈蹱糓銝<EFBFBD>銝芣鰵韏<EFBFBD><EFBFBD>"
}
```
**<EFBFBD>𣂼<EFBFBD><EFBFBD>滚<EFBFBD>嚗?* `201 Created`
```json
{
"success": true,
"data": {
"id": 124,
"userId": 456,
"fieldName": "<22>啗<EFBFBD>皞?,
"description": "餈蹱糓銝<EFBFBD>銝芣鰵韏<EFBFBD><EFBFBD>",
"status": "active",
"createdAt": "2025-11-06T10:00:00.000Z",
"updatedAt": "2025-11-06T10:00:00.000Z"
},
"message": "<EFBFBD>𥕦遣<EFBFBD>𣂼<EFBFBD>"
}
```
**<EFBFBD>躰秤<EFBFBD>滚<EFBFBD>嚗?*
```json
// 422 Unprocessable Entity
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "<22><>㺭撉諹<E69289>憭梯揖",
"details": [
{ "field": "fieldName", "message": "摮埈挾<E59F88>滨妍銝滩<E98A9D>銝箇征" },
{ "field": "fieldName", "message": "摮埈挾<E59F88>滨妍<E6BBA8>踹漲敹<E6BCB2>◆<EFBFBD>?-200銋钅𡢿" }
]
}
}
// 409 Conflict
{
"success": false,
"error": {
"code": "ALREADY_EXISTS",
"message": "霂亥<E99C82>皞𣂼歇摮睃銁"
}
}
```
---
### 4. <20>湔鰵韏<E9B0B5><E99F8F>
**蝡舐<E89DA1>嚗?* `PUT /api/v1/xxx/resources/:id`
**<EFBFBD>券<EFBFBD>䈑<EFBFBD>** <20>湔鰵<E6B994><E9B0B5><EFBFBD>韏<EFBFBD><E99F8F>嚗<EFBFBD><E59A97><EFBFBD>湔凒<E6B994>堆<EFBFBD>
**頝臬<E9A09D><E887AC><EFBFBD>㺭嚗?*
- `id` (敹<>‵): 韏<><E99F8F>ID
**霂瑟<E99C82>雿橒<E99BBF>**
```json
{
"fieldName": "<22>湔鰵<E6B994>𡒊<EFBFBD><F0A1928A>滨妍",
"description": "<22>湔鰵<E6B994>𡒊<EFBFBD><F0A1928A>讛膩",
"status": "inactive"
}
```
**霂瑟<E99C82>蝷箔<E89DB7>嚗?*
```bash
PUT /api/v1/xxx/resources/123
Authorization: Bearer <token>
Content-Type: application/json
{
"fieldName": "<22>湔鰵<E6B994>𡒊<EFBFBD><F0A1928A>滨妍",
"description": "<22>湔鰵<E6B994>𡒊<EFBFBD><F0A1928A>讛膩"
}
```
**<EFBFBD>𣂼<EFBFBD><EFBFBD>滚<EFBFBD>嚗?* `200 OK`
```json
{
"success": true,
"data": {
"id": 123,
"fieldName": "<22>湔鰵<E6B994>𡒊<EFBFBD><F0A1928A>滨妍",
"description": "<22>湔鰵<E6B994>𡒊<EFBFBD><F0A1928A>讛膩",
"updatedAt": "2025-11-06T11:00:00.000Z"
},
"message": "<22>湔鰵<E6B994>𣂼<EFBFBD>"
}
```
**<EFBFBD>躰秤<EFBFBD>滚<EFBFBD>嚗?*
```json
// 404 Not Found
{
"success": false,
"error": {
"code": "NOT_FOUND",
"message": "韏<><E99F8F>銝滚<E98A9D><E6BB9A>?
}
}
// 403 Forbidden
{
"success": false,
"error": {
"code": "FORBIDDEN",
"message": "<EFBFBD>䭾<EFBFBD>靽格㺿甇方<EFBFBD>皞?
}
}
```
---
### 5. <20>𣳇膄韏<E88684><E99F8F>
**蝡舐<E89DA1>嚗?* `DELETE /api/v1/xxx/resources/:id`
**<EFBFBD>券<EFBFBD>䈑<EFBFBD>** <20>𣳇膄<F0A3B387><E88684><EFBFBD>韏<EFBFBD><E99F8F>嚗<EFBFBD>蔓<EFBFBD>𣳇膄嚗?
**頝臬<E9A09D><E887AC><EFBFBD>㺭嚗?*
- `id` (敹<>‵): 韏<><E99F8F>ID
**霂瑟<E99C82>蝷箔<E89DB7>嚗?*
```bash
DELETE /api/v1/xxx/resources/123
Authorization: Bearer <token>
```
**<EFBFBD>𣂼<EFBFBD><EFBFBD>滚<EFBFBD>嚗?* `200 OK`
```json
{
"success": true,
"data": null,
"message": "<22>𣳇膄<F0A3B387>𣂼<EFBFBD>"
}
```
**<EFBFBD>躰秤<EFBFBD>滚<EFBFBD>嚗?*
```json
// 404 Not Found
{
"success": false,
"error": {
"code": "NOT_FOUND",
"message": "韏<><E99F8F>銝滚<E98A9D><E6BB9A>?
}
}
// 403 Forbidden
{
"success": false,
"error": {
"code": "FORBIDDEN",
"message": "<EFBFBD>䭾<EFBFBD><EFBFBD>𣳇膄甇方<EFBFBD>皞?
}
}
// 409 Conflict
{
"success": false,
"error": {
"code": "CANNOT_DELETE",
"message": "霂亥<EFBFBD>皞鞉<EFBFBD><EFBFBD>唾<EFBFBD><EFBFBD>唳旿嚗峕<EFBFBD>瘜訫<EFBFBD><EFBFBD>?
}
}
```
---
## <20><> 霈方<E99C88>銝擧<E98A9D><E693A7>?
### 霈方<E99C88><E696B9>孵<EFBFBD>
<EFBFBD><EFBFBD><EFBFBD>𡅅PI<EFBFBD>賡<EFBFBD>閬<EFBFBD>WT Token霈方<E99C88>嚗?
```
Authorization: Bearer <token>
```
### <20><><EFBFBD>璉<EFBFBD><E79289>?
- <20>冽<EFBFBD><E586BD>芾<EFBFBD>霈輸䔮<E8BCB8>芸楛<E88AB8><E6A59B><EFBFBD>皞?
- ADMIN閫坿𠧧<E59DBF>臭誑霈輸䔮<E8BCB8><E494AE><EFBFBD>㕑<EFBFBD>皞?
---
## <20><> <20>躰秤<E8BAB0><E7A7A4><EFBFBD><EFBFBD>?
| <20>躰秤<E8BAB0>?| HTTP<54>嗆<EFBFBD>?| 霂湔<E99C82> |
|--------|---------|------|
| UNAUTHORIZED | 401 | <20>芣<EFBFBD><E88AA3>?|
| FORBIDDEN | 403 | <20>䭾<EFBFBD><E4ADBE>?|
| NOT_FOUND | 404 | 韏<><E99F8F>銝滚<E98A9D><E6BB9A>?|
| VALIDATION_ERROR | 422 | <20><>㺭撉諹<E69289>憭梯揖 |
| ALREADY_EXISTS | 409 | 韏<><E99F8F>撌脣<E6928C><E884A3>?|
| INTERNAL_ERROR | 500 | <20>滚𦛚<E6BB9A>券<EFBFBD>霂?|
---
## <20><> 雿輻鍂蝷箔<E89DB7>
### JavaScript/TypeScript
```typescript
// <20>瑕<EFBFBD>韏<EFBFBD><E99F8F><EFBFBD>𡑒”
const response = await fetch('/api/v1/xxx/resources?page=1&pageSize=10', {
headers: {
'Authorization': `Bearer ${token}`,
},
});
const data = await response.json();
// <20>𥕦遣韏<E981A3><E99F8F>
const response = await fetch('/api/v1/xxx/resources', {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
fieldName: '<27>啗<EFBFBD>皞?,
description: '<EFBFBD>讛膩',
}),
});
```
### cURL
```bash
# <20>瑕<EFBFBD><E79195>𡑒”
curl -X GET "http://localhost:3001/api/v1/xxx/resources?page=1&pageSize=10" \
-H "Authorization: Bearer <token>"
# <20>𥕦遣韏<E981A3><E99F8F>
curl -X POST "http://localhost:3001/api/v1/xxx/resources" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"fieldName":"<22>啗<EFBFBD>皞?,"description":"<22>讛膩"}'
```
---
## <20>𩤃<EFBFBD> 瘜冽<E7989C>鈭钅★
**<EFBFBD>扯<EFBFBD>隡睃<EFBFBD>嚗?*
- <20>𡑒”<F0A19192>亙藁敹<E89781>◆<EFBFBD>舀<EFBFBD><E88880><EFBFBD>△嚗屸<E59A97>霈小ageSize=10嚗峕<E59A97>憭?00
- <20>踹<EFBFBD>餈𥪜<E9A488>餈<EFBFBD><E9A488><EFBFBD>唾<EFBFBD><E594BE>唳旿嚗峕<E59A97><E5B395><EFBFBD><EFBFBD>㰘蝸
- 憭折<E686AD><E68A98>唳旿撖澆枂雿輻鍂撘<E98D82>郊隞餃𦛚
**摰匧<E691B0><E58CA7>改<EFBFBD>**
- <20><><EFBFBD>㗇𦻖<E39787><F0A6BB96><EFBFBD>憿駁<E686BF>霂<EFBFBD>WT Token
- 敹<>◆璉<E29786><E79289>亥<EFBFBD>皞𣂼<E79A9E>撅痹<E69285><E797B9>冽<EFBFBD><E586BD>芾<EFBFBD><E88ABE>滢<EFBFBD><E6BBA2>芸楛<E88AB8><E6A59B><EFBFBD>皞琜<E79A9E>
- <20>𤩺<EFBFBD>摮埈挾銝滩<E98A9D>餈𥪜<E9A488>嚗<EFBFBD><E59A97>撖<EFBFBD><E69296>嚗?
**<EFBFBD>穃<EFBFBD><EFBFBD>澆捆嚗?*
- API<50>䀹凒雿輻鍂<E8BCBB><E98D82>𧋦<EFBFBD>瘀<EFBFBD>/api/v2嚗?
- 銝滩<E98A9D><E6BBA9>𣳇膄撌脫<E6928C>摮埈挾嚗<E68CBE>蘨<EFBFBD>賣<EFBFBD>霈唬蛹deprecated
- <20>啣<EFBFBD>摮埈挾敹<E68CBE>◆<EFBFBD>厰<EFBFBD>霈文<E99C88>?
---
## <20><> <20>詨<EFBFBD><E8A9A8><EFBFBD>﹝
**閫<><E996AB>嚗?*
- [API霈曇恣閫<EFBFBD><EFBFBD>](../../04-撘<><E69298>𤏸<EFBFBD><F0A48FB8>?02-API霈曇恣閫<E681A3><E996AB>.md)
- [API頝舐眏<EFBFBD>餉<EFBFBD>](../../04-撘<><E69298>𤏸<EFBFBD><F0A48FB8>?04-API頝舐眏<E88890>餉<EFBFBD>.md)
**<EFBFBD>唳旿摨橒<EFBFBD>**
- [<EFBFBD>祆芋<EFBFBD>埈㺭<EFBFBD>桀<EFBFBD>霈曇恣](./01-<2D>唳旿摨栞挽霈?md)
---
**<EFBFBD><EFBFBD><EFBFBD>擧凒<EFBFBD>堆<EFBFBD>** YYYY-MM-DD
**蝏湔擪鈭綽<E988AD>** <20><><EFBFBD>舀沲<E88880><E6B2B2><EFBFBD>
Reference in New Issue View Git Blame Copy Permalink