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%)
This commit is contained in:
2026-01-14 19:15:01 +08:00
parent 3d35e9c58b
commit 1b53ab9d52
386 changed files with 52096 additions and 65238 deletions

View File

@@ -4,8 +4,7 @@
> **<2A><>𧋦**: V2.0 (MVP)
> **Base URL**: `/api/v1/dc/tool-b`
> **<2A>湔鰵<E6B994><EFBFBD>**: 2025-12-03
> **状态**: MVP完成8个API端点全部可用已验证
> **<EFBFBD><EFBFBD>?*: <EFBFBD>?MVP摰峕<EFBFBD>嚗?銝服PI蝡舐<E89DA1><E88890><EFBFBD><E588B8>舐鍂嚗<E98D82>歇撉諹<E69289>嚗?
---
## <20><> <20><EFBFBD>
@@ -13,8 +12,8 @@
- [<EFBFBD><EFBFBD><EFBFBD>PI璁<EFBFBD><EFBFBD>](#銝<>api璁<69><E79281>)
- [鈭䎚<EFBFBD><EFBFBD>恕霂<EFBFBD><EFBFBD><EFBFBD><EFBFBD>](#鈭諹恕霂<E68195><E99C82><EFBFBD><EFBFBD>)
- [銝剹<EFBFBD><EFBFBD>PI蝡舐<EFBFBD>霂行<EFBFBD>](#銝学pi蝡舐<E89DA1>霂行<E99C82>)
- [四、数据模型](#四数据模型)
- [五、错误处理](#五错误处理)
- [<EFBFBD><EFBFBD><EFBFBD><EFBFBD>格芋<EFBFBD>尜(#<23>𥟇㺭<F0A59F87>格芋<E6A0BC>?
- [鈭𢛵<EFBFBD><EFBFBD><EFBFBD>霂臬<EFBFBD><EFBFBD><EFBFBD>(#鈭娪<EFBFBD>霂臬<EFBFBD><EFBFBD>?
- [<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>](#<23><EFBFBD><EFBFBD><E689AF><EFBFBD><EFBFBD>)
---
@@ -23,63 +22,47 @@
### 1.1 蝡舐<E89DA1><E88890>𡑒”
| # | 方法 | 路径 | 说明 | 后端状态 | 前端状态 | 测试状态 |
| # | <EFBFBD><EFBFBD> | 頝臬<E9A09D> | 霂湔<E99C82> | <20>𡒊垢<F0A1928A><EFBFBD>?| <20>滨垢<E6BBA8><EFBFBD>?| 瘚贝<E7989A><E8B49D><EFBFBD>?|
|---|------|------|------|---------|---------|---------|
| 0 | POST | `/upload` | 文件上传 | ✅ 已完成 | ✅ 已对接 | ✅ 通过 |
| 1 | POST | `/health-check` | 健康检查 | ✅ 已完成 | ✅ 已对接 | ✅ 通过 |
| 2 | GET | `/templates` | 获取模板列表 | ✅ 已完成 | ✅ 已对接 | ✅ 通过 |
| 3 | POST | `/tasks` | 创建提取任务 | ✅ 已完成 | ✅ 已对接 | ✅ 通过 |
| 4 | GET | `/tasks/:taskId/progress` | 查询任务进度 | ✅ 已完成 | ✅ 已对接 | ✅ 通过 |
| 5 | GET | `/tasks/:taskId/items` | 获取验证网格数据 | ✅ 已完成 | ✅ 已对接 | ✅ 通过 |
| 6 | POST | `/items/:itemId/resolve` | 裁决冲突 | ✅ 已完成 | ✅ 已对接 | ✅ 通过 |
| 7 | GET | `/tasks/:taskId/export` | 导出Excel结果 | ✅ 已完成 | ✅ 已对接 | ✅ 通过 |
**✅ MVP完成状态2025-12-03**
- 后端代码:~2200行含Service、Controller、Routes
- 前端代码:~1400行5步工作流完整实现
- 数据库表4张表已创建3个预设模板已就绪
- API对接8个端点全部集成并测试通过
- LLM调用DeepSeek-V3 + Qwen-Max 双模型验证成功
- 真实测试9条病理数据提取成功Token消耗~10k
- **已知问题**4个技术债务`07-技术债务/Tool-B技术债务清单.md`
| 0 | POST | `/upload` | <EFBFBD><EFBFBD>辣銝𠹺<EFBFBD> | <20>?撌脣<E6928C><E884A3>?| <20>?撌脣笆<E884A3>?| <20>?<3F><EFBFBD> |
| 1 | POST | `/health-check` | <EFBFBD>亙熒璉<EFBFBD><EFBFBD>?| <20>?撌脣<E6928C><E884A3>?| <20>?撌脣笆<E884A3>?| <20>?<3F><EFBFBD> |
| 2 | GET | `/templates` | <EFBFBD><EFBFBD>璅⊥踎<EFBFBD>𡑒” | <20>?撌脣<E6928C><E884A3>?| <20>?撌脣笆<E884A3>?| <20>?<3F><EFBFBD> |
| 3 | POST | `/tasks` | <EFBFBD>𥕦遣<EFBFBD>𣂼<EFBFBD>隞餃𦛚 | <20>?撌脣<E6928C><E884A3>?| <20>?撌脣笆<E884A3>?| <20>?<3F><EFBFBD> |
| 4 | GET | `/tasks/:taskId/progress` | <EFBFBD>亥砭隞餃𦛚餈𥕦漲 | <20>?撌脣<E6928C><E884A3>?| <20>?撌脣笆<E884A3>?| <20>?<3F><EFBFBD> |
| 5 | GET | `/tasks/:taskId/items` | <EFBFBD><EFBFBD>撉諹<EFBFBD>蝵烐聢<EFBFBD>唳旿 | <20>?撌脣<E6928C><E884A3>?| <20>?撌脣笆<E884A3>?| <20>?<3F><EFBFBD> |
| 6 | POST | `/items/:itemId/resolve` | <EFBFBD><EFBFBD><EFBFBD><EFBFBD> | <20>?撌脣<E6928C><E884A3>?| <20>?撌脣笆<E884A3>?| <20>?<3F><EFBFBD> |
| 7 | GET | `/tasks/:taskId/export` | 撖澆枂Excel蝏𤘪<EFBFBD> | <20>?撌脣<E6928C><E884A3>?| <20>?撌脣笆<E884A3>?| <20>?<3F><EFBFBD> |
**<EFBFBD>?MVP摰峕<E691B0><E5B395><EFBFBD><E59786><EFBFBD>2025-12-03嚗?*嚗?- <20>𡒊垢隞<E59EA2><E99A9E>嚗鰺2200銵䕘<E98AB5><E49598>俟ervice<63><65>ontroller<65><72>outes嚗?- <20>滨垢隞<E59EA2><E99A9E>嚗鰺1400銵䕘<E98AB5>5甇亙極雿𨀣<E99BBF>摰峕㟲摰䂿緵嚗?- <20>唳旿摨栞”嚗?撘㰘”撌脣<E6928C>撱綽<E692B1>3銝芷<E98A9D>霈暹芋<E69AB9>踹歇撠梁貌
- API撖寞𦻖嚗?銝芰垢<E88AB0><EFBFBD><E5ADB5><EFBFBD><E588B8>𣂼僎瘚贝<E7989A><E8B49D><EFBFBD>
- LLM靚<4D>鍂嚗鋽eepSeek-V3 + Qwen-Max <20>峕芋<E5B395><EFBFBD><EFBFBD><E99C82><EFBFBD>?- <20><EFBFBD>瘚贝<E7989A>嚗?<3F><EFBFBD><E288A0><EFBFBD><EFBFBD><EFBFBD><E6A0BC>𡝗<EFBFBD><F0A19D97><EFBFBD><EFBFBD>Token瘨<6E><E798A8>煫10k
- **撌脩䰻<E884A9><EFBFBD>**嚗?銝芣<E98A9D><E88AA3><EFBFBD>箏𦛚嚗<F0A69B9A><E59A97>`07-<2D><><EFBFBD><EFBFBD>箏𦛚/Tool-B<><42><EFBFBD><EFBFBD>箏𦛚皜<F0A69B9A><E79A9C>.md`嚗?
### 1.2 <20>𡁶鍂閫<E98D82><E996AB>
**请求头**
```http
**霂瑟<EFBFBD>憭?*嚗?```http
Content-Type: application/json
Authorization: Bearer {token} # <20>芣䔉摰䂿緵
```
**响应格式**
```json
**<EFBFBD><EFBFBD><EFBFBD><EFBFBD>**嚗?```json
{
"data": {...}, // 成功时返回
"error": "...", // 失败时返回
"code": 200
"data": {...}, // <20>𣂼<EFBFBD><F0A382BC><EFBFBD><E59789>? "error": "...", // 憭梯揖<EFBFBD><EFBFBD><EFBFBD>? "code": 200
}
```
**HTTP状态码**
- `200`: 成功
**HTTP<EFBFBD><EFBFBD><EFBFBD><EFBFBD>**嚗?- `200`: <20>𣂼<EFBFBD>
- `400`: 霂瑟<E99C82><E7919F><EFBFBD><EFBFBD>躰秤
- `401`: 未认证
- `403`: 无权限
- `404`: 资源不存在
- `500`: 服务器内部错误
- `401`: <20>芾恕霂?- `403`: <20><EFBFBD><E4ADBE>?- `404`: 韏<><E99F8F>銝滚<E98A9D><E6BB9A>?- `500`: <20>滚𦛚<E6BB9A><EFBFBD><E585B8><EFBFBD>霂?
---
## 鈭䎚<E988AD><E48E9A>恕霂<E68195><E99C82><EFBFBD><EFBFBD>
### 2.1 霈方<E99C88><E696B9><EFBFBD>
**当前阶段MVP**
- ❌ 暂不实现认证
**敶枏<EFBFBD><EFBFBD>嗆挾嚗㇈VP嚗?*嚗?- <20>?<3F><><EFBFBD>摰䂿緵霈方<E99C88>
- 雿輻鍂銝湔𧒄`userId`<60><><EFBFBD><EFBFBD><E59A97>霂瑟<E99C82>銝𠹺<E98A9D><F0A0B9BA><EFBFBD><EFBFBD><EFBFBD>
**未来实现V1.0**
```http
**<EFBFBD>芣䔉摰䂿緵嚗Ā1.0嚗?*嚗?```http
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```
@@ -87,38 +70,35 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
| <20><EFBFBD> | <20><><EFBFBD><EFBFBD><E996AC> | 霂湔<E99C82> |
|------|---------|------|
| 健康检查 | user | 所有用户 |
| 查看模板 | user | 所有用户 |
| 创建任务 | user | 所有用户 |
| 查询任务 | owner | 仅任务创建者 |
| 裁决冲突 | owner | 仅任务创建者 |
| <EFBFBD>亙熒璉<EFBFBD><EFBFBD>?| user | <EFBFBD><EFBFBD><EFBFBD>厩鍂<EFBFBD>?|
| <EFBFBD><EFBFBD>璅⊥踎 | user | <EFBFBD><EFBFBD><EFBFBD>厩鍂<EFBFBD>?|
| <EFBFBD>𥕦遣隞餃𦛚 | user | <EFBFBD><EFBFBD><EFBFBD>厩鍂<EFBFBD>?|
| <EFBFBD>亥砭隞餃𦛚 | owner | <EFBFBD><EFBFBD><EFBFBD>撱箄<EFBFBD>?|
| <EFBFBD><EFBFBD><EFBFBD><EFBFBD> | owner | <EFBFBD><EFBFBD><EFBFBD>撱箄<EFBFBD>?|
---
## 銝剹<E98A9D><E589B9>PI蝡舐<E89DA1>霂行<E99C82>
### 3.1 健康检查
### 3.1 <EFBFBD>亙熒璉<EFBFBD><EFBFBD>?
**蝡舐<E89DA1>**: `POST /api/v1/dc/tool-b/health-check`
**用途**: 检查Excel列的数据质量拦截低质量数据
**<2A><EFBFBD>?*: 璉<><E79289>乍xcel<65><EFBFBD><E39B96>唳旿韐券<E99F90>嚗峕㜃<E5B395><EFBFBD>韐券<E99F90><E588B8>唳旿
**请求体**
```json
**霂瑟<EFBFBD>雿?*嚗?```json
{
"fileKey": "uploads/user123/data.xlsx",
"columnName": "<22><><EFBFBD><EFBFBD><EFBFBD>𧋦"
}
```
**请求参数**
**霂瑟<EFBFBD><EFBFBD><EFBFBD>㺭**嚗?
| 摮埈挾 | 蝐餃<E89D90> | 敹<> | 霂湔<E99C82> |
|------|------|------|------|
| `fileKey` | string | | Storage中的文件路径 |
| `columnName` | string | ✅ | 要检查的列名 |
| `fileKey` | string | <EFBFBD>?| Storage銝剔<EFBFBD><EFBFBD><EFBFBD>辣頝臬<EFBFBD> |
| `columnName` | string | <EFBFBD>?| 閬<><E996AC><EFBFBD><EFBFBD><E4BAA6><EFBFBD> |
**响应**(成功 - 200
**<EFBFBD><EFBFBD>**嚗<><E59A97><EFBFBD>?- 200嚗㚁<E59A97>
```json
{
"status": "good",
@@ -126,11 +106,11 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
"avgLength": 256.8,
"totalRows": 500,
"estimatedTokens": 150000,
"message": "健康度良好,预计消耗约 150.0k Token(双模型约 300.0k Token"
"message": "<22>亙熒摨西<E691A8>憟踝<E6869F><EFBFBD>恣瘨<E681A3><E798A8>㛖漲 150.0k Token<EFBFBD><EFBFBD><EFBFBD>蝥?300.0k Token嚗?
}
```
**响应**(失败 - 200但status=bad
**<EFBFBD><EFBFBD>**嚗<>仃韐?- 200<EFBFBD>tatus=bad嚗㚁<EFBFBD>
```json
{
"status": "bad",
@@ -138,30 +118,26 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
"avgLength": 256.8,
"totalRows": 500,
"estimatedTokens": 0,
"message": "空值率过高85.0%),该列不适合提取"
"message": "蝛箏<E89D9B><EFBFBD><EFBFBD><E9A488>嚗?5.0%嚗㚁<E59A97>霂亙<E99C82>銝漤<E98A9D><E6BCA4><EFBFBD><EFBFBD>𣂼<EFBFBD>"
}
```
**响应字段**
**<EFBFBD><EFBFBD>摮埈挾**嚗?
| 摮埈挾 | 蝐餃<E89D90> | 霂湔<E99C82> |
|------|------|------|
| `status` | string | `good``bad` |
| `status` | string | `good` <20>?`bad` |
| `emptyRate` | number | 蝛箏<E89D9B><EFBFBD> (0-1) |
| `avgLength` | number | 撟喳<E6929F><E596B3><EFBFBD>𧋦<EFBFBD>踹漲 |
| `totalRows` | number | 总行数 |
| `estimatedTokens` | number | 预估Token|
| `totalRows` | number | <EFBFBD><EFBFBD><EFBFBD>?|
| `estimatedTokens` | number | <EFBFBD>Token<EFBFBD>?|
| `message` | string | <20>鞟內靽⊥<E99DBD> |
**业务规则**
- 空值率 > 80% → `status = 'bad'`
- 平均长度 < 10 → `status = 'bad'`
- 只检查前100行性能优化
**错误响应**
```json
**銝𡁜𦛚閫<EFBFBD><EFBFBD>**嚗?- 蝛箏<E89D9B><EFBFBD> > 80% <20>?`status = 'bad'`
- 撟喳<E6929F><E596B3>踹漲 < 10 <20>?`status = 'bad'`
- <20><EFBFBD><E88AA3><EFBFBD>100銵䕘<E98AB5><E49598><EFBFBD>隡睃<E99AA1>嚗?
**<2A>躰秤<E8BAB0><EFBFBD>**嚗?```json
{
"error": "列'病历文本'不存在",
"error": "<22>?<3F><><EFBFBD><EFBFBD><EFBFBD>𧋦'銝滚<E98A9D><E6BB9A>?,
"code": 400
}
```
@@ -172,11 +148,10 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
**蝡舐<E89DA1>**: `GET /api/v1/dc/tool-b/templates`
**用途**: 获取所有预设的提取模板
**<EFBFBD><EFBFBD>?*: <20><EFBFBD><E79195><EFBFBD><EFBFBD><EFBFBD>霈曄<E99C88><E69B84>𣂼<EFBFBD>璅⊥踎
**请求**: 无参数
**响应**200
**霂瑟<EFBFBD>**: <EFBFBD><EFBFBD><EFBFBD>?
**<2A><EFBFBD>**嚗?00嚗㚁<E59A97>
```json
{
"templates": [
@@ -192,7 +167,7 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
},
{
"name": "<22><><EFBFBD>蝔见漲",
"desc": "高/中/低分化",
"desc": "擃?銝?雿𤾸<E99BBF><F0A4BEB8>?,
"width": "w-32"
}
]
@@ -200,15 +175,14 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
{
"diseaseType": "diabetes",
"reportType": "admission",
"displayName": "糖尿病入院记录",
"displayName": "蝟硋倏<E7A18B><E5808F><EFBFBD><EFBFBD>扇敶?,
"fields": [...]
}
]
}
```
**响应字段**
**<EFBFBD><EFBFBD>摮埈挾**嚗?
| 摮埈挾 | 蝐餃<E89D90> | 霂湔<E99C82> |
|------|------|------|
| `templates` | array | 璅⊥踎<E28AA5>𡑒” |
@@ -217,8 +191,7 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
| `templates[].displayName` | string | <20>曄內<E69B84>滨妍 |
| `templates[].fields` | array | <20>𣂼<EFBFBD>摮埈挾<E59F88>滨蔭 |
**缓存策略**
- 客户端缓存1小时
**蝻枏<EFBFBD>蝑𣇉裦**嚗?- 摰<E691B0>蝡舐<E89DA1>摮矋<E691AE>1撠𤩺𧒄
- <20>滚𦛚蝡舐<E89DA1>摮矋<E691AE>瘞訾<E7989E><EFBFBD><EFBFBD><EFBFBD><E59C88><EFBFBD>
---
@@ -227,10 +200,9 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
**蝡舐<E89DA1>**: `POST /api/v1/dc/tool-b/tasks`
**用途**: 创建批量提取任务,推送到异步队列
**<2A><EFBFBD>?*: <20>𥕦遣<F0A595A6><EFBFBD><E5AFA5>𣂼<EFBFBD>隞餃𦛚嚗峕綫<E5B395><E7B6AB><EFBFBD><EFBFBD><EFBFBD><EFBFBD>
**请求体**
```json
**霂瑟<EFBFBD>雿?*嚗?```json
{
"projectName": "<22><EFBFBD><E7AE87><EFBFBD><EFBFBD><EFBFBD>唳旿<E594B3>𣂼<EFBFBD>-2025Q1",
"fileKey": "uploads/user123/lung_cancer_pathology.xlsx",
@@ -244,41 +216,36 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
},
{
"name": "<22><><EFBFBD>蝔见漲",
"desc": "高/中/低分化"
"desc": "擃?銝?雿𤾸<E99BBF><F0A4BEB8>?
}
]
}
```
**请求参数**
**霂瑟<EFBFBD><EFBFBD><EFBFBD>㺭**嚗?
| 摮埈挾 | 蝐餃<E89D90> | 敹<> | 霂湔<E99C82> |
|------|------|------|------|
| `projectName` | string | ✅ | 任务名称 |
| `fileKey` | string | | Storage中的文件路径 |
| `textColumn` | string | ✅ | 文本列名 |
| `diseaseType` | string | ✅ | 疾病类型 |
| `reportType` | string | ✅ | 报告类型 |
| `targetFields` | array | ✅ | 提取字段配置 |
| `projectName` | string | <EFBFBD>?| 隞餃𦛚<E9A483>滨妍 |
| `fileKey` | string | <EFBFBD>?| Storage銝剔<EFBFBD><EFBFBD><EFBFBD>辣頝臬<EFBFBD> |
| `textColumn` | string | <EFBFBD>?| <20><>𧋦<EFBFBD><EFBFBD> |
| `diseaseType` | string | <EFBFBD>?| <20><EFBFBD>蝐餃<E89D90> |
| `reportType` | string | <EFBFBD>?| <20><EFBFBD>蝐餃<E89D90> |
| `targetFields` | array | <EFBFBD>?| <20>𣂼<EFBFBD>摮埈挾<E59F88>滨蔭 |
**响应**200
**<EFBFBD><EFBFBD>**嚗?00嚗㚁<E59A97>
```json
{
"taskId": "550e8400-e29b-41d4-a716-446655440000"
}
```
**流程**
1. 验证文件存在
2. 解析Excel统计总行数
3. 创建任务记录status=pending
4. 推送到BullMQ队列
**<EFBFBD><EFBFBD>**嚗?1. 撉諹<E69289><E8ABB9><EFBFBD>辣摮睃銁
2. 閫<><E996AB>Excel嚗𣬚<E59A97>霈⊥<E99C88><EFBFBD><E9A489>?3. <20>𥕦遣隞餃𦛚霈啣<E99C88>嚗ìtatus=pending嚗?4. <20><EFBFBD><E588B8><EFBFBD>BullMQ<4D><EFBFBD>
5. 蝡见朖餈𥪜<E9A488>taskId
**错误响应**
```json
**<EFBFBD>躰秤<EFBFBD><EFBFBD>**嚗?```json
{
"error": "文件不存在: uploads/user123/lung_cancer_pathology.xlsx",
"error": "<22><>辣銝滚<E98A9D><E6BB9A>? uploads/user123/lung_cancer_pathology.xlsx",
"code": 404
}
```
@@ -289,14 +256,14 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
**蝡舐<E89DA1>**: `GET /api/v1/dc/tool-b/tasks/:taskId/progress`
**用途**: 实时查询任务处理进度
**<EFBFBD><EFBFBD>?*: 摰墧𧒄<E5A2A7>亥砭隞餃𦛚憭<F0A69B9A><E686AD>餈𥕦漲
**霂瑟<E99C82>**:
```
GET /api/v1/dc/tool-b/tasks/550e8400-e29b-41d4-a716-446655440000/progress
```
**响应**200
**<EFBFBD><EFBFBD>**嚗?00嚗㚁<E59A97>
```json
{
"taskId": "550e8400-e29b-41d4-a716-446655440000",
@@ -314,46 +281,41 @@ GET /api/v1/dc/tool-b/tasks/550e8400-e29b-41d4-a716-446655440000/progress
}
```
**响应字段**
**<EFBFBD><EFBFBD>摮埈挾**嚗?
| 摮埈挾 | 蝐餃<E89D90> | 霂湔<E99C82> |
|------|------|------|
| `status` | string | `pending/processing/completed/failed` |
| `progress` | number | 进度百分比 (0-100) |
| `progress` | number | 餈𥕦漲<EFBFBD><EFBFBD>瘥?(0-100) |
| `totalCount` | number | <20>餉扇敶閙㺭 |
| `processedCount` | number | 撌脣<E6928C><E884A3><EFBFBD>㺭 |
| `cleanCount` | number | 銝<><E98A9D>渲扇敶閙㺭 |
| `conflictCount` | number | 冲突记录数 |
| `failedCount` | number | 失败记录数 |
| `totalTokens` | number | 累计Token|
| `conflictCount` | number | <EFBFBD><EFBFBD>霈啣<EFBFBD><EFBFBD>?|
| `failedCount` | number | 憭梯揖霈啣<EFBFBD><EFBFBD>?|
| `totalTokens` | number | 蝝航恣Token<EFBFBD>?|
| `totalCost` | number | 蝝航恣<E888AA>鞉𧋦($) |
**轮询建议**
- 客户端每3秒轮询一次
-`status = 'completed'`时停止轮询
**頧株砭撱箄悅**嚗?- 摰<E691B0>蝡舀<E89DA1>3蝘坿蔭霂<E99C82>甈?- 敶𨦨status = 'completed'`<EFBFBD><EFBFBD>蔭霂?
---
### 3.5 <20><EFBFBD>撉諹<E69289>蝵烐聢<E78390>唳旿
**蝡舐<E89DA1>**: `GET /api/v1/dc/tool-b/tasks/:taskId/items`
**用途**: 获取双模型提取结果,用于人工裁决
**<EFBFBD><EFBFBD>?*: <20><EFBFBD><E79195>峕芋<E5B395>𧢲<EFBFBD><F0A7A2B2>𣇉<EFBFBD><F0A38789><EFBFBD><E9A0A3><EFBFBD>鈭箏極鋆<E6A5B5><E98B86>
**霂瑟<E99C82>**:
```
GET /api/v1/dc/tool-b/tasks/550e8400.../items?page=1&limit=50&status=conflict
```
**查询参数**
| 参数 | 类型 | 必填 | 默认值 | 说明 |
**<EFBFBD>亥砭<EFBFBD><EFBFBD>㺭**嚗?
| <20><>㺭 | 蝐餃<E89D90> | 敹<> | 暺䁅恕<E48185>?| 霂湔<E99C82> |
|------|------|------|--------|------|
| `page` | number | | 1 | 页码 |
| `limit` | number | | 50 | 每页数量 |
| `status` | string | | - | 过滤状态 |
| `page` | number | <EFBFBD>?| 1 | 憿萇<EFBFBD> |
| `limit` | number | <EFBFBD>?| 50 | 瘥誯△<EFBFBD><EFBFBD> |
| `status` | string | <EFBFBD>?| - | <EFBFBD><EFBFBD><EFBFBD>?|
**响应**200
**<EFBFBD><EFBFBD>**嚗?00嚗㚁<E59A97>
```json
{
"items": [
@@ -362,13 +324,13 @@ GET /api/v1/dc/tool-b/tasks/550e8400.../items?page=1&limit=50&status=conflict
"rowIndex": 5,
"originalText": "<22><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>45撗<35><E69297>霂𦠜鱏銝箸絡瘨行<E798A8><EFBFBD><E689AF><EFBFBD>銝剖<E98A9D><E58996><EFBFBD><E59094>輻𠈔<E8BCBB><F0A08894>憭批<E686AD>3cm...",
"resultA": {
"病理类型": "浸润性腺癌",
"分化程度": "中分化",
"<EFBFBD><EFBFBD><EFBFBD>蝐餃<EFBFBD>": "瘚豢隋<EFBFBD><EFBFBD><EFBFBD>?,
"<EFBFBD><EFBFBD><EFBFBD>": "<EFBFBD><EFBFBD>?,
"<22>輻𠈔憭批<E686AD>": "3cm"
},
"resultB": {
"病理类型": "浸润性腺癌",
"分化程度": "中分化",
"<EFBFBD><EFBFBD><EFBFBD>蝐餃<EFBFBD>": "瘚豢隋<EFBFBD><EFBFBD><EFBFBD>?,
"<EFBFBD><EFBFBD><EFBFBD>": "<EFBFBD><EFBFBD>?,
"<22>輻𠈔憭批<E686AD>": "3.0cm"
},
"status": "conflict",
@@ -385,8 +347,7 @@ GET /api/v1/dc/tool-b/tasks/550e8400.../items?page=1&limit=50&status=conflict
}
```
**响应字段**
**<EFBFBD><EFBFBD>摮埈挾**嚗?
| 摮埈挾 | 蝐餃<E89D90> | 霂湔<E99C82> |
|------|------|------|
| `items` | array | 霈啣<E99C88><E595A3>𡑒” |
@@ -400,8 +361,7 @@ GET /api/v1/dc/tool-b/tasks/550e8400.../items?page=1&limit=50&status=conflict
**蝡舐<E89DA1>**: `POST /api/v1/dc/tool-b/items/:itemId/resolve`
**用途**: 人工选择正确的提取结果
**<EFBFBD><EFBFBD>?*: 鈭箏極<E7AE8F>㗇𥋘甇<F0A58B98><EFBFBD><EFBC86><EFBFBD><EFBFBD>𣇉<EFBFBD><F0A38789>?
**霂瑟<E99C82>**:
```json
{
@@ -410,22 +370,20 @@ GET /api/v1/dc/tool-b/tasks/550e8400.../items?page=1&limit=50&status=conflict
}
```
**请求参数**
**霂瑟<EFBFBD><EFBFBD><EFBFBD>㺭**嚗?
| 摮埈挾 | 蝐餃<E89D90> | 敹<> | 霂湔<E99C82> |
|------|------|------|------|
| `field` | string | ✅ | 冲突字段名 |
| `chosenValue` | string | ✅ | 选择的值 |
| `field` | string | <EFBFBD>?| <20><EFBFBD>摮埈挾<E59F88>?|
| `chosenValue` | string | <EFBFBD>?| <20>㗇𥋘<E39787><F0A58B98><EFBFBD>?|
**响应**200
**<EFBFBD><EFBFBD>**嚗?00嚗㚁<E59A97>
```json
{
"success": true
}
```
**业务逻辑**
1. 更新`finalResult[field] = chosenValue`
**銝𡁜𦛚<EFBFBD><EFBFBD>**嚗?1. <20>湔鰵`finalResult[field] = chosenValue`
2. 隞𥳾conflictFields`銝剔宏<E58994>方砲摮埈挾
3.<><E68692><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><E59689>湔鰵`status = 'resolved'`
@@ -435,33 +393,27 @@ GET /api/v1/dc/tool-b/tasks/550e8400.../items?page=1&limit=50&status=conflict
**蝡舐<E89DA1>**: `GET /api/v1/dc/tool-b/tasks/:taskId/export`
**用途**: 导出最终提取结果为Excel
**<EFBFBD><EFBFBD>?*: 撖澆枂<E6BE86><E69E82><EFBFBD><E89D8F><EFBFBD>𣇉<EFBFBD><F0A38789>靝蛹Excel
**霂瑟<E99C82>**:
```
GET /api/v1/dc/tool-b/tasks/550e8400.../export?format=xlsx
```
**查询参数**
| 参数 | 类型 | 必填 | 默认值 | 说明 |
**<EFBFBD>亥砭<EFBFBD><EFBFBD>㺭**嚗?
| <20><>㺭 | 蝐餃<E89D90> | 敹<> | 暺䁅恕<E48185>?| 霂湔<E99C82> |
|------|------|------|--------|------|
| `format` | string | | `xlsx` | 导出格式:`xlsx/csv` |
| `format` | string | <EFBFBD>?| `xlsx` | 撖澆枂<EFBFBD><EFBFBD>嚗䫤xlsx/csv` |
**响应**200
- 文件流下载
- Content-Type: `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`
**<EFBFBD><EFBFBD>**嚗?00嚗㚁<E59A97>
- <20><>辣瘚<E8BEA3><E7989A>頧?- Content-Type: `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`
- Content-Disposition: `attachment; filename="extraction_result_2025-11-27.xlsx"`
**导出内容**
- 包含原始列 + 所有提取字段
- 只包含`clean``resolved`状态的记录
- 冲突记录不导出(需人工裁决)
**撖澆枂<EFBFBD><EFBFBD>捆**嚗?- <20><><EFBFBD><EFBFBD><E7AC94>?+ <20><><EFBFBD><EFBFBD><E39787><EFBFBD>畾?- <20><EFBFBD><E88AB8>冑clean`<EFBFBD>䈣resolved`<60><EFBFBD><E59786><EFBFBD>霈啣<E99C88>
- <20><EFBFBD>霈啣<E99C88>銝滚紡<E6BB9A><EFBFBD><E7B6BD><EFBFBD>鈭箏極鋆<E6A5B5><E98B86>嚗?
---
## 四、数据模型
## <EFBFBD><EFBFBD><EFBFBD><EFBFBD>格芋<EFBFBD>?
### 4.1 HealthCheckResult
```typescript
@@ -546,8 +498,7 @@ interface ExtractionItem {
---
## 五、错误处理
## 鈭𢛵<EFBFBD><EFBFBD><EFBFBD>霂臬<EFBFBD><EFBFBD>?
### 5.1 <20>躰秤<E8BAB0><EFBFBD><E6BB9A><EFBFBD>
```json
@@ -556,27 +507,24 @@ interface ExtractionItem {
"code": 400,
"details": {
"field": "fileKey",
"reason": "文件不存在"
"reason": "<22><>辣銝滚<E98A9D><E6BB9A>?
}
}
```
### 5.2 常见错误码
| HTTP状态 | code | 说明 | 示例 |
### 5.2 撣貉<EFBFBD><EFBFBD>躰秤<EFBFBD>?
| HTTP<54><EFBFBD>?| code | 霂湔<E99C82> | 蝷箔<E89DB7> |
|----------|------|------|------|
| 400 | `INVALID_PARAMS` | <20><><EFBFBD>躰秤 | 蝻箏<E89DBB>fileKey |
| 400 | `COLUMN_NOT_FOUND` | 列不存在 | 列"病历文本"不存在 |
| 400 | `COLUMN_NOT_FOUND` | <EFBFBD>𦯀<EFBFBD>摮睃銁 | <20>?<3F><><EFBFBD><EFBFBD><EFBFBD>𧋦"銝滚<E98A9D><E6BB9A>?|
| 400 | `BAD_HEALTH` | <20>亙熒璉<E78692><E79289>交𧊋<E4BAA4><EFBFBD> | 蝛箏<E89D9B><EFBFBD><EFBFBD><E9A488> |
| 404 | `FILE_NOT_FOUND` | 文件不存在 | 文件路径无效 |
| 404 | `TASK_NOT_FOUND` | 任务不存在 | taskId无效 |
| 403 | `FORBIDDEN` | 无权访问 | 只能访问自己的任务 |
| 500 | `INTERNAL_ERROR` | 服务器错误 | 数据库连接失败 |
| 404 | `FILE_NOT_FOUND` | <EFBFBD><EFBFBD>辣銝滚<EFBFBD><EFBFBD>?| <20><>辣頝臬<E9A09D><E887AC><EFBFBD> |
| 404 | `TASK_NOT_FOUND` | 隞餃𦛚銝滚<EFBFBD><EFBFBD>?| taskId<EFBFBD><EFBFBD> |
| 403 | `FORBIDDEN` | <EFBFBD><EFBFBD>霈輸䔮 | <20><EFBFBD>霈輸䔮<E8BCB8>芸楛<E88AB8><E6A59B><EFBFBD>?|
| 500 | `INTERNAL_ERROR` | <EFBFBD>滚𦛚<EFBFBD><EFBFBD>霂?| <20>唳旿摨栞<E691A8><E6A09E>亙仃韐?|
### 5.3 错误处理最佳实践
**客户端**
```typescript
### 5.3 <EFBFBD>躰秤憭<EFBFBD><EFBFBD><EFBFBD><EFBFBD>雿喳<EFBFBD>頝?
**摰<E691B0>蝡?*嚗?```typescript
try {
const response = await fetch('/api/v1/dc/tool-b/health-check', {
method: 'POST',
@@ -595,9 +543,8 @@ try {
return;
}
// 继续下一步
} catch (error) {
console.error('健康检查失败:', error);
// 蝏抒賒銝衤<EFBFBD>甇?} catch (error) {
console.error('<27>亙熒璉<E78692><E79289>亙仃韐?', error);
}
```
@@ -609,54 +556,41 @@ try {
| API | <20><EFBFBD> | 霂湔<E99C82> |
|-----|------|------|
| `/health-check` | < 3| Excel解析+统计 |
| `/health-check` | < 3蝘?| Excel<EFBFBD><EFBFBD>+蝏蠘恣 |
| `/templates` | < 100ms | <20><><EFBFBD>蝻枏<E89DBB> |
| `/tasks` (create) | < 500ms | 敹恍<E695B9><EFBFBD>撱箏僎餈𥪜<E9A488> |
| `/tasks/:id/progress` | < 100ms | <20>唳旿摨枏<E691A8><E69E8F>亥砭 |
| `/tasks/:id/items` | < 500ms | <20><><EFBFBD>亥砭 |
| `/items/:id/resolve` | < 200ms | <20><EFBFBD><E99697>湔鰵 |
| `/tasks/:id/export` | < 10秒 | 生成Excel文件 |
| `/tasks/:id/export` | < 10蝘?| <20><><EFBFBD>Excel<EFBFBD><EFBFBD> |
### 6.2 撟嗅<E6929F><EFBFBD><E686AD><EFBFBD><EFBFBD>
- **健康检查**: 10 req/sIO密集
- **任务创建**: 5 req/s写入数据库
- **进度查询**: 100 req/s读密集可缓存
- **验证网格**: 50 req/s分页查询
- **<2A>亙熒璉<E78692><E79289>?*: 10 req/s嚗㇆O撖<4F><E69296>嚗?- **隞餃𦛚<E9A483>𥕦遣**: 5 req/s嚗<73><E59A97><EFBFBD>交㺭<E4BAA4><EFBFBD>嚗?- **餈𥕦漲<F0A595A6>亥砭**: 100 req/s嚗<73>粉撖<E7B289><E69296><EFBFBD>虾蝻枏<E89DBB>嚗?- **撉諹<E69289>蝵烐聢**: 50 req/s嚗<73><E59A97>憿菜䰻霂<E99C82>
### 6.3 隡睃<E99AA1>蝑𣇉裦
**缓存**
- `/templates` → 永久缓存(内存)
- `/tasks/:id/progress` → Redis缓存5秒TTL
**异步处理**
- 任务处理使用BullMQ后台队列
**蝻枏<EFBFBD>**嚗?- `/templates` <20>?瘞訾<E7989E>蝻枏<E89DBB><EFBFBD><E59A97>摮矋<E691AE>
- `/tasks/:id/progress` <20>?Redis蝻枏<E89DBB>嚗?蝘塬TL嚗?
**撘<>郊憭<E9838A><E686AD>**嚗?- 隞餃𦛚憭<F0A69B9A><E686AD>雿輻鍂BullMQ<4D>𤾸蝱<F0A4BEB8><EFBFBD>
- <20><EFBFBD><E8B8B9><EFBFBD><E9A483><EFBFBD>霂瑟<E99C82>
**分页**
- 验证网格默认50条/页
- 最大1000条/页
**<EFBFBD><EFBFBD>△**嚗?- 撉諹<E69289>蝵烐聢暺䁅恕50<35>?憿?- <20><>憭?000<30>?憿?
---
## 七、版本控制
## <EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>祆綉<EFBFBD>?
### 7.1 API<50><49>𧋦蝑𣇉裦
**敶枏<E695B6><E69E8F><EFBFBD>𧋦**: `v1`
**URL<52><EFBFBD>**: `/api/v1/dc/tool-b/*`
**向后兼容承诺**
- v1版本在2026年前保持稳定
- 新功能通过可选参数添加
- 破坏性变更发布v2
**<EFBFBD><EFBFBD><EFBFBD>澆捆<EFBFBD>輯笑**嚗?- v1<76><31>𧋦<EFBFBD>?026撟游<E6929F>靽脲<E99DBD>蝔喳<E89D94>
- <20><EFBFBD><E595A3><EFBFBD><EFBFBD><E69C9E><EFBFBD><EFBFBD><E58CA7>唳溶<E594B3>?- <20><EFBFBD><E6B8B8><EFBFBD><E689B9><EFBFBD><EFBFBD>2
### 7.2 摨笔<E691A8><E7AC94>𡁶䰻
当API需要废弃时
```http
敶𨯗PI<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>𧒄嚗?```http
HTTP/1.1 200 OK
X-API-Deprecated: true
X-API-Sunset: 2026-12-31
@@ -665,19 +599,16 @@ X-API-Replacement: /api/v2/dc/tool-b/health-check
---
## 八、测试
## <EFBFBD><EFBFBD><EFBFBD><EFBFBD>霂?
### 8.1 Postman Collection
完整的API测试集合
```
docs/03-业务模块/DC-数据清洗整理/02-技术设计/ToolB-API.postman_collection.json
摰峕㟲<EFBFBD><EFBFBD>PI瘚贝<EFBFBD><EFBFBD><EFBFBD><EFBFBD>嚗?```
docs/03-銝𡁜𦛚璅<E79285>/DC-<2D>唳旿皜<E697BF><E79A9C><EFBFBD><EFBFBD>/02-<2D><><EFBFBD>航挽霈?ToolB-API.postman_collection.json
```
### 8.2 蝷箔<E89DB7>霂瑟<E99C82>
**健康检查**
```bash
**<EFBFBD>亙熒璉<EFBFBD><EFBFBD>?*嚗?```bash
curl -X POST http://localhost:3001/api/v1/dc/tool-b/health-check \
-H "Content-Type: application/json" \
-d '{
@@ -686,13 +617,11 @@ curl -X POST http://localhost:3001/api/v1/dc/tool-b/health-check \
}'
```
**获取模板**
```bash
**<EFBFBD><EFBFBD>璅⊥踎**嚗?```bash
curl http://localhost:3001/api/v1/dc/tool-b/templates
```
**创建任务**
```bash
**<EFBFBD>𥕦遣隞餃𦛚**嚗?```bash
curl -X POST http://localhost:3001/api/v1/dc/tool-b/tasks \
-H "Content-Type: application/json" \
-d '{
@@ -707,21 +636,19 @@ curl -X POST http://localhost:3001/api/v1/dc/tool-b/tasks \
---
## 九、附录
## 銋腈<EFBFBD><EFBFBD><EFBFBD>敶?
### 9.1 <20><EFBFBD><E8A9A8><EFBFBD>
- [数据库设计文档](./数据库设计文档-工具B.md)
- [PRD文档](../01-需求分析/PRDTool B - 病历结构化机器人 (The AI Structurer).md)
- [开发计划](../04-开发计划/工具B开发计划-病历结构化机器人.md)
- [<EFBFBD>唳旿摨栞挽霈⊥<EFBFBD>獢β(./<2F>唳旿摨栞挽霈⊥<E99C88>獢?撌亙<E6928C>B.md)
- [PRD<EFBFBD><EFBFBD>](../01-<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>?PRD嚗関ool B - <EFBFBD><EFBFBD><EFBFBD>蝏𤘪<EFBFBD><EFBFBD>𡝗㦤<EFBFBD>其犖 (The AI Structurer).md)
- [<EFBFBD><EFBFBD>𤏸恣<EFBFBD>哋(../04-撘<><E69298>𤏸恣<F0A48FB8>?撌亙<E6928C>B撘<42><E69298>𤏸恣<F0A48FB8>?<3F><><EFBFBD>蝏𤘪<E89D8F><F0A498AA>𡝗㦤<F0A19D97>其犖.md)
### 9.2 <20>䀹凒<E480B9><EFBFBD>
| <20><>𧋦 | <20><EFBFBD> | <20>䀹凒<E480B9><E58792>捆 |
|------|------|---------|
| V1.0 | 2025-11-27 | 初始版本7个API端点 |
| V1.0 | 2025-11-27 | <EFBFBD><EFBFBD><EFBFBD><EFBFBD>𧋦嚗?銝服PI蝡舐<E89DA1> |
---
**文档结束**
**<EFBFBD><EFBFBD>﹝蝏𤘪<EFBFBD>** <20>?