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

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

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

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

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

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

View File

@@ -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 倾向于全量加载内存,容易 OOMNode.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())