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

353
docs/03-业务模块/DC-数据清洗整理/02-技术设计/API设计文档-DC模块（完整版）.md
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/s（IO密集）
- **任务创建**: 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-需求分析/PRD：Tool 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>?

139
docs/03-业务模块/DC-数据清洗整理/02-技术设计/工具 C：AI 辅助医疗数据清洗场景分级清单.md
View File

@@ -1,114 +1,99 @@
# **撌亙<E6928C> C嚗鋫I 颲<>𨭌<EFBFBD>餌<EFBFBD><E9A48C>唳旿皜<E697BF><E79A9C><EFBFBD>箸艶<E7AEB8><E889B6>漣皜<E6BCA3><E79A9C>**
这份清单按**技术实现难度**和**业务逻辑复杂度**从简单到复杂排列。所有场景均假设数据已加载为 Pandas DataFrame (df)。
餈嗘遢皜<EFBFBD><EFBFBD><EFBFBD>?*<2A><><EFBFBD>臬<EFBFBD><E887AC>圈𠗕摨?*<2A>?*銝𡁜𦛚<F0A1819C>餉<EFBFBD>憭齿<E686AD>摨?*隞𡒊<E99A9E><F0A1928A>訫<EFBFBD>憭齿<E686AD><E9BDBF>鍦<EFBFBD><E98DA6><EFBFBD><EFBFBD><EFBFBD>匧㦤<E58CA7>臬<EFBFBD><E887AC><EFBFBD>挽<EFBFBD>唳旿撌脣<E6928C>頧賭蛹 Pandas DataFrame (df)<EFBFBD>?
## **Level 1: <20>箇<EFBFBD><E7AE87>怎<EFBFBD>皜<EFBFBD><E79A9C> (Data Hygiene)**
*目标：把“脏”数据变成“能读”的数据。Excel 也能做，但 Python 更快更准。*
*<2A>格<EFBFBD>嚗𡁏<E59A97><F0A1818F>𡏭<EFBFBD><F0A18FAD>脲㺭<E884B2>桀<EFBFBD><E6A180>鐥<EFBFBD>𡏭<EFBFBD>霂領<E99C82>萘<EFBFBD><E89098>唳旿<E594B3><E697BF>xcel 銋蠘<E98A8B><E8A098>𡄯<EFBFBD>雿?Python <20>游翰<E6B8B8>游<EFBFBD><E6B8B8>?
### **1.1 <20>㗛<EFBFBD><E3979B>齿<EFBFBD><E9BDBF><EFBFBD><EFBFBD> (Rename)**
* **场景：** 原始表头是中文或含特殊符号（年龄(岁), 性别/Gender, 入院\_日期），SPSS 报错。
* **用户指令：** “把所有列名转为纯英文小写，去掉括号。”
* **Python 逻辑：** 使用映射字典或正则替换列名。
* **<EFBFBD>箸艶嚗?* <20>笔<EFBFBD>銵典仍<E585B8>臭葉<E887AD><E89189><EFBFBD><EFBFBD>怎鸌畾羓泵<E7BE93>瘀<EFBFBD>撟湧<E6929F>(撗?, <20>批<EFBFBD>/Gender, <20>仿堺\_<>交<EFBFBD>嚗㚁<E59A97>SPSS <20>仿<EFBFBD><E4BBBF>?
* **<EFBFBD>冽<EFBFBD><EFBFBD><EFBFBD>誘嚗?* <20>𨀣<EFBFBD><F0A880A3><EFBFBD><EFBFBD>匧<EFBFBD><E58CA7>滩蓮銝箇滲<E7AE87>望<EFBFBD>撠誩<E692A0>嚗<EFBFBD>縧<EFBFBD>㗇𡠺<E39787>瑯<EFBFBD><E791AF><EFBFBD>?
* **Python <EFBFBD>餉<EFBFBD>嚗?* 雿輻鍂<E8BCBB>惩<EFBFBD>摮堒<E691AE><E5A092>𡝗迤<F0A19D97>蹱𤜯<E8B9B1>Ｗ<EFBFBD><EFBCB7>溻<EFBFBD>?
### **1.2 <20>啣<EFBFBD>澆<EFBFBD><E6BE86>𨀣<EFBFBD>瘥圝<E798A5>?(Clean Numeric)**
### **1.2 数值列“排毒” (Clean Numeric)**
* **<2A>箸艶嚗?* 璉<>撉𣬚<E69289>撖澆枂<E6BE86><E69E82>㺭<EFBFBD>殷<EFBFBD><E6AEB7>啣<EFBFBD>澆<EFBFBD>瘛瑕<E7989B>鈭<EFBFBD>泵<EFBFBD>瘀<EFBFBD>\>100, \<0.1, 12.5+, <20>芣䰻嚗剹<E59A97>?
* **<2A>冽<EFBFBD><E586BD><EFBFBD>誘嚗?* <20>𨀣<EFBFBD><F0A880A3>䁅<EFBFBD><E48185>鐥<EFBFBD>坔<EFBFBD><E59D94>𣬚<EFBFBD><F0A3AC9A>墧㺭摮㛖泵<E39B96>瑕縧<E79195>㚁<EFBFBD><E39A81>娫<0.1<EFBFBD>蹱<EFBFBD><EFBFBD>?.05<EFBFBD>坔<EFBFBD><EFBFBD><EFBFBD><EFBFBD>頧砌蛹瘚桃<EFBFBD><EFBFBD>啜<EFBFBD><EFBFBD><EFBFBD>?
* **Python <20>餉<EFBFBD>嚗?* str.replace \+ 甇<><E79487><EFBFBD>𣂼<EFBFBD> \+ pd.to\_numeric(errors='coerce')<29>?
### **1.3 蝏煺<E89D8F>蝻箏仃<E7AE8F>?(Standardize Nulls)**
* **场景：** 检验科导出的数据，数值列混入了符号（\>100, \<0.1, 12.5+, 未查）。
* **用户指令：** “把‘肌酐’列里的非数字符号去掉，‘\<0.1’按‘0.05’处理，转为浮点数。”
* **Python 逻辑：** str.replace \+ 正则提取 \+ pd.to\_numeric(errors='coerce')。
* **<EFBFBD>箸艶嚗?* <20>唳旿<E594B3>峕毽<E5B395><E6AFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>隞<EFBFBD>”<EFBFBD>𦦵征<F0A6A6B5>萘<EFBFBD>霂㵪<E99C82>NA, N/A, \-, \\, 銝滩祕<E6BBA9>?
* **<EFBFBD>冽<EFBFBD><EFBFBD><EFBFBD>誘嚗?* <20>𨀣<EFBFBD><F0A880A3><EFBFBD><EFBFBD>劐誨銵兩<E98AB5>䀹瓷<E480B9>争<EFBFBD>嗵<EFBFBD>摮㛖泵<E39B96>賜<EFBFBD>銝<EFBFBD><E98A9D>踵揢銝箸<E98A9D><E7AEB8><EFBFBD><EFBFBD>蝛箏<E89D9B>潦<EFBFBD><E6BDA6><EFBFBD>?
* **Python <EFBFBD>餉<EFBFBD>嚗?* df.replace(\['-', '銝滩祕', 'NA'\], np.nan, inplace=True)<29>?
## **Level 2: <20>㗛<EFBFBD><E3979B><EFBFBD><EFBFBD><EFBFBD>碶<EFBFBD><E7A2B6>滨<EFBFBD><E6BBA8>?(Recode & Standardization)**
### **1.3 统一缺失值 (Standardize Nulls)**
*<2A>格<EFBFBD>嚗帋蛹蝏蠘恣<E8A098><E681A3><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>掩<EFBFBD>㗛<EFBFBD><E3979B>?
* **场景：** 数据里混杂了各种代表“空”的词：NA, N/A, \-, \\, 不详。
* **用户指令：** “把所有代表‘没有’的字符都统一替换为标准的空值。”
* **Python 逻辑：** df.replace(\['-', '不详', 'NA'\], np.nan, inplace=True)。
## **Level 2: 变量标准化与重编码 (Recode & Standardization)**
*目标：为统计分析准备分类变量。*
### **2.1 文本转数值映射 (Map Categorical)**
* **场景：** 性别列是 Male/Female，吸烟史是 Yes/No。
* **用户指令：** “把性别转为 1(男)/0(女)，把吸烟史转为 1/0。”
* **Python 逻辑：** df\['sex'\].map({'Male': 1, 'Female': 0})。
### **2.1 <20><>𧋦頧祆㺭<E7A586>潭<EFBFBD>撠?(Map Categorical)**
* **<2A>箸艶嚗?* <20>批<EFBFBD><E689B9>埈糓 Male/Female嚗<65>𢙺<EFBFBD>笔蟮<E7AC94>?Yes/No<4E>?
* **<2A>冽<EFBFBD><E586BD><EFBFBD>誘嚗?* <20>𨀣<EFBFBD><F0A880A3>批<EFBFBD>頧砌蛹 1(<28>?/0(憟?嚗峕<E59A97><E5B395>貊<EFBFBD><E8B28A>脰蓮銝?1/0<><30><EFBFBD>?
* **Python <20>餉<EFBFBD>嚗?* df\['sex'\].map({'Male': 1, 'Female': 0})<29>?
### **2.2 餈䂿賒<E482BF>㗛<EFBFBD><E3979B><EFBFBD>拳 (Binning)**
* **场景：** 需要按年龄分组进行卡方检验。
* **用户指令：** “把年龄按 0-18, 19-60, 60+ 分为‘未成年’, ‘成年’, ‘老年’三组。”
* **Python 逻辑：** pd.cut() 函数。
* **<EFBFBD>箸艶嚗?* <20><>閬<EFBFBD><E996AC>撟湧<E6929F><E6B9A7><EFBFBD><EFBFBD>餈𥡝<E9A488><F0A5A19D>⊥䲮璉<E4B2AE>撉䎚<E69289>?
* **<EFBFBD>冽<EFBFBD><EFBFBD><EFBFBD>誘嚗?* <20>𨀣<EFBFBD>撟湧<E6929F><E6B9A7>?0-18, 19-60, 60+ <20><>蛹<EFBFBD>䀹𧊋<E480B9>𣂼僑<F0A382BC>? <20>䀹<EFBFBD>撟氯<E6929F>? <20>䁅<EFBFBD><E48185>僑<EFBFBD>嗘<EFBFBD>蝏<EFBFBD><E89D8F><EFBFBD><EFBFBD>?
* **Python <EFBFBD>餉<EFBFBD>嚗?* pd.cut() <EFBFBD>賣㺭<EFBFBD>?
### **2.3 憭齿<E686AD><E9BDBF>交<EFBFBD>霈∠<E99C88> (Date Logic)**
* **场景：** 计算生存时间（OS）。Excel 经常算错闰年或月份。
* **用户指令：** “根据‘确诊日期’和‘随访日期’计算生存月数，保留1位小数。”
* **Python 逻辑：** (df\['end\_date'\] \- df\['start\_date'\]).dt.days / 30.4。
* **<EFBFBD>箸艶嚗?* 霈∠<E99C88><E288A0>笔<EFBFBD><E7AC94>園𡢿嚗㇉S嚗剹<E59A97><E589B9>xcel 蝏誩虜蝞烾<E89D9E><E783BE>啣僑<E595A3>𡝗<EFBFBD>隞賬<E99A9E>?
* **<EFBFBD>冽<EFBFBD><EFBFBD><EFBFBD>誘嚗?* <20>𨀣覔<F0A880A3>栽<EFBFBD>条＆霂𦠜𠯫<F0A6A09C>麨<EFBFBD>坔<EFBFBD><E59D94>㗛<EFBFBD>霈踵𠯫<E8B8B5>麨<EFBFBD>躰恣蝞㛖<E89D9E>摮䀹<E691AE><E480B9>堆<EFBFBD>靽萘<E99DBD>1雿滚<E99BBF><E6BB9A>啜<EFBFBD><E5959C><EFBFBD>?
* **Python <EFBFBD>餉<EFBFBD>嚗?* (df\['end\_date'\] \- df\['start\_date'\]).dt.days / 30.4<EFBFBD>?
## **Level 3: 銝游<E98A9D><E6B8B8>餉<EFBFBD><E9A489>孵<EFBFBD>撌亦<E6928C> (Feature Engineering)**
*目标：基于医学知识生成新的分析指标。*
*<2A>格<EFBFBD>嚗𡁜抅鈭𤾸龫摮衣䰻霂<E4B0BB><E99C82><EFBFBD>鞉鰵<E99E89><E9B0B5><EFBFBD><EFBFBD>鞉<EFBFBD><E99E89><EFBFBD><EFBFBD>?
### **3.1 憭滚<E686AD><E6BB9A>砍<EFBFBD>霈∠<E99C88> (Complex Formula)**
* **场景：** 计算 eGFR (肾小球滤过率) 或 BMI。
* **用户指令：** “帮我计算 BMI。如果 BMI \> 28，生成新列标记为‘肥胖’。”
* **Python 逻辑：** 向量化计算 df\['weight'\] / (df\['height'\]/100)\*\*2 \+ 条件赋值 np.where。
* **<EFBFBD>箸艶嚗?* 霈∠<E99C88> eGFR (<28>曉<EFBFBD><E69B89><EFBFBD>誘餈<E8AA98><E9A488>) <20>?BMI<EFBFBD>?
* **<EFBFBD>冽<EFBFBD><EFBFBD><EFBFBD>誘嚗?* <20>𨅯葬<F0A885AF>𤏸恣蝞?BMI<4D><49><EFBFBD><EFBFBD>?BMI \> 28嚗𣬚<E59A97><F0A3AC9A>鞉鰵<E99E89>埈<EFBFBD>霈唬蛹<E594AC>䁅<EFBFBD><E48185>砽<EFBFBD>踺<EFBFBD><E8B8BA><EFBFBD>?
* **Python <EFBFBD>餉<EFBFBD>嚗?* <20>煾<EFBFBD><E785BE>𤥁恣蝞?df\['weight'\] / (df\['height'\]/100)\*\*2 \+ <EFBFBD>∩辣韏见<EFBFBD>?np.where<EFBFBD>?
### **3.2 <20>𣂼<EFBFBD><F0A382BC>交<EFBFBD><E4BAA4><EFBFBD><EFBFBD> (Cohort Selection)**
* **场景：** 筛选符合条件的入组人群。
* **用户指令：** “筛选出：确诊为肺腺癌，且年龄大于18岁，且没有高血压病史的病人。”
* **Python 逻辑：** df.query("diagnosis \== 'Lung Adenocarcinoma' & age \> 18 & hypertension \== 0")。
* **<EFBFBD>箸艶嚗?* 蝑偦<E89D91>厩泵<E58EA9><E6B3B5>辺隞嗥<E99A9E><E597A5>亦<EFBFBD>鈭箇黎<E7AE87>?
* **<EFBFBD>冽<EFBFBD><EFBFBD><EFBFBD>誘嚗?* <20>𦦵<EFBFBD><F0A6A6B5>匧枂嚗𡁶＆霂𠹺蛹<F0A0B9BA>箄<EFBFBD><E7AE84>䕘<EFBFBD>銝𥪜僑樴<E58391>之鈭?8撗<38><E69297>銝娍瓷<E5A88D>厰<EFBFBD>銵<EFBFBD><E98AB5>讠<EFBFBD><E8AEA0>脩<EFBFBD><E884A9><EFBFBD>犖<EFBFBD><E78A96><EFBFBD>?
* **Python <EFBFBD>餉<EFBFBD>嚗?* df.query("diagnosis \== 'Lung Adenocarcinoma' & age \> 18 & hypertension \== 0")<EFBFBD>?
### **3.3 <20>穃<EFBFBD><E7A983>讐<EFBFBD><E8AE90>?(One-Hot Encoding)**
### **3.3 哑变量生成 (One-Hot Encoding)**
* **<2A>箸艶嚗?* <20><><EFBFBD><EFBFBD>?Logistic <20>𧼮<EFBFBD>嚗峕<E59A97>銝<EFBFBD>銝芣<E98A9D>摨誩<E691A8><E8AAA9><EFBFBD>掩<EFBFBD>㗛<EFBFBD><E3979B>𡏭<EFBFBD><F0A18FAD>?(A, B, AB, O)<29>腈<EFBFBD>?
* **<2A>冽<EFBFBD><E586BD><EFBFBD>誘嚗?* <20>𨀣<EFBFBD>銵<EFBFBD><E98AB5>讠<EFBFBD><E8AEA0>𣂼<EFBFBD><F0A382BC>㗛<EFBFBD><E3979B><EFBFBD><EFBFBD>?
* **Python <20>餉<EFBFBD>嚗?* pd.get\_dummies(df\['blood\_type'\], prefix='blood')<29>?
## **Level 4: 蝏𤘪<E89D8F><F0A498AA>滚<EFBFBD>銝𡡞<E98A9D>蝥扳祥<E689B3>?(Reshaping & Governance)**
* **场景：** 准备做 Logistic 回归，有一个无序多分类变量“血型 (A, B, AB, O)”。
* **用户指令：** “把血型生成哑变量。”
* **Python 逻辑：** pd.get\_dummies(df\['blood\_type'\], prefix='blood')。
*<2A>格<EFBFBD>嚗𡁏㺿<F0A1818F>䁅”<E48185>潛<EFBFBD><E6BD9B><EFBFBD>誑<EFBFBD><E8AA91><EFBFBD><EFBFBD>孵<EFBFBD><E5ADB5><EFBFBD><EFBFBD>霈⊥芋<E28AA5>页<EFBFBD><E9A1B5>𤥁<EFBFBD>銵屸<E98AB5><E5B1B8>嗆㺭<E59786>桐耨憭溻<E686AD>?
## **Level 4: 结构重塑与高级治理 (Reshaping & Governance)**
*目标：改变表格结构以适应特定的统计模型，或进行高阶数据修复。*
### **4.1 长宽表转换 (Pivot/Melt) —— Excel 的噩梦**
* **场景：** 目前是“一人多行”（张三-第1次化验，张三-第2次化验），要做重复测量分析，需要变成“一人一行”（张三-化验1-化验2）。
* **用户指令：** “把表格从长表转为宽表，按病人ID索引，用‘访视次序’做后缀，铺开‘白细胞’列。”
* **Python 逻辑：** df.pivot(index='id', columns='visit', values='wbc')。
### **4.1 <20>踹捐銵刻蓮<E588BB>?(Pivot/Melt) <20>婙<EFBFBD>?Excel <20><>埯璇?*
* **<2A>箸艶嚗?* <20>桀<EFBFBD><E6A180>胼<EFBFBD>靝<EFBFBD>鈭箏<E988AD>銵𢞖<E98AB5>嘅<EFBFBD>撘牐<E69298>-蝚?甈∪<E79488>撉䕘<E69289>撘牐<E69298>-蝚?甈∪<E79488>撉䕘<E69289>嚗諹<E59A97><E8ABB9>𡁻<EFBFBD>憭齿<E686AD><E9BDBF>誩<EFBFBD><E8AAA9>琜<EFBFBD><E7909C><EFBFBD>閬<EFBFBD><E996AC><EFBFBD>鐥<EFBFBD>靝<EFBFBD>鈭箔<E988AD>銵𢞖<E98AB5>嘅<EFBFBD>撘牐<E69298>-<2D>㚚<EFBFBD>1-<2D>㚚<EFBFBD>2嚗剹<E59A97>?
* **<2A>冽<EFBFBD><E586BD><EFBFBD>誘嚗?* <20>𨀣<EFBFBD>銵冽聢隞𡡞鵭銵刻蓮銝箏捐銵剁<E98AB5><E58981>厩<EFBFBD>鈭截D蝝Ｗ<E89D9D>嚗𣬚鍂<F0A3AC9A>䁅挪閫<E68CAA>活摨謿<E691A8>坔<EFBFBD><E59D94>𡒊<EFBFBD>嚗屸唍撘<E5948D><E69298>条蒾蝏<E892BE><E89D8F><EFBFBD>坔<EFBFBD><E59D94><EFBFBD><EFBFBD>?
* **Python <20>餉<EFBFBD>嚗?* df.pivot(index='id', columns='visit', values='wbc')<29>?
### **4.2 <20>箄<EFBFBD><E7AE84>駁<EFBFBD> (Smart Deduplication)**
* **场景：** 同一个病人有两条记录，一条信息全，一条信息缺。
* **用户指令：** “按病人ID去重。如果有重复，保留‘检查日期’最近的那一条；如果日期一样，保留‘数据完整度’最高的那条。”
* **Python 逻辑：** df.sort\_values(\['date', 'completeness'\]).drop\_duplicates(subset=\['id'\], keep='last')。
* **<EFBFBD>箸艶嚗?* <20>䔶<EFBFBD>銝芰<E98A9D>鈭箸<E988AD>銝斗辺霈啣<E99C88>嚗䔶<E59A97><E494B6>∩縑<E288A9>臬<EFBFBD>嚗䔶<E59A97><E494B6>∩縑<E288A9>舐撩<E88890>?
* **<EFBFBD>冽<EFBFBD><EFBFBD><EFBFBD>誘嚗?* <20>𨀣<EFBFBD><F0A880A3><EFBFBD>犖ID<49>駁<EFBFBD><E9A781><EFBFBD><EFBFBD><EFBFBD>𨀣<EFBFBD><F0A880A3>滚<EFBFBD>嚗䔶<E59A97><E494B6>仮<EFBFBD>䀹<EFBFBD><E480B9>交𠯫<E4BAA4>麨<EFBFBD>蹱<EFBFBD>餈𤑳<E9A488><F0A491B3><EFBFBD><EFBFBD><EFBFBD>∴<EFBFBD>憒<EFBFBD><E68692><EFBFBD>交<EFBFBD>銝<EFBFBD><E98A9D>瘀<EFBFBD>靽萘<E99DBD><E89098>䀹㺭<E480B9>桀<EFBFBD><E6A180>游漲<E6B8B8>蹱<EFBFBD>擃条<E69383><E69DA1><EFBFBD>辺<EFBFBD><E8BEBA><EFBFBD>?
* **Python <EFBFBD>餉<EFBFBD>嚗?* df.sort\_values(\['date', 'completeness'\]).drop\_duplicates(subset=\['id'\], keep='last')<EFBFBD>?
### **4.3 頝典<E9A09D><E585B8>餉<EFBFBD><E9A489>⊿<EFBFBD> (Cross-Check)**
* **场景：** 发现脏数据。
* **用户指令：** “检查一下有没有‘男性’但是‘怀孕次数\>0’的错误数据，标记出来。”
* **Python 逻辑：** df.loc\[(df\['sex'\]=='男') & (df\['preg\_count'\]\>0), 'error\_flag'\] \= 1。
* **<EFBFBD>箸艶嚗?* <20>𤑳緵<F0A491B3>𤩺㺭<F0A4A9BA>柴<EFBFBD>?
* **<EFBFBD>冽<EFBFBD><EFBFBD><EFBFBD>誘嚗?* <20>𨀣<EFBFBD><F0A880A3>乩<EFBFBD>銝𧢲<E98A9D>瘝⊥<E7989D><E28AA5>条琸<E69DA1>把<EFBFBD>嗘<EFBFBD><E59798>胼<EFBFBD>䀹<EFBFBD><E480B9>摮閙活<E99699>豹>0<>嗵<EFBFBD><E597B5>躰秤<E8BAB0>唳旿嚗峕<E59A97>霈啣枂<E595A3>乓<EFBFBD><E4B993><EFBFBD>?
* **Python <EFBFBD>餉<EFBFBD>嚗?* df.loc\[(df\['sex'\]=='<EFBFBD>?) & (df\['preg\_count'\]\>0), 'error\_flag'\] \= 1<EFBFBD>?
### **4.4 憭𡁻<E686AD><F0A181BB>坿‘ (Multiple Imputation) <20>婙<EFBFBD>?蝏蠘恣摮衣<E691AE>擃条漣憛怨‘**
### **4.4 多重插补 (Multiple Imputation) —— 统计学的高级填补**
* **<2A>箸艶嚗?* <20>唳旿<E594B3><E697BF><EFBFBD>蝻箏仃<E7AE8F>潘<EFBFBD>憒?BMI 蝻箏仃嚗㚁<E59A97><E39A81>閧滲<E996A7>典<EFBFBD><E585B8>澆‵銵乩<E98AB5><E4B9A9>游<EFBFBD><E6B8B8>唳旿<E594B3><E697BF><EFBFBD><EFBFBD><EFBFBD><EFBFBD>閬<EFBFBD>⏚<EFBFBD>典<EFBFBD>隞硋<E99A9E><E7A18B>𧶏<EFBFBD>憒<EFBFBD>僑樴<E58391><E6A8B4><EFBFBD><EFBFBD>批<EFBFBD><E689B9><EFBFBD><EFBFBD><EFBFBD>琜<EFBFBD><E7909C><EFBFBD>㮾<EFBFBD>單<EFBFBD>扳䔉憸<E49489><E686B8>憛怨‘<E680A8>?
* **<2A>冽<EFBFBD><E586BD><EFBFBD>誘嚗?* <20>靝蝙<E99D9D>典<EFBFBD><E585B8>齿<EFBFBD>銵交<E98AB5>(MICE)撖嫖<E69296>𦲂MI<4D>坔<EFBFBD><E59D94>睃僑樴<E58391><E6A8B4>坔<EFBFBD><E59D94><EFBFBD>撩憭勗<E686AD>潸<EFBFBD>銵<EFBFBD>‵銵乓<E98AB5><E4B993><EFBFBD>?
* # **Python <20>餉<EFBFBD>嚗?\`\`\`python** **from sklearn.experimental import enable\_iterative\_imputer** **from sklearn.impute import IterativeImputer** **隞<><E99A9E>撖寞㺭<E5AF9E>澆<EFBFBD>餈𥡝<E9A488><F0A5A19D>坿‘** **cols \= \['bmi', 'age', 'creatinine'\]** **imp \= IterativeImputer(max\_iter=10, random\_state=0)** **df\[cols\] \= imp.fit\_transform(df\[cols\])**
* **场景：** 数据集有缺失值（如 BMI 缺失），单纯用均值填补会破坏数据分布。需要利用其他变量（如年龄、性别、肌酐）的相关性来预测填补。
* **用户指令：** “使用多重插补法(MICE)对‘BMI’和‘年龄’列的缺失值进行填补。”
## **Level 5: <20>䂿<EFBFBD><E482BF><EFBFBD><EFBFBD><EFBFBD><EFBFBD>𧋦<EFBFBD>𡝗<EFBFBD> (Text Mining) <20>婙<EFBFBD>?Python <20><><EFBFBD>撖寧<E69296>瘝餃躹**
* # **Python 逻辑： \`\`\`python** **from sklearn.experimental import enable\_iterative\_imputer** **from sklearn.impute import IterativeImputer** **仅针对数值列进行插补** **cols \= \['bmi', 'age', 'creatinine'\]** **imp \= IterativeImputer(max\_iter=10, random\_state=0)** **df\[cols\] \= imp.fit\_transform(df\[cols\])**
*<2A>格<EFBFBD>嚗帋<E59A97>憭<EFBFBD>釣<EFBFBD>𡝗𥁒<F0A19D97>𦠜<EFBFBD><F0A6A09C>砌葉<E7A08C>𨀣<EFBFBD><F0A880A3>嘥枂<E598A5>唳旿<E594B3><E697BF><EFBFBD><EFBFBD>?Excel 蝏嘥笆<E598A5>帋<EFBFBD><E5B88B>啁<EFBFBD><E59581>?
## **Level 5: 非结构化文本挖掘 (Text Mining) —— Python 的绝对统治区**
### **5.1 甇<><E79487>銵刻噢撘𤩺<E69298><F0A4A9BA>?(Regex Extraction)**
*目标：从备注或报告文本中“抠”出数据。这是 Excel 绝对做不到的。*
* **<2A>箸艶嚗?* <20>芣<EFBFBD>銝<EFBFBD><E98A9D>埈<EFBFBD><E59F88>砂<EFBFBD>𦦵<EFBFBD><F0A6A6B5><EFBFBD><EFBFBD><EFBFBD>凌<EFBFBD>嘅<EFBFBD><E59885><EFBFBD>捆憒<E68D86><E68692><EFBFBD>?撌西<E6928C>銝𠰴蠏)瘚豢隋<E8B1A2>扯<EFBFBD><E689AF>䕘<EFBFBD>憭批<E686AD>3.5\*2cm<63>腈<EFBFBD><E88588><EFBFBD>閬<EFBFBD><E996AC><EFBFBD>𤥁<EFBFBD><F0A4A581>文之撠譌<E692A0>?
* **<2A>冽<EFBFBD><E586BD><EFBFBD>誘嚗?* <20>靝<EFBFBD><E99D9D>条<EFBFBD><E69DA1><EFBFBD><EFBFBD><EFBFBD>凌<EFBFBD>䠷<EFBFBD><E4A0B7>𣂼<EFBFBD><F0A382BC>箄<EFBFBD><E7AE84>斤<EFBFBD><E696A4>踹<EFBFBD>嚗<EFBFBD><E59A97>憭抒<E686AD><E68A92><EFBFBD>葵<EFBFBD>啣<EFBFBD>嚗剹<E59A97><E589B9><EFBFBD>?
* **Python <20>餉<EFBFBD>嚗?* df\['text'\].str.extract(r'(\\d+\\.?\\d\*)\\s\*\[\\\*xX\]\\s\*(\\d+\\.?\\d\*)') 撟嗅<E6929F><E59785><EFBFBD>憭批<E686AD>潦<EFBFBD>?
### **5.2 摮㛖泵銝脫芋蝟𠰴龪<F0A0B0B4>?(Fuzzy Matching)**
### **5.1 正则表达式提取 (Regex Extraction)**
* **场景：** 只有一列文本“病理诊断”，内容如：“(左肺上叶)浸润性腺癌，大小3.5\*2cm”。需要提取肿瘤大小。
* **用户指令：** “从‘病理诊断’里提取出肿瘤的长径（最大的那个数字）。”
* **Python 逻辑：** df\['text'\].str.extract(r'(\\d+\\.?\\d\*)\\s\*\[\\\*xX\]\\s\*(\\d+\\.?\\d\*)') 并取最大值。
### **5.2 字符串模糊匹配 (Fuzzy Matching)**
* **场景：** 医院名称录入混乱：“协和医院”、“北京协和”、“协和”。需要统一。
* **用户指令：** “把‘医院名称’列里所有包含‘协和’的，都统一改为‘PUMCH’。”
* **Python 逻辑：** df.loc\[df\['hospital'\].str.contains('协和'), 'hospital'\] \= 'PUMCH'。
* **<2A>箸艶嚗?* <20>駁堺<E9A781>滨妍敶訫<E695B6>瘛瑚僚嚗尠<E59A97>𨅯<EFBFBD><F0A885AF><EFBFBD>龫<EFBFBD>Ｔ<EFBFBD>腈<EFBFBD><E88588><EFBFBD>𨅯<EFBFBD>鈭砍<E988AD><E7A08D>𢞖<EFBFBD>腈<EFBFBD><E88588><EFBFBD>𨅯<EFBFBD><F0A885AF>𢞖<EFBFBD>腈<EFBFBD><E88588><EFBFBD>閬<EFBFBD><E996AC>銝<EFBFBD><E98A9D>?
* **<2A>冽<EFBFBD><E586BD><EFBFBD>誘嚗?* <20>𨀣<EFBFBD><F0A880A3>睃龫<E79D83>Ｗ<EFBFBD>蝘售<E89D98>坔<EFBFBD><E59D94>峕<EFBFBD><E5B395>匧<EFBFBD><E58CA7>徉<EFBFBD>睃<EFBFBD><E79D83>𢞖<EFBFBD>嗵<EFBFBD>嚗屸<E59A97>蝏煺<E89D8F><E785BA>嫣蛹<E5ABA3>婱UMCH<43>踺<EFBFBD><E8B8BA><EFBFBD>?
* **Python <20>餉<EFBFBD>嚗?* df.loc\[df\['hospital'\].str.contains('<27>誩<EFBFBD>'), 'hospital'\] \= 'PUMCH'<27>

117
docs/03-业务模块/DC-数据清洗整理/02-技术设计/总体技术设计文档：医疗科研智能数据清洗平台.md
View File

@@ -4,16 +4,15 @@
| :---- | :---- |
| **撖孵<E69296> PRD** | **PRD\_<>颱<EFBFBD>\_<>餌<EFBFBD>蝘𤑳<E89D98><F0A491B3>箄<EFBFBD><E7AE84>唳旿皜<E697BF><E79A9C>撟喳蝱.md** |
| **<EFBFBD><EFBFBD>𧋦** | **V1.0** |
| **状态** | Final Draft |
| **核心目标** | 确立平台的统一技术标准，梳理通用模块与专用模块的技术边界，指导多团队并行开发。 |
| **<EFBFBD>嗆<EFBFBD>?* | Final Draft |
| **<EFBFBD>詨<EFBFBD><EFBFBD>格<EFBFBD>** | 蝖桃<EFBFBD>撟喳蝱<EFBFBD><EFBFBD><EFBFBD>銝<EFBFBD><EFBFBD><EFBFBD><EFBFBD>舀<EFBFBD><EFBFBD><EFBFBD><EFBFBD>璇喟<EFBFBD><EFBFBD>𡁶鍂璅∪<EFBFBD>銝𦒘<EFBFBD><EFBFBD>冽芋<EFBFBD>㛖<EFBFBD><EFBFBD><EFBFBD><EFBFBD>航器<EFBFBD>䕘<EFBFBD><EFBFBD><EFBFBD>紡憭𡁜𣪧<EFBFBD>笔僎銵<EFBFBD><EFBFBD><EFBFBD>㻫<EFBFBD>?|
## **1\. 总体系统架构图 (System Architecture)**
平台采用 **“微服务化单体 (Modular Monolith)”** 或 **“BFF \+ Worker”** 架构。前端统一入口，后端按功能拆分服务或模块。
## **1\. <EFBFBD>颱<EFBFBD>蝟餌<EFBFBD><EFBFBD>嗆<EFBFBD><EFBFBD>?(System Architecture)**
撟喳蝱<EFBFBD><EFBFBD>鍂 **<EFBFBD>𨅯凝<EFBFBD>滚𦛚<EFBFBD>硋<EFBFBD>雿?(Modular Monolith)<29>?* <20>?**<2A>輶FF \+ Worker<65>?* <20>嗆<EFBFBD><E59786><EFBFBD><EFBFBD>蝡舐<E89DA1>銝<EFBFBD><E98A9D>亙藁嚗<E89781><E59A97>蝡舀<E89DA1><E88880>蠘<EFBFBD><E8A098><EFBFBD><EFBFBD><EFBFBD>滚𦛚<E6BB9A>𡝗芋<F0A19D97>𨰜<EFBFBD>?
graph TD
subgraph Client\_Layer \[前端交互层 (Browser)\]
Portal\[工作台 (Portal)\]
subgraph Client\_Layer \[<EFBFBD>滨垢鈭支<EFBFBD>撅?(Browser)\]
Portal\[撌乩<EFBFBD><EFBFBD>?(Portal)\]
ToolA\_UI\[撌亙<E6928C>A: 頞<>漣<EFBFBD><E6BCA3>僎<EFBFBD>沔]
ToolB\_UI\[撌亙<E6928C>B: 蝏𤘪<E89D8F><F0A498AA>𡝗㦤<F0A19D97>其犖\]
ToolC\_UI\[撌亙<E6928C>C: 蝘𤑳<E89D98>蝻𤥁<E89DBB><F0A4A581>沔]
@@ -48,93 +47,89 @@ graph TD
ToolC\_UI \--Local First--\> IndexedDB\[(Browser DB)\]
ToolC\_UI \--敹怎<E695B9><E6808E>峕郊--\> BFF
## **2\. 通用技术基座 (The Common Foundation)**
## **2\. <EFBFBD>𡁶鍂<EFBFBD><EFBFBD><EFBFBD>臬抅摨?(The Common Foundation)**
这部分技术栈贯穿所有模块，是团队必须统一遵循的标准。
### **2.1 前端通用栈 (Frontend Core)**
餈䠷<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>舀<EFBFBD>韐舐忽<EFBFBD><EFBFBD><EFBFBD>㗇芋<EFBFBD>梹<EFBFBD><EFBFBD>臬𣪧<EFBFBD>笔<EFBFBD>憿餌<EFBFBD>銝<EFBFBD><EFBFBD>萄儐<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>?
### **2.1 <20>滨垢<E6BBA8>𡁶鍂<F0A181B6>?(Frontend Core)**
| 蝏<>辣 | <20>匧<EFBFBD> | 霂湔<E99C82> |
| :---- | :---- | :---- |
| **框架** | **React 19** | 利用最新的 Hooks 和并发特性。 |
| **构建工具** | **Vite 5.x** | 极速构建，支持 HMR。 |
| **语言** | **TypeScript 5.x** | 强制强类型，前后端共享类型定义 (shared-types)。 |
| **样式库** | **Tailwind CSS** | 统一 UI 风格，快速开发。 |
| **图标库** | **Lucide React** | 风格统一的轻量级 SVG 图标。 |
| **路由** | **React Router v6** | 管理 Portal 与各个 Tool 之间的路由嵌套。 |
| **数据请求** | **SWR** 或 **TanStack Query** | 处理 API 请求、缓存、以及任务状态的**轮询 (Polling)**。 |
| **獢<EFBFBD>沲** | **React 19** | <EFBFBD>拍鍂<EFBFBD><EFBFBD><EFBFBD>啁<EFBFBD> Hooks <20><>僎<EFBFBD>𤑳鸌<F0A491B3>扼<EFBFBD>?|
| **<EFBFBD><EFBFBD>遣撌亙<EFBFBD>** | **Vite 5.x** | <EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>撱綽<EFBFBD><EFBFBD>舀<EFBFBD> HMR<EFBFBD>?|
| **霂剛<EFBFBD>** | **TypeScript 5.x** | 撘箏<EFBFBD>撘箇掩<EFBFBD>页<EFBFBD><EFBFBD>滚<EFBFBD>蝡臬<EFBFBD>鈭怎掩<EFBFBD>见<EFBFBD>銋?(shared-types)<EFBFBD>?|
| **<EFBFBD>瑕<EFBFBD>摨?* | **Tailwind CSS** | 蝏煺<EFBFBD> UI 憌擧聢嚗<EFBFBD>翰<EFBFBD>笔<EFBFBD><EFBFBD>㻫<EFBFBD>?|
| **<EFBFBD>暹<EFBFBD>摨?* | **Lucide React** | 憌擧聢蝏煺<EFBFBD><EFBFBD><EFBFBD>蝠<EFBFBD>讐漣 SVG <20>暹<EFBFBD><E69AB9>?|
| **頝舐眏** | **React Router v6** | 蝞∠<EFBFBD> Portal 銝𤾸<EFBFBD>銝?Tool 銋钅𡢿<E99285><F0A1A2BF>楝<EFBFBD>勗<EFBFBD>憟𨰜<E6869F>?|
| **<EFBFBD>唳旿霂瑟<EFBFBD>** | **SWR** <EFBFBD>?**TanStack Query** | 憭<EFBFBD><EFBFBD> API 霂瑟<EFBFBD><EFBFBD><EFBFBD><EFBFBD>摮塩<EFBFBD><EFBFBD>誑<EFBFBD>𠹺遙<EFBFBD>∠𠶖<EFBFBD><EFBFBD><EFBFBD>**頧株砭 (Polling)**<EFBFBD>?|
### **2.2 后端通用栈 (Backend Core)**
### **2.2 <EFBFBD>𡒊垢<EFBFBD>𡁶鍂<EFBFBD>?(Backend Core)**
| 蝏<>辣 | <20>匧<EFBFBD> | 霂湔<E99C82> |
| :---- | :---- | :---- |
| **运行时** | **Node.js 22 (LTS)** | 保持最新 LTS 版本。 |
| **Web 框架** | **Fastify 5.x** | 高性能，低开销，Schema 校验友好。 |
| **ORM** | **Prisma 6** | 类型安全的数据库操作，支持 Schema Migration。 |
| **参数校验** | **Zod** | 运行时 Schema 校验，可生成 TypeScript 类型。 |
| **日志** | **Winston / Pino** | 结构化 JSON 日志。 |
| **餈鞱<EFBFBD><EFBFBD>?* | **Node.js 22 (LTS)** | 靽脲<EFBFBD><EFBFBD><EFBFBD><EFBFBD>?LTS <20><>𧋦<EFBFBD>?|
| **Web 獢<EFBFBD>沲** | **Fastify 5.x** | 擃䀹<EFBFBD>扯<EFBFBD>嚗䔶<EFBFBD>撘<EFBFBD><EFBFBD><EFBFBD>嚗玺chema <20>⊿<EFBFBD><E28ABF>见末<E8A781>?|
| **ORM** | **Prisma 6** | 蝐餃<EFBFBD>摰匧<EFBFBD><EFBFBD><EFBFBD>㺭<EFBFBD>桀<EFBFBD><EFBFBD>滢<EFBFBD>嚗峕𣈲<EFBFBD>?Schema Migration<EFBFBD>?|
| **<EFBFBD><EFBFBD>㺭<EFBFBD>⊿<EFBFBD>** | **Zod** | 餈鞱<EFBFBD><EFBFBD>?Schema <EFBFBD>⊿<EFBFBD>嚗<EFBFBD>虾<EFBFBD><EFBFBD><EFBFBD> TypeScript 蝐餃<EFBFBD><EFBFBD>?|
| **<EFBFBD>亙<EFBFBD>** | **Winston / Pino** | 蝏𤘪<EFBFBD><EFBFBD>?JSON <20>亙<EFBFBD><E4BA99>?|
### **2.3 基础设施栈 (Infrastructure)**
### **2.3 <EFBFBD>箇<EFBFBD>霈暹鴌<EFBFBD>?(Infrastructure)**
| 蝏<>辣 | <20>匧<EFBFBD> | 霂湔<E99C82> |
| :---- | :---- | :---- |
| **数据库** | **PostgreSQL 15** | 存储用户、任务、资产元数据、结构化结果 (JSONB)。 |
| **缓存/队列** | **Redis 7** | 这里的 Redis 既做缓存，也是 **BullMQ** 的后端。 |
| **文件存储** | **MinIO / AWS S3** | 存储用户上传的 Excel、PDF 以及生成的中间文件。 |
| **<EFBFBD>唳旿摨?* | **PostgreSQL 15** | 摮睃<EFBFBD><EFBFBD>冽<EFBFBD><EFBFBD><EFBFBD>遙<EFBFBD>～<EFBFBD><EFBFBD><EFBFBD>鈭批<EFBFBD><EFBFBD>唳旿<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>蝏𤘪<EFBFBD> (JSONB)<EFBFBD>?|
| **蝻枏<EFBFBD>/<2F>笔<EFBFBD>** | **Redis 7** | 餈䠷<EFBFBD><EFBFBD>?Redis <EFBFBD>Ｗ<EFBFBD>蝻枏<EFBFBD>嚗䔶<EFBFBD><EFBFBD>?**BullMQ** <20><><EFBFBD>蝡胯<E89DA1>?|
| **<EFBFBD><EFBFBD>辣摮睃<EFBFBD>** | **MinIO / AWS S3** | 摮睃<EFBFBD><EFBFBD>冽<EFBFBD>銝𠹺<EFBFBD><EFBFBD>?Excel<EFBFBD><EFBFBD>DF 隞亙<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>葉<EFBFBD>湔<EFBFBD>隞嗚<EFBFBD>?|
## **3\. 璅∪<E79285>銝梶鍂<E6A2B6><E98D82><EFBFBD>舀<EFBFBD> (Module-Specific Stack)**
针对不同场景的特殊需求，各工具引入了特定的技术组件。
<EFBFBD><EFBFBD>笆銝滚<EFBFBD><EFBFBD>箸艶<EFBFBD><EFBFBD>鸌畾𢠃<EFBFBD>瘙<EFBFBD><EFBFBD><EFBFBD><EFBFBD>極<EFBFBD>瑕<EFBFBD><EFBFBD>乩<EFBFBD><EFBFBD>孵<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>舐<EFBFBD>隞嗚<EFBFBD>?
### **3.1 撌亙<E6928C> A嚗朞<E59A97>蝥批<E89DA5>撟嗅膥 (IO 撖<><E69296><EFBFBD>?**
### **3.1 工具 A：超级合并器 (IO 密集型)**
*核心挑战：大文件流式处理、日期解析、哈希匹配。*
*<2A>詨<EFBFBD><E8A9A8>烐<EFBFBD>嚗𡁜之<F0A1819C><E4B98B>辣瘚<E8BEA3><E7989A>憭<EFBFBD><E686AD><EFBFBD><EFBFBD>𠯫<EFBFBD>蠘圾<E8A098>僐<EFBFBD><E58390><EFBFBD>撣<EFBFBD>龪<EFBFBD>溻<EFBFBD>?
| 憸<><E686B8> | 銝梶鍂蝏<E98D82>辣 | <20>匧<EFBFBD><E58CA7><EFBFBD>眏 |
| :---- | :---- | :---- |
| **后端 (Excel)** | **ExcelJS** | 相比 SheetJS，它对 **Stream (流)** 的支持更好，能处理超过内存限制的大文件。 |
| **后端 (Date)** | **Day.js \+ CustomParseFormat** | 解决 Excel 杂乱的日期格式 (44927, 2023/1/1)，轻量且强大。 |
| **异步队列** | **BullMQ** | 处理耗时合并任务，支持进度汇报。 |
| **前端组件** | **Ant Design Steps / Upload** | 快速实现向导式 UI。 |
| **<EFBFBD>𡒊垢 (Excel)** | **ExcelJS** | <EFBFBD>豢<EFBFBD> SheetJS嚗<EFBFBD><EFBFBD>撖?**Stream (瘚?** <20><>𣈲<EFBFBD><F0A388B2>凒憟踝<E6869F><E8B89D>賢<EFBFBD><E8B3A2><EFBFBD><EFBFBD>餈<EFBFBD><E9A488>摮㗛<E691AE><E3979B>嗥<EFBFBD>憭扳<E686AD>隞嗚<E99A9E>?|
| **<EFBFBD>𡒊垢 (Date)** | **Day.js \+ CustomParseFormat** | 閫<EFBFBD><EFBFBD> Excel <EFBFBD><EFBFBD>僚<EFBFBD><EFBFBD>𠯫<EFBFBD><EFBFBD>聢撘?(44927, 2023/1/1)嚗諹蝠<EFBFBD>譍<EFBFBD>撘箏之<EFBFBD>?|
| **撘<EFBFBD>郊<EFBFBD>笔<EFBFBD>** | **BullMQ** | 憭<EFBFBD><EFBFBD><EFBFBD>埈𧒄<EFBFBD><EFBFBD>僎隞餃𦛚嚗峕𣈲<EFBFBD><EFBFBD><EFBFBD>摨行<EFBFBD><EFBFBD>乓<EFBFBD>?|
| **<EFBFBD>滨垢蝏<EFBFBD>辣** | **Ant Design Steps / Upload** | 敹恍<EFBFBD>笔<EFBFBD><EFBFBD>啣<EFBFBD>撖澆<EFBFBD> UI<EFBFBD>?|
### **3.2 工具 B：病历结构化机器人 (API/计算密集型)**
### **3.2 撌亙<EFBFBD> B嚗𡁶<E59A97><F0A181B6><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>箏膥鈭?(API/霈∠<E99C88>撖<EFBFBD><E69296><EFBFBD>?**
*核心挑战：LLM 编排、双模型并发、文本比对。*
*<2A>詨<EFBFBD><E8A9A8>烐<EFBFBD>嚗匁LM 蝻𡝗<E89DBB><F0A19D97><EFBFBD><EFBFBD>璅∪<E79285>撟嗅<E6929F><E59785><EFBFBD><EFBFBD><EFBFBD>祆<EFBFBD>撖嫘<E69296>?
| 憸<><E686B8> | 銝梶鍂蝏<E98D82>辣 | <20>匧<EFBFBD><E58CA7><EFBFBD>眏 |
| :---- | :---- | :---- |
| **后端 (AI)** | **LangChain.js** | 统一 DeepSeek 和 Qwen 的调用接口，管理 Prompt Template。 |
| **后端 (Diff)** | **diff-match-patch** (Google) | 计算两个模型输出的文本差异，或者原文的高亮位置。 |
| **后端 (比对)** | **Lodash / Dice Coefficient** | 用于 JSON 对象的深层比对和字符串相似度计算。 |
| **前端 (Grid)** | **TanStack Table** (Headless) | 因为需要高度定制“冲突单元格”的 UI (左右并排按钮)，Headless 库比 AntD Table 更灵活。 |
| **<EFBFBD>𡒊垢 (AI)** | **LangChain.js** | 蝏煺<EFBFBD> DeepSeek <EFBFBD>?Qwen <EFBFBD><EFBFBD><EFBFBD><EFBFBD>冽𦻖<EFBFBD><EFBFBD><EFBFBD>蝞∠<EFBFBD> Prompt Template<EFBFBD>?|
| **<EFBFBD>𡒊垢 (Diff)** | **diff-match-patch** (Google) | 霈∠<EFBFBD>銝支葵璅∪<EFBFBD>颲枏枂<EFBFBD><EFBFBD><EFBFBD><EFBFBD>砍榆撘<EFBFBD><EFBFBD><EFBFBD>𤥁<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>擃䀝漁雿滨蔭<EFBFBD>?|
| **<EFBFBD>𡒊垢 (瘥𥪜笆)** | **Lodash / Dice Coefficient** | <EFBFBD>其<EFBFBD> JSON 撖寡情<EFBFBD><EFBFBD>楛撅<EFBFBD><EFBFBD>撖孵<EFBFBD>摮㛖泵銝脩㮾隡澆漲霈∠<EFBFBD><EFBFBD>?|
| **<EFBFBD>滨垢 (Grid)** | **TanStack Table** (Headless) | <EFBFBD>牐蛹<EFBFBD><EFBFBD>閬<EFBFBD><EFBFBD>摨血<EFBFBD><EFBFBD>嗯<EFBFBD>𨅯<EFBFBD>蝒<EFBFBD><EFBFBD><EFBFBD><EFBFBD>聢<EFBFBD>萘<EFBFBD> UI (撌血𢰧撟嗆<E6929F><E59786>厰僼)嚗峵eadless 摨𤘪<EFBFBD> AntD Table <EFBFBD>渡<EFBFBD>瘣颯<EFBFBD>?|
### **3.3 工具 C：科研数据编辑器 (交互密集型)**
### **3.3 撌亙<EFBFBD> C嚗𡁶<E59A97><F0A181B6>娍㺭<E5A88D>桃<EFBFBD>颲穃膥 (鈭支<E988AD>撖<EFBFBD><E69296><EFBFBD>?**
*核心挑战：前端高性能渲染、本地计算、撤销重做。*
*<2A>詨<EFBFBD><E8A9A8>烐<EFBFBD>嚗𡁜<E59A97>蝡舫<E89DA1><E888AB>扯<EFBFBD>皜脫<E79A9C><E884AB><EFBFBD>𧋦<EFBFBD>啗恣蝞𨰜<E89D9E><F0A8B09C>伃<EFBFBD><E4BC83><EFBFBD>滚<EFBFBD><E6BB9A>?
| 憸<><E686B8> | 銝梶鍂蝏<E98D82>辣 | <20>匧<EFBFBD><E58CA7><EFBFBD>眏 |
| :---- | :---- | :---- |
| **前端 (Grid)** | **AG Grid Community** | **核心组件**。唯一能免费支持虚拟滚动、列拖拽、Excel 级交互的库。 |
| **前端 (Storage)** | **Dexie.js (IndexedDB)** | **Local-First 架构核心**。在浏览器端存储 5-10 万行数据，避免频繁网络请求。 |
| **前端 (State)** | **Zustand \+ Immer** | 利用 Immer 的 Patches 功能实现 **Undo/Redo (撤销重做)** 栈。 |
| **前端 (Calc)** | **Math.js** | 解决 JS 浮点数精度问题，解析用户输入的医学公式 (ln, pow)。 |
| **前端 (Chart)** | **Ant Design Charts (G2)** | 在智能侧边栏中绘制直方图和频次图。 |
| **<EFBFBD>滨垢 (Grid)** | **AG Grid Community** | **<EFBFBD>詨<EFBFBD>蝏<EFBFBD>辣**<2A><>𣈲銝<F0A388B2><E98A9D>賢<EFBFBD>韐寞𣈲<E5AF9E><F0A388B2><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>具<EFBFBD><E585B7><EFBFBD><EFBFBD>𡝗嗻<F0A19D97><E597BB>xcel 蝥找漱鈭垍<E988AD>摨瓐<E691A8>?|
| **<EFBFBD>滨垢 (Storage)** | **Dexie.js (IndexedDB)** | **Local-First <EFBFBD>嗆<EFBFBD><EFBFBD>詨<EFBFBD>**<EFBFBD><EFBFBD>銁瘚讛<EFBFBD><EFBFBD>函垢摮睃<EFBFBD> 5-10 銝<><E98A9D><EFBFBD>唳旿嚗屸<E59A97><E5B1B8>漤<EFBFBD>蝜<EFBFBD><E89D9C>蝏𡏭窈瘙<E7AA88><E79899>?|
| **<EFBFBD>滨垢 (State)** | **Zustand \+ Immer** | <EFBFBD>拍鍂 Immer <EFBFBD>?Patches <EFBFBD>蠘<EFBFBD>摰䂿緵 **Undo/Redo (<EFBFBD>日<EFBFBD><EFBFBD>滚<EFBFBD>)** <EFBFBD><EFBFBD><EFBFBD>?|
| **<EFBFBD>滨垢 (Calc)** | **Math.js** | 閫<EFBFBD><EFBFBD> JS 瘚桃<EFBFBD><EFBFBD>啁移摨阡䔮憸矋<EFBFBD>閫<EFBFBD><EFBFBD><EFBFBD>冽<EFBFBD>颲枏<EFBFBD><EFBFBD><EFBFBD>龫摮血<EFBFBD>撘?(ln, pow)<EFBFBD>?|
| **<EFBFBD>滨垢 (Chart)** | **Ant Design Charts (G2)** | <EFBFBD>冽惣<EFBFBD>賭儒颲寞<EFBFBD>銝剔<EFBFBD><EFBFBD>嗥凒<EFBFBD>孵㦛<EFBFBD>屸<EFBFBD>甈∪㦛<EFBFBD>?|
## **4\. <20>唳旿鈭支<E988AD><E694AF><EFBFBD><EFBFBD> (Data Standards)**
为了打通 A \-\> B \-\> C 的流转，必须定义统一的数据交换格式。
銝箔<EFBFBD><EFBFBD>㯄<EFBFBD>?A \-\> B \-\> C <EFBFBD><EFBFBD><EFBFBD>頧穿<EFBFBD>敹<EFBFBD>◆摰帋<EFBFBD>蝏煺<EFBFBD><EFBFBD><EFBFBD>㺭<EFBFBD>桐漱<EFBFBD>Ｘ聢撘譌<EFBFBD>?
### **4.1 <20><><EFBFBD>瘚<EFBFBD>蓮<EFBFBD>澆<EFBFBD>**
* **文件物理格式：** 统一使用 **CSV (UTF-8 with BOM)** 或 **JSON Lines (.jsonl)**。
* *理由：* Stream 处理最快，且不依赖 Excel 复杂的 XML 结构。
* **日期标准：** 所有工具产出的日期，必须归一化为 YYYY-MM-DD 字符串。
* **空值标准：** 统一为 null (JSON) 或 "" (CSV)，严禁使用 "NA", "-"。
* **<EFBFBD><EFBFBD>辣<EFBFBD>拍<EFBFBD><EFBFBD>澆<EFBFBD>嚗?* 蝏煺<E89D8F>雿輻鍂 **CSV (UTF-8 with BOM)** <EFBFBD>?**JSON Lines (.jsonl)**<2A>?
* *<EFBFBD><EFBFBD>眏嚗? Stream 憭<EFBFBD><EFBFBD><EFBFBD><EFBFBD>敹恬<EFBFBD>銝𥪯<EFBFBD>靘肽<EFBFBD> Excel 憭齿<E686AD><E9BDBF>?XML 蝏𤘪<E89D8F><F0A498AA>?
* **<EFBFBD>交<EFBFBD><EFBFBD><EFBFBD><EFBFBD>嚗?* <20><><EFBFBD>匧極<E58CA7>瑚漣<E7919A>箇<EFBFBD><E7AE87>交<EFBFBD>嚗<EFBFBD><E59A97>憿餃<E686BF>銝<EFBFBD><E98A9D>碶蛹 YYYY-MM-DD 摮㛖泵銝脯<EFBFBD>?
* **蝛箏<EFBFBD>潭<EFBFBD><EFBFBD><EFBFBD><EFBFBD>** 蝏煺<E89D8F>銝?null (JSON) <EFBFBD>?"" (CSV)嚗䔶艇蝳<EFBFBD>蝙<EFBFBD>?"NA", "-"<EFBFBD>?
### **4.2 API <20>滚<EFBFBD>蝏𤘪<E89D8F> (Standard Response)**
interface ApiResponse\<T\> {
code: number; // 0: 成功, \>0: 错误码
code: number; // 0: <EFBFBD>𣂼<EFBFBD>, \>0: <EFBFBD>躰秤<EFBFBD>?
data: T; // 銝𡁜𦛚<F0A1819C>唳旿
message?: string; // <20>躰秤<E8BAB0>鞟內
meta?: { // <20><>△<EFBFBD>硋<EFBFBD><E7A18B>唳旿
@@ -145,8 +140,8 @@ interface ApiResponse\<T\> {
## **5\. 撘<><E69298>𤑳㴓憓<E3B493><E68693><EFBFBD>函蔡 (DevOps)**
* **包管理：** **pnpm** (推荐，节省磁盘空间，安装快)。
* **Monorepo (可选)：** 建议使用 Turborepo 或 Nx 管理 frontend, backend-api, worker-merger, worker-ai 等包，共享类型定义。
* **<EFBFBD><EFBFBD>恣<EFBFBD><EFBFBD><EFBFBD>** **pnpm** (<EFBFBD>刻<EFBFBD>嚗諹<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>条征<EFBFBD>湛<EFBFBD>摰㕑<EFBFBD>敹?<3F>?
* **Monorepo (<EFBFBD>舫<EFBFBD>?嚗?* 撱箄悅雿輻鍂 Turborepo <EFBFBD>?Nx 蝞∠<EFBFBD> frontend, backend-api, worker-merger, worker-ai 蝑匧<EFBFBD>嚗<EFBFBD><EFBFBD>鈭怎掩<EFBFBD>见<EFBFBD>銋剹<EFBFBD>?
* **摰孵膥<E5ADB5>吔<EFBFBD>**
* **API Service:** 无状态，可水平扩展。
* **Worker Service:** 单独部署，根据 CPU/内存负载进行扩容（特别是 Worker A 处理大文件时内存消耗大）。
* **API Service:** <EFBFBD>删𠶖<EFBFBD><EFBFBD><EFBFBD><EFBFBD>舀偌撟單<EFBFBD>撅𨰻<EFBFBD>?
* **Worker Service:** <EFBFBD>閧𡠺<EFBFBD>函蔡嚗峕覔<EFBFBD>?CPU/<2F><><EFBFBD>韐蠘蝸餈𥡝<E9A488><F0A5A19D>拙捆嚗<E68D86>鸌<EFBFBD>急糓 Worker A 憭<><E686AD>憭扳<E686AD>隞嗆𧒄<E59786><F0A79284><EFBFBD>瘨<EFBFBD><E798A8>堒之嚗剹<E59A97>

61
docs/03-业务模块/DC-数据清洗整理/02-技术设计/技术设计文档：工具 A - 医疗数据超级合并器 (The Super Merger).md
View File

@@ -1,17 +1,16 @@
# **技术设计文档：工具 A \- 医疗数据超级合并器 (The Super Merger)**
# **技术设计文档：工具 A \- 医疗数æ<C2B0>®è¶…级å<C2A7>ˆå¹¶å™?(The Super Merger)**
| 文档类型 | Technical Design Document (TDD) |
| :---- | :---- |
| **对应 PRD** | **PRD\_工具A\_超级å<C2A7>ˆå¹¶å™¨\_V2.md** |
| **版本** | **V2.0** (架构升级：访视基准 \+ 时间窗) |
| **状态** | Draft |
| **核心目标** | 构建一个基于 Web 的 ETL 工具，解决临床科研中“一对多”数据对齐难题，实现基于时间窗的精准合并。 |
| **版本** | **V2.0** (架构å<EFBFBD>‡çº§ï¼šè®¿è§†åŸºå‡?\+ 时间çª? |
| **状�* | Draft |
| **核心目标** | 构建一个基äº?Web çš?ETL 工具，解决临床科研中“一对多â€<EFBFBD>æ•°æ<EFBFBD>®å¯¹é½<EFBFBD>难题，实现基于时间窗的精准å<EFBFBD>ˆå¹¶ã€?|
## **1\. 总体架构设计 (Architecture Overview)**
鉴于处理 Excel 文件（解析、合并、写入）是 CPU 密集型和内存敏感型操作，为了避免阻塞 Node.js 主线程，我们采用 **“异步任务队列 \+ 流式处理”** 的架构模式。
### **1.1 系统架构图**
鉴于处ç<EFBFBD>† Excel 文件（解æž<C3A6>ã€<C3A3>å<EFBFBD>ˆå¹¶ã€<C3A3>写入）æ˜?CPU 密集型和内存æ•<C3A6>æ„Ÿåž‹æ“<C3A6>作，为了é<E280A0>¿å…<C3A5>阻塞 Node.js 主线程，我们采用 **“异步任务队åˆ?\+ æµ<C3A6>å¼<C3A5>处ç<E2809E>†â€?* 的架构模å¼<C3A5>ã€?
### **1.1 系统架构�*
graph TD
Client\[React å‰<C3A5>端 (Wizard UI)\]
@@ -30,7 +29,7 @@ graph TD
end
subgraph Storage \[æ•°æ<C2B0>®å­˜å‚¨\]
PG\[(PostgreSQL 业务库)\]
PG\[(PostgreSQL 业务�\]
FileSys\[临时文件存储 (Local/S3)\]
Redis\[(Redis 缓存/队列)\]
end
@@ -43,38 +42,36 @@ graph TD
BullMQ \--消费任务--\> Merger
Merger \--读å<C2BB>–辅表(å…¨é‡<C3A9>)--\> FileSys
Merger \--读å<C2BB>–主表(æµ<C3A6>å¼<C3A5>)--\> FileSys
Merger \--流式合并与写入--\> FileSys
Merger \--更新状态--\> PG
Merger \--æµ<EFBFBD>å¼<EFBFBD>å<EFBFBD>ˆå¹¶ä¸Žå†™å…?-\> FileSys
Merger \--更新状�-\> PG
Client \--3.轮询/WS 进度--\> TaskAPI
Client \--4.下载结果--\> API\_Server
## **2\. 技术选型 (Tech Stack)**
基于现有技术栈的针对性选择：
| 层级 | 技术组件 | 选型理由 |
基于现有技术栈的针对性选择�
| 层级 | 技术组ä»?| 选型ç<E280B9>†ç”± |
| :---- | :---- | :---- |
| **前端** | **React 19 \+ Ant Design 5** | 利用 AntD 的 Steps, Upload, Tree (树状选择器) 快速构建 UI。 |
| **后端框架** | **Fastify 5.x** | 高性能 HTTP 框架，适合高并发 I/O。 |
| **Excel 处理** | **ExcelJS** | **核心组件**。支持流式读写 (Streaming I/O)，这是处理大数据量不崩的关键。 |
| **日期处理** | **Day.js \+ CustomParseFormat** | **新增**。处理“时间地狱”的核心库，需要极强的容错解析能力。 |
| **任务队列** | **BullMQ \+ Redis** | 必须异步处理。合并逻辑复杂，耗时较长，必须用队列。 |
| **数据库** | **PostgreSQL 15 \+ Prisma** | 存储任务状态、文件元数据。**不建议将原始 Excel 数据存入 PG**。 |
| **验证库** | **Zod** | 用于校验前端提交的复杂映射配置结构。 |
| **å‰<EFBFBD>端** | **React 19 \+ Ant Design 5** | 利用 AntD çš?Steps, Upload, Tree (树状选择å™? 快速构å»?UIã€?|
| **å<EFBFBD>Žç«¯æ¡†æž¶** | **Fastify 5.x** | 高性能 HTTP 框架，适å<E2809A>ˆé«˜å¹¶å<C2B6>?I/Oã€?|
| **Excel 处ç<EFBFBD>†** | **ExcelJS** | **核心组件**。支æŒ<C3A6>æµ<C3A6>å¼<C3A5>读å†?(Streaming I/O)，这是处ç<E2809E>†å¤§æ•°æ<C2B0>®é‡<C3A9>ä¸<C3A4>崩的关键ã€?|
| **日期处ç<EFBFBD>†** | **Day.js \+ CustomParseFormat** | **新增**。处ç<E2809E>†â€œæ—¶é—´åœ°ç‹±â€<C3A2>的核心库，需è¦<C3A8>æž<C3A6>强的容错解æž<C3A6>能力ã€?|
| **任务队列** | **BullMQ \+ Redis** | 必须异步处ç<EFBFBD>†ã€‚å<EFBFBD>ˆå¹¶é€»è¾‘å¤<EFBFBD>æ<EFBFBD>‚，耗时较长，必须用队列ã€?|
| **æ•°æ<EFBFBD>®åº?* | **PostgreSQL 15 \+ Prisma** | 存储任务状æ€<EFBFBD>ã€<EFBFBD>文件元数æ<EFBFBD>®ã€?*ä¸<C3A4>建议将原始 Excel æ•°æ<C2B0>®å­˜å…¥ PG**ã€?|
| **验è¯<EFBFBD>åº?* | **Zod** | 用于校验å‰<EFBFBD>端æ<EFBFBD><EFBFBD>交的å¤<EFBFBD>æ<EFBFBD>‚映射é…<EFBFBD>置结构ã€?|
### **2.1 关键技术决策 (ADR): 为什么不用 Python (Pandas)?**
### **2.1 关键技术决ç­?(ADR): 为什么ä¸<C3A4>ç”?Python (Pandas)?**
虽然 Python Pandas 在数据合并上代码更简洁，但针对**本工具**的场景，我们决定坚持使用 **Node.js**，理由如下：
虽然 Python Pandas 在数æ<EFBFBD>®å<EFBFBD>ˆå¹¶ä¸Šä»£ç <EFBFBD>更简æ´<EFBFBD>，但针å¯?*本工å…?*的场景，我们决定å<C5A1>šæŒ<C3A6>使用 **Node.js**，ç<C592>†ç”±å¦‚下：
1. **流式处理优势：** Pandas 倾向于全量加载内存，容易 OOM。Node.js 的 Stream API 天然支持背压，能稳定处理“数据膨胀”问题。
2. **架构一致性：** 避免引入 Python Runtime 带来的运维成本和 IPC 开销。
3. **结论：** 对于精确匹配和逻辑清洗，Node.js 性能足够且更可控。
## **3\. 数据库设计 (Database Schema)**
1. **æµ<EFBFBD>å¼<EFBFBD>处ç<EFBFBD>†ä¼˜åŠ¿ï¼?* Pandas 倾å<C2BE>‘于全é‡<C3A9>加载内存，容易 OOM。Node.js çš?Stream API 天然支æŒ<EFBFBD>背压，能稳定处ç<EFBFBD>†â€œæ•°æ<EFBFBD>®è†¨èƒ€â€<EFBFBD>问题ã€?
2. **架构一致性：** é<>¿å…<C3A5>引入 Python Runtime 带æ<C2A6>¥çš„è¿<C3A8>ç»´æˆ<C3A6>本和 IPC 开销ã€?
3. **结论ï¼?* 对于精确匹é…<C3A9>和逻辑清洗，Node.js 性能足够且更å<C2B4>¯æŽ§ã€?
## **3\. æ•°æ<C2B0>®åº“设è®?(Database Schema)**
### **Prisma Schema 定义**
// 任务状态枚举
// 任务状æ€<EFBFBD>æžšä¸?
enum TaskStatus {
PENDING
PROCESSING
@@ -82,7 +79,7 @@ enum TaskStatus {
FAILED
}
// 合并任务表
// å<EFBFBD>ˆå¹¶ä»»åŠ¡è¡?
model MergeTask {
id String @id @default(uuid())
userId String
@@ -92,9 +89,9 @@ model MergeTask {
// 核心é…<C3A9>置字段 (V2 æ›´æ–°)
// 结构: {
// anchorFileId: string,
// anchorKeys: { id: "住院号", time: "入院日期" },
// anchorKeys: { id: "ä½<EFBFBD>院å<EFBFBD>?, time: "入院日期" },
// window: { daysBefore: 7, daysAfter: 7 },
// files: \[{ id: "f2", timeCol: "报告时间", columns: \["白细胞"\] }\]
// files: \[{ id: "f2", timeCol: "报告时间", columns: \["白细�\] }\]
// }
config Json?
@@ -113,7 +110,7 @@ model SourceFile {
task MergeTask @relation(fields: \[taskId\], references: \[id\])
filename String
filepath String
headers Json // \["住院号", "姓名", "入院日期"\]
headers Json // \["ä½<EFBFBD>院å<EFBFBD>?, "姓å<E2809C><C3A5>", "入院日期"\]
rowCount Int
fileSize Int
uploadedAt DateTime @default(now())

121
docs/03-业务模块/DC-数据清洗整理/02-技术设计/技术设计文档：工具 B - 病历结构化机器人 (The AI Structurer).md
View File

@@ -4,14 +4,13 @@
| :---- | :---- |
| **撖孵<E69296> PRD** | **PRD\_撌亙<E6928C>B\_<><5F><EFBFBD>蝏𤘪<E89D8F><F0A498AA>𡝗㦤<F0A19D97>其犖\_V2.md** |
| **<EFBFBD><EFBFBD>𧋦** | **V2.0** (<28>嗆<EFBFBD><E59786><EFBFBD>漣嚗𡁜<E59A97>璅∪<E79285>鈭文<E988AD>撉諹<E69289>) |
| **状态** | Draft |
| **核心目标** | 构建一个高可信度的医疗文本结构化引擎，通过**双模型（DeepSeek & Qwen）并发提取**与**自动交叉验证**，解决 AI 幻觉问题。 |
| **<EFBFBD>嗆<EFBFBD>?* | Draft |
| **<EFBFBD>詨<EFBFBD><EFBFBD>格<EFBFBD>** | <EFBFBD><EFBFBD>遣銝<EFBFBD>銝芷<EFBFBD><EFBFBD>臭縑摨衣<EFBFBD><EFBFBD>餌<EFBFBD><EFBFBD><EFBFBD>𧋦蝏𤘪<EFBFBD><EFBFBD>硋<EFBFBD><EFBFBD>𠬍<EFBFBD><EFBFBD>朞<EFBFBD>**<2A>峕芋<E5B395>页<EFBFBD>DeepSeek & Qwen嚗匧僎<E58CA7>烐<EFBFBD><E78390>?*銝?*<2A>芸𢆡鈭文<E988AD>撉諹<E69289>**嚗諹圾<E8ABB9>?AI 撟餉<E6929F><E9A489>桅<EFBFBD><E6A185>?|
## **1\. <20>颱<EFBFBD><E9A2B1>嗆<EFBFBD>霈曇恣 (Architecture Overview)**
系统架构从“单线性流水线”升级为 **“Y型并发流水线”**。数据进入后，分发给两个不同的 LLM 模型并行处理，结果汇聚到“冲突检测引擎”进行比对，最后输出到人工验证网格。
### **1.1 系统架构图**
蝟餌<EFBFBD><EFBFBD>嗆<EFBFBD>隞𢛶<EFBFBD>𨅯<EFBFBD>蝥踵<EFBFBD>扳<EFBFBD>瘞渡瑪<EFBFBD>嘥<EFBFBD>蝥找蛹 **<EFBFBD>陖<EFBFBD>见僎<EFBFBD>烐<EFBFBD>瘞渡瑪<EFBFBD>?*<2A><>㺭<EFBFBD>株<EFBFBD><E6A0AA>亙<EFBFBD>嚗<EFBFBD><E59A97><EFBFBD>𤑳<EFBFBD>銝支葵銝滚<E98A9D><E6BB9A>?LLM 璅∪<E79285>撟嗉<E6929F>憭<EFBFBD><E686AD>嚗𣬚<E59A97><F0A3AC9A>𨀣<EFBFBD><F0A880A3>𡁜<EFBFBD><F0A1819C>𨅯<EFBFBD>蝒<EFBFBD><E89D92>瘚见<E7989A><E8A781>𢛶<EFBFBD>肽<EFBFBD>銵峕<E98AB5>撖對<E69296><E5B08D><EFBFBD><EFBFBD>舘<EFBFBD><E88898>箏<EFBFBD>鈭箏極撉諹<E69289>蝵烐聢<E78390>?
### **1.1 蝟餌<E89D9F><E9A48C>嗆<EFBFBD><E59786>?*
graph TD
Client\[React <20>滨垢 (Grid & Drawer UI)\]
@@ -46,50 +45,45 @@ graph TD
Orchestrator \--4.<2E>望<EFBFBD>--\> PII\_Engine
PII\_Engine \--5.撟嗉<E6929F>靚<EFBFBD>鍂--\> ClientA & ClientB
ClientA & ClientB \--6.餈𥪜<E9A488>JSON--\> CrossValidator
CrossValidator \--7.计算一致性--\> PG
CrossValidator \--7.霈∠<EFBFBD>銝<EFBFBD><EFBFBD>湔<EFBFBD>?-\> PG
Client \--8.<2E>匧<EFBFBD>蝵烐聢<E78390>唳旿--\> VerifyAPI
VerifyAPI \--9.鈭箏極鋆<E6A5B5><E98B86>--\> PG
## **2\. <20><><EFBFBD>舫<EFBFBD>匧<EFBFBD> (Tech Stack)**
| 层级 | 技术组件 | 选型理由 |
| 撅<EFBFBD>漣 | <20><><EFBFBD>舐<EFBFBD>隞?| <20>匧<EFBFBD><E58CA7><EFBFBD>眏 |
| :---- | :---- | :---- |
| **后端框架** | **Fastify 5.x** | 高性能异步 I/O，适合处理高并发模型调用。 |
| **模型接入** | **LangChain.js** | 统一封装 DeepSeek 和 Qwen 的调用接口，便于切换模型。 |
| **任务队列** | **BullMQ** | 核心组件。V2 需要利用 Flow 功能或手动编排来实现“等待两个模型都返回”的逻辑。 |
| **冲突检测** | **Lodash (基础) \+ Dice Coefficient (进阶)** | 用于比对两个 JSON 对象的字段差异。文本相似度可使用简单的 Dice 系数或 Levenshtein 距离，暂不需要重型向量库。 |
| **数据库** | **PostgreSQL 15** | 存储 JSONB 格式的双模型结果。 |
| **前端交互** | **React \+ TanStack Table** | V2 改为全景网格，数据量大时需要 TanStack Table (Headless) 配合虚拟滚动。 |
| **<EFBFBD>𡒊垢獢<EFBFBD>沲** | **Fastify 5.x** | 擃䀹<EFBFBD>扯<EFBFBD>撘<EFBFBD>郊 I/O嚗屸<E59A97><E5B1B8><EFBFBD>憭<EFBFBD><E686AD>擃睃僎<E79D83>烐芋<E78390>贝<EFBFBD><E8B49D>具<EFBFBD>?|
| **璅∪<EFBFBD><EFBFBD>亙<EFBFBD>** | **LangChain.js** | 蝏煺<EFBFBD>撠<EFBFBD><EFBFBD> DeepSeek <EFBFBD>?Qwen <EFBFBD><EFBFBD><EFBFBD><EFBFBD>冽𦻖<EFBFBD><EFBFBD><EFBFBD>靘蹂<EFBFBD><EFBFBD><EFBFBD>揢璅∪<EFBFBD><EFBFBD>?|
| **隞餃𦛚<EFBFBD>笔<EFBFBD>** | **BullMQ** | <EFBFBD>詨<EFBFBD>蝏<EFBFBD>辣<EFBFBD><EFBFBD>2 <20><>閬<EFBFBD>⏚<EFBFBD>?Flow <20>蠘<EFBFBD><E8A098>𡝗<EFBFBD><F0A19D97>函<EFBFBD><E587BD>埝䔉摰䂿緵<E482BF>𦦵<EFBFBD>敺<EFBFBD>舅銝芣芋<E88AA3>钅<EFBFBD>餈𥪜<E9A488><F0A5AA9C>萘<EFBFBD><E89098>餉<EFBFBD><E9A489>?|
| **<EFBFBD>脩<EFBFBD>璉<EFBFBD>瘚?* | **Lodash (<EFBFBD>箇<EFBFBD>) \+ Dice Coefficient (餈偦𧫴)** | <EFBFBD>其<EFBFBD>瘥𥪜笆銝支葵 JSON 撖寡情<E5AFA1><E68385><EFBFBD>畾萄榆撘<E6A686><E69298><EFBFBD><EFBFBD><EFBFBD>祉㮾隡澆漲<E6BE86>臭蝙<E887AD>函<EFBFBD><E587BD>閧<EFBFBD> Dice 蝟餅㺭<EFBFBD>?Levenshtein 頝萘氖嚗峕<EFBFBD>銝漤<EFBFBD>閬<EFBFBD><EFBFBD><EFBFBD>见<EFBFBD><EFBFBD>誩<EFBFBD><EFBFBD>?|
| **<EFBFBD>唳旿摨?* | **PostgreSQL 15** | 摮睃<EFBFBD> JSONB <EFBFBD>澆<EFBFBD><EFBFBD><EFBFBD><EFBFBD>璅∪<EFBFBD>蝏𤘪<EFBFBD><EFBFBD>?|
| **<EFBFBD>滨垢鈭支<EFBFBD>** | **React \+ TanStack Table** | V2 <EFBFBD>嫣蛹<EFBFBD>冽艶蝵烐聢嚗峕㺭<EFBFBD>桅<EFBFBD>憭扳𧒄<EFBFBD><EFBFBD>閬?TanStack Table (Headless) <EFBFBD>滚<EFBFBD><EFBFBD>𡁏<EFBFBD>皛𡁜𢆡<EFBFBD>?|
## **3\. <20>詨<EFBFBD>瘚<EFBFBD><E7989A>霈曇恣 (Core Logic)**
### **3.1 <20>箄<EFBFBD>雿𤘪<E99BBF> (Health Check Logic)**
* **触发时机：** 用户在前端选择“文本列”的瞬间。
* **执行逻辑：**
1. 后端读取该列的前 100 行（不读全量）。
2. 计算统计指标：
* emptyRate: 空值 / 总行数。
* avgLength: 非空行的平均字符数。
3. **拦截策略：** 若 emptyRate \> 0.8 或 avgLength \< 10，返回 status: 'BAD'。
4. **Token 预估：** totalRows \* avgLength \* 1.5 (粗略估算)。
* **閫血<EFBFBD><EFBFBD>嗆㦤嚗?* <20>冽<EFBFBD><E586BD>典<EFBFBD>蝡舫<E89DA1>㗇𥋘<E39787>𨀣<EFBFBD><F0A880A3>砍<EFBFBD><E7A08D>萘<EFBFBD><E89098>祇𡢿<E7A587>?
* **<EFBFBD>扯<EFBFBD><EFBFBD>餉<EFBFBD>嚗?*
1. <EFBFBD>𡒊垢霂餃<EFBFBD>霂亙<EFBFBD><EFBFBD><EFBFBD><EFBFBD> 100 銵䕘<E98AB5>銝滩粉<E6BBA9>券<EFBFBD>嚗剹<E59A97>?
2. 霈∠<EFBFBD>蝏蠘恣<EFBFBD><EFBFBD><EFBFBD>嚗?
* emptyRate: 蝛箏<EFBFBD>?/ <20>餉<EFBFBD><E9A489>啜<EFBFBD>?
* avgLength: <EFBFBD>䂿征銵𣬚<EFBFBD>撟喳<EFBFBD>摮㛖泵<EFBFBD>啜<EFBFBD>?
3. **<EFBFBD>行⏛蝑𣇉裦嚗?* <20>?emptyRate \> 0.8 <EFBFBD>?avgLength \< 10嚗諹<EFBFBD><EFBFBD>?status: 'BAD'<EFBFBD>?
4. **Token 憸<EFBFBD>摯嚗?* totalRows \* avgLength \* 1.5 (蝎㛖裦隡啁<EFBFBD>)<29>?
### **3.2 <20>𣬚𤩅<F0A3AC9A>𣂼<EFBFBD>銝𦒘漱<F0A69298>厰<EFBFBD>霂?(Double-Blind & Validation)**
### **3.2 双盲提取与交叉验证 (Double-Blind & Validation)**
这是 V2 的心脏。
#### **A. 提示词工程 (Prompt Engineering)**
为了方便比对，必须强制两个模型输出**完全一致的 JSON 结构**。
餈蹱糓 V2 <20><><EFBFBD><EFBFBD>譌<EFBFBD>?
#### **A. <20>鞟內霂滚極蝔?(Prompt Engineering)**
銝箔<EFBFBD><EFBFBD>嫣噶瘥𥪜笆嚗<EFBFBD><EFBFBD>憿餃撩<EFBFBD>嗡舅銝芣芋<EFBFBD>贝<EFBFBD><EFBFBD>?*摰<><E691B0>銝<EFBFBD><E98A9D>渡<EFBFBD> JSON 蝏𤘪<E89D8F>**<2A>?
* **System Prompt:** "You are a medical structural extraction assistant..."
* **Constraint:** "Output strictly in JSON format. Keys must be: \['tumor\_size', 'lymph\_node', ...\]."
* **Temperature:** 设为 0，追求最大确定性。
* **Temperature:** 霈曆蛹 0嚗諹蕭瘙<E895AD><E79899>憭抒＆摰𡁏<E691B0>扼<EFBFBD>?
#### **B. 鈭文<E988AD>撉諹<E69289>蝞埈<E89D9E> (The Judge)**
当 Model A (DeepSeek) 和 Model B (Qwen) 返回结果后，执行比对：
敶?Model A (DeepSeek) <EFBFBD>?Model B (Qwen) 餈𥪜<EFBFBD>蝏𤘪<EFBFBD><EFBFBD>𠬍<EFBFBD><EFBFBD>扯<EFBFBD>瘥𥪜笆嚗?
function validate(jsonA, jsonB) {
const conflicts \= \[\];
const keys \= Object.keys(jsonA);
@@ -101,10 +95,10 @@ function validate(jsonA, jsonB) {
// 1\. 蝎曄＆<E69B84>寥<EFBFBD>
if (valA \=== valB) continue;
// 2\. 数值归一化匹配 (如 "3cm" vs "3.0cm")
// 2\. <EFBFBD>啣<EFBFBD>澆<EFBFBD>銝<EFBFBD><EFBFBD>硋龪<EFBFBD>?(憒?"3cm" vs "3.0cm")
if (isNumber(valA) && isNumber(valB) && parse(valA) \=== parse(valB)) continue;
// 3\. (可选) 语义相似度匹配
// 3\. (<EFBFBD>舫<EFBFBD>? 霂凋<E99C82><E5878B>訾撮摨血龪<E8A180>?
// if (similarity(valA, valB) \> 0.95) continue;
conflicts.push(key);
@@ -113,13 +107,12 @@ function validate(jsonA, jsonB) {
return conflicts.length \=== 0 ? 'CLEAN' : 'CONFLICT';
}
## **4\. 数据库设计 (Database Schema)**
V2 需要存储两份 AI 结果以及用户的裁决结果。
## **4\. <EFBFBD>唳旿摨栞挽霈?(Database Schema)**
V2 <20><>閬<EFBFBD><E996AC><EFBFBD>其舅隞?AI 蝏𤘪<E89D8F>隞亙<E99A9E><E4BA99>冽<EFBFBD><E586BD><EFBFBD><EFBFBD><EFBFBD>喟<EFBFBD><E5969F>栶<EFBFBD>?
### **Prisma Schema <20>湔鰵**
// 任务表
// 隞餃𦛚銵?
model ExtractionJob {
id String @id @default(uuid())
// ...<2E>嗡<EFBFBD>摮埈挾
@@ -128,7 +121,7 @@ model ExtractionJob {
targetFields Json // <20>格<EFBFBD>摮埈挾摰帋<E691B0> \[{name: "<22>輻𠈔憭批<E686AD>", desc: "..."}\]
}
// 单行记录表
// <EFBFBD>閗<EFBFBD>霈啣<EFBFBD>銵?
model ExtractionItem {
id String @id @default(uuid())
jobId String
@@ -138,51 +131,47 @@ model ExtractionItem {
resultA Json? // DeepSeek 蝏𤘪<E89D8F> { "size": "3cm" }
resultB Json? // Qwen 蝏𤘪<E89D8F> { "size": "3.0 cm" }
// 冲突检测结果
// <EFBFBD>脩<EFBFBD>璉<EFBFBD>瘚讠<EFBFBD><EFBFBD>?
status ItemStatus // PENDING, CLEAN, CONFLICT, RESOLVED
conflictFields String\[\] // \["size"\] 记录哪些字段冲突了
conflictFields String\[\] // \["size"\] 霈啣<EFBFBD><EFBFBD>芯<EFBFBD>摮埈挾<EFBFBD>脩<EFBFBD>鈭?
// 最终采纳结果 (用户裁决后写入，或者一致时自动写入)
// <EFBFBD><EFBFBD>蝏<EFBFBD><EFBFBD>蝥喟<EFBFBD><EFBFBD>?(<28>冽<EFBFBD>鋆<EFBFBD><E98B86><EFBFBD>𤾸<EFBFBD><F0A4BEB8>伐<EFBFBD><E4BC90>𤥁<EFBFBD><F0A4A581><EFBFBD><EFBFBD>湔𧒄<E6B994>芸𢆡<E88AB8>坔<EFBFBD>)
finalResult Json?
}
## **5\. <20>亙藁霈曇恣 (API Endpoints)**
### **5.1 模版与配置**
* GET /api/templates: 获取预设的疾病和报告模版列表。
* POST /api/jobs: 创建任务，Payload 中需包含 diseaseType 和 reportType，便于后端组装 Prompt。
### **5.1 璅∠<EFBFBD>銝𡡞<EFBFBD>蝵?*
* GET /api/templates: <20>瑕<EFBFBD>憸<EFBFBD>挽<EFBFBD><E68CBD>𪆴<EFBFBD><F0AA86B4><EFBFBD><EFBFBD>亙<EFBFBD>璅∠<E79285><E288A0>𡑒”<F0A19192>?
* POST /api/jobs: <20>𥕦遣隞餃𦛚嚗釶ayload 銝剝<E98A9D><E5899D><EFBFBD>鉄 diseaseType <20>?reportType嚗䔶噶鈭𤾸<E988AD>蝡舐<E89DA1>鋆?Prompt<70>?
### **5.2 蝵烐聢撉諹<E69289> (Grid Verification)**
* GET /api/jobs/:id/rows: 分页获取验证数据。
* **Response:** 返回 originalText, resultA, resultB, conflictFields。
* POST /api/items/:id/resolve: 单行裁决。
* **Payload:** { field: "tumor\_size", chosenValue: "3cm" }。
* **Logic:** 更新 finalResult，如果该行所有冲突字段都已解决，将 status 更新为 RESOLVED。
* GET /api/jobs/:id/rows: <EFBFBD><EFBFBD>△<EFBFBD>瑕<EFBFBD>撉諹<EFBFBD><EFBFBD>唳旿<EFBFBD>?
* **Response:** 餈𥪜<EFBFBD> originalText, resultA, resultB, conflictFields<EFBFBD>?
* POST /api/items/:id/resolve: <EFBFBD>閗<EFBFBD>鋆<EFBFBD><EFBFBD><EFBFBD>?
* **Payload:** { field: "tumor\_size", chosenValue: "3cm" }<EFBFBD>?
* **Logic:** <EFBFBD>湔鰵 finalResult嚗<EFBFBD><EFBFBD><EFBFBD>𡏭砲銵峕<EFBFBD><EFBFBD>匧<EFBFBD>蝒<EFBFBD><EFBFBD>畾菟<EFBFBD>撌脰圾<EFBFBD>喉<EFBFBD>撠?status <EFBFBD>湔鰵銝?RESOLVED<EFBFBD>?
## **6\. <20>滨垢霂衣<E99C82>霈曇恣 (Frontend)**
### **6.1 <20>冽艶撉諹<E69289>蝵烐聢 (Verification Grid)**
* **组件选型：** 依然推荐 **TanStack Table** (逻辑层) \+ **UI 组件库** (渲染层)。
* **蝏<EFBFBD>辣<EFBFBD>匧<EFBFBD>嚗?* 靘萘<E99D98><E89098>刻<EFBFBD> **TanStack Table** (<EFBFBD>餉<EFBFBD>撅? \+ **UI 蝏<EFBFBD>辣摨?* (皜脫<E79A9C>撅?<3F>?
* **<2A>脩<EFBFBD><E884A9>訫<EFBFBD><E8A8AB>潭葡<E6BDAD>橒<EFBFBD>**
* 当 conflictFields.includes(column.id) 时，单元格渲染为**对比模式**。
* 显示两个小按钮：\[DS: 3cm\] 和 \[QW: 3.0cm\]。
* 用户点击任一按钮，触发 resolve API，前端乐观更新（Optimistic Update）为选中状态。
### **6.2 侧边栏原文 (Context Drawer)**
* **触发：** 点击表格行的空白处或“查看原文”图标。
* **功能：** 展示 originalText。
* **高亮优化：** 简单实现 String.indexOf 查找当前字段的值并标黄。
* 敶?conflictFields.includes(column.id) <EFBFBD>塚<EFBFBD><EFBFBD>訫<EFBFBD><EFBFBD>潭葡<EFBFBD>㮖蛹**撖寞<E69296>璅∪<E79285>**<2A>?
* <EFBFBD>曄內銝支葵撠𤩺<EFBFBD><EFBFBD>殷<EFBFBD>\[DS: 3cm\] <EFBFBD>?\[QW: 3.0cm\]<EFBFBD>?
* <EFBFBD>冽<EFBFBD><EFBFBD>孵稬隞颱<EFBFBD><EFBFBD>厰僼嚗諹圻<EFBFBD>?resolve API嚗<49><E59A97>蝡臭<E89DA1>閫<EFBFBD>凒<EFBFBD>堆<EFBFBD>Optimistic Update嚗劐蛹<EFBFBD>劐葉<EFBFBD>嗆<EFBFBD><EFBFBD><EFBFBD>?
### **6.2 靘扯器<E689AF>誩<EFBFBD><E8AAA9>?(Context Drawer)**
* **閫血<E996AB>嚗?* <20>孵稬銵冽聢銵𣬚<E98AB5>蝛箇蒾憭<E892BE><E686AD><EFBFBD>𨀣䰻<F0A880A3>见<EFBFBD><E8A781><EFBFBD><EFBFBD>嘥㦛<E598A5><E3A69B><EFBFBD>?
* **<2A>蠘<EFBFBD>嚗?* 撅閧內 originalText<78>?
* **擃䀝漁隡睃<E99AA1>嚗?* 蝞<><E89D9E>訫<EFBFBD><E8A8AB>?String.indexOf <20>交𪄳敶枏<E695B6>摮埈挾<E59F88><E68CBE><EFBFBD>澆僎<E6BE86><E5838E><EFBFBD><EFBFBD>?
## **7\. 憌𡡞埯<F0A1A19E>批<EFBFBD>銝擧<E98A9D>扯<EFBFBD>隡睃<E99AA1>**
| 瞏𨅯銁憌𡡞埯 | 閫<><E996AB><EFBFBD>寞<EFBFBD> |
| :---- | :---- |
| **双倍 Token 成本** | 1\. 默认使用 DeepSeek (极低成本) \+ Qwen (低成本) 组合。 2\. 在“体检”阶段严格拦截无效数据。 |
| **处理速度慢** | 两个模型必须 **并发调用 (Promise.all)**，而不是串行。整体耗时取决于最慢的那个模型。 |
| **模型格式不听话** | Prompt 中增加 Few-Shot (少样本) 示例，明确展示 JSON 格式。如果 JSON 解析失败，自动重试 1 次。 |
| **前端网格卡顿** | 如果数据超过 1000 条，开启 Virtual Scrolling (虚拟滚动)。 |
| **<EFBFBD><EFBFBD><EFBFBD>?Token <EFBFBD>鞉𧋦** | 1\. 暺䁅恕雿輻鍂 DeepSeek (<EFBFBD><EFBFBD><EFBFBD><EFBFBD>鞉𧋦) \+ Qwen (雿擧<EFBFBD><EFBFBD>? 蝏<><E89D8F><EFBFBD>?2\. <20>兩<EFBFBD>靝<EFBFBD>璉<EFBFBD><E79289>嗪𧫴畾萎艇<E8908E>潭㜃<E6BDAD>芣<EFBFBD><E88AA3><EFBFBD>㺭<EFBFBD>柴<EFBFBD>?|
| **憭<EFBFBD><EFBFBD><EFBFBD>笔漲<EFBFBD>?* | 銝支葵璅∪<E79285>敹<EFBFBD>◆ **撟嗅<E6929F>靚<EFBFBD>鍂 (Promise.all)**嚗諹<E59A97>䔶<EFBFBD><E494B6>臭葡銵䎚<E98AB5><E48E9A>㟲雿栞<E99BBF>埈𧒄<E59F88>硋<EFBFBD>鈭擧<E988AD><E693A7>Ｙ<EFBFBD><EFBCB9><EFBFBD>葵璅∪<E79285><E288AA>?|
| **璅∪<EFBFBD><EFBFBD>澆<EFBFBD>銝滚𨯬霂?* | Prompt 銝剖<EFBFBD><EFBFBD>?Few-Shot (撠烐甅<EFBFBD>? 蝷箔<E89DB7>嚗峕<E59A97>蝖桀<E89D96>蝷?JSON <20>澆<EFBFBD><E6BE86><EFBFBD><EFBFBD><EFBFBD>?JSON 閫<><E996AB>憭梯揖嚗諹䌊<E8ABB9>券<EFBFBD>霂?1 甈～<E79488>?|
| **<EFBFBD>滨垢蝵烐聢<EFBFBD>⊿▼** | 憒<EFBFBD><EFBFBD><EFBFBD>唳旿頞<EFBFBD><EFBFBD> 1000 <20>∴<EFBFBD>撘<EFBFBD><E69298>?Virtual Scrolling (<EFBFBD>𡁏<EFBFBD>皛𡁜𢆡)<29>?|

144
docs/03-业务模块/DC-数据清洗整理/02-技术设计/技术设计文档：工具 C - 科研数据编辑器 (V7 云端沙箱抗风险版).md
View File

@@ -1,18 +1,17 @@
# **技术设计文档：工具 C \- 科研数据编辑器 (V7 云端沙箱抗风险版)**
# **謚€譛ｯ隶ｾ隶｡譁<EFBFBD>｡｣<EFBFBD>壼ｷ･蜈ｷ C \- 遘醍<E98198>疲焚謐ｮ郛冶ｾ大<EFBDBE>?(V7 莠醍ｫｯ豐咏ｮｱ謚鈴｣朱勦迚<E58BA6>)**
| 譁<>｡｣邀ｻ蝙<EFBDBB> | Technical Design Document (TDD) |
| :---- | :---- |
| **对应原型** | **工具C\_科研数据编辑器\_原型设计\_V6\_修复版.html** |
| **版本** | **V7.1** (完整收录架构决策 ADR 与红队风险对策) |
| **状态** | Final Standard |
| **核心目标** | 构建一个高可靠的云端 Python 数据清洗平台。在保障“数据不出域”的前提下，通过 Apache Arrow 和样式分离技术，解决服务端执行带来的延迟与格式丢失问题。 |
| **蟇ｹ蠎泌次蝙<EFBFBD>** | **蟾･蜈ｷC\_遘醍<E98198>疲焚謐ｮ郛冶ｾ大勣\_蜴溷梛隶ｾ隶｡\_V6\_菫ｮ螟咲<E89E9F>?html** |
| **迚域悽** | **V7.1** (螳梧紛謾ｶ蠖墓楔譫<EFBFBD><EFBFBD>遲<EFBFBD> ADR 荳守ｺ｢髦滄｣朱勦蟇ｹ遲? |
| **迥ｶ諤?* | Final Standard |
| **譬ｸ蠢<EFBFBD>岼譬<EFBFBD>** | 譫<EFBFBD>ｻｺ荳€荳ｪ鬮伜庄髱<EFBFBD>逧<EFBFBD>ｺ醍ｫ?Python 謨ｰ謐ｮ貂<EFBDAE>ｴ怜ｹｳ蜿ｰ縲ょ惠菫晞囿窶懈焚謐ｮ荳榊<E88DB3>蝓溪€晉噪蜑肴署荳具ｼ碁€夊ｿ<E5A48A> Apache Arrow 蜥梧<E89CA5>ｷ蠑丞<E8A091>遖ｻ謚€譛ｯ<E8AD9B>瑚ｧ｣蜀ｳ譛榊苅遶ｯ謇ｧ陦悟ｸｦ譚･逧<EFBDA5>ｻｶ霑滉ｸ取<EFBDB8>ｼ蠑丈ｸ｢螟ｱ髣ｮ鬚倥€?|
## **1\. 諤ｻ菴捺楔譫<E6A594>ｮｾ隶｡ (System Architecture)**
鉴于文件大小限制 (\<20MB) 和脱敏前提，采用 “Node.js BFF \+ Python Microservice” 架构。
V7 核心升级： 引入 Apache Arrow 作为前后端数据交换标准，替代低效的 Excel 文件反复读写，将单次交互延迟从 8s 降低至 0.5s。
### **1.1 架构拓扑图 (V7 优化版)**
驩ｴ莠取枚莉ｶ螟ｧ蟆城剞蛻ｶ (\<20MB) 蜥瑚┳謨丞燕謠撰ｼ碁㊦逕ｨ 窶廸ode.js BFF \+ Python Microservice窶?譫ｶ譫<EFBDB6>€?
V7 譬ｸ蠢<EFBFBD>合郤ｧ<EFBFBD>?蠑募<E8A091> Apache Arrow 菴應ｸｺ蜑榊錘遶ｯ謨ｰ謐ｮ莠､謐｢譬<EFBFBD>㊥<EFBFBD>梧崛莉｣菴取譜逧?Excel 譁<>ｻｶ蜿榊､崎ｯｻ蜀呻ｼ悟ｰ<E6829F>黒谺｡莠､莠貞ｻｶ霑滉ｻ?8s 髯堺ｽ手<EFBDBD>?0.5s縲?
### **1.1 譫ｶ譫<EFBDB6>挙謇大<E8AC87>?(V7 莨伜喧迚?**
graph TD
subgraph Client\_Layer \[逕ｨ謌ｷ遶ｯ\]
@@ -20,13 +19,13 @@ graph TD
ArrowClient\[Apache Arrow JS\]
end
subgraph Aliyun\_SAE \[阿里云 Serverless 应用引擎\]
subgraph Aliyun\_SAE \[髦ｿ驥御ｺ?Serverless 蠎皮畑蠑墓梼\]
BFF\[Node.js Web 譛榊苅 (Fastify)\]
PythonService\[Python 计算微服务 (FastAPI)\]
PythonService\[Python 隶｡邂怜ｾｮ譛榊<EFBFBD>?(FastAPI)\]
end
subgraph Cache\_Layer \[鬮倬€溽ｼ灘ｭ伜ｱ<E4BC9C>]
Redis\_Session\[Redis (存 DataFrame Arrow 序列化)\]
Redis\_Session\[Redis (蟄?DataFrame Arrow 蠎丞<EFBFBD>蛹?\]
end
subgraph AI\_PaaS \[AI 閭ｽ蜉帛ｱ<E5B89B>]
@@ -35,15 +34,15 @@ graph TD
end
subgraph Cloud\_Infra \[謖∽ｹ<E288BD>喧螻<E596A7>]
OSS\[对象存储 (存 Excel 底板)\]
OSS\[蟇ｹ雎｡蟄伜お (蟄?Excel 蠎墓攸)\]
RDS\[RDS PostgreSQL (蟄伜<E89F84>謨ｰ謐ｮ)\]
end
%% 交互流
%% 莠､莠呈ｵ?
User\[逕ｨ謌ｷ\] \--\>|1. 荳贋ｼ<E8B48B>| BFF
BFF \--\>|2. 蟄伜次蟋畿xcel| OSS
BFF \--\>|3. 鬚<>Ο Session| PythonService
PythonService \--\>|4. 加载并转为 Arrow| Redis\_Session
PythonService \--\>|4. 蜉<EFBFBD>霓ｽ蟷ｶ霓ｬ荳?Arrow| Redis\_Session
User \--\>|5. AI 謖<>ｻ､| Dify
Dify \--\>|6. Python 莉｣遐－ BFF
@@ -61,77 +60,69 @@ graph TD
## **2\. 蜈ｳ髞ｮ譫ｶ譫<EFBDB6><E8ADAB>遲冶ｮｰ蠖<EFBDB0> (ADR)**
本节记录了为何从“前端 Pyodide”转向“后端沙箱”的决策过程，供团队参考。
譛ｬ闃りｮｰ蠖穂ｺ<EFBFBD>ｸｺ菴穂ｻ寂€懷燕遶?Pyodide窶晁ｽｬ蜷鯛€懷錘遶ｯ豐咏ｮｱ窶晉噪蜀ｳ遲冶ｿ<E586B6>ｨ具ｼ御ｾ帛屬髦溷盾閠<E79BBE>€?
### **蜀ｳ遲也せ<E4B99F>壼燕遶ｯ霑占｡<E58DA0> (WASM) vs 蜷守ｫｯ霑占｡<E58DA0> (Server-side)**
| 维度 | 方案 A：前端 Pyodide (WASM) | 方案 B：后端 Python (本方案) | 决策结论 |
| 扈ｴ蠎ｦ | 譁ｹ譯<EFBDB9> A<>壼燕遶?Pyodide (WASM) | 譁ｹ譯<EFBDB9> B<>壼錘遶?Python (譛ｬ譁ｹ譯? | 蜀ｳ遲也ｻ楢ｮｺ |
| :---- | :---- | :---- | :---- |
| **启动延迟** | **极慢 (15s+)**。需下载 \~20MB 引擎包，用户体验极差。 | **秒开**。环境在服务器预热，即开即用。 | **后端胜** |
| **交互延迟** | **极快 (\< 0.1s)**。本地内存操作，无网络开销。 | **中等 (0.5s)**。通过 Apache Arrow 优化后可接受。 | 前端胜 |
| **稳定性** | **高风险**。浏览器 Tab 内存有限，易 OOM 崩溃。 | **高稳定**。服务器内存充足，容器隔离，崩溃不影响前端。 | **后端胜** |
| **库支持** | **有限**。不支持部分 C 扩展库 (如复杂统计库)。 | **无限**。标准 Linux 环境，生态完整。 | **后端胜** |
| **开发难度** | **极高**。需处理 JS-Python 通信、内存管理。 | **低**。标准 Web API 开发。 | **后端胜** |
| **蜷ｯ蜉ｨ蟒ｶ霑<EFBFBD>** | **譫∵<EFBFBD> (15s+)**縲る怙荳玖ｽｽ \~20MB 蠑墓梼蛹<E6A2BC>ｼ檎畑謌ｷ菴馴ｪ梧栫蟾ｮ縲?| **遘貞ｼ€**縲ら識蠅<E8AD98>惠譛榊苅蝎ｨ鬚<EFBDA8>Ο<EFBFBD>悟叉蠑€蜊ｳ逕ｨ縲?| **蜷守ｫｯ閭?* |
| **莠､莠貞ｻｶ霑<EFBFBD>** | **譫∝ｿｫ (\< 0.1s)**縲よ悽蝨ｰ蜀<EFBDB0>ｭ俶桃菴懶ｼ梧裏鄂醍ｻ懷ｼ€髞€縲?| **荳ｭ遲<EFBFBD> (0.5s)**縲る€夊ｿ<E5A48A> Apache Arrow 莨伜喧蜷主庄謗･蜿励€?| 蜑咲ｫｯ閭?|
| **遞ｳ螳壽€?* | **鬮倬｣朱<EFBFBD>?*縲よｵ剰ｧ亥勣 Tab 蜀<>ｭ俶怏髯撰ｼ梧<EFBDBC> OOM 蟠ｩ貅<EFBDA9>€?| **鬮倡ｨｳ螳?*縲よ恪蜉｡蝎ｨ蜀<EFBDA8>ｭ伜<EFBDAD>雜ｳ<E99B9C>悟ｮｹ蝎ｨ髫皮ｦｻ<EFBDA6>悟ｴｩ貅<EFBDA9>ｸ榊ｽｱ蜩榊燕遶ｯ縲?| **蜷守ｫｯ閭?* |
| **蠎捺髪謖?* | **譛蛾剞**縲ゆｸ肴髪謖<E9ABAA>Κ蛻<CE9A> C 謇ｩ螻募ｺ?(螯ょ､肴揩扈溯ｮ｡蠎<EFBDA1>)縲?| **譌<EFBFBD>髯<EFBFBD>**縲よ<E7B8B2><E38288><EFBFBD>?Linux 邇ｯ蠅<EFBDAF>ｼ檎函諤∝ｮ梧紛縲?| **蜷守ｫｯ閭?* |
| **蠑€蜿鷹埓蠎?* | **譫<EFBFBD>ｫ<EFBFBD>**縲る怙螟<E68099>炊 JS-Python 騾壻ｿ｡縲∝<E7B8B2>蟄倡ｮ｡逅<EFBDA1>€?| **菴?*縲よ<E7B8B2><E38288><EFBFBD>?Web API 蠑€蜿代€?| **蜷守ｫｯ閭?* |
**结论：** 鉴于“数据已脱敏”且“文件较小”，**后端执行方案** 在稳定性、兼容性和开发成本上全面胜出。
## **3\. 技术选型与融合 (Tech Stack Fusion)**
**扈楢ｮｺ<EFBFBD>?* 驩ｴ莠寂€懈焚謐ｮ蟾ｲ閼ｱ謨鞘€昜ｸ披€懈枚莉ｶ霎<EFBDB6>ｰ鞘€晢ｼ<E699A2>**蜷守ｫｯ謇ｧ陦梧婿譯<E5A9BF>** 蝨ｨ遞ｳ螳壽€ｧ縲∝<E7B8B2>螳ｹ諤ｧ蜥悟ｼ€蜿第<E89CBF>譛ｬ荳雁<E88DB3>髱｢閭懷<E996AD>縲?
## **3\. 謚€譛ｯ騾牙梛荳手檮蜷?(Tech Stack Fusion)**
### **3.1 譬ｸ蠢<EFBDB8>ｻ<EFBFBD>ｻｶ譖ｴ譁ｰ**
| 鬚<>沺 | 騾牙梛 | V7 譁ｰ蠅樒炊逕ｱ |
| :---- | :---- | :---- |
| **数据交换** | **Apache Arrow** | **关键升级**。用于 Python 和 Node.js/前端之间的高性能数据传输，避免 JSON 序列化开销，**解决 IO 延迟核心**。 |
| **Excel 处理** | **openpyxl** | 替代纯 Pandas。用于在导出时**保留原始 Excel 样式**（如颜色、边框），**解决格式丢失核心**。 |
| **会话缓存** | **Redis** | 用于暂存用户的 DataFrame (序列化为 Parquet/Arrow)，避免每次操作都去 OSS 读文件。 |
| **计算服务** | **FastAPI \+ Celery** | 引入 Celery 处理异步任务，防止长计算阻塞 HTTP 线程。 |
| **謨ｰ謐ｮ莠､謐｢** | **Apache Arrow** | **蜈ｳ髞ｮ蜊<EFBFBD>ｺｧ**縲ら畑莠?Python 蜥?Node.js/蜑咲ｫｯ荵矩龍逧<EFBFBD>ｫ俶€ｧ閭ｽ謨ｰ謐ｮ莨<EFBFBD>霎難ｼ碁∩蜈?JSON 蠎丞<E8A08E>蛹門ｼ€髞€<E9AB9E>?*隗｣蜀ｳ IO 蟒ｶ霑滓<E99C91>ｸ蠢<EFBDB8>**縲?|
| **Excel 螟<EFBFBD>炊** | **openpyxl** | 譖ｿ莉｣郤?Pandas縲ら畑莠主惠蟇ｼ蜃ｺ譌?*菫晉蕗蜴溷ｧ<E6BAB7> Excel 譬ｷ蠑<EFBDB7>**<2A>亥ｦる｢懆牡縲∬ｾｹ譯<EFBDB9>ｼ会ｼ?*隗｣蜀ｳ譬ｼ蠑丈ｸ｢螟ｱ譬ｸ蠢<EFBDB8>**縲?|
| **莨夊ｯ晉ｼ灘ｭ<EFBFBD>** | **Redis** | 逕ｨ莠取嘯蟄倡畑謌ｷ逧?DataFrame (蠎丞<EFBFBD>蛹紋ｸｺ Parquet/Arrow)<EFBFBD>碁∩蜈肴ｯ乗ｬ｡謫堺ｽ憺<EFBFBD>蜴?OSS 隸ｻ譁<EFBDBB>ｻｶ縲?|
| **隶｡邂玲恪蜉｡** | **FastAPI \+ Celery** | 蠑募<EFBFBD> Celery 螟<EFBFBD>炊蠑よｭ･莉ｻ蜉｡<EFBFBD>碁亟豁｢髟ｿ隶｡邂鈴仆蝪<EFBFBD> HTTP 郤ｿ遞九€?|
## **4\. 逆向风险评估与对策 (Red Teaming Analysis)**
## **4\. 騾<EFBFBD>髄鬟朱勦隸<EFBFBD>ｼｰ荳主ｯｹ遲?(Red Teaming Analysis)**
本节详细记录了“红队测试”中发现的潜在致命风险及其工程化解决方案。
### **风险一：交互延迟的“体感崩塌”**
* **逆向拷问：** 每次 AI 操作都走 OSS 下载 \-\> Pandas 读取 \-\> 计算 \-\> 上传，单次耗时可能超过 8秒，用户无法忍受。
* **V7 解决方案：** **Session 驻留模式 (Memory-Resident)**
1. **初始化：** 用户上传 Excel 后，后端将其加载为 DataFrame，并序列化为 **Arrow** 格式存入 Redis (TTL 30min)。
2. **增量交互：** 前端发送指令，Python 从 Redis 读取 Arrow 数据（毫秒级），执行 Pandas 计算，将结果写回 Redis。
3. **轻量反馈：** 计算完成后，只返回 **前 100 行预览数据** 给前端 AG Grid 渲染。
4. **效果：** 耗时缩短至 **0.5s \- 1s**。
譛ｬ闃りｯｦ扈<EFBFBD>ｮｰ蠖穂ｺ<EFBFBD>€懃ｺ｢髦滓ｵ玖ｯ補€昜ｸｭ蜿醍鴫逧<EFBFBD>ｽ懷惠閾ｴ蜻ｽ鬟朱勦蜿雁<EFBFBD>蟾･遞句喧隗｣蜀ｳ譁ｹ譯医€?
### **鬟朱勦荳€<E88DB3>壻ｺ､莠貞ｻｶ霑溽噪窶應ｽ捺─蟠ｩ蝪娯€?*
* **騾<>髄諡ｷ髣ｮ<E9ABA3>?* 豈乗ｬ｡ AI 謫堺ｽ憺<EFBDBD>襍ｰ OSS 荳玖ｽｽ \-\> Pandas 隸ｻ蜿<EFBDBB> \-\> 隶｡邂<EFBDA1> \-\> 荳贋ｼ<E8B48B><EFBDBC>悟黒谺｡閠玲慮蜿ｯ閭ｽ雜<EFBDBD>ｿ<EFBFBD> 8遘抵ｼ檎畑謌ｷ譌<EFBDB7>豕募ｿ榊女縲?
* **V7 隗｣蜀ｳ譁ｹ譯茨ｼ?* **Session 鬩ｻ逡呎ｨ｡蠑<EFBDA1> (Memory-Resident)**
1. **蛻晏ｧ句喧<E58FA5><E596A7>** 逕ｨ謌ｷ荳贋ｼ<E8B48B> Excel 蜷趣ｼ悟錘遶ｯ蟆<EFBDAF><E89F86>蜉<EFBFBD>霓ｽ荳?DataFrame<6D>悟ｹｶ蠎丞<E8A08E>蛹紋ｸｺ **Arrow** 譬ｼ蠑丞ｭ伜<EFBDAD> Redis (TTL 30min)縲?
2. **蠅樣㍼莠､莠抵ｼ?* 蜑咲ｫｯ蜿鷹€∵欠莉､<E88E89>訓ython 莉?Redis 隸ｻ蜿<EFBDBB> Arrow 謨ｰ謐ｮ<E8AC90>域ｯｫ遘堤ｺｧ<EFBDBA>会ｼ梧鴬陦<E9B4AC> Pandas 隶｡邂暦ｼ悟ｰ<E6829F>ｻ捺棡蜀吝屓 Redis縲?
3. **霓ｻ驥丞渚鬥茨ｼ?* 隶｡邂怜ｮ梧<EFBDAE>蜷趣ｼ悟宵霑泌<E99C91>?**蜑?100 陦碁｢<E7A281>ｧ域焚謐?* 扈吝燕遶?AG Grid 貂ｲ譟薙€?
4. **謨域棡<E59F9F>?* 閠玲慮郛ｩ遏ｭ閾?**0.5s \- 1s**縲?
### **鬟朱勦莠鯉ｼ哘xcel 譬ｼ蠑丈ｸ｢螟ｱ (The Format Loss)**
* **逆向拷问：** Pandas 的 to\_excel 会重置所有单元格样式，医生标注的颜色和批注会丢失。
* **V7 解决方案：** **底板分离策略 (Template Separation)**
1. **上传时：** 将原始 Excel 标记为 **"Style Template" (样式底板)**，永久保存在 OSS。
2. **计算时：** 只在内存/Redis 中处理纯数据 (Values)，不关心样式。
3. **导出时：** 使用 openpyxl 加载“样式底板”，将内存中的新数据**填入**到底板的对应坐标中，保留未修改区域的背景色和批注。
* **騾<EFBFBD>髄諡ｷ髣ｮ<EFBFBD>?* Pandas 逧?to\_excel 莨夐㍾鄂ｮ謇€譛牙黒蜈<EFBFBD><EFBFBD>ｼ譬ｷ蠑擾ｼ悟現逕滓<EFBFBD><EFBFBD>ｳｨ逧<EFBFBD>｢懆牡蜥梧音豕ｨ莨壻ｸ｢螟ｱ縲?
* **V7 隗｣蜀ｳ譁ｹ譯茨ｼ?* **蠎墓攸蛻<E694B8>ｦｻ遲也払 (Template Separation)**
1. **荳贋ｼ<EFBFBD>譌ｶ<EFBFBD><EFBFBD>** 蟆<EFBFBD>次蟋?Excel 譬<EFBFBD>ｮｰ荳?**"Style Template" (譬ｷ蠑丞ｺ墓攸)**<2A>梧ｰｸ荵<EFBDB8>ｿ晏ｭ伜惠 OSS縲?
2. **隶｡邂玲慮<EFBFBD><EFBFBD>** 蜿ｪ蝨ｨ蜀<EFBDA8>ｭ<EFBFBD>/Redis 荳ｭ螟<EFBDAD>炊郤ｯ謨ｰ謐ｮ (Values)<29>御ｸ榊<EFBDB8>蠢<EFBFBD><E8A0A2>ｷ蠑上€?
3. **蟇ｼ蜃ｺ譌ｶ<EFBFBD><EFBFBD>** 菴ｿ逕ｨ openpyxl 蜉<EFBFBD>霓ｽ窶懈<EFBFBD>ｷ蠑丞ｺ墓攸窶晢ｼ悟ｰ<EFBFBD><EFBFBD>蟄倅ｸｭ逧<EFBFBD>眠謨ｰ謐ｮ**蝪ｫ蜈･**蛻ｰ蠎墓攸逧<E694B8>ｯｹ蠎泌攝譬<E6949D>ｸｭ<EFBDB8>御ｿ晉蕗譛ｪ菫ｮ謾ｹ蛹ｺ蝓溽噪閭梧勹濶ｲ蜥梧音豕ｨ縲?
### **鬟朱勦荳会ｼ夂憾諤∝酔豁･逧<EFBDA5>€懷曙蜀吝<E89C80>遯≫€?*
### **风险三：状态同步的“双写冲突”**
* **騾<>髄諡ｷ髣ｮ<E9ABA3>?* 逕ｨ謌ｷ謇句勘菫ｮ謾ｹ莠<EFBDB9>ｬｬ 5 陦鯉ｼ悟酔譌ｶ AI 蛻<>髯､莠<EFBDA4>ｬｬ 5 陦鯉ｼ悟ｯｼ閾ｴ謨ｰ謐ｮ迥ｶ諤∽ｸ堺ｸ€閾ｴ縲?
* **V7 隗｣蜀ｳ譁ｹ譯茨ｼ?* **UI 莠呈箕髞?(UI Locking)**
* 蠖?AI 豁｣蝨ｨ逕滓<E98095>莉｣遐∵<E98190>蜷守ｫｯ豁｣蝨ｨ隶｡邂玲慮<E78EB2>窟G Grid 蠑ｺ蛻ｶ霑帛<E99C91> **readOnly** 讓｡蠑擾ｼ悟ｹｶ蝨ｨ逡碁擇譏ｾ遉?"AI 豁｣蝨ｨ螟<EFBDA8>炊..." 驕ｮ鄂ｩ<E98482>?*迚ｩ逅<EFBDA9>ｱる擇荳顔ｦ∵ｭ｢蟷ｶ蜿第桃菴?*縲?
### **鬟朱勦蝗幢ｼ壼ｮ牙<EFBDAE>豐咏ｮｱ騾<EFBDB1>€?*
* **逆向拷问：** 用户手动修改了第 5 行，同时 AI 删除了第 5 行，导致数据状态不一致。
* **V7 解决方案：** **UI 互斥锁 (UI Locking)**
* 当 AI 正在生成代码或后端正在计算时，AG Grid 强制进入 **readOnly** 模式，并在界面显示 "AI 正在处理..." 遮罩，**物理层面上禁止并发操作**。
### **风险四：安全沙箱逃逸**
* **逆向拷问：** AI 生成了 import os; os.system('rm \-rf /')。
* **V7 解决方案：** **AST 静态分析 \+ 容器隔离**
* **预检：** 在执行 exec() 前，使用 Python ast 模块扫描代码树，检测到 import os 等关键词直接抛出异常。
* **资源限额：** 使用 Python resource 模块限制单次执行的 CPU 时间 (10s) 和 内存 (1GB)。
## **5\. 数据库设计 (元数据层)**
新增 TaskAudit 表用于记录每一次 AI 操作的上下文，便于回滚和审计。
* **騾<EFBFBD>髄諡ｷ髣ｮ<EFBFBD>?* AI 逕滓<E98095>莠?import os; os.system('rm \-rf /')縲?
* **V7 隗｣蜀ｳ譁ｹ譯茨ｼ?* **AST 髱呎€∝<C280>譫?\+ 螳ｹ蝎ｨ髫皮ｦｻ**
* **鬚<>｣€<EFBDA3>?* 蝨ｨ謇ｧ陦?exec() 蜑搾ｼ御ｽｿ逕ｨ Python ast 讓｡蝮玲沖謠丈ｻ｣遐∵<E98190>托ｼ梧｣€豬句芦 import os 遲牙<E981B2>髞ｮ隸咲峩謗･謚帛<E8AC9A>蠑ょｸｸ縲?
* **襍<>ｺ宣剞鬚晢ｼ?* 菴ｿ逕ｨ Python resource 讓｡蝮鈴剞蛻ｶ蜊墓ｬ｡謇ｧ陦檎<E999A6>?CPU 譌ｶ髣ｴ (10s) 蜥?蜀<>ｭ<EFBFBD> (1GB)縲?
## **5\. 謨ｰ謐ｮ蠎楢ｮｾ隶?(蜈<>焚謐ｮ螻<EFBDAE>)**
譁ｰ蠅<EFBFBD> TaskAudit 陦ｨ逕ｨ莠手ｮｰ蠖墓ｯ丈ｸ€谺?AI 謫堺ｽ懃噪荳贋ｸ区枚<E58CBA>御ｾｿ莠主屓貊壼柱螳｡隶｡縲?
model TaskAudit {
id String @id @default(uuid())
datasetId String
version Int // 操作后的版本号
version Int // 謫堺ｽ懷錘逧<EFBFBD>沿譛ｬ蜿?
actionType String // "AI\_CODE" or "MANUAL\_EDIT"
prompt String? // 逕ｨ謌ｷ逧<EFBDB7><E980A7>辟ｶ隸ｭ險€謖<C280>ｻ､
code String? // AI 生成的 Python 代码
code String? // AI 逕滓<EFBFBD>逧?Python 莉｣遐<EFBFBD>
executionTime Int // 謇ｧ陦瑚€玲慮 (ms)
status String // SUCCESS / FAILED
@@ -141,24 +132,23 @@ model TaskAudit {
## **6\. API 謗･蜿｣螳壻ｹ<E5A3BB> (V7 莨伜喧)**
* POST /api/session/init: 上传文件，初始化 Redis Session，返回 sessionId。
* POST /api/session/init: 荳贋ｼ<EFBFBD>譁<EFBFBD>ｻｶ<EFBFBD>悟<EFBFBD>蟋句喧 Redis Session<EFBFBD>瑚ｿ泌<EFBFBD>?sessionId縲?
* POST /api/session/execute:
* **Input:** { sessionId, code, version }
* **Output:** { previewData: ArrowBase64, newVersion: int, logs: string }
* **说明:** 仅返回预览数据，不生成 Excel 文件。
* **隸ｴ譏<EFBFBD>:** 莉<>ｿ泌屓鬚<E5B193>ｧ域焚謐ｮ<E8AC90>御ｸ咲函謌?Excel 譁<>ｻｶ縲?
* POST /api/session/save:
* **Input:** { sessionId }
* **Output:** { downloadUrl }
* **说明:** 触发 openpyxl 合并逻辑，生成最终 Excel 并上传 OSS。
* **隸ｴ譏<EFBFBD>:** 隗ｦ蜿<EFBDA6> openpyxl 蜷亥ｹｶ騾ｻ霎托ｼ檎函謌先怙扈?Excel 蟷ｶ荳贋ｼ?OSS縲?
## **7\. 蠑€蜿大<E89CBF>蟾･蟒ｺ隶?*
## **7\. 开发分工建议**
* **Python 组 (重中之重):**
* 实现 Arrow \<-\> Pandas 的序列化逻辑。
* 封装 openpyxl 的样式回填逻辑。
* 搭建 FastAPI \+ Redis 环境。
* **Node.js 组:**
* 负责 Dify 转发和鉴权。
* **前端组:**
* 集成 apache-arrow JS 库，解析后端返回的二进制流并在 AG Grid 展示。
* 实现“AI 处理中”的全屏锁定交互。
* **Python 扈?(驥堺ｸｭ荵矩㍾):**
* 螳樒鴫 Arrow \<-\> Pandas 逧<>ｺ丞<EFBDBA>蛹夜€ｻ霎代€?
* 蟆∬｣<EFBFBD> openpyxl 逧<><E980A7>ｷ蠑丞屓蝪ｫ騾ｻ霎代€?
* 謳ｭ蟒ｺ FastAPI \+ Redis 邇ｯ蠅<EFBDAF>€?
* **Node.js 扈?**
* 雍溯ｴ｣ Dify 霓ｬ蜿大柱驩ｴ譚<EFBDB4>€?
* **蜑咲ｫｯ扈?**
* 髮<EFBFBD><EFBFBD> apache-arrow JS 蠎難ｼ瑚ｧ｣譫仙錘遶ｯ霑泌屓逧<E5B193>ｺ瑚ｿ帛宛豬∝ｹｶ蝨?AG Grid 螻慕､ｺ縲?
* 螳樒鴫窶廣I 螟<>炊荳ｭ窶晉噪蜈ｨ螻城煤螳壻ｺ､莠偵€

156
docs/03-业务模块/DC-数据清洗整理/02-技术设计/技术设计文档：工具 C - 科研数据编辑器.md
View File

@@ -1,37 +1,34 @@
# **技术设计文档：工具 C \- 科研数据编辑器 (The Research Editor)**
# **<EFBFBD><EFBFBD><EFBFBD>航挽霈⊥<EFBFBD>獢<EFBFBD><EFBFBD>撌亙<EFBFBD> C \- 蝘𤑳<E89D98><F0A491B3>唳旿蝻𤥁<E89DBB><F0A4A581>?(The Research Editor)**
| <20><>﹝蝐餃<E89D90> | Technical Design Document (TDD) |
| :---- | :---- |
| **撖孵<E69296> PRD** | **PRD\_撌亙<E6928C>C\_蝘𤑳<E89D98><F0A491B3>唳旿蝻𤥁<E89DBB><F0A4A581>沔_V2.1.md** |
| **版本** | **V2.1** (新增 Pivot 算法与 Web Worker 架构) |
| **状态** | Final Draft |
| **核心目标** | 构建一个高性能的 Web 端数据编辑器，支持 5 万行级数据的实时清洗、变量加工（含长宽转换）与逻辑治理，提供“零延迟”操作体验。 |
| **<EFBFBD><EFBFBD>𧋦** | **V2.1** (<EFBFBD>啣<EFBFBD> Pivot 蝞埈<EFBFBD>銝?Web Worker <EFBFBD>嗆<EFBFBD>) |
| **<EFBFBD>嗆<EFBFBD>?* | Final Draft |
| **<EFBFBD>詨<EFBFBD><EFBFBD>格<EFBFBD>** | <EFBFBD><EFBFBD>遣銝<EFBFBD>銝芷<EFBFBD><EFBFBD>扯<EFBFBD><EFBFBD>?Web 蝡舀㺭<E88880>桃<EFBFBD>颲穃膥嚗峕𣈲<E5B395>?5 銝<><E98A9D>蝥扳㺭<E689B3>桃<EFBFBD>摰墧𧒄皜<F0A79284><E79A9C><EFBFBD><EFBFBD><EFBFBD><EFBFBD>誩<EFBFBD>撌伐<E6928C><E4BC90>恍鵭摰質蓮<E8B3AA>ｇ<EFBFBD>銝𡡞<E98A9D>餉<EFBFBD>瘝餌<E7989D>嚗峕<E59A97>靘𥕞<E99D98>𣈯妟撱嗉<E692B1><E59789>脲<EFBFBD>雿靝<E99BBF>撉䎚<E69289>?|
## **1\. <20>颱<EFBFBD><E9A2B1>嗆<EFBFBD>霈曇恣 (Architecture Overview)**
为了满足 **PRD V2.1** 中“即时反馈”、“撤销重做”以及复杂的“长宽转换”需求，工具 C 采用 **"Local-First" (本地优先)** 架构。
核心策略：
1. **数据驻留：** 数据加载后主要存储在浏览器的 **IndexedDB (Dexie.js)** 和 **内存 (Zustand)** 中。
2. **计算下放：** 复杂的计算逻辑（如 Pivot、公式解析）下放至 **Web Worker**，避免阻塞 UI 主线程。
### **1.1 系统架构图**
銝箔<EFBFBD>皛∟雲 **PRD V2.1** 銝凌<EFBFBD>𨅯朖<EFBFBD>嗅<EFBFBD>擐<EFBFBD><EFBFBD>腈<EFBFBD><EFBFBD><EFBFBD>𨀣伃<EFBFBD><EFBFBD><EFBFBD>滚<EFBFBD><EFBFBD>苷誑<EFBFBD>𠰴<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>𣈯鵭摰質蓮<EFBFBD>Ｔ<EFBFBD>嗪<EFBFBD>瘙<EFBFBD><EFBFBD>撌亙<EFBFBD> C <20><>鍂 **"Local-First" (<EFBFBD>砍𧑐隡睃<EFBFBD>)** <20>嗆<EFBFBD><E59786>?
<EFBFBD>詨<EFBFBD>蝑𣇉裦嚗?
1. **<EFBFBD>唳旿撽餌<EFBFBD>嚗?* <20>唳旿<E594B3>㰘蝸<E3B098>𦒘蜓閬<E89C93><E996AC><EFBFBD>典銁瘚讛<E7989A><E8AE9B>函<EFBFBD> **IndexedDB (Dexie.js)** <20>?**<2A><><EFBFBD> (Zustand)** 銝准<E98A9D>?
2. **霈∠<E99C88>銝𧢲𦆮嚗?* 憭齿<E686AD><E9BDBF><EFBFBD>恣蝞烾<E89D9E>餉<EFBFBD>嚗<EFBFBD><E59A97> Pivot<6F><74><EFBFBD>撘讛圾<E8AE9B>琜<EFBFBD>銝𧢲𦆮<F0A7A2B2>?**Web Worker**嚗屸<E59A97><E5B1B8>漤獈憛?UI 銝餌瑪蝔卝<E89D94>?
### **1.1 蝟餌<E89D9F><E9A48C>嗆<EFBFBD><E59786>?*
graph TD
subgraph Browser\_Layer \[瘚讛<E7989A><E8AE9B>函垢 (React SPA)\]
UI\_Shell\[UI 壳层: 扁平化 Toolbar \+ 智能 Sidebar\]
UI\_Shell\[UI 憯喳<EFBFBD>: <20><>像<EFBFBD>?Toolbar \+ <EFBFBD>箄<EFBFBD> Sidebar\]
subgraph Core\_Engine \[<5B>詨<EFBFBD>撘閙<E69298>\]
GridComponent\[AG Grid (视图层)\]
GridComponent\[AG Grid (閫<EFBFBD>㦛撅?\]
StateManager\[Zustand Store (<28>嗆<EFBFBD><E59786><EFBFBD>)\]
subgraph Worker\_Thread \[Web Worker 蝥輻<E89DA5>\]
ComputeEngine\[霈∠<E99C88>撘閙<E69298> (Math.js / Pivot Alg)\]
StatEngine\[统计引擎 (直方图/频次)\]
StatEngine\[蝏蠘恣撘閙<EFBFBD> (<28>湔䲮<E6B994>?憸烐活)\]
end
HistoryManager\[Immer Patches (撤销栈)\]
HistoryManager\[Immer Patches (<EFBFBD>日<EFBFBD><EFBFBD>?\]
end
subgraph Local\_Storage \[<5B><><EFBFBD><EFBFBD>硋<EFBFBD>\]
@@ -39,13 +36,13 @@ graph TD
end
end
subgraph Server\_Layer \[服务端 (Node.js)\]
subgraph Server\_Layer \[<EFBFBD>滚𦛚蝡?(Node.js)\]
API\[Fastify API\]
S3\[撖寡情摮睃<E691AE> (MinIO/OSS)\]
end
User \--1.<2E>滢<EFBFBD>(憒<>ivot)--\> UI\_Shell
UI\_Shell \--2.发送消息(postMessage)--\> Worker\_Thread
UI\_Shell \--2.<EFBFBD>煾<EFBFBD><EFBFBD><EFBFBD><EFBFBD>?postMessage)--\> Worker\_Thread
Worker\_Thread \--3.霈∠<E99C88>蝏𤘪<E89D8F>--\> StateManager
StateManager \--4.<2E>湔鰵閫<E9B0B5>㦛--\> GridComponent
StateManager \--5.撘<>郊憭<E9838A>遢--\> Dexie
@@ -54,14 +51,14 @@ graph TD
## **2\. <20><><EFBFBD>舫<EFBFBD>匧<EFBFBD> (Tech Stack)**
| 层级 | 技术组件 | 选型理由 |
| 撅<EFBFBD>漣 | <20><><EFBFBD>舐<EFBFBD>隞?| <20>匧<EFBFBD><E58CA7><EFBFBD>眏 |
| :---- | :---- | :---- |
| **表格核心** | **AG Grid Community** | 唯一能免费支持虚拟滚动、列拖拽、高性能渲染的 React 表格库。 |
| **本地数据库** | **Dexie.js (IndexedDB)** | 相比 localStorage (5MB限制)，IndexedDB 容量大且异步，适合存储 5万+ 行的 JSON 数据集。 |
| **状态管理** | **Zustand \+ Immer** | Zustand 轻量高效；Immer 用于处理不可变数据结构，其 produce 和 patches 功能是实现 Undo/Redo 的核心。 |
| **计算引擎** | **Math.js \+ Web Worker** | 解决 JS 浮点数精度问题 (0.1+0.2\!=0.3)；Web Worker 用于将 Pivot 等重计算移出主线程。 |
| **数据处理** | **Lodash** | 基础的数据操作（分组、过滤、深拷贝）。 |
| **可视化** | **Ant Design Charts** | 在智能侧边栏中绘制直方图 (Histogram) 和频次图 (Bar)。 |
| **銵冽聢<EFBFBD>詨<EFBFBD>** | **AG Grid Community** | <EFBFBD>臭<EFBFBD><EFBFBD>賢<EFBFBD>韐寞𣈲<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>具<EFBFBD><EFBFBD><EFBFBD><EFBFBD>𡝗嗻<EFBFBD><EFBFBD><EFBFBD><EFBFBD>扯<EFBFBD>皜脫<EFBFBD><EFBFBD>?React 銵冽聢摨瓐<E691A8>?|
| **<EFBFBD>砍𧑐<EFBFBD>唳旿摨?* | **Dexie.js (IndexedDB)** | <EFBFBD>豢<EFBFBD> localStorage (5MB<EFBFBD>𣂼<EFBFBD>)嚗䬠ndexedDB 摰寥<EFBFBD>憭找<EFBFBD>撘<EFBFBD>郊嚗屸<EFBFBD><EFBFBD><EFBFBD>摮睃<EFBFBD> 5銝? 銵𣬚<E98AB5> JSON <20>唳旿<E594B3><E697BF><EFBFBD>?|
| **<EFBFBD>嗆<EFBFBD><EFBFBD>恣<EFBFBD>?* | **Zustand \+ Immer** | Zustand 頧駁<EFBFBD>擃䀹<EFBFBD>嚗熘mmer <20>其<EFBFBD>憭<EFBFBD><E686AD>銝滚虾<E6BB9A>䀹㺭<E480B9>桃<EFBFBD><E6A183><EFBFBD><EFBFBD><EFBFBD>?produce <EFBFBD>?patches <EFBFBD>蠘<EFBFBD><EFBFBD>臬<EFBFBD><EFBFBD>?Undo/Redo <EFBFBD><EFBFBD>瓲敹<EFBFBD><EFBFBD>?|
| **霈∠<EFBFBD>撘閙<EFBFBD>** | **Math.js \+ Web Worker** | 閫<EFBFBD><EFBFBD> JS 瘚桃<EFBFBD><EFBFBD>啁移摨阡䔮憸?(0.1+0.2\!=0.3)嚗𢫕eb Worker <EFBFBD>其<EFBFBD>撠?Pivot 蝑厰<EFBFBD>霈∠<EFBFBD>蝘餃枂銝餌瑪蝔卝<EFBFBD>?|
| **<EFBFBD>唳旿憭<EFBFBD><EFBFBD>** | **Lodash** | <EFBFBD>箇<EFBFBD><EFBFBD><EFBFBD>㺭<EFBFBD>格<EFBFBD>雿頣<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>皛扎<EFBFBD><EFBFBD>楛<EFBFBD>瑁<EFBFBD>嚗剹<EFBFBD>?|
| **<EFBFBD>航<EFBFBD><EFBFBD>?* | **Ant Design Charts** | <EFBFBD>冽惣<EFBFBD>賭儒颲寞<EFBFBD>銝剔<EFBFBD><EFBFBD>嗥凒<EFBFBD>孵㦛 (Histogram) <EFBFBD>屸<EFBFBD>甈∪㦛 (Bar)<EFBFBD>?|
## **3\. <20>詨<EFBFBD>璅∪<E79285>霂衣<E99C82>霈曇恣**
@@ -69,74 +66,68 @@ graph TD
#### **A. <20>踹捐頧祆揢 (Pivot / Reshaping Algorithm) \- V2.1 <20>詨<EFBFBD><E8A9A8>曄<EFBFBD>**
这是最复杂的计算任务，必须在 Web Worker 中执行，否则页面会卡死。
* **输入参数：**
餈蹱糓<EFBFBD><EFBFBD>憭齿<EFBFBD><EFBFBD><EFBFBD>恣蝞𦯀遙<EFBFBD>∴<EFBFBD>敹<EFBFBD>◆<EFBFBD>?Web Worker 銝剜<E98A9D>銵䕘<E98AB5><E49598>血<EFBFBD>憿菟𢒰隡𡁜㨃甇颯<E79487>?
* **颲枏<E9A2B2><E69E8F><EFBFBD>㺭嚗?*
* data: <20>笔<EFBFBD>撖寡情<E5AFA1>啁<EFBFBD> Row\[\]
* indexCol: 主键列名 (e.g., 'patient\_id') \- 确定“行”
* pivotKeyCol: 区分列名 (e.g., 'visit\_date') \- 确定“列后缀”
* valueCols: 值列名数组 (e.g., \['wbc', 'bmi'\]) \- 确定“填充值”
* **算法逻辑：**
1. **预检查 (Guard):** 计算 Unique(pivotKeyCol).length \* valueCols.length。如果生成的潜在列数 \> 1000，抛出错误“生成的列数过多，请先筛选数据”。
2. **分组 (Grouping):** 使用 \_.groupBy(data, indexCol) 按主键分组。
3. **转换 (Transformation):** 遍历每组数据：
* 创建一个新行对象，保留主键。
* 遍历该组的每一条记录，获取 pivotKeyCol 的值（例如 "2023-01-01"）。
* 遍历 valueCols，将值映射为 ValueCol\_PivotKey (例如 "wbc\_2023-01-01")。
4. **Schema生成:** 动态生成新的 ColumnDefs。
* **输出：** { newRows, newColumnDefs }
* indexCol: 銝駁睸<EFBFBD>堒<EFBFBD> (e.g., 'patient\_id') \- 蝖桀<EFBFBD><EFBFBD>𡏭<EFBFBD><EFBFBD>?
* pivotKeyCol: <EFBFBD>箏<EFBFBD><EFBFBD>堒<EFBFBD> (e.g., 'visit\_date') \- 蝖桀<EFBFBD><EFBFBD>𨅯<EFBFBD><EFBFBD>𡒊<EFBFBD><EFBFBD>?
* valueCols: <EFBFBD>澆<EFBFBD><EFBFBD>齿㺭蝏?(e.g., \['wbc', 'bmi'\]) \- 蝖桀<EFBFBD><EFBFBD>𨅯‵<EFBFBD><EFBFBD><EFBFBD>潑<EFBFBD>?
* **蝞埈<EFBFBD><EFBFBD>餉<EFBFBD>嚗?*
1. **憸<EFBFBD><EFBFBD><EFBFBD>?(Guard):** 霈∠<EFBFBD> Unique(pivotKeyCol).length \* valueCols.length<EFBFBD><EFBFBD><EFBFBD><EFBFBD>𦦵<EFBFBD><EFBFBD>鞟<EFBFBD>瞏𨅯銁<EFBFBD>埈㺭 \> 1000嚗峕<E59A97><E5B395>粹<EFBFBD>霂胼<E99C82>𦦵<EFBFBD><F0A6A6B5>鞟<EFBFBD><E99E9F>埈㺭餈<E3BAAD><E9A488>嚗諹窈<E8ABB9><E7AA88><EFBFBD><EFBFBD>㗇㺭<E39787>栽<EFBFBD>腈<EFBFBD>?
2. **<EFBFBD><EFBFBD><EFBFBD> (Grouping):** 雿輻鍂 \_.groupBy(data, indexCol) <EFBFBD>劐蜓<EFBFBD>桀<EFBFBD>蝏<EFBFBD><EFBFBD>?
3. **頧祆揢 (Transformation):** <EFBFBD>滚<EFBFBD>瘥讐<EFBFBD><EFBFBD>唳旿嚗?
* <EFBFBD>𥕦遣銝<EFBFBD>銝芣鰵銵<EFBFBD>笆鞊∴<EFBFBD>靽萘<EFBFBD>銝駁睸<EFBFBD>?
* <EFBFBD>滚<EFBFBD>霂亦<EFBFBD><EFBFBD><EFBFBD><EFBFBD>銝<EFBFBD><EFBFBD>∟扇敶𤏪<EFBFBD><EFBFBD>瑕<EFBFBD> pivotKeyCol <EFBFBD><EFBFBD><EFBFBD>潘<EFBFBD>靘见<EFBFBD> "2023-01-01"嚗剹<EFBFBD>?
* <EFBFBD>滚<EFBFBD> valueCols嚗<EFBFBD><EFBFBD><EFBFBD>潭<EFBFBD>撠<EFBFBD>蛹 ValueCol\_PivotKey (靘见<EFBFBD> "wbc\_2023-01-01")<EFBFBD>?
4. **Schema<EFBFBD><EFBFBD><EFBFBD>:** <EFBFBD>冽<EFBFBD><EFBFBD><EFBFBD><EFBFBD>鞉鰵<EFBFBD>?ColumnDefs<EFBFBD>?
* **颲枏枂嚗?* { newRows, newColumnDefs }
#### **B. <20>砍<EFBFBD><E7A08D>㗛<EFBFBD> (Formula)**
* 使用 math.evaluate(formula, row)。
* **安全沙箱：** 限制公式中可访问的变量仅为当前行的数据，防止 XSS。
* **异常处理：** 处理除以零 (Infinity) 和非数字计算 (NaN) 的情况，统一返回 null 或错误标记。
* 雿輻鍂 math.evaluate(formula, row)<EFBFBD>?
* **摰匧<EFBFBD>瘝嗵拳嚗?* <20>𣂼<EFBFBD><F0A382BC>砍<EFBFBD>銝剖虾霈輸䔮<E8BCB8><E494AE><EFBFBD><EFBFBD>譍<EFBFBD>銝箏<E98A9D><E7AE8F>滩<EFBFBD><E6BBA9><EFBFBD>㺭<EFBFBD>殷<EFBFBD><E6AEB7>脫迫 XSS<EFBFBD>?
* **撘<EFBFBD>虜憭<EFBFBD><EFBFBD>嚗?* 憭<><E686AD><EFBFBD>支誑<E694AF>?(Infinity) <20>屸<EFBFBD><E5B1B8>啣<EFBFBD>霈∠<E99C88> (NaN) <20><><EFBFBD><EFBFBD>蛛<EFBFBD>蝏煺<E89D8F>餈𥪜<E9A488> null <20>㚚<EFBFBD>霂舀<E99C82>霈啜<E99C88>?
### **3.2 <20>箄<EFBFBD>靘扯器<E689AF>誩<EFBFBD><E8AAA9>?(Insight Engine)**
### **3.2 智能侧边栏引擎 (Insight Engine)**
* **触发:** 监听 AG Grid 的 onColumnHeaderClicked 事件。
* **去抖 (Debounce):** 200ms 延迟计算，防止快速切换列时 UI 闪烁。
* **閫血<E996AB>:** <20>穃𨯬 AG Grid <20>?onColumnHeaderClicked 鈭衤辣<E8A1A4>?
* **<2A>餅<EFBFBD> (Debounce):** 200ms 撱嗉<E692B1>霈∠<E99C88>嚗屸俈甇Ｗ翰<EFBCB7>笔<EFBFBD><E7AC94>Ｗ<EFBFBD><EFBCB7>?UI <20>芰<EFBFBD><E88AB0>?
* **蝏蠘恣<E8A098>餉<EFBFBD>:**
* **数值列:** 计算 Min, Max, Mean, SD，并使用 Freedman-Diaconis 规则计算直方图的 Bins。
* **文本列:** 计算 Top 10 频率最高的词。
* **<EFBFBD>啣<EFBFBD>澆<EFBFBD>:** 霈∠<EFBFBD> Min, Max, Mean, SD嚗<EFBFBD>僎雿輻鍂 Freedman-Diaconis 閫<EFBFBD><EFBFBD>霈∠<EFBFBD><EFBFBD>湔䲮<EFBFBD>曄<EFBFBD> Bins<EFBFBD>?
* **<EFBFBD><EFBFBD>𧋦<EFBFBD>?** 霈∠<E99C88> Top 10 憸𤑳<E686B8><F0A491B3><EFBFBD>擃条<E69383>霂溻<E99C82>?
### **3.3 <20><>蟮霈啣<E99C88>銝擧伃<E693A7><E4BC83> (History Manager)**
* **Undo/Redo 蝑𣇉裦:**
* **普通操作 (编辑/替换):** 记录 patches (Immer)。
* **结构性操作 (Pivot/拆分/生成新变量):** 由于表结构完全改变，记录 patches 成本过高且难以回滚。策略改为：**在执行此类操作前，强制保存一个全量快照 (Checkpoint)**。撤销时直接重载快照。
* **<EFBFBD>桅<EFBFBD>𡁏<EFBFBD>雿?(蝻𤥁<E89DBB>/<2F>踵揢):** 霈啣<EFBFBD> patches (Immer)<EFBFBD>?
* **蝏𤘪<EFBFBD><EFBFBD>扳<EFBFBD>雿?(Pivot/<2F><><EFBFBD>/<2F><><EFBFBD><EFBFBD>啣<EFBFBD><E595A3>?:** <20>曹<EFBFBD>銵函<E98AB5><E587BD><EFBFBD><EFBFBD><EFBFBD>冽㺿<E586BD>矋<EFBFBD>霈啣<E99C88> patches <20>鞉𧋦餈<F0A78BA6><E9A488>銝娪𠗕隞亙<E99A9E>皛𠾼<E79A9B><F0A0BEBC><EFBFBD><EFBFBD>交㺿銝綽<E98A9D>**<2A>冽<EFBFBD>銵峕迨蝐餅<E89D90>雿𨅯<E99BBF>嚗<EFBFBD>撩<EFBFBD>嗡<EFBFBD>摮䀝<E691AE>銝芸<E98A9D><E88AB8>誩翰<E8AAA9>?(Checkpoint)**<2A><>伃<EFBFBD><E4BC83><EFBFBD>嗥凒<E597A5>仿<EFBFBD>頧賢翰<E8B3A2>扼<EFBFBD>?
## **4\. <20>唳旿瘚<E697BF><E7989A>摮睃<E691AE>霈曇恣**
### **4.1 瘚讛<E7989A><E8AE9B>函垢摮睃<E691AE> (Dexie Schema)**
用于暂存用户正在编辑的数据，实现“自动快照”和“崩溃恢复”。
<EFBFBD>其<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>冽<EFBFBD>甇<EFBFBD>銁蝻𤥁<EFBFBD><EFBFBD><EFBFBD>㺭<EFBFBD>殷<EFBFBD>摰䂿緵<EFBFBD>𡏭䌊<EFBFBD>典翰<EFBFBD>把<EFBFBD>嘥<EFBFBD><EFBFBD>𨅯援皞<EFBFBD><EFBFBD>憭𨧀<EFBFBD>腈<EFBFBD>?
const db \= new Dexie('ResearchEditorDB');
db.version(2).stores({
// 项目元数据
// 憿寧𤌍<EFBFBD><EFBFBD>㺭<EFBFBD>?
projects: '++id, name, lastModified, rowCount',
// 数据块 (Chunks): 将 5万行数据切分为多个 Chunk 存储，避免单次读写过大导致浏览器崩溃
// <EFBFBD>唳旿<EFBFBD>?(Chunks): 撠?5銝<35><E98A9D><EFBFBD>唳旿<E594B3><E697BF><EFBFBD>銝箏<E98A9D>銝?Chunk 摮睃<E691AE>嚗屸<E59A97><E5B1B8>滚<EFBFBD>甈∟粉<E2889F>躰<EFBFBD>憭批紡<E689B9>湔<EFBFBD>閫<EFBFBD>膥撏拇<E6928F>
dataChunks: '\[projectId+chunkIndex\], projectId',
// <20>滢<EFBFBD><E6BBA2><EFBFBD>蟮 (<28>其<EFBFBD><E585B6>Ｗ<EFBFBD><EFBCB7>啣㦤)
history: 'projectId, stack',
// 完整快照 (用于 Pivot 等大操作的回滚)
// 摰峕㟲敹怎<EFBFBD> (<28>其<EFBFBD> Pivot 蝑匧之<E58CA7>滢<EFBFBD><E6BBA2><EFBFBD><EFBFBD>皛?
checkpoints: '++id, projectId, createdAt'
});
### **4.2 <20>𡒊垢摮睃<E691AE> (PostgreSQL \+ OSS)**
后端仅负责存储“已保存”的快照，不参与实时编辑。
<EFBFBD>𡒊垢隞<EFBFBD><EFBFBD>韐<EFBFBD><EFBFBD><EFBFBD>兩<EFBFBD>𨅯歇靽嘥<EFBFBD><EFBFBD>萘<EFBFBD>敹怎<EFBFBD>嚗䔶<EFBFBD><EFBFBD><EFBFBD><EFBFBD>摰墧𧒄蝻𤥁<EFBFBD><EFBFBD>?
model DatasetSnapshot {
id String @id @default(uuid())
taskId String // <20>唾<EFBFBD>隞餃𦛚
version Int // 版本号
version Int // <EFBFBD><EFBFBD>𧋦<EFBFBD>?
// 存储为大的 JSON Blob，或者指向 OSS 文件路径 (推荐 OSS)
// 摮睃<EFBFBD>銝箏之<EFBFBD>?JSON Blob嚗峕<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>?OSS <20><>辣頝臬<E9A09D> (<28>刻<EFBFBD> OSS)
// <20><>捆<EFBFBD><E68D86>鉄嚗鬏ows\[\], columnDefs\[\], metadata
ossKey String
@@ -145,32 +136,31 @@ model DatasetSnapshot {
## **5\. API <20>亙藁摰帋<E691B0>**
* POST /api/editor/init: 初始化编辑器会话，从 OSS 加载原始文件（如果是从工具 A/B 流转过来的）。
* POST /api/editor/save: 保存当前快照。
* POST /api/editor/export: 请求后端生成 Excel/SPSS 文件。
* POST /api/editor/init: <EFBFBD>嘥<EFBFBD><EFBFBD>𣇉<EFBFBD>颲穃膥隡朞<EFBFBD>嚗䔶<EFBFBD> OSS <20>㰘蝸<E3B098>笔<EFBFBD><E7AC94><EFBFBD>辣嚗<E8BEA3><E59A97><EFBFBD>𨀣糓隞𤾸極<F0A4BEB8>?A/B 瘚<>蓮餈<E893AE>䔉<EFBFBD><E49489><EFBFBD><EFBFBD>?
* POST /api/editor/save: 靽嘥<EFBFBD>敶枏<EFBFBD>敹怎<EFBFBD><EFBFBD>?
* POST /api/editor/export: 霂瑟<EFBFBD><EFBFBD>𡒊垢<EFBFBD><EFBFBD><EFBFBD> Excel/SPSS <EFBFBD><EFBFBD>辣<EFBFBD>?
* *Payload:* { rows: \[...\], format: 'spss' }
* *说明:* 如果数据量小，直接前端 SheetJS 生成；数据量大 (\>5MB) 发给后端生成。
## **6\. 性能准入与边界 (Performance Guardrails)**
* *霂湔<EFBFBD>:* 憒<><E68692><EFBFBD>唳旿<E594B3>誩<EFBFBD>嚗𣬚凒<F0A3AC9A>亙<EFBFBD>蝡?SheetJS <20><><EFBFBD>嚗𥟇㺭<F0A59F87>桅<EFBFBD>憭?(\>5MB) <20>𤑳<EFBFBD><F0A491B3>𡒊垢<F0A1928A><E59EA2><EFBFBD><EFBFBD>?
## **6\. <20>扯<EFBFBD><E689AF><EFBFBD><EFBFBD>銝舘器<E88898>?(Performance Guardrails)**
| <20>唳旿<E594B3>讐漣 | 蝑𣇉裦 |
| :---- | :---- |
| **\< 50,000 行** | **全量加载模式**。所有数据都在内存/IndexedDB，操作极快。 |
| **\> 50,000 行** | **降采样模式 (Downsampling)**。前端仅加载前 5 万行用于预览和规则制定。导出时，将清洗规则（Recipe）发送给后端，由后端 Worker 对全量数据进行批处理。 |
| **\< 50,000 銵?* | **<EFBFBD>券<EFBFBD><EFBFBD>㰘蝸璅∪<EFBFBD>**<2A><><EFBFBD><EFBFBD>㗇㺭<E39787>桅<EFBFBD><E6A185>典<EFBFBD>摮?IndexedDB嚗峕<E59A97>雿𨀣<E99BBF>敹怒<E695B9>?|
| **\> 50,000 銵?* | **<EFBFBD>漤<EFBFBD><EFBFBD>瑟芋撘?(Downsampling)**<2A><><EFBFBD>蝡臭<E89DA1><E887AD>㰘蝸<E3B098>?5 銝<><E98A9D><EFBFBD>其<EFBFBD>憸<EFBFBD><E686B8><EFBFBD>諹<EFBFBD><E8ABB9>坔<EFBFBD>摰𠾼<E691B0><F0A0BEBC>紡<EFBFBD>箸𧒄嚗<F0A79284><E59A97>皜<EFBFBD><E79A9C>閫<EFBFBD><E996AB>嚗㇌ecipe嚗匧<E59A97><E58CA7><EFBFBD><EFBFBD><EFBFBD>𡒊垢嚗𣬚眏<F0A3AC9A>𡒊垢 Worker 撖孵<E69296><E5ADB5>𤩺㺭<F0A4A9BA>株<EFBFBD>銵峕鸌憭<E9B88C><E686AD><EFBFBD>?|
## **7\. 开发计划 (Milestones)**
## **7\. 撘<EFBFBD><EFBFBD>𤏸恣<EFBFBD>?(Milestones)**
1. **Week 1: 核心网格与存储**
* 搭建 React \+ AG Grid 环境。
* 实现 SheetJS 导入与 Dexie.js 持久化逻辑。
2. **Week 2: 扁平化工具栏与 Web Worker**
* 搭建 Web Worker 通信架构。
* 实现 Formula 计算和 Math.js 集成。
* 实现 Undo/Redo 栈（Immer）。
1. **Week 1: <EFBFBD>詨<EFBFBD>蝵烐聢銝𤾸<EFBFBD><EFBFBD>?*
* <EFBFBD>剖遣 React \+ AG Grid <EFBFBD>臬<EFBFBD><EFBFBD>?
* 摰䂿緵 SheetJS 撖澆<EFBFBD>銝?Dexie.js <EFBFBD><EFBFBD><EFBFBD><EFBFBD>㚚<EFBFBD>餉<EFBFBD><EFBFBD>?
2. **Week 2: <EFBFBD><EFBFBD>像<EFBFBD>硋極<EFBFBD>瑟<EFBFBD>銝?Web Worker**
* <EFBFBD>剖遣 Web Worker <EFBFBD>帋縑<EFBFBD>嗆<EFBFBD><EFBFBD>?
* 摰䂿緵 Formula 霈∠<EFBFBD><EFBFBD>?Math.js <EFBFBD><EFBFBD><EFBFBD><EFBFBD>?
* 摰䂿緵 Undo/Redo <EFBFBD><EFBFBD><EFBFBD>Immer嚗剹<EFBFBD>?
3. **Week 3: 憭齿<E686AD>霈∠<E99C88> (Pivot)**
* **重点攻坚：** 在 Web Worker 中实现 Pivot 算法。
* 实现 Pivot 的 UI 配置弹窗。
* **<EFBFBD>滨<EFBFBD><EFBFBD>餃<EFBFBD>嚗?* <20>?Web Worker 銝剖<EFBFBD><EFBFBD>?Pivot 蝞埈<EFBFBD><EFBFBD>?
* 摰䂿緵 Pivot <EFBFBD>?UI <EFBFBD>滨蔭撘寧<EFBFBD><EFBFBD>?
4. **Week 4: <20>箄<EFBFBD>靘扯器<E689AF>譍<EFBFBD>撖澆枂**
* 开发直方图/频次图组件 (AntD Charts)。
* 实现分箱、映射、填补缺失值逻辑。
* 对接后端保存接口。
* 撘<EFBFBD><EFBFBD>𤑳凒<EFBFBD>孵㦛/憸烐活<E78390>曄<EFBFBD>隞?(AntD Charts)<EFBFBD>?
* 摰䂿緵<EFBFBD><EFBFBD>拳<EFBFBD><EFBFBD><EFBFBD>撠<EFBFBD><EFBFBD><EFBFBD>‵銵亦撩憭勗<EFBFBD>潮<EFBFBD>餉<EFBFBD><EFBFBD>?
* 撖寞𦻖<EFBFBD>𡒊垢靽嘥<EFBFBD><EFBFBD>亙藁<EFBFBD>

303
docs/03-业务模块/DC-数据清洗整理/02-技术设计/数据库设计文档-DC模块（完整版）.md
View File

@@ -1,11 +1,10 @@
# 数据库设计文档 - 工具B（病历结构化机器人）
# <EFBFBD>唳旿摨栞挽霈⊥<EFBFBD>獢?- 撌亙<E6928C>B嚗<42><E59A97><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>箏膥鈭綽<E988AD>
> **璅∪<E79285>**: DC<44>唳旿皜<E697BF><E79A9C><EFBFBD>渡<EFBFBD> - 撌亙<E6928C>B
> **<2A><>𧋦**: V2.0 (MVP)
> **Schema**: `dc_schema`
> **<2A>湔鰵<E6B994>交<EFBFBD>**: 2025-12-03
> **状态**: ✅ MVP完成（已验证可用，真实数据测试通过）
> **<EFBFBD>嗆<EFBFBD>?*: <EFBFBD>?MVP摰峕<EFBFBD>嚗<EFBFBD>歇撉諹<EFBFBD><EFBFBD>舐鍂嚗𣬚<EFBFBD>摰墧㺭<EFBFBD>格<EFBFBD>霂閖<EFBFBD>朞<EFBFBD>嚗?
---
## <20><> <20>桀<EFBFBD>
@@ -13,49 +12,37 @@
- [銝<><E98A9D><EFBFBD><EFBFBD>餈財(#銝<EFBFBD>璁<EFBFBD>膩)
- [鈭䎚<EFBFBD><EFBFBD>chema霈曇恣<EFBFBD>笔<EFBFBD>](#鈭众chema霈曇恣<E69B87>笔<EFBFBD>)
- [銝剹<EFBFBD><EFBFBD>㺭<EFBFBD>株”霈曇恣](#銝㗇㺭<E39787>株”霈曇恣)
- [四、索引设计](#四索引设计)
- [五、外键约束](#五外键约束)
- [六、数据生命周期](#六数据生命周期)
- [<EFBFBD>䜘<EFBFBD><EFBFBD>揣撘閗挽霈（(#<23>𤤿揣撘閗挽霈?
- [鈭𢛵<EFBFBD><EFBFBD><EFBFBD><EFBFBD>桃漲<EFBFBD>篏(#鈭𥪜<EFBFBD><EFBFBD>桃漲<EFBFBD>?
- [<EFBFBD>准<EFBFBD><EFBFBD>㺭<EFBFBD>桃<EFBFBD><EFBFBD>賢𪂹<EFBFBD>篏(#<23>剜㺭<E5899C>桃<EFBFBD><E6A183>賢𪂹<E8B3A2>?
---
## 一、概述
## 銝<EFBFBD><EFBFBD><EFBFBD><EFBFBD>餈?
### 1.1 霈曇恣<E69B87>格<EFBFBD>
工具B的数据库设计旨在支持：
- ✅ 双大模型交叉验证的文本结构化
- ✅ 大规模异步任务处理（1000+条记录）
- ✅ 冲突检测与人工裁决
- ✅ 预设模板管理与复用
- ✅ 健康检查缓存优化
撌亙<EFBFBD>B<EFBFBD><EFBFBD>㺭<EFBFBD>桀<EFBFBD>霈曇恣<EFBFBD>典銁<EFBFBD>舀<EFBFBD>嚗?- <20>?<3F><>之璅∪<E79285>鈭文<E988AD>撉諹<E69289><E8ABB9><EFBFBD><EFBFBD><EFBFBD>祉<EFBFBD><E7A589><EFBFBD><EFBFBD>
- <EFBFBD>?憭扯<E686AD>璅∪<E79285>甇乩遙<E4B9A9>∪<EFBFBD><E288AA><EFBFBD><EFBFBD>1000+<2B>∟扇敶𤏪<E695B6>
- <EFBFBD>?<3F>脩<EFBFBD>璉<EFBFBD>瘚衤<E7989A>鈭箏極鋆<E6A5B5><E98B86>
- <EFBFBD>?憸<>挽璅⊥踎蝞∠<E89D9E>銝𤾸<E98A9D><F0A4BEB8>?- <20>?<3F>亙熒璉<E78692><E79289>亦<EFBFBD>摮䀝<E691AE><E4809D>?
### 1.2 銵典<E98AB5>蝟餅<E89D9F>餉<EFBFBD>
```
dc_schema ✅ 已创建并运行中
├── dc_health_checks [健康检查缓存] ✅ 运行正常
├── dc_templates [预设模板] ✅ 3个预设模板可用
├── dc_extraction_tasks [提取任务] ✅ 已完成多个任务
│ └── dc_extraction_items [提取记录] (1:N) ✅ 双模型结果正常保存
```
dc_schema <EFBFBD>?撌脣<E6928C>撱箏僎餈鞱<E9A488>銝?<3F>鎿<EFBFBD><E98EBF><EFBFBD> dc_health_checks [<5B>亙熒璉<E78692><E79289>亦<EFBFBD>摮𤊓 <20>?餈鞱<E9A488>甇<EFBFBD>虜
<EFBFBD>鎿<EFBFBD><EFBFBD><EFBFBD> dc_templates [憸<>挽璅⊥踎] <20>?3銝芷<E98A9D>霈暹芋<E69AB9>踹虾<E8B8B9>?<3F>鎿<EFBFBD><E98EBF><EFBFBD> dc_extraction_tasks [<5B>𣂼<EFBFBD>隞餃𦛚] <20>?撌脣<E6928C><E884A3>𣂼<EFBFBD>銝芯遙<E88AAF>?<3F>? <20>婙<EFBFBD><E5A999><EFBFBD> dc_extraction_items [<5B>𣂼<EFBFBD>霈啣<E99C88>] (1:N) <20>?<3F>峕芋<E5B395>讠<EFBFBD><E8AEA0>𨀣迤撣訾<E692A3>摮?```
**✅ MVP完成状态（2025-12-03）**：
- 所有表正常工作，已处理多个真实任务
- 3个预设模板：肺癌病理报告、糖尿病入院记录、高血压门诊病历
- 真实测试：9条病理数据提取成功，100%成功率
- 双模型结果：resultA、resultB、finalResult字段正常保存
**<2A>?MVP摰峕<E691B0><E5B395>嗆<EFBFBD><E59786><EFBFBD>2025-12-03嚗?*嚗?- <20><><EFBFBD>㕑”甇<E2809D>虜撌乩<E6928C>嚗<EFBFBD>歇憭<E6AD87><E686AD>憭帋葵<E5B88B>笔<EFBFBD>隞餃𦛚
- 3銝芷<E98A9D>霈暹芋<E69AB9>選<EFBFBD><E981B8>箇<EFBFBD><E7AE87><EFBFBD><EFBFBD><EFBFBD>亙<EFBFBD><E4BA99><EFBFBD><EFBFBD>撠輻<E692A0><E8BCBB>仿堺霈啣<E99C88><E595A3><EFBFBD><EFBFBD>銵<EFBFBD><E98AB5>钅秄霂羓<E99C82><E7BE93>?- <20>笔<EFBFBD>瘚贝<E7989A>嚗?<3F>∠<EFBFBD><E288A0><EFBFBD>㺭<EFBFBD>格<EFBFBD><E6A0BC>𡝗<EFBFBD><F0A19D97><EFBFBD><EFBFBD>100%<25>𣂼<EFBFBD><F0A382BC>?- <20>峕芋<E5B395>讠<EFBFBD><E8AEA0>頣<EFBFBD>resultA<74><41>esultB<74><42>inalResult摮埈挾甇<E68CBE>虜靽嘥<E99DBD>
- Token蝏蠘恣嚗魩otalTokens摮埈挾甇<E68CBE>虜蝝臬<E89D9D>
- <20>脩<EFBFBD>璉<EFBFBD>瘚页<E7989A>conflictFields<64>啁<EFBFBD>甇<EFBFBD>虜撌乩<E6928C>
- 撉諹<E69289><E8ABB9>𡁏𧋦嚗䫤backend/scripts/check-task-progress.mjs`
### 1.3 <20><><EFBFBD>舀<EFBFBD>
- **数据库**: PostgreSQL 15
- **<2A>唳旿摨?*: PostgreSQL 15
- **ORM**: Prisma 6
- **Schema<6D>𠉛氖**: `dc_schema`嚗<>𡠺蝡见𦶢<E8A781>滨征<E6BBA8>湛<EFBFBD>
- **JSON字段**: 使用JSONB类型（高性能查询）
- **JSON摮埈挾**: 雿輻鍂JSONB蝐餃<EFBFBD>嚗<EFBFBD><EFBFBD><EFBFBD>扯<EFBFBD><EFBFBD>亥砭嚗?
---
## 鈭䎚<E988AD><E48E9A>chema霈曇恣<E69B87>笔<EFBFBD>
@@ -68,10 +55,9 @@ CREATE TABLE "dc_schema"."dc_health_checks" (...);
CREATE TABLE "dc_schema"."dc_extraction_tasks" (...);
```
**优势**：
- ✅ 与其他模块完全隔离（platform_schema、asl_schema等）
- ✅ 数据安全，避免误操作
- ✅ 便于模块化管理和迁移
**隡睃飵**嚗?- <20>?銝𤾸<E98A9D>隞𡝗芋<F0A19D97>堒<EFBFBD><E5A092>券<EFBFBD>蝳鳴<E89DB3>platform_schema<6D><61>sl_schema蝑㚁<E89D91>
- <EFBFBD>?<3F>唳旿摰匧<E691B0>嚗屸<E59A97><E5B1B8>滩秤<E6BBA9>滢<EFBFBD>
- <EFBFBD>?靘蹂<E99D98>璅∪<E79285><E288AA>𣇉恣<F0A38789><E681A3><EFBFBD>餈<EFBFBD>宏
### 2.2 <20>賢<EFBFBD>閫<EFBFBD><E996AB>
@@ -79,24 +65,23 @@ CREATE TABLE "dc_schema"."dc_extraction_tasks" (...);
|------|------|------|
| **銵典<E98AB5><E585B8>滨<EFBFBD>** | `dc_` | `dc_extraction_tasks` |
| **摮埈挾<E59F88>賢<EFBFBD>** | snake_case | `user_id`, `source_file_key` |
| **时间戳** | 统一后缀 | `created_at`, `started_at` |
| **<EFBFBD>園𡢿<EFBFBD>?* | 蝏煺<E89D8F><E785BA>𡒊<EFBFBD> | `created_at`, `started_at` |
| **憭㚚睸** | 摰硺<E691B0><E7A1BA>䇭id | `task_id`, `user_id` |
### 2.3 JSONB摮埈挾雿輻鍂<E8BCBB>箸艶
| 摮埈挾 | 蝐餃<E89D90> | <20>笔<EFBFBD> |
|------|------|------|
| `target_fields` | JSONB | 灵活的字段配置 |
| `result_a/result_b` | JSONB | 动态提取结果 |
| `final_result` | JSONB | 最终裁决结果 |
| `target_fields` | JSONB | <EFBFBD>菜暑<EFBFBD><EFBFBD><EFBFBD>畾菟<EFBFBD>蝵?|
| `result_a/result_b` | JSONB | <EFBFBD>冽<EFBFBD><EFBFBD><EFBFBD><EFBFBD>𣇉<EFBFBD><EFBFBD>?|
| `final_result` | JSONB | <EFBFBD><EFBFBD>蝏<EFBFBD><EFBFBD><EFBFBD>喟<EFBFBD><EFBFBD>?|
---
## 銝剹<E98A9D><E589B9>㺭<EFBFBD>株”霈曇恣
### 3.1 dc_health_checks（健康检查缓存表）
**用途**: 缓存健康检查结果，避免重复计算
### 3.1 dc_health_checks嚗<EFBFBD><EFBFBD>摨瑟<EFBFBD><EFBFBD>亦<EFBFBD>摮䁅”嚗?
**<2A>券<EFBFBD>?*: 蝻枏<E89DBB><E69E8F>亙熒璉<E78692><E79289>亦<EFBFBD><E4BAA6>頣<EFBFBD><E9A0A3>踹<EFBFBD><E8B8B9>滚<EFBFBD>霈∠<E99C88>
```sql
CREATE TABLE "dc_schema"."dc_health_checks" (
@@ -111,46 +96,39 @@ CREATE TABLE "dc_schema"."dc_health_checks" (
"total_rows" INTEGER NOT NULL,
"estimated_tokens" INTEGER NOT NULL,
-- 检查结果
"status" TEXT NOT NULL, -- 'good' | 'bad'
-- 璉<EFBFBD><EFBFBD>亦<EFBFBD><EFBFBD>? "status" TEXT NOT NULL, -- 'good' | 'bad'
"message" TEXT NOT NULL,
"created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP
);
```
**字段说明**：
**摮埈挾霂湔<EFBFBD>**嚗?
| 摮埈挾 | 蝐餃<E89D90> | 霂湔<E99C82> | 蝷箔<E89DB7> |
|------|------|------|------|
| `id` | TEXT | UUID銝駁睸 | `uuid()` |
| `user_id` | TEXT | <20>冽<EFBFBD>ID | `user-123` |
| `file_name` | TEXT | 文件名 | `患者数据.xlsx` |
| `file_name` | TEXT | <EFBFBD><EFBFBD>辣<EFBFBD>?| `<60><><EFBFBD><EFBFBD>㺭<EFBFBD>?xlsx` |
| `column_name` | TEXT | 璉<><E79289>亦<EFBFBD><E4BAA6>堒<EFBFBD> | `<60><><EFBFBD><EFBFBD><EFBFBD>𧋦` |
| `empty_rate` | DOUBLE | 蝛箏<E89D9B>潛<EFBFBD> (0-1) | 0.15 (15%) |
| `avg_length` | DOUBLE | 撟喳<E6929F><E596B3><EFBFBD>𧋦<EFBFBD>踹漲 | 256.8 |
| `total_rows` | INT | 总行数 | 500 |
| `estimated_tokens` | INT | 预估Token数 | 150000 |
| `status` | TEXT | 健康状态 | `good` / `bad` |
| `total_rows` | INT | <EFBFBD>餉<EFBFBD><EFBFBD>?| 500 |
| `estimated_tokens` | INT | 憸<EFBFBD>摯Token<EFBFBD>?| 150000 |
| `status` | TEXT | <EFBFBD>亙熒<EFBFBD>嗆<EFBFBD>?| `good` / `bad` |
| `message` | TEXT | <20>鞟內靽⊥<E99DBD> | `<60>亙熒摨西<E691A8>憟窯 |
**索引**：
```sql
**蝝Ｗ<EFBFBD>**嚗?```sql
CREATE INDEX "dc_health_checks_user_id_file_name_idx"
ON "dc_schema"."dc_health_checks"("user_id", "file_name");
```
**业务规则**：
- 空值率 > 80% → `status = 'bad'`
- 平均长度 < 10 → `status = 'bad'`
- 缓存有效期：24小时（应用层实现）
**銝𡁜𦛚閫<EFBFBD><EFBFBD>**嚗?- 蝛箏<E89D9B>潛<EFBFBD> > 80% <20>?`status = 'bad'`
- 撟喳<E6929F><E596B3>踹漲 < 10 <20>?`status = 'bad'`
- 蝻枏<E89DBB><E69E8F>㗇<EFBFBD><E39787><EFBFBD><EFBFBD>24撠𤩺𧒄嚗<F0A79284><E59A97><EFBFBD>典<EFBFBD>摰䂿緵嚗?
---
### 3.2 dc_templates（预设模板表）
**用途**: 存储疾病类型的预设提取模板
### 3.2 dc_templates嚗<EFBFBD><EFBFBD>霈暹芋<EFBFBD>輯”嚗?
**<2A>券<EFBFBD>?*: 摮睃<E691AE><E79D83>曄<EFBFBD>蝐餃<E89D90><E9A483><EFBFBD><EFBFBD>霈暹<E99C88><E69AB9>𡝗芋<F0A19D97>?
```sql
CREATE TABLE "dc_schema"."dc_templates" (
"id" TEXT NOT NULL PRIMARY KEY,
@@ -168,18 +146,16 @@ CREATE TABLE "dc_schema"."dc_templates" (
);
```
**字段说明**：
**摮埈挾霂湔<EFBFBD>**嚗?
| 摮埈挾 | 蝐餃<E89D90> | 霂湔<E99C82> | 蝷箔<E89DB7> |
|------|------|------|------|
| `disease_type` | TEXT | <20>曄<EFBFBD>蝐餃<E89D90> | `lung_cancer` |
| `report_type` | TEXT | <20>亙<EFBFBD>蝐餃<E89D90> | `pathology` |
| `display_name` | TEXT | <20>曄內<E69B84>滨妍 | `<EFBFBD>箇<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>亙<EFBFBD>` |
| `fields` | JSONB | 提取字段配置 | 见下方示例 |
| `prompt_template` | TEXT | Prompt模板 | `请从以下病理报告中提取...` |
| `fields` | JSONB | <EFBFBD>𣂼<EFBFBD>摮埈挾<EFBFBD>滨蔭 | 閫<><E996AB><EFBFBD>寧內靘?|
| `prompt_template` | TEXT | Prompt璅⊥踎 | `霂瑚<EFBFBD>隞乩<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>亙<EFBFBD>銝剜<EFBFBD><EFBFBD>?..` |
**fields字段结构**：
```json
**fields摮埈挾蝏𤘪<EFBFBD>**嚗?```json
[
{
"name": "<22><><EFBFBD>蝐餃<E89D90>",
@@ -188,23 +164,20 @@ CREATE TABLE "dc_schema"."dc_templates" (
},
{
"name": "<22><><EFBFBD>蝔见漲",
"desc": "高/中/低分化",
"desc": "擃?銝?雿𤾸<E99BBF><F0A4BEB8>?,
"width": "w-32"
}
]
```
**唯一约束**：
```sql
**<EFBFBD>臭<EFBFBD>蝥行<EFBFBD>**嚗?```sql
UNIQUE ("disease_type", "report_type")
```
同一疾病+报告类型组合只能有一个模板
<EFBFBD>䔶<EFBFBD><EFBFBD>曄<EFBFBD>+<2B>亙<EFBFBD>蝐餃<E89D90>蝏<EFBFBD><E89D8F><EFBFBD>芾<EFBFBD><E88ABE>劐<EFBFBD>銝芣芋<E88AA3>?
---
### 3.3 dc_extraction_tasks（提取任务表）
**用途**: 管理批量提取任务，追踪进度和成本
### 3.3 dc_extraction_tasks嚗<EFBFBD><EFBFBD><EFBFBD>碶遙<EFBFBD>∟”嚗?
**<2A>券<EFBFBD>?*: 蝞∠<E89D9E><E288A0>寥<EFBFBD><E5AFA5>𣂼<EFBFBD>隞餃𦛚嚗諹蕭頦芾<E9A0A6>摨血<E691A8><E8A180>鞉𧋦
```sql
CREATE TABLE "dc_schema"."dc_extraction_tasks" (
@@ -219,12 +192,10 @@ CREATE TABLE "dc_schema"."dc_extraction_tasks" (
"report_type" TEXT NOT NULL,
"target_fields" JSONB NOT NULL,
-- 双模型配置
"model_a" TEXT NOT NULL DEFAULT 'deepseek-v3',
-- <EFBFBD>峕芋<EFBFBD>钅<EFBFBD>蝵? "model_a" TEXT NOT NULL DEFAULT 'deepseek-v3',
"model_b" TEXT NOT NULL DEFAULT 'qwen3-72b',
-- 任务状态
"status" TEXT NOT NULL DEFAULT 'pending',
-- 隞餃𦛚<EFBFBD>嗆<EFBFBD>? "status" TEXT NOT NULL DEFAULT 'pending',
"total_count" INTEGER NOT NULL DEFAULT 0,
"processed_count" INTEGER NOT NULL DEFAULT 0,
"clean_count" INTEGER NOT NULL DEFAULT 0,
@@ -238,47 +209,41 @@ CREATE TABLE "dc_schema"."dc_extraction_tasks" (
-- <20>躰秤靽⊥<E99DBD>
"error" TEXT,
-- 时间戳
"created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
-- <EFBFBD>園𡢿<EFBFBD>? "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
"started_at" TIMESTAMP(3),
"completed_at" TIMESTAMP(3)
);
```
**字段说明**：
**摮埈挾霂湔<EFBFBD>**嚗?
| 摮埈挾 | 蝐餃<E89D90> | 霂湔<E99C82> | 蝷箔<E89DB7> |
|------|------|------|------|
| `source_file_key` | TEXT | Storage頝臬<E9A09D> | `uploads/user123/data.xlsx` |
| `text_column` | TEXT | <20><>𧋦<EFBFBD>堒<EFBFBD> | `<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>𧋦` |
| `target_fields` | JSONB | <20>𣂼<EFBFBD>摮埈挾 | `[{name, desc}]` |
| `status` | TEXT | 任务状态 | `pending/processing/completed/failed` |
| `status` | TEXT | 隞餃𦛚<EFBFBD>嗆<EFBFBD>?| `pending/processing/completed/failed` |
| `total_count` | INT | <20>餉扇敶閙㺭 | 500 |
| `processed_count` | INT | 撌脣<E6928C><E884A3><EFBFBD>㺭 | 250 |
| `clean_count` | INT | 銝<><E98A9D>湔㺭 | 200 |
| `conflict_count` | INT | 冲突数 | 45 |
| `failed_count` | INT | 失败数 | 5 |
| `total_tokens` | INT | 总Token数 | 150000 |
| `total_cost` | DOUBLE | 总成本($) | 0.27 |
| `conflict_count` | INT | <EFBFBD>脩<EFBFBD><EFBFBD>?| 45 |
| `failed_count` | INT | 憭梯揖<EFBFBD>?| 5 |
| `total_tokens` | INT | <EFBFBD>蓉oken<EFBFBD>?| 150000 |
| `total_cost` | DOUBLE | <EFBFBD>餅<EFBFBD><EFBFBD>?$) | 0.27 |
**状态流转**：
```
pending → processing → completed
→ failed
**<EFBFBD>嗆<EFBFBD><EFBFBD><EFBFBD>頧?*嚗?```
pending <20>?processing <20>?completed
<20>?failed
```
**索引**：
```sql
**蝝Ｗ<EFBFBD>**嚗?```sql
CREATE INDEX "dc_extraction_tasks_user_id_status_idx"
ON "dc_schema"."dc_extraction_tasks"("user_id", "status");
```
---
### 3.4 dc_extraction_items（提取记录表）
**用途**: 存储每条记录的双模型提取结果和冲突状态
### 3.4 dc_extraction_items嚗<EFBFBD><EFBFBD><EFBFBD>𤥁扇敶閗”嚗?
**<2A>券<EFBFBD>?*: 摮睃<E691AE>瘥𤩺辺霈啣<E99C88><E595A3><EFBFBD><EFBFBD>璅∪<E79285><E288AA>𣂼<EFBFBD>蝏𤘪<E89D8F><F0A498AA><EFBFBD><EFBFBD>蝒<EFBFBD>𠶖<EFBFBD>?
```sql
CREATE TABLE "dc_schema"."dc_extraction_items" (
"id" TEXT NOT NULL PRIMARY KEY,
@@ -288,16 +253,13 @@ CREATE TABLE "dc_schema"."dc_extraction_items" (
"row_index" INTEGER NOT NULL,
"original_text" TEXT NOT NULL,
-- 双模型结果
"result_a" JSONB,
-- <EFBFBD>峕芋<EFBFBD>讠<EFBFBD><EFBFBD>? "result_a" JSONB,
"result_b" JSONB,
-- 冲突检测
"status" TEXT NOT NULL DEFAULT 'pending',
-- <EFBFBD>脩<EFBFBD>璉<EFBFBD>瘚? "status" TEXT NOT NULL DEFAULT 'pending',
"conflict_fields" TEXT[] DEFAULT ARRAY[]::TEXT[],
-- 最终结果
"final_result" JSONB,
-- <EFBFBD><EFBFBD>蝏<EFBFBD><EFBFBD><EFBFBD>? "final_result" JSONB,
-- Token蝏蠘恣
"tokens_a" INTEGER NOT NULL DEFAULT 0,
@@ -316,78 +278,63 @@ CREATE TABLE "dc_schema"."dc_extraction_items" (
);
```
**字段说明**：
**摮埈挾霂湔<EFBFBD>**嚗?
| 摮埈挾 | 蝐餃<E89D90> | 霂湔<E99C82> | 蝷箔<E89DB7> |
|------|------|------|------|
| `row_index` | INT | Excel銵<6C>噡 | 5 |
| `original_text` | TEXT | 原始病历文本 | `患者，男，45岁...` |
| `original_text` | TEXT | <EFBFBD>笔<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>𧋦 | `<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>瘀<EFBFBD>45撗?..` |
| `result_a` | JSONB | DeepSeek蝏𤘪<E89D8F> | `{"<22>輻𠈔憭批<E686AD>": "3cm"}` |
| `result_b` | JSONB | Qwen蝏𤘪<E89D8F> | `{"<22>輻𠈔憭批<E686AD>": "3.0cm"}` |
| `status` | TEXT | 处理状态 | `clean/conflict/resolved/failed` |
| `status` | TEXT | 憭<EFBFBD><EFBFBD><EFBFBD>嗆<EFBFBD>?| `clean/conflict/resolved/failed` |
| `conflict_fields` | TEXT[] | <20>脩<EFBFBD>摮埈挾<E59F88>𡑒” | `["<22>輻𠈔憭批<E686AD>"]` |
| `final_result` | JSONB | 最终裁决结果 | `{"肿瘤大小": "3cm"}` |
| `final_result` | JSONB | <EFBFBD><EFBFBD>蝏<EFBFBD><EFBFBD><EFBFBD>喟<EFBFBD><EFBFBD>?| `{"<22>輻𠈔憭批<E686AD>": "3cm"}` |
**result_a/result_b结构示例**：
```json
**result_a/result_b蝏𤘪<EFBFBD>蝷箔<EFBFBD>**嚗?```json
{
"病理类型": "浸润性腺癌",
"分化程度": "中分化",
"<22><><EFBFBD>蝐餃<E89D90>": "瘚豢隋<E8B1A2>扯<EFBFBD><E689AF>?,
"<22><><EFBFBD>蝔见漲": "銝剖<E98A9D><E58996>?,
"<22>輻𠈔憭批<E686AD>": "3cm",
"淋巴结转移": "无"
"瘛见毀蝏栞蓮蝘?: "<22>?
}
```
**状态说明**：
- `pending`: 等待处理
- `clean`: 双模型结果一致
- `conflict`: 存在冲突，需人工裁决
- `resolved`: 冲突已解决
- `failed`: 提取失败
**<EFBFBD>嗆<EFBFBD><EFBFBD>秩<EFBFBD>?*嚗?- `pending`: 蝑匧<E89D91>憭<EFBFBD><E686AD>
- `clean`: <20>峕芋<E5B395>讠<EFBFBD><E8AEA0>靝<EFBFBD><E99D9D>?- `conflict`: 摮睃銁<E79D83>脩<EFBFBD>嚗屸<E59A97>鈭箏極鋆<E6A5B5><E98B86>
- `resolved`: <20>脩<EFBFBD>撌脰圾<E884B0>?- `failed`: <20>𣂼<EFBFBD>憭梯揖
**索引**：
```sql
**蝝Ｗ<EFBFBD>**嚗?```sql
CREATE INDEX "dc_extraction_items_task_id_status_idx"
ON "dc_schema"."dc_extraction_items"("task_id", "status");
```
**外键约束**：
- `ON DELETE CASCADE`: 删除任务时自动删除所有记录
**憭㚚睸蝥行<EFBFBD>**嚗?- `ON DELETE CASCADE`: <20>𣳇膄隞餃𦛚<E9A483>嗉䌊<E59789>典<EFBFBD><E585B8>斗<EFBFBD><E69697>㕑扇敶?
---
## 四、索引设计
## <EFBFBD>䜘<EFBFBD><EFBFBD>揣撘閗挽霈?
### 4.1 蝝Ｗ<E89D9D><EFBCB7>𡑒”
| 表名 | 索引字段 | 类型 | 用途 |
| 銵典<EFBFBD> | 蝝Ｗ<E89D9D>摮埈挾 | 蝐餃<E89D90> | <20>券<EFBFBD>?|
|------|---------|------|------|
| `dc_health_checks` | `(user_id, file_name)` | 复合 | 查询用户的历史检查 |
| `dc_health_checks` | `(user_id, file_name)` | 憭滚<EFBFBD> | <20>亥砭<E4BAA5>冽<EFBFBD><E586BD><EFBFBD><EFBFBD><EFBFBD>脫<EFBFBD><E884AB>?|
| `dc_templates` | `(disease_type, report_type)` | <20>臭<EFBFBD> | <20>脫迫<E884AB>滚<EFBFBD>璅⊥踎 |
| `dc_extraction_tasks` | `(user_id, status)` | 复合 | 查询用户的任务列表 |
| `dc_extraction_items` | `(task_id, status)` | 复合 | 查询任务的记录列表 |
| `dc_extraction_tasks` | `(user_id, status)` | 憭滚<EFBFBD> | <20>亥砭<E4BAA5>冽<EFBFBD><E586BD><EFBFBD>遙<EFBFBD>∪<EFBFBD>銵?|
| `dc_extraction_items` | `(task_id, status)` | 憭滚<EFBFBD> | <20>亥砭隞餃𦛚<E9A483><F0A69B9A>扇敶訫<E695B6>銵?|
### 4.2 <20>扯<EFBFBD><E689AF><EFBFBD><EFBFBD>
**查询优化**：
```sql
-- 高效查询：利用索引
SELECT * FROM dc_extraction_tasks
**<EFBFBD>亥砭隡睃<EFBFBD>**嚗?```sql
-- 擃䀹<E69383><E480B9>亥砭嚗𡁜⏚<F0A1819C>函揣撘?SELECT * FROM dc_extraction_tasks
WHERE user_id = 'user123' AND status = 'processing';
-- 高效查询：利用索引
SELECT * FROM dc_extraction_items
-- 擃䀹<E69383><E480B9>亥砭嚗𡁜⏚<F0A1819C>函揣撘?SELECT * FROM dc_extraction_items
WHERE task_id = 'task456' AND status = 'conflict';
```
**避免全表扫描**：
- ✅ 始终在WHERE子句中包含索引字段
- ✅ 使用`status`字段过滤可以显著减少扫描行数
**<EFBFBD>踹<EFBFBD><EFBFBD>刻”<EFBFBD>急<EFBFBD>**嚗?- <20>?憪讠<E686AA><E8AEA0>汾HERE摮𣂼蘂銝剖<E98A9D><E58996>怎揣撘訫<E69298>畾?- <20>?雿輻鍂`status`摮埈挾餈<E68CBE>誘<EFBFBD>臭誑<E887AD>曇<EFBFBD><E69B87>誩<EFBFBD><E8AAA9>急<EFBFBD>銵峕㺭
---
## 五、外键约束
## 鈭𢛵<EFBFBD><EFBFBD><EFBFBD><EFBFBD>桃漲<EFBFBD>?
### 5.1 蝥扯<E89DA5><E689AF>𣳇膄
```sql
@@ -398,46 +345,34 @@ REFERENCES "dc_schema"."dc_extraction_tasks"("id")
ON DELETE CASCADE;
```
**行为**：
- 删除任务 → 自动删除所有关联的提取记录
- 保证数据一致性
### 5.2 无外键的表
- `dc_health_checks`: 独立表，无外键
- `dc_templates`: 独立表，无外键
- `dc_extraction_tasks`: 无外键（user_id仅为标识，不强制关联）
**原因**：
- ✅ 减少跨Schema依赖
- ✅ 提高模块独立性
- ✅ 简化迁移和回滚
**銵䔶蛹**嚗?- <20>𣳇膄隞餃𦛚 <20>?<3F>芸𢆡<E88AB8>𣳇膄<F0A3B387><E88684><EFBFBD>匧<EFBFBD><E58CA7>𠉛<EFBFBD><F0A0899B>𣂼<EFBFBD>霈啣<E99C88>
- 靽肽<E99DBD><E882BD>唳旿銝<E697BF><E98A9D>湔<EFBFBD>?
### 5.2 <20>惩<EFBFBD><E683A9>桃<EFBFBD>銵?
- `dc_health_checks`: <20>祉<EFBFBD>銵剁<E98AB5><E58981>惩<EFBFBD><E683A9>?- `dc_templates`: <20>祉<EFBFBD>銵剁<E98AB5><E58981>惩<EFBFBD><E683A9>?- `dc_extraction_tasks`: <20>惩<EFBFBD><E683A9>殷<EFBFBD>user_id隞<64>蛹<EFBFBD><E89BB9><EFBFBD>嚗䔶<E59A97>撘箏<E69298><E7AE8F>唾<EFBFBD>嚗?
**<2A>笔<EFBFBD>**嚗?- <20>?<3F>誩<EFBFBD>頝沒chema靘肽<E99D98>
- <20>?<3F>鞾<EFBFBD>璅∪<E79285><E288AA>祉<EFBFBD><E7A589>?- <20>?蝞<><E89D9E>𤥁<EFBFBD>蝘餃<E89D98><E9A483>墧<EFBFBD>
---
## 六、数据生命周期
## <EFBFBD>准<EFBFBD><EFBFBD>㺭<EFBFBD>桃<EFBFBD><EFBFBD>賢𪂹<EFBFBD>?
### 6.1 <20>唳旿靽萘<E99DBD>蝑𣇉裦
| 銵典<E98AB5> | 靽萘<E99DBD><E89098>園𡢿 | 皜<><E79A9C>蝑𣇉裦 |
|------|---------|---------|
| `dc_health_checks` | 7天 | 定期清理旧记录 |
| `dc_health_checks` | 7憭?| 摰𡁏<E691B0>皜<EFBFBD><E79A9C><EFBFBD>扯扇敶?|
| `dc_templates` | 瘞訾<E7989E> | <20>见𢆡蝞∠<E89D9E> |
| `dc_extraction_tasks` | 90天 | 归档后删除 |
| `dc_extraction_items` | 90天 | 随任务删除 |
| `dc_extraction_tasks` | 90憭?| 敶埝﹝<E59F9D>𤾸<EFBFBD><F0A4BEB8>?|
| `dc_extraction_items` | 90憭?| <20>譍遙<E8AD8D>∪<EFBFBD><E288AA>?|
### 6.2 敶埝﹝蝑𣇉裦
**大任务归档** (> 1000条记录)：
1. 任务完成后，导出结果到CSV/Excel
**憭找遙<EFBFBD>∪<EFBFBD>獢?* (> 1000<30>∟扇敶?嚗?1. 隞餃𦛚摰峕<E691B0><E5B395>𠬍<EFBFBD>撖澆枂蝏𤘪<E89D8F><F0A498AA>蚓SV/Excel
2. 銝𠹺<E98A9D><F0A0B9BA>訕torage嚗<65>偶銋<E581B6><E98A8B>摮矋<E691AE>
3. 删除数据库记录（释放空间）
3. <20>𣳇膄<F0A3B387>唳旿摨栞扇敶𤏪<E695B6><F0A48FAA>𦠜𦆮蝛粹𡢿嚗?
### 6.3 皜<><E79A9C><EFBFBD>𡁏𧋦嚗<F0A78BA6>內靘页<E99D98>
```typescript
// 清理7天前的健康检查记录
await prisma.dCHealthCheck.deleteMany({
// 皜<><E79A9C>7憭拙<E686AD><E68B99><EFBFBD><EFBFBD>摨瑟<E691A8><E7919F>亥扇敶?await prisma.dCHealthCheck.deleteMany({
where: {
createdAt: {
lt: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000)
@@ -456,8 +391,7 @@ const oldTasks = await prisma.dCExtractionTask.findMany({
include: { items: true }
});
// 导出后删除
for (const task of oldTasks) {
// 撖澆枂<EFBFBD>𤾸<EFBFBD><EFBFBD>?for (const task of oldTasks) {
await exportTaskToStorage(task);
await prisma.dCExtractionTask.delete({ where: { id: task.id } });
}
@@ -465,52 +399,39 @@ for (const task of oldTasks) {
---
## 七、数据安全
## 銝<EFBFBD><EFBFBD><EFBFBD>㺭<EFBFBD>桀<EFBFBD><EFBFBD>?
### 7.1 PII靽脲擪
**敏感字段**：
- `original_text`: 可能包含患者姓名、身份证号
- `result_a/result_b/final_result`: 可能包含结构化的敏感信息
**<EFBFBD>𤩺<EFBFBD>摮埈挾**嚗?- `original_text`: <20>航<EFBFBD><E888AA><EFBFBD>鉄<EFBFBD><E98984><EFBFBD><EFBFBD><EFBFBD><EFBFBD>溻<EFBFBD><E6BABB>澈隞質<E99A9E><E8B3AA>?- `result_a/result_b/final_result`: <20>航<EFBFBD><E888AA><EFBFBD>鉄蝏𤘪<E89D8F><F0A498AA>𣇉<EFBFBD><F0A38789>𤩺<EFBFBD>靽⊥<E99DBD>
**保护措施**：
- ✅ 发送LLM前自动脱敏（PIIMaskUtil）
- ✅ 数据库加密（PostgreSQL SSL）
- ✅ 定期清理历史数据
**靽脲擪<EFBFBD>芣鴌**嚗?- <20>?<3F>煾<EFBFBD><E785BE>LM<4C>滩䌊<E6BBA9>刻<EFBFBD><E588BB>𧶏<EFBFBD>PIIMaskUtil嚗?- <20>?<3F>唳旿摨枏<E691A8>撖<EFBFBD><E69296>PostgreSQL SSL嚗?- <20>?摰𡁏<E691B0>皜<EFBFBD><E79A9C><EFBFBD><EFBFBD>蟮<EFBFBD>唳旿
### 7.2 <20>冽<EFBFBD><E586BD>𠉛氖
**机制**：
- 所有表包含`user_id`字段
**<EFBFBD>箏<EFBFBD>**嚗?- <20><><EFBFBD>㕑”<E39591><E2809D>鉄`user_id`摮埈挾
- 摨𠉛鍂撅<E98D82>撩<EFBFBD>嗉<EFBFBD>皛歹<E79A9B>`WHERE user_id = currentUserId`
- 永不跨用户查询
- 瘞訾<E7989E>頝函鍂<E587BD>瑟䰻霂?
---
## 八、附录
## <EFBFBD>怒<EFBFBD><EFBFBD><EFBFBD>敶?
### 8.1 摰峕㟲Schema DDL
完整的Schema创建脚本位于：
```
摰峕㟲<EFBFBD><EFBFBD>chema<EFBFBD>𥕦遣<EFBFBD>𡁏𧋦雿滢<EFBFBD>嚗?```
backend/prisma/migrations/20251127_add_dc_tool_b_tables/migration.sql
```
### 8.2 Prisma璅∪<E79285>摰帋<E691B0>
完整的Prisma模型定义位于：
```
摰峕㟲<EFBFBD><EFBFBD>risma璅∪<EFBFBD>摰帋<EFBFBD>雿滢<EFBFBD>嚗?```
backend/prisma/schema.prisma
```
搜索 `dc_schema` 查看所有模型。
<EFBFBD>𦦵揣 `dc_schema` <20>亦<EFBFBD><E4BAA6><EFBFBD><EFBFBD>㗇芋<E39787>卝<EFBFBD>?
### 8.3 <20>䀹凒<E480B9><E58792>蟮
| <20><>𧋦 | <20>交<EFBFBD> | <20>䀹凒<E480B9><E58792>捆 |
|------|------|---------|
| V1.0 | 2025-11-27 | 初始版本，4个表 |
| V1.0 | 2025-11-27 | <EFBFBD>嘥<EFBFBD><EFBFBD><EFBFBD>𧋦嚗?銝芾” |
---
**文档结束** ✅
**<EFBFBD><EFBFBD>﹝蝏𤘪<EFBFBD>** <20>?