feat(admin): Add user management and upgrade to module permission system

Features - User Management (Phase 4.1): - Database: Add user_modules table for fine-grained module permissions - Database: Add 4 user permissions (view/create/edit/delete) to role_permissions - Backend: UserService (780 lines) - CRUD with tenant isolation - Backend: UserController + UserRoutes (648 lines) - 13 API endpoints - Backend: Batch import users from Excel - Frontend: UserListPage (412 lines) - list/filter/search/pagination - Frontend: UserFormPage (341 lines) - create/edit with module config - Frontend: UserDetailPage (393 lines) - details/tenant/module management - Frontend: 3 modal components (592 lines) - import/assign/configure - API: GET/POST/PUT/DELETE /api/admin/users/* endpoints Architecture Upgrade - Module Permission System: - Backend: Add getUserModules() method in auth.service - Backend: Login API returns modules array in user object - Frontend: AuthContext adds hasModule() method - Frontend: Navigation filters modules based on user.modules - Frontend: RouteGuard checks requiredModule instead of requiredVersion - Frontend: Remove deprecated version-based permission system - UX: Only show accessible modules in navigation (clean UI) - UX: Smart redirect after login (avoid 403 for regular users) Fixes: - Fix UTF-8 encoding corruption in ~100 docs files - Fix pageSize type conversion in userService (String to Number) - Fix authUser undefined error in TopNavigation - Fix login redirect logic with role-based access check - Update Git commit guidelines v1.2 with UTF-8 safety rules Database Changes: - CREATE TABLE user_modules (user_id, tenant_id, module_code, is_enabled) - ADD UNIQUE CONSTRAINT (user_id, tenant_id, module_code) - INSERT 4 permissions + role assignments - UPDATE PUBLIC tenant with 8 module subscriptions Technical: - Backend: 5 new files (~2400 lines) - Frontend: 10 new files (~2500 lines) - Docs: 1 development record + 2 status updates + 1 guideline update - Total: ~4900 lines of code Status: User management 100% complete, module permission system operational
2026-01-16 13:42:10 +08:00
parent 98d862dbd4
commit 66255368b7
560 changed files with 70424 additions and 52353 deletions
--- a/docs/03-业务模块/DC-数据清洗整理/02-技术设计/API设计文档-DC模块（完整版）.md
+++ b/docs/03-业务模块/DC-数据清洗整理/02-技术设计/API设计文档-DC模块（完整版）.md
@@ -4,7 +4,8 @@
 > **版本**: V2.0 (MVP)  
 > **Base URL**: `/api/v1/dc/tool-b`  
 > **更新日期**: 2025-12-03  
-> **<EFBFBD>嗆<EFBFBD>?*: <EFBFBD>?MVP摰峕<EFBFBD>嚗?銝服PI蝡舐<E89DA1><E88890>券<EFBFBD><E588B8>舐鍂嚗<E98D82>歇撉諹<E69289>嚗?
+> **状态**: ✅ MVP完成（8个API端点全部可用，已验证）
+
 ---

 ## 📋 目录
@@ -12,8 +13,8 @@
 - [一、API概览](#一api概览)
 - [二、认证与鉴权](#二认证与鉴权)
 - [三、API端点详情](#三api端点详情)
- [<EFBFBD>䜘<EFBFBD><EFBFBD>㺭<EFBFBD>格芋<EFBFBD>尜(#<23>𥟇㺭<F0A59F87>格芋<E6A0BC>?
- [鈭𢛵<EFBFBD><EFBFBD><EFBFBD>霂臬<EFBFBD><EFBFBD><EFBFBD>(#鈭娪<EFBFBD>霂臬<EFBFBD><EFBFBD>?
+- [四、数据模型](#四数据模型)
+- [五、错误处理](#五错误处理)
 - [六、性能指标](#六性能指标)

 ---
@@ -22,47 +23,63 @@

 ### 1.1 端点列表

-| # | <EFBFBD>寞<EFBFBD> | 頝臬<E9A09D> | 霂湔<E99C82> | <20>𡒊垢<F0A1928A>嗆<EFBFBD>?| <20>滨垢<E6BBA8>嗆<EFBFBD>?| 瘚贝<E7989A><E8B49D>嗆<EFBFBD>?|
+| # | 方法 | 路径 | 说明 | 后端状态 | 前端状态 | 测试状态 |
 |---|------|------|------|---------|---------|---------|
-| 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> |
+| 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`）

-**<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 通用规范

-**霂瑟<EFBFBD>憭?*嚗?```http
+**请求头**：
+```http
 Content-Type: application/json
 Authorization: Bearer {token}  # 未来实现
 ```

-**<EFBFBD>滚<EFBFBD><EFBFBD>澆<EFBFBD>**嚗?```json
+**响应格式**：
+```json
 {
-  "data": {...},      // <EFBFBD>𣂼<EFBFBD><EFBFBD>嗉<EFBFBD><EFBFBD>?  "error": "...",     // 憭梯揖<E6A2AF>嗉<EFBFBD><E59789>?  "code": 200
+  "data": {...},      // 成功时返回
+  "error": "...",     // 失败时返回
+  "code": 200
 }
 ```

-**HTTP<EFBFBD>嗆<EFBFBD><EFBFBD><EFBFBD>**嚗?- `200`: <20>𣂼<EFBFBD>
+**HTTP状态码**：
+- `200`: 成功
 - `400`: 请求参数错误
- `401`: <20>芾恕霂?- `403`: <20>䭾<EFBFBD><E4ADBE>?- `404`: 韏<><E99F8F>銝滚<E98A9D><E6BB9A>?- `500`: <20>滚𦛚<E6BB9A>典<EFBFBD><E585B8>券<EFBFBD>霂?
+- `401`: 未认证
+- `403`: 无权限
+- `404`: 资源不存在
+- `500`: 服务器内部错误
+
 ---

 ## 二、认证与鉴权

 ### 2.1 认证机制

-**敶枏<EFBFBD><EFBFBD>嗆挾嚗㇈VP嚗?*嚗?- <20>?<3F><><EFBFBD>摰䂿緵霈方<E99C88>
+**当前阶段（MVP）**：
+- ❌ 暂不实现认证
 - 使用临时`userId`标识（从请求上下文获取）

-**<EFBFBD>芣䔉摰䂿緵嚗Ā1.0嚗?*嚗?```http
+**未来实现（V1.0）**：
+```http
 Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
 ```

@@ -70,35 +87,38 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

 | 操作 | 权限要求 | 说明 |
 |------|---------|------|
-| <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>?|
+| 健康检查 | user | 所有用户 |
+| 查看模板 | user | 所有用户 |
+| 创建任务 | user | 所有用户 |
+| 查询任务 | owner | 仅任务创建者 |
+| 裁决冲突 | owner | 仅任务创建者 |

 ---

 ## 三、API端点详情

-### 3.1 <EFBFBD>亙熒璉<EFBFBD><EFBFBD>?
+### 3.1 健康检查
+
 **端点**: `POST /api/v1/dc/tool-b/health-check`

-**<EFBFBD>券<EFBFBD>?*: 璉<><E79289>乍xcel<65>㛖<EFBFBD><E39B96>唳旿韐券<E99F90>嚗峕㜃<E5B395>芯<EFBFBD>韐券<E99F90><E588B8>唳旿
+**用途**: 检查Excel列的数据质量，拦截低质量数据

-**霂瑟<EFBFBD>雿?*嚗?```json
+**请求体**：
+```json
 {
  "fileKey": "uploads/user123/data.xlsx",
  "columnName": "病历文本"
 }
 ```

-**霂瑟<EFBFBD><EFBFBD><EFBFBD>㺭**嚗?
+**请求参数**：
+
 | 字段 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `fileKey` | string | <EFBFBD>?| Storage銝剔<EFBFBD><EFBFBD><EFBFBD>辣頝臬<EFBFBD> |
-| `columnName` | string | <EFBFBD>?| 閬<><E996AC><EFBFBD>亦<EFBFBD><E4BAA6>堒<EFBFBD> |
+| `fileKey` | string | ✅ | Storage中的文件路径 |
+| `columnName` | string | ✅ | 要检查的列名 |

-**<EFBFBD>滚<EFBFBD>**嚗<><E59A97><EFBFBD>?- 200嚗㚁<E59A97>
+**响应**（成功 - 200）：
 ```json
 {
  "status": "good",
@@ -106,11 +126,11 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
  "avgLength": 256.8,
  "totalRows": 500,
  "estimatedTokens": 150000,
-  "message": "<22>亙熒摨西<E691A8>憟踝<E6869F>憸<EFBFBD>恣瘨<E681A3><E798A8>㛖漲 150.0k Token嚗<EFBFBD><EFBFBD>璅∪<EFBFBD>蝥?300.0k Token嚗?
+  "message": "健康度良好，预计消耗约 150.0k Token（双模型约 300.0k Token）"
 }
 ```

-**<EFBFBD>滚<EFBFBD>**嚗<>仃韐?- 200雿<EFBFBD>tatus=bad嚗㚁<EFBFBD>
+**响应**（失败 - 200但status=bad）：
 ```json
 {
  "status": "bad",
@@ -118,26 +138,30 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
  "avgLength": 256.8,
  "totalRows": 500,
  "estimatedTokens": 0,
-  "message": "蝛箏<E89D9B>潛<EFBFBD>餈<EFBFBD><E9A488>嚗?5.0%嚗㚁<E59A97>霂亙<E99C82>銝漤<E98A9D><E6BCA4><EFBFBD><EFBFBD>𣂼<EFBFBD>"
+  "message": "空值率过高（85.0%），该列不适合提取"
 }
 ```

-**<EFBFBD>滚<EFBFBD>摮埈挾**嚗?
+**响应字段**：
+
 | 字段 | 类型 | 说明 |
 |------|------|------|
-| `status` | string | `good` <20>?`bad` |
+| `status` | string | `good` 或 `bad` |
 | `emptyRate` | number | 空值率 (0-1) |
 | `avgLength` | number | 平均文本长度 |
-| `totalRows` | number | <EFBFBD>餉<EFBFBD><EFBFBD>?|
-| `estimatedTokens` | number | 憸<EFBFBD>摯Token<EFBFBD>?|
+| `totalRows` | number | 总行数 |
+| `estimatedTokens` | number | 预估Token数 |
 | `message` | string | 提示信息 |

-**銝𡁜𦛚閫<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
+**业务规则**：
+- 空值率 > 80% → `status = 'bad'`
+- 平均长度 < 10 → `status = 'bad'`
+- 只检查前100行（性能优化）
+
+**错误响应**：
+```json
 {
-  "error": "<22>?<3F><><EFBFBD><EFBFBD><EFBFBD>𧋦'銝滚<E98A9D><E6BB9A>?,
+  "error": "列'病历文本'不存在",
  "code": 400
 }
 ```
@@ -148,10 +172,11 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

 **端点**: `GET /api/v1/dc/tool-b/templates`

-**<EFBFBD>券<EFBFBD>?*: <20>瑕<EFBFBD><E79195><EFBFBD><EFBFBD>厰<EFBFBD>霈曄<E99C88><E69B84>𣂼<EFBFBD>璅⊥踎
+**用途**: 获取所有预设的提取模板

-**霂瑟<EFBFBD>**: <EFBFBD>惩<EFBFBD><EFBFBD>?
-**<2A>滚<EFBFBD>**嚗?00嚗㚁<E59A97>
+**请求**: 无参数
+
+**响应**（200）：
 ```json
 {
  "templates": [
@@ -167,7 +192,7 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
        },
        {
          "name": "分化程度",
-          "desc": "擃?銝?雿𤾸<E99BBF><F0A4BEB8>?,
+          "desc": "高/中/低分化",
          "width": "w-32"
        }
      ]
@@ -175,14 +200,15 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
    {
      "diseaseType": "diabetes",
      "reportType": "admission",
-      "displayName": "蝟硋倏<E7A18B><E5808F><EFBFBD><EFBFBD>Ｚ扇敶?,
+      "displayName": "糖尿病入院记录",
      "fields": [...]
    }
  ]
 }
 ```

-**<EFBFBD>滚<EFBFBD>摮埈挾**嚗?
+**响应字段**：
+
 | 字段 | 类型 | 说明 |
 |------|------|------|
 | `templates` | array | 模板列表 |
@@ -191,7 +217,8 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
 | `templates[].displayName` | string | 显示名称 |
 | `templates[].fields` | array | 提取字段配置 |

-**蝻枏<EFBFBD>蝑𣇉裦**嚗?- 摰Ｘ<E691B0>蝡舐<E89DA1>摮矋<E691AE>1撠𤩺𧒄
+**缓存策略**：
+- 客户端缓存：1小时
 - 服务端缓存：永久（直到重启）

 ---
@@ -200,9 +227,10 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

 **端点**: `POST /api/v1/dc/tool-b/tasks`

-**<EFBFBD>券<EFBFBD>?*: <20>𥕦遣<F0A595A6>寥<EFBFBD><E5AFA5>𣂼<EFBFBD>隞餃𦛚嚗峕綫<E5B395><E7B6AB><EFBFBD>撘<EFBFBD>郊<EFBFBD>笔<EFBFBD>
+**用途**: 创建批量提取任务，推送到异步队列

-**霂瑟<EFBFBD>雿?*嚗?```json
+**请求体**：
+```json
 {
  "projectName": "肺癌病理数据提取-2025Q1",
  "fileKey": "uploads/user123/lung_cancer_pathology.xlsx",
@@ -216,36 +244,41 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
    },
    {
      "name": "分化程度",
-      "desc": "擃?銝?雿𤾸<E99BBF><F0A4BEB8>?
+      "desc": "高/中/低分化"
    }
  ]
 }
 ```

-**霂瑟<EFBFBD><EFBFBD><EFBFBD>㺭**嚗?
+**请求参数**：
+
 | 字段 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `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>滨蔭 |
+| `projectName` | string | ✅ | 任务名称 |
+| `fileKey` | string | ✅ | Storage中的文件路径 |
+| `textColumn` | string | ✅ | 文本列名 |
+| `diseaseType` | string | ✅ | 疾病类型 |
+| `reportType` | string | ✅ | 报告类型 |
+| `targetFields` | array | ✅ | 提取字段配置 |

-**<EFBFBD>滚<EFBFBD>**嚗?00嚗㚁<E59A97>
+**响应**（200）：
 ```json
 {
  "taskId": "550e8400-e29b-41d4-a716-446655440000"
 }
 ```

-**瘚<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>
+**流程**：
+1. 验证文件存在
+2. 解析Excel，统计总行数
+3. 创建任务记录（status=pending）
+4. 推送到BullMQ队列
 5. 立即返回taskId

-**<EFBFBD>躰秤<EFBFBD>滚<EFBFBD>**嚗?```json
+**错误响应**：
+```json
 {
-  "error": "<22><>辣銝滚<E98A9D><E6BB9A>? uploads/user123/lung_cancer_pathology.xlsx",
+  "error": "文件不存在: uploads/user123/lung_cancer_pathology.xlsx",
  "code": 404
 }
 ```
@@ -256,14 +289,14 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

 **端点**: `GET /api/v1/dc/tool-b/tasks/:taskId/progress`

-**<EFBFBD>券<EFBFBD>?*: 摰墧𧒄<E5A2A7>亥砭隞餃𦛚憭<F0A69B9A><E686AD>餈𥕦漲
+**用途**: 实时查询任务处理进度

 **请求**: 
 ```
 GET /api/v1/dc/tool-b/tasks/550e8400-e29b-41d4-a716-446655440000/progress
 ```

-**<EFBFBD>滚<EFBFBD>**嚗?00嚗㚁<E59A97>
+**响应**（200）：
 ```json
 {
  "taskId": "550e8400-e29b-41d4-a716-446655440000",
@@ -281,41 +314,46 @@ GET /api/v1/dc/tool-b/tasks/550e8400-e29b-41d4-a716-446655440000/progress
 }
 ```

-**<EFBFBD>滚<EFBFBD>摮埈挾**嚗?
+**响应字段**：
+
 | 字段 | 类型 | 说明 |
 |------|------|------|
 | `status` | string | `pending/processing/completed/failed` |
-| `progress` | number | 餈𥕦漲<EFBFBD>曉<EFBFBD>瘥?(0-100) |
+| `progress` | number | 进度百分比 (0-100) |
 | `totalCount` | number | 总记录数 |
 | `processedCount` | number | 已处理数 |
 | `cleanCount` | number | 一致记录数 |
-| `conflictCount` | number | <EFBFBD>脩<EFBFBD>霈啣<EFBFBD><EFBFBD>?|
-| `failedCount` | number | 憭梯揖霈啣<EFBFBD><EFBFBD>?|
-| `totalTokens` | number | 蝝航恣Token<EFBFBD>?|
+| `conflictCount` | number | 冲突记录数 |
+| `failedCount` | number | 失败记录数 |
+| `totalTokens` | number | 累计Token数 |
 | `totalCost` | number | 累计成本($) |

-**頧株砭撱箄悅**嚗?- 摰Ｘ<E691B0>蝡舀<E89DA1>3蝘坿蔭霂Ｖ<E99C82>甈?- 敶𨦨status = 'completed'`<EFBFBD>嗅<EFBFBD>甇Ｚ蔭霂?
+**轮询建议**：
+- 客户端每3秒轮询一次
+- 当`status = 'completed'`时停止轮询
+
 ---

 ### 3.5 获取验证网格数据

 **端点**: `GET /api/v1/dc/tool-b/tasks/:taskId/items`

-**<EFBFBD>券<EFBFBD>?*: <20>瑕<EFBFBD><E79195>峕芋<E5B395>𧢲<EFBFBD><F0A7A2B2>𣇉<EFBFBD><F0A38789>頣<EFBFBD><E9A0A3>其<EFBFBD>鈭箏極鋆<E6A5B5><E98B86>
+**用途**: 获取双模型提取结果，用于人工裁决

 **请求**: 
 ```
 GET /api/v1/dc/tool-b/tasks/550e8400.../items?page=1&limit=50&status=conflict
 ```

-**<EFBFBD>亥砭<EFBFBD><EFBFBD>㺭**嚗?
-| <20><>㺭 | 蝐餃<E89D90> | 敹<>‵ | 暺䁅恕<E48185>?| 霂湔<E99C82> |
-|------|------|------|--------|------|
-| `page` | number | <20>?| 1 | 憿萇<E686BF> |
-| `limit` | number | <20>?| 50 | 瘥誯△<E8AAAF>圈<EFBFBD> |
-| `status` | string | <20>?| - | 餈<>誘<EFBFBD>嗆<EFBFBD>?|
+**查询参数**：

-**<EFBFBD>滚<EFBFBD>**嚗?00嚗㚁<E59A97>
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `page` | number | ❌ | 1 | 页码 |
+| `limit` | number | ❌ | 50 | 每页数量 |
+| `status` | string | ❌ | - | 过滤状态 |
+
+**响应**（200）：
 ```json
 {
  "items": [
@@ -324,13 +362,13 @@ GET /api/v1/dc/tool-b/tasks/550e8400.../items?page=1&limit=50&status=conflict
      "rowIndex": 5,
      "originalText": "患者，男，45岁，诊断为浸润性腺癌，中分化，肿瘤最大径3cm...",
      "resultA": {
-        "<EFBFBD><EFBFBD><EFBFBD>蝐餃<EFBFBD>": "瘚豢隋<EFBFBD>扯<EFBFBD><EFBFBD>?,
-        "<EFBFBD><EFBFBD><EFBFBD>蝔见漲": "銝剖<EFBFBD><EFBFBD>?,
+        "病理类型": "浸润性腺癌",
+        "分化程度": "中分化",
        "肿瘤大小": "3cm"
      },
      "resultB": {
-        "<EFBFBD><EFBFBD><EFBFBD>蝐餃<EFBFBD>": "瘚豢隋<EFBFBD>扯<EFBFBD><EFBFBD>?,
-        "<EFBFBD><EFBFBD><EFBFBD>蝔见漲": "銝剖<EFBFBD><EFBFBD>?,
+        "病理类型": "浸润性腺癌",
+        "分化程度": "中分化",
        "肿瘤大小": "3.0cm"
      },
      "status": "conflict",
@@ -347,7 +385,8 @@ GET /api/v1/dc/tool-b/tasks/550e8400.../items?page=1&limit=50&status=conflict
 }
 ```

-**<EFBFBD>滚<EFBFBD>摮埈挾**嚗?
+**响应字段**：
+
 | 字段 | 类型 | 说明 |
 |------|------|------|
 | `items` | array | 记录列表 |
@@ -361,7 +400,8 @@ GET /api/v1/dc/tool-b/tasks/550e8400.../items?page=1&limit=50&status=conflict

 **端点**: `POST /api/v1/dc/tool-b/items/:itemId/resolve`

-**<EFBFBD>券<EFBFBD>?*: 鈭箏極<E7AE8F>㗇𥋘甇<F0A58B98>＆<EFBFBD><EFBC86><EFBFBD><EFBFBD>𣇉<EFBFBD><F0A38789>?
+**用途**: 人工选择正确的提取结果
+
 **请求**: 
 ```json
 {
@@ -370,20 +410,22 @@ GET /api/v1/dc/tool-b/tasks/550e8400.../items?page=1&limit=50&status=conflict
 }
 ```

-**霂瑟<EFBFBD><EFBFBD><EFBFBD>㺭**嚗?
+**请求参数**：
+
 | 字段 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `field` | string | <EFBFBD>?| <20>脩<EFBFBD>摮埈挾<E59F88>?|
-| `chosenValue` | string | <EFBFBD>?| <20>㗇𥋘<E39787><F0A58B98><EFBFBD>?|
+| `field` | string | ✅ | 冲突字段名 |
+| `chosenValue` | string | ✅ | 选择的值 |

-**<EFBFBD>滚<EFBFBD>**嚗?00嚗㚁<E59A97>
+**响应**（200）：
 ```json
 {
  "success": true
 }
 ```

-**銝𡁜𦛚<EFBFBD>餉<EFBFBD>**嚗?1. <20>湔鰵`finalResult[field] = chosenValue`
+**业务逻辑**：
+1. 更新`finalResult[field] = chosenValue`
 2. 从`conflictFields`中移除该字段
 3. 如果所有冲突解决，更新`status = 'resolved'`

@@ -393,27 +435,33 @@ GET /api/v1/dc/tool-b/tasks/550e8400.../items?page=1&limit=50&status=conflict

 **端点**: `GET /api/v1/dc/tool-b/tasks/:taskId/export`

-**<EFBFBD>券<EFBFBD>?*: 撖澆枂<E6BE86><E69E82>蝏<EFBFBD><E89D8F><EFBFBD>𣇉<EFBFBD><F0A38789>靝蛹Excel
+**用途**: 导出最终提取结果为Excel

 **请求**: 
 ```
 GET /api/v1/dc/tool-b/tasks/550e8400.../export?format=xlsx
 ```

-**<EFBFBD>亥砭<EFBFBD><EFBFBD>㺭**嚗?
-| <20><>㺭 | 蝐餃<E89D90> | 敹<>‵ | 暺䁅恕<E48185>?| 霂湔<E99C82> |
-|------|------|------|--------|------|
-| `format` | string | <20>?| `xlsx` | 撖澆枂<E6BE86>澆<EFBFBD>嚗䫤xlsx/csv` |
+**查询参数**：

-**<2A>滚<EFBFBD>**嚗?00嚗㚁<E59A97>
- <20><>辣瘚<E8BEA3><E7989A>頧?- Content-Type: `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `format` | string | ❌ | `xlsx` | 导出格式：`xlsx/csv` |
+
+**响应**（200）：
+- 文件流下载
+- Content-Type: `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`
 - Content-Disposition: `attachment; filename="extraction_result_2025-11-27.xlsx"`

-**撖澆枂<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>嚗?
+**导出内容**：
+- 包含原始列 + 所有提取字段
+- 只包含`clean`和`resolved`状态的记录
+- 冲突记录不导出（需人工裁决）
+
 ---

-## <EFBFBD>䜘<EFBFBD><EFBFBD>㺭<EFBFBD>格芋<EFBFBD>?
+## 四、数据模型
+
 ### 4.1 HealthCheckResult

 ```typescript
@@ -498,7 +546,8 @@ interface ExtractionItem {

 ---

-## 鈭𢛵<EFBFBD><EFBFBD><EFBFBD>霂臬<EFBFBD><EFBFBD>?
+## 五、错误处理
+
 ### 5.1 错误响应格式

 ```json
@@ -507,24 +556,27 @@ interface ExtractionItem {
  "code": 400,
  "details": {
    "field": "fileKey",
-    "reason": "<22><>辣銝滚<E98A9D><E6BB9A>?
+    "reason": "文件不存在"
  }
 }
 ```

-### 5.2 撣貉<EFBFBD><EFBFBD>躰秤<EFBFBD>?
-| HTTP<54>嗆<EFBFBD>?| code | 霂湔<E99C82> | 蝷箔<E89DB7> |
+### 5.2 常见错误码
+
+| HTTP状态 | code | 说明 | 示例 |
 |----------|------|------|------|
 | 400 | `INVALID_PARAMS` | 参数错误 | 缺少fileKey |
-| 400 | `COLUMN_NOT_FOUND` | <EFBFBD>𦯀<EFBFBD>摮睃銁 | <20>?<3F><><EFBFBD><EFBFBD><EFBFBD>𧋦"銝滚<E98A9D><E6BB9A>?|
+| 400 | `COLUMN_NOT_FOUND` | 列不存在 | 列"病历文本"不存在 |
 | 400 | `BAD_HEALTH` | 健康检查未通过 | 空值率过高 |
-| 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>亙仃韐?|
+| 404 | `FILE_NOT_FOUND` | 文件不存在 | 文件路径无效 |
+| 404 | `TASK_NOT_FOUND` | 任务不存在 | taskId无效 |
+| 403 | `FORBIDDEN` | 无权访问 | 只能访问自己的任务 |
+| 500 | `INTERNAL_ERROR` | 服务器错误 | 数据库连接失败 |

-### 5.3 <EFBFBD>躰秤憭<EFBFBD><EFBFBD><EFBFBD><EFBFBD>雿喳<EFBFBD>頝?
-**摰Ｘ<E691B0>蝡?*嚗?```typescript
+### 5.3 错误处理最佳实践
+
+**客户端**：
+```typescript
 try {
  const response = await fetch('/api/v1/dc/tool-b/health-check', {
    method: 'POST',
@@ -543,8 +595,9 @@ try {
    return;
  }
  
-  // 蝏抒賒銝衤<EFBFBD>甇?} catch (error) {
-  console.error('<27>亙熒璉<E78692><E79289>亙仃韐?', error);
+  // 继续下一步
+} catch (error) {
+  console.error('健康检查失败:', error);
 }
 ```

@@ -556,41 +609,54 @@ try {

 | API | 目标 | 说明 |
 |-----|------|------|
-| `/health-check` | < 3蝘?| Excel閫<EFBFBD><EFBFBD>+蝏蠘恣 |
+| `/health-check` | < 3秒 | Excel解析+统计 |
 | `/templates` | < 100ms | 内存缓存 |
 | `/tasks` (create) | < 500ms | 快速创建并返回 |
 | `/tasks/:id/progress` | < 100ms | 数据库单查询 |
 | `/tasks/:id/items` | < 500ms | 分页查询 |
 | `/items/:id/resolve` | < 200ms | 单行更新 |
-| `/tasks/:id/export` | < 10蝘?| <20><><EFBFBD>Excel<EFBFBD><EFBFBD>辣 |
+| `/tasks/:id/export` | < 10秒 | 生成Excel文件 |

 ### 6.2 并发处理能力

- **<2A>亙熒璉<E78692><E79289>?*: 10 req/s嚗㇆O撖<4F><E69296>嚗?- **隞餃𦛚<E9A483>𥕦遣**: 5 req/s嚗<73><E59A97><EFBFBD>交㺭<E4BAA4>桀<EFBFBD>嚗?- **餈𥕦漲<F0A595A6>亥砭**: 100 req/s嚗<EFBFBD>粉撖<EFBFBD><EFBFBD>嚗<EFBFBD>虾蝻枏<EFBFBD>嚗?- **撉諹<E69289>蝵烐聢**: 50 req/s嚗<73><E59A97>憿菜䰻霂ｇ<E99C82>
+- **健康检查**: 10 req/s（IO密集）
+- **任务创建**: 5 req/s（写入数据库）
+- **进度查询**: 100 req/s（读密集，可缓存）
+- **验证网格**: 50 req/s（分页查询）

 ### 6.3 优化策略

-**蝻枏<EFBFBD>**嚗?- `/templates` <20>?瘞訾<E7989E>蝻枏<E89DBB>嚗<EFBFBD><E59A97>摮矋<E691AE>
- `/tasks/:id/progress` <20>?Redis蝻枏<E89DBB>嚗?蝘塬TL嚗?
-**撘<>郊憭<E9838A><E686AD>**嚗?- 隞餃𦛚憭<F0A69B9A><E686AD>雿輻鍂BullMQ<4D>𤾸蝱<F0A4BEB8>笔<EFBFBD>
+**缓存**：
+- `/templates` → 永久缓存（内存）
+- `/tasks/:id/progress` → Redis缓存（5秒TTL）
+
+**异步处理**：
+- 任务处理使用BullMQ后台队列
 - 避免阻塞用户请求

-**<EFBFBD><EFBFBD>△**嚗?- 撉諹<E69289>蝵烐聢暺䁅恕50<35>?憿?- <20><>憭?000<30>?憿?
+**分页**：
+- 验证网格默认50条/页
+- 最大1000条/页
+
 ---

-## 銝<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>祆綉<EFBFBD>?
+## 七、版本控制
+
 ### 7.1 API版本策略

 **当前版本**: `v1`

 **URL格式**: `/api/v1/dc/tool-b/*`

-**<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
+**向后兼容承诺**：
+- v1版本在2026年前保持稳定
+- 新功能通过可选参数添加
+- 破坏性变更发布v2

 ### 7.2 废弃通知

-敶𨯗PI<EFBFBD><EFBFBD>閬<EFBFBD><EFBFBD>撘<EFBFBD>𧒄嚗?```http
+当API需要废弃时：
+```http
 HTTP/1.1 200 OK
 X-API-Deprecated: true
 X-API-Sunset: 2026-12-31
@@ -599,16 +665,19 @@ X-API-Replacement: /api/v2/dc/tool-b/health-check

 ---

-## <EFBFBD>怒<EFBFBD><EFBFBD><EFBFBD>霂?
+## 八、测试
+
 ### 8.1 Postman Collection

-摰峕㟲<EFBFBD><EFBFBD>PI瘚贝<EFBFBD><EFBFBD><EFBFBD><EFBFBD>嚗?```
-docs/03-銝𡁜𦛚璅∪<E79285>/DC-<2D>唳旿皜<E697BF><E79A9C><EFBFBD>渡<EFBFBD>/02-<2D><><EFBFBD>航挽霈?ToolB-API.postman_collection.json
+完整的API测试集合：
+```
+docs/03-业务模块/DC-数据清洗整理/02-技术设计/ToolB-API.postman_collection.json
 ```

 ### 8.2 示例请求

-**<EFBFBD>亙熒璉<EFBFBD><EFBFBD>?*嚗?```bash
+**健康检查**：
+```bash
 curl -X POST http://localhost:3001/api/v1/dc/tool-b/health-check \
  -H "Content-Type: application/json" \
  -d '{
@@ -617,11 +686,13 @@ curl -X POST http://localhost:3001/api/v1/dc/tool-b/health-check \
  }'
 ```

-**<EFBFBD>瑕<EFBFBD>璅⊥踎**嚗?```bash
+**获取模板**：
+```bash
 curl http://localhost:3001/api/v1/dc/tool-b/templates
 ```

-**<EFBFBD>𥕦遣隞餃𦛚**嚗?```bash
+**创建任务**：
+```bash
 curl -X POST http://localhost:3001/api/v1/dc/tool-b/tasks \
  -H "Content-Type: application/json" \
  -d '{
@@ -636,19 +707,21 @@ curl -X POST http://localhost:3001/api/v1/dc/tool-b/tasks \

 ---

-## 銋腈<EFBFBD><EFBFBD><EFBFBD>敶?
+## 九、附录
+
 ### 9.1 相关文档

- [<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)
+- [数据库设计文档](./数据库设计文档-工具B.md)
+- [PRD文档](../01-需求分析/PRD：Tool B - 病历结构化机器人 (The AI Structurer).md)
+- [开发计划](../04-开发计划/工具B开发计划-病历结构化机器人.md)

 ### 9.2 变更日志

 | 版本 | 日期 | 变更内容 |
 |------|------|---------|
-| V1.0 | 2025-11-27 | <EFBFBD>嘥<EFBFBD><EFBFBD><EFBFBD>𧋦嚗?銝服PI蝡舐<E89DA1> |
+| V1.0 | 2025-11-27 | 初始版本，7个API端点 |

 ---

-**<EFBFBD><EFBFBD>﹝蝏𤘪<EFBFBD>** <20>?
+**文档结束** ✅
+