AIclinicalresearch/docs/03-业务模块/DC-数据清洗整理/04-开发计划/DC模块Tool-B开发计划.md

DC模块 Tool-B 开发计划

文档版本： V2.0 (MVP完成)
创建日期： 2025-12-02
完成日期： 2025-12-03
实际周期： 2个工作日
状态： ✅ MVP完成

---

🎉 MVP完成通告（2025-12-03）

Tool B病历结构化机器人MVP版本已完成！

• ✅ 前端5步工作流完整实现（~1400行）
• ✅ 8个API端点全部对接并测试通过
• ✅ LLM双模型提取验证成功（DeepSeek-V3 + Qwen-Max）
• ✅ 真实数据测试：9条病理报告提取成功
• ✅ Excel导出功能可用
• ⚠️ 4个技术债务待处理（见07-技术债务/Tool-B技术债务清单.md）

完成详情： 参见 06-开发记录/Tool-B-MVP完成总结-2025-12-03.md

---

原始开发计划

目标： 完成Tool-B（病历结构化机器人）的前端开发和完整功能集成

---

📋 一、项目当前状态调研总结

1.1 后端代码状态 ✅ 100%完成

通用能力平台（可复用）

基于 backend/src/common/ 平台基础设施，已完整实现：

能力模块	导入路径	功能说明	状态
存储服务	@/common/storage	文件上传/下载（Local ↔ OSS）	✅ 完成
日志系统	@/common/logging	结构化日志（Winston）	✅ 完成
缓存服务	@/common/cache	缓存（Memory ↔ Redis）	✅ 完成
异步任务	@/common/jobs	长时间任务队列	✅ 完成
LLM工厂	@/common/llm/adapters/LLMFactory	统一LLM调用（DeepSeek/Qwen/GPT/Claude）	✅ 完成
数据库	@/config/database	Prisma连接池	✅ 完成

复用策略：

• ✅ Tool B后端代码已100%复用平台能力
• ✅ 前端开发应参考后端模式，复用前端共享组件

---

Tool B后端实现状态

代码位置：backend/src/modules/dc/tool-b/

文件	功能	代码量	状态	复用能力
services/HealthCheckService.ts	Excel健康检查	~190行	✅ 完成	storage, logger, cache, prisma
services/TemplateService.ts	预设模板管理	~243行	✅ 完成	logger, prisma
services/DualModelExtractionService.ts	双模型提取	~390行	✅ 完成	LLMFactory, logger, prisma
services/ConflictDetectionService.ts	冲突检测算法	~215行	✅ 完成	logger
controllers/ExtractionController.ts	API控制器	~388行	✅ 完成	全部服务
routes/index.ts	路由配置	~115行	✅ 完成	-
index.ts	模块入口	~117行	✅ 完成	-

总计：约1,658行，7个文件，100%完成

---

API端点清单

Base URL: /api/v1/dc/tool-b

方法	路径	功能	请求体	响应	状态
POST	/health-check	Excel列健康检查	{fileKey, columnName}	健康度报告	✅ 完成
GET	/templates	获取预设模板列表	-	模板数组	✅ 完成
POST	/tasks	创建提取任务	{projectName, fileKey, textColumn, diseaseType, reportType}	{taskId}	✅ 完成
GET	/tasks/:taskId/progress	查询任务进度	-	进度详情	✅ 完成
GET	/tasks/:taskId/items	获取验证网格数据	?status=conflict&page=1	分页数据	✅ 完成
POST	/items/:itemId/resolve	裁决冲突	{resolvedData}	成功状态	✅ 完成

预设模板（3个）：

1. 肺癌病理报告（lung_cancer/pathology）- 5个字段
2. 糖尿病入院记录（diabetes/admission）- 5个字段
3. 高血压门诊病历（hypertension/outpatient）- 5个字段

---

1.2 数据库状态 ✅ 已验证完成（2025-12-02）

Schema: dc_schema（独立隔离）

表名	用途	字段数	关键字段	状态	数据量
dc_health_checks	健康检查记录	10	status, emptyRate, avgLength	✅ 已创建	2条
dc_templates	预设模板	7	diseaseType, reportType, fields	✅ 已创建	3条
dc_extraction_tasks	提取任务	21	status, totalCount, processedCount	✅ 已创建	1条
dc_extraction_items	提取明细	15	resultA, resultB, conflictFields	✅ 已创建	4条

✅ 验证结果（2025-12-02）：

• ✅ dc_schema已存在
• ✅ 4个表全部创建成功
• ✅ 3个预设模板已初始化：
  1. 肺癌病理报告 (lung_cancer/pathology)
  2. 糖尿病入院记录 (diabetes/admission)
  3. 高血压门诊病历 (hypertension/outpatient)
• ✅ 有测试数据可用于开发调试

验证脚本：

cd backend
node scripts/check-dc-tables.mjs  # 执行数据库表检查脚本

结论：✅ 数据库完全准备就绪，可以开始前端开发！

---

1.3 前端代码状态 ❌ 0%（仅Placeholder）

代码位置：frontend-v2/src/modules/dc/

frontend-v2/src/modules/dc/
├── index.tsx           # ❌ 仅Placeholder（14行）
├── components/         # 📁 空
├── pages/              # 📁 空文件夹结构
│   ├── tool-a/         # 📁 空
│   ├── tool-b/         # 📁 空
│   └── tool-c/         # 📁 空
└── types/              # 📁 空

当前内容：

// frontend-v2/src/modules/dc/index.tsx
import Placeholder from '@/shared/components/Placeholder'

const DCModule = () => {
  return (
    <Placeholder 
      title="数据清洗模块"
      description="功能规划中，将提供智能数据清洗和整理工具"
      moduleName="DC - Data Cleaning"
    />
  )
}
export default DCModule

---

1.4 前端架构设计 ✅ 已明确

系统级架构

• 导航模式：顶部导航
• 路由路径：/data-cleaning
• 技术栈：React 19 + TypeScript + Vite + Ant Design 5

DC模块架构方案

选择：方案A - 独立Portal页面（推荐）

/data-cleaning (Portal工作台 - 总览页)
    ├── 快速启动区（3个工具卡片）
    │   ├── [超级合并器] → /data-cleaning/tool-a
    │   ├── [病历结构化] → /data-cleaning/tool-b
    │   └── [数据编辑器] → /data-cleaning/tool-c
    ├── 最近任务列表（实时进度）
    └── 数据资产库（文件管理）

/data-cleaning/tool-b (Tool B - 全屏5步流程)
    ├── Step 1: 上传与健康检查
    ├── Step 2: 智能模板配置
    ├── Step 3: 双盲提取进度
    ├── Step 4: 冲突验证网格 ⭐ 核心
    └── Step 5: 结果导出

参考模块：

• ASL模块（frontend-v2/src/modules/asl/）
  • 有完整的布局、页面、组件结构
  • 使用React Router嵌套路由
  • 左侧导航 + 右侧内容区

---

🎯 二、开发计划总览

2.1 开发阶段划分

阶段	任务	预计工时	优先级	目标
Phase 1	Portal工作台页面	4-6h	P0	DC模块入口
Phase 2	Tool B - Step 1&2	6h	P0	上传+配置
Phase 3	Tool B - Step 3	3h	P0	进度监控
Phase 4	Tool B - Step 4	9h	P0	冲突验证网格⭐
Phase 5	Tool B - Step 5	3h	P0	结果导出
Phase 6	集成测试	4h	P1	端到端验证

总计：约29-31小时（4-5个工作日）

---

2.2 里程碑时间表

里程碑	完成标志	预计完成
M1: Portal上线	用户可访问DC模块入口	Day 1
M2: Tool B可用	Step1-5全部完成	Day 4
M3: 集成测试通过	端到端流程测试通过	Day 5
M4: 文档完善	开发文档和用户文档	Day 6

---

📐 三、Phase 1: Portal工作台开发（Day 1）

3.1 目标

创建DC模块的入口页面，适配系统顶部导航，提供工具启动、任务监控和文件管理功能。

3.2 设计参考

• 原型文件：docs/03-业务模块/DC-数据清洗整理/03-UI设计/智能数据清洗工作台V2.html
• PRD文档：docs/03-业务模块/DC-数据清洗整理/01-需求分析/PRD：智能数据清洗工作台 (The Data Cleaning Portal).md

3.3 功能清单

3.3.1 快速启动区（3个工具卡片）

组件：components/ToolCard.tsx

interface ToolCardProps {
  id: 'tool-a' | 'tool-b' | 'tool-c';
  title: string;
  description: string;
  icon: ReactNode;
  color: 'blue' | 'purple' | 'emerald';
  status: 'ready' | 'disabled';
  onClick: () => void;
}

卡片内容：

1. Tool A - 超级合并器

   • 图标：FileSpreadsheet（蓝色）
   • 描述："解决多源数据时间轴对齐难题"
   • 状态：disabled（暂未开发）

2. Tool B - 病历结构化机器人 ⭐ 本次开发

   • 图标：Bot（紫色）
   • 描述："利用大模型提取非结构化文本"
   • 状态：ready
   • 点击跳转：/data-cleaning/tool-b

3. Tool C - 科研数据编辑器

   • 图标：Table2（绿色）
   • 描述："Excel风格的在线清洗工具"
   • 状态：disabled（暂未开发）

---

3.3.2 最近任务列表

组件：components/TaskList.tsx

API：GET /api/v1/dc/tasks/recent（需后端新增）

数据结构：

interface Task {
  id: string;
  name: string;
  tool: 'tool-a' | 'tool-b' | 'tool-c';
  status: 'pending' | 'processing' | 'completed' | 'failed';
  progress: number; // 0-100
  createdAt: string;
  completedAt?: string;
}

功能：

• 显示最近10条任务
• 实时轮询进度（processing状态时，每5秒轮询）
• 智能流转按钮：
  • Tool A完成 → [下载] + [去AI提取]（跳Tool B）
  • Tool B完成 → [下载] + [去清洗]（跳Tool C）
  • Tool C完成 → [下载]

---

3.3.3 数据资产库

组件：components/AssetLibrary.tsx

API：GET /api/v1/dc/assets（需后端新增）

Tab分类：

• 全部：所有文件
• 处理结果：工具A/B/C生成的文件（绿色/蓝色图标）
• 原始上传：用户直接上传的底表（灰色图标）

功能：

• 文件卡片显示（文件名、行数、标签、修改时间）
• 快捷操作：[下载] [去处理] [分析]
• 底部固定按钮：[+ 上传原始文件到库]

---

3.4 技术实现

3.4.1 目录结构

frontend-v2/src/modules/dc/
├── pages/
│   └── Portal.tsx                 # ⭐ Portal主页面
├── components/
│   ├── ToolCard.tsx               # 工具卡片
│   ├── TaskList.tsx               # 任务列表
│   └── AssetLibrary.tsx           # 数据资产库
├── hooks/
│   ├── useRecentTasks.ts          # 任务列表Hook
│   └── useAssets.ts               # 资产列表Hook
├── services/
│   └── portalApi.ts               # Portal API封装
└── types/
    └── portal.ts                  # Portal类型定义

---

3.4.2 路由配置

// frontend-v2/src/modules/dc/index.tsx
import { Routes, Route } from 'react-router-dom';
import Portal from './pages/Portal';
import ToolBModule from './pages/tool-b';

const DCModule = () => {
  return (
    <Routes>
      <Route path="" element={<Portal />} />
      <Route path="tool-b/*" element={<ToolBModule />} />
      {/* 未来扩展 */}
      <Route path="tool-a/*" element={<ToolAPlaceholder />} />
      <Route path="tool-c/*" element={<ToolCPlaceholder />} />
    </Routes>
  );
};

export default DCModule;

---

3.4.3 API对接

需要后端新增的API：

// GET /api/v1/dc/tasks/recent
interface GetRecentTasksResponse {
  tasks: Task[];
}

// GET /api/v1/dc/assets
interface GetAssetsResponse {
  assets: Asset[];
}

临时方案（后端API未开发时）：

• 使用Mock数据
• 后续替换为真实API

---

3.5 验收标准

• Portal页面可访问（http://localhost:3000/data-cleaning）
• 3个工具卡片正确显示
• Tool B卡片可点击跳转（其他两个显示disabled）
• 任务列表显示Mock数据
• 数据资产库Tab切换正常
• 整体样式符合系统设计规范

---

🛠️ 四、Phase 2: Tool B - Step 1&2（Day 2）

4.1 Step 1: 文件上传与健康检查（3小时）

4.1.1 页面设计

组件：pages/tool-b/Step1Upload.tsx

UI参考：原型V4第260-310行

布局：

1. 文件信息卡片（显示已上传文件）
2. 列选择下拉框
3. 健康检查结果卡片（动态显示）

---

4.1.2 功能实现

1. Excel文件上传

// 使用Ant Design Upload组件
import { Upload } from 'antd';

// 上传到Storage
const handleUpload = async (file: File) => {
  const formData = new FormData();
  formData.append('file', file);
  
  const response = await fetch('/api/v1/storage/upload', {
    method: 'POST',
    body: formData
  });
  
  const { fileKey } = await response.json();
  setFileKey(fileKey); // 保存fileKey用于后续步骤
};

2. 列选择与健康检查

const [columns, setColumns] = useState<string[]>([]);
const [selectedColumn, setSelectedColumn] = useState('');
const [healthResult, setHealthResult] = useState<HealthCheckResult | null>(null);

// 自动检测列名（可选：从后端获取）
useEffect(() => {
  if (fileKey) {
    // TODO: 调用API获取Excel列名
    // 或前端解析Excel（使用xlsx库）
  }
}, [fileKey]);

// 健康检查
const handleHealthCheck = async (columnName: string) => {
  setIsChecking(true);
  try {
    const response = await fetch('/api/v1/dc/tool-b/health-check', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ fileKey, columnName })
    });
    
    const result = await response.json();
    setHealthResult(result.data);
  } finally {
    setIsChecking(false);
  }
};

3. 健康度显示

// 根据status显示不同样式
{healthResult?.status === 'good' && (
  <Alert
    type="success"
    icon={<CheckCircle2 />}
    message="健康度优秀，适合提取"
    description={
      <div className="mt-2">
        <span>平均字符: {healthResult.avgLength}</span>
        <span className="ml-4">空值率: {(healthResult.emptyRate * 100).toFixed(1)}%</span>
        <span className="ml-4 text-purple-600 font-bold">
          预计Token: {healthResult.estimatedTokens.toLocaleString()}
        </span>
      </div>
    }
  />
)}

{healthResult?.status === 'bad' && (
  <Alert
    type="error"
    icon={<AlertTriangle />}
    message="警告：该列不适合AI处理"
    description={healthResult.message}
  />
)}

---

4.2 Step 2: 智能模板配置（3小时）

4.2.1 页面设计

组件：pages/tool-b/Step2Schema.tsx

UI参考：原型V4第313-372行

布局：

1. 疾病类型与报告类型选择（级联）
2. 字段列表（左侧，可编辑）
3. Prompt预览（右侧，代码高亮）

---

4.2.2 功能实现

1. 获取模板列表

const [templates, setTemplates] = useState<Template[]>([]);
const [diseaseType, setDiseaseType] = useState('');
const [reportType, setReportType] = useState('');
const [fields, setFields] = useState<Field[]>([]);

useEffect(() => {
  // 获取所有模板
  fetch('/api/v1/dc/tool-b/templates')
    .then(res => res.json())
    .then(data => setTemplates(data.data.templates));
}, []);

// 当选择疾病类型和报告类型时，自动加载字段
useEffect(() => {
  if (diseaseType && reportType) {
    const template = templates.find(
      t => t.diseaseType === diseaseType && t.reportType === reportType
    );
    if (template) {
      setFields(template.fields);
    }
  }
}, [diseaseType, reportType, templates]);

2. 字段编辑

// 添加字段
const handleAddField = () => {
  setFields([...fields, {
    id: `custom_${Date.now()}`,
    name: '新字段',
    desc: '字段描述',
    width: 'w-32'
  }]);
};

// 删除字段
const handleDeleteField = (id: string) => {
  setFields(fields.filter(f => f.id !== id));
};

// 编辑字段
const handleEditField = (id: string, key: 'name' | 'desc', value: string) => {
  setFields(fields.map(f => 
    f.id === id ? { ...f, [key]: value } : f
  ));
};

3. Prompt预览

// 动态生成Prompt预览
const generatePrompt = () => {
  return `You are an expert in ${diseaseType.replace('_', ' ')} pathology.
Extract fields in JSON format:

{
${fields.map(f => `  "${f.name}": "string", // ${f.desc}`).join('\n')}
}

Original text:
{originalText}

Output JSON only.`;
};

// 使用代码高亮库（如react-syntax-highlighter）
<SyntaxHighlighter language="javascript" style={atomOneDark}>
  {generatePrompt()}
</SyntaxHighlighter>

---

4.3 验收标准

Step 1:

• Excel上传成功，获取fileKey
• 列名列表正确显示
• 健康检查API调用成功
• 健康度卡片根据结果正确显示（绿色/红色）
• Token预估数值正确
• 空值率>50%时禁止进入下一步

Step 2:

• 模板列表加载成功
• 疾病类型和报告类型选择框正常
• 选择模板后字段自动加载
• 字段支持添加/删除/编辑
• Prompt预览实时更新
• 代码高亮正确显示

---

⚙️ 五、Phase 3: Tool B - Step 3（Day 3上午）

5.1 处理进度监控（3小时）

5.1.1 页面设计

组件：pages/tool-b/Step3Processing.tsx

UI参考：原型V4第375-400行

布局：

1. 圆形进度环（双模型动画）
2. 进度百分比和文本
3. 日志滚动区域

---

5.1.2 功能实现

1. 创建任务

const handleStartExtraction = async () => {
  const response = await fetch('/api/v1/dc/tool-b/tasks', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      projectName: 'Test Project',
      sourceFileKey: fileKey,
      textColumn: selectedColumn,
      diseaseType,
      reportType,
      modelA: 'deepseek-v3',
      modelB: 'qwen-max'
    })
  });
  
  const { taskId } = await response.json();
  setTaskId(taskId);
  
  // 开始轮询
  startPolling(taskId);
};

2. 进度轮询

const startPolling = (taskId: string) => {
  const interval = setInterval(async () => {
    const response = await fetch(`/api/v1/dc/tool-b/tasks/${taskId}/progress`);
    const data = await response.json();
    
    setProgress(data.progress); // 百分比
    setLogs(prevLogs => [...prevLogs, data.latestLog]); // 新增日志
    
    if (data.status === 'completed') {
      clearInterval(interval);
      // 跳转到Step 4
      setTimeout(() => navigate(`/data-cleaning/tool-b/verify/${taskId}`), 800);
    } else if (data.status === 'failed') {
      clearInterval(interval);
      message.error('提取任务失败');
    }
  }, 5000); // 每5秒轮询
  
  return () => clearInterval(interval);
};

3. 进度动画

// 使用Ant Design Progress组件或自定义SVG
<Progress
  type="circle"
  percent={progress}
  format={percent => (
    <div>
      <div className="text-2xl font-bold">{percent}%</div>
      <div className="text-sm text-gray-500">双盲提取中</div>
    </div>
  )}
  strokeColor={{
    '0%': '#9333ea',
    '100%': '#4f46e5'
  }}
/>

// 双模型动画（两个小球跳动）
<div className="flex gap-2">
  <div className="w-3 h-3 bg-blue-500 rounded-full animate-bounce" />
  <div className="w-3 h-3 bg-orange-500 rounded-full animate-bounce delay-200" />
</div>

4. 日志显示

<div className="h-40 overflow-y-auto bg-slate-50 p-4 rounded font-mono text-xs">
  {logs.map((log, i) => (
    <div key={i} className="mb-1 text-slate-600">
      <span className="text-slate-400">[{log.timestamp}]</span> {log.message}
    </div>
  ))}
  <div className="animate-pulse text-purple-500">_</div>
</div>

---

5.2 验收标准

• 点击"开始提取"后成功创建任务
• 获取到taskId
• 进度轮询正常（每5秒）
• 进度条实时更新
• 日志滚动区域正常显示
• 任务完成后自动跳转到Step 4
• 任务失败时显示错误提示

---

🎯 六、Phase 4: Tool B - Step 4（Day 3下午+Day 4）⭐ 核心

6.1 冲突验证网格（9小时）

这是整个Tool B最复杂、最核心的页面！

6.1.1 页面设计

组件：pages/tool-b/Step4Verify.tsx

UI参考：原型V4第402-569行

布局：

┌─────────────────────────────────────────────────┐
│ Toolbar: 统计信息 + [导出][完成]                 │
├─────────────────────────────────────────────────┤
│                                                 │
│  全景验证网格（表格）                             │
│  ┌────┬────────────┬────────┬────────┬──────┐  │
│  │ #  │ 原文摘要   │ 字段1  │ 字段2  │ 状态 │  │
│  ├────┼────────────┼────────┼────────┼──────┤  │
│  │ 1  │ 病理诊断.. │ 冲突单元格（A/B按钮）│待裁决│  │
│  │ 2  │ 送检组织.. │ 绿色（一致）│ 绿色  │ 通过 │  │
│  └────┴────────────┴────────┴────────┴──────┘  │
│                                                 │
└─────────────────────────────────────────────────┘
                    ↓ 点击行
┌──────────────────────────────────┐
│ 侧边栏（Drawer）                  │
│ ─────────────────────────────── │
│ 病历原文详情                      │
│                                  │
│ 病理诊断：(右肺上叶)浸润性腺癌... │
│ 肿瘤大小 3.2*2.5*2.0cm...        │
│ ...                              │
│                                  │
│ [关闭]                           │
└──────────────────────────────────┘

---

6.1.2 技术选型

方案选择：

Option 1: Ant Design Table（推荐，数据量<1000行）

• 优点：开箱即用，API友好，样式统一
• 缺点：数据量大时可能卡顿
• 适用场景：大部分场景（预计数据量<500行）

Option 2: TanStack Table（高性能，数据量>1000行）

• 优点：虚拟滚动，性能极佳
• 缺点：Headless需自己实现UI
• 适用场景：处理大数据集

决策：先用Ant Design Table，如性能不佳再迁移到TanStack Table

---

6.1.3 核心数据结构

interface VerifyRow {
  id: string;
  rowIndex: number;
  originalText: string; // 原文摘要（前50字）
  fullText: string; // 原文全文（侧边栏显示）
  results: Record<string, {
    A: string; // DeepSeek结果
    B: string; // Qwen结果
    chosen: string | null; // 用户采纳的值（null=未解决）
  }>;
  status: 'clean' | 'conflict' | 'resolved';
  conflictFields: string[]; // 冲突字段名称列表
}

---

6.1.4 功能实现

1. 获取验证数据

const [rows, setRows] = useState<VerifyRow[]>([]);
const [pagination, setPagination] = useState({ page: 1, pageSize: 20, total: 0 });

useEffect(() => {
  fetch(`/api/v1/dc/tool-b/tasks/${taskId}/items?status=conflict&page=${pagination.page}`)
    .then(res => res.json())
    .then(data => {
      setRows(data.data.items);
      setPagination({ ...pagination, total: data.data.pagination.total });
    });
}, [taskId, pagination.page]);

2. 表格列配置

const columns: ColumnsType<VerifyRow> = [
  {
    title: '#',
    dataIndex: 'rowIndex',
    width: 60,
    fixed: 'left',
  },
  {
    title: '原文摘要',
    dataIndex: 'originalText',
    width: 200,
    render: (text, record) => (
      <div className="flex items-center gap-2">
        <FileText size={14} className="text-slate-300" />
        <Tooltip title={text}>
          <span className="truncate w-40">{text}</span>
        </Tooltip>
      </div>
    ),
  },
  // 动态字段列（根据模板生成）
  ...fields.map(field => ({
    title: field.name,
    dataIndex: ['results', field.name],
    width: 180,
    render: (cellData: { A: string; B: string; chosen: string | null }, record: VerifyRow) => {
      const isConflict = cellData.A !== cellData.B && cellData.chosen === null;
      
      if (isConflict) {
        return <ConflictCell 
          fieldName={field.name}
          valueA={cellData.A}
          valueB={cellData.B}
          onAdopt={(value) => handleAdopt(record.id, field.name, value)}
        />;
      }
      
      return <CleanCell value={cellData.chosen || cellData.A} />;
    },
  })),
  {
    title: '状态',
    dataIndex: 'status',
    width: 100,
    fixed: 'right',
    render: (status) => {
      if (status === 'clean' || status === 'resolved') {
        return <Tag color="success">通过</Tag>;
      }
      return <Tag color="warning" className="animate-pulse">待裁决</Tag>;
    },
  },
];

3. 冲突单元格组件 ⭐ 核心

// components/ConflictCell.tsx
interface ConflictCellProps {
  fieldName: string;
  valueA: string;
  valueB: string;
  onAdopt: (value: string) => void;
}

const ConflictCell: React.FC<ConflictCellProps> = ({ fieldName, valueA, valueB, onAdopt }) => {
  return (
    <div className="flex flex-col gap-1.5 bg-orange-50 p-2 rounded">
      {/* 选项A - DeepSeek */}
      <button
        className="text-left text-xs px-2 py-1.5 rounded border border-blue-200 bg-white hover:bg-blue-50 hover:border-blue-400 transition-all flex justify-between group"
        onClick={() => onAdopt(valueA)}
      >
        <Tooltip title={valueA}>
          <span className="truncate max-w-[100px]">{valueA}</span>
        </Tooltip>
        <Badge className="text-[10px] text-blue-400 group-hover:text-blue-600">DS</Badge>
      </button>
      
      {/* 选项B - Qwen */}
      <button
        className="text-left text-xs px-2 py-1.5 rounded border border-orange-200 bg-white hover:bg-orange-50 hover:border-orange-400 transition-all flex justify-between group"
        onClick={() => onAdopt(valueB)}
      >
        <Tooltip title={valueB}>
          <span className="truncate max-w-[100px]">{valueB}</span>
        </Tooltip>
        <Badge className="text-[10px] text-orange-400 group-hover:text-orange-600">QW</Badge>
      </button>
    </div>
  );
};

4. 裁决逻辑

const handleAdopt = async (itemId: string, fieldName: string, value: string) => {
  // 乐观更新UI
  setRows(prevRows =>
    prevRows.map(row => {
      if (row.id !== itemId) return row;
      
      const newResults = { ...row.results };
      newResults[fieldName].chosen = value;
      
      // 检查该行是否还有未解决的冲突
      const hasConflict = Object.values(newResults).some(
        cell => cell.chosen === null && cell.A !== cell.B
      );
      
      return {
        ...row,
        results: newResults,
        status: hasConflict ? 'conflict' : 'resolved',
      };
    })
  );
  
  // 调用API
  try {
    await fetch(`/api/v1/dc/tool-b/items/${itemId}/resolve`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        resolvedData: { [fieldName]: value }
      })
    });
  } catch (error) {
    message.error('裁决失败');
    // 回滚UI
    // TODO: 实现回滚逻辑
  }
};

5. 侧边栏原文显示

const [selectedRowId, setSelectedRowId] = useState<string | null>(null);

// 点击行时打开侧边栏
const onRow = (record: VerifyRow) => ({
  onClick: () => setSelectedRowId(record.id),
});

// Drawer组件
<Drawer
  title="病历原文详情"
  placement="right"
  width={400}
  open={!!selectedRowId}
  onClose={() => setSelectedRowId(null)}
>
  {(() => {
    const row = rows.find(r => r.id === selectedRowId);
    if (!row) return null;
    
    return (
      <div className="prose">
        <p className="whitespace-pre-wrap font-serif leading-7">
          {row.fullText}
        </p>
        
        <Divider />
        
        <div className="flex flex-wrap gap-2">
          {Object.keys(row.results).map(fieldName => (
            <Tag
              key={fieldName}
              color={row.conflictFields.includes(fieldName) ? 'orange' : 'default'}
            >
              {fieldName}
            </Tag>
          ))}
        </div>
      </div>
    );
  })()}
</Drawer>

6. Toolbar统计

const conflictCount = rows.filter(r => r.status === 'conflict').length;
const resolvedCount = rows.filter(r => r.status === 'resolved').length;
const cleanCount = rows.filter(r => r.status === 'clean').length;

<div className="flex items-center gap-4 mb-4">
  <div className="bg-slate-100 px-3 py-1.5 rounded">
    总数据: <strong>{rows.length}</strong>
  </div>
  
  {conflictCount > 0 ? (
    <div className="bg-orange-50 px-3 py-1.5 rounded text-orange-700 animate-pulse">
      <AlertTriangle size={16} className="inline mr-1" />
      <strong>{conflictCount}</strong> 条冲突待裁决
    </div>
  ) : (
    <div className="bg-emerald-50 px-3 py-1.5 rounded text-emerald-700">
      <CheckCircle2 size={16} className="inline mr-1" />
      所有冲突已解决
    </div>
  )}
  
  <Button onClick={handleExport}>导出当前结果</Button>
  <Button type="primary" onClick={handleComplete}>完成并入库</Button>
</div>

---

6.2 验收标准

数据加载：

• 成功获取验证数据
• 表格列根据模板动态生成
• 分页功能正常

冲突单元格：

• 冲突单元格显示A/B两个按钮
• 按钮显示正确的值和模型标识（DS/QW）
• 点击按钮后采纳值
• UI乐观更新（立即生效）
• API调用成功

侧边栏：

• 点击行时侧边栏滑出
• 显示完整病历原文
• 显示字段标签（冲突字段高亮）
• 点击关闭按钮或外部区域关闭侧边栏

Toolbar：

• 冲突数统计正确
• 实时更新（裁决后减少）
• 导出按钮可点击
• 完成按钮跳转到Step 5

---

📦 七、Phase 5: Tool B - Step 5（Day 5上午）

7.1 结果导出（3小时）

7.1.1 页面设计

组件：pages/tool-b/Step5Result.tsx

UI参考：原型V4第572-607行

布局：

1. 完成图标和标题
2. 统计卡片（4个）
3. 操作按钮（下载、流转）

---

7.1.2 功能实现

1. 统计数据获取

const [stats, setStats] = useState({
  totalCount: 0,
  cleanCount: 0,
  conflictCount: 0,
  failedCount: 0,
  totalTokens: 0,
  totalCost: 0,
});

useEffect(() => {
  fetch(`/api/v1/dc/tool-b/tasks/${taskId}/progress`)
    .then(res => res.json())
    .then(data => setStats(data.data));
}, [taskId]);

2. Excel导出

const handleExport = async () => {
  try {
    const response = await fetch(`/api/v1/dc/tool-b/tasks/${taskId}/export`, {
      method: 'POST'
    });
    
    const blob = await response.blob();
    const url = window.URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = `extraction_result_${taskId}.xlsx`;
    a.click();
    
    message.success('导出成功');
  } catch (error) {
    message.error('导出失败');
  }
};

3. 流转到工具C

const handleGoToToolC = () => {
  // 跳转到工具C，传递taskId
  navigate(`/data-cleaning/tool-c?sourceTaskId=${taskId}`);
};

---

7.2 验收标准

• 统计卡片数据正确显示
• Token消耗和成本计算正确
• 下载按钮触发Excel导出
• Excel文件包含4个Sheet（完整结果、无冲突、冲突项、失败项）
• 流转到工具C按钮可点击（提示暂未开发）
• 返回Portal按钮可点击

---

🧪 八、Phase 6: 集成测试（Day 5下午）

8.1 端到端测试清单

8.1.1 完整流程测试

测试场景：肺癌病理报告提取

测试步骤：

1. 访问Portal页面（/data-cleaning）
2. 点击Tool B卡片，跳转到Step 1
3. 上传测试Excel文件（包含病理报告列）
4. 选择"病理报告"列，触发健康检查
5. 验证健康度显示为"绿色 - 优秀"
6. 进入Step 2，选择"肺癌 + 病理报告"
7. 验证字段自动加载（5个字段）
8. 编辑一个字段（修改描述）
9. 进入Step 3，点击"开始提取"
10. 验证进度条开始更新
11. 验证日志滚动显示
12. 等待任务完成（或模拟完成）
13. 自动跳转到Step 4
14. 验证验证网格加载数据
15. 找到一个冲突单元格，点击"DS"按钮采纳
16. 验证冲突数减1
17. 点击某行，验证侧边栏显示原文
18. 点击"完成并入库"，跳转到Step 5
19. 验证统计卡片数据正确
20. 点击"下载"，验证Excel下载成功

---

8.1.2 异常场景测试

测试场景1：健康检查失败

• 上传Excel，选择空值率>50%的列
• 验证健康度显示为"红色 - 警告"
• 验证"下一步"按钮被禁用

测试场景2：任务失败

• 模拟API返回失败状态
• 验证错误提示显示
• 验证可以重新尝试

测试场景3：网络错误

• 断网后点击"下一步"
• 验证错误提示显示
• 重新联网后可继续

---

8.2 性能测试

测试场景：大数据量验证网格

测试步骤：

1. 加载500行数据
2. 验证表格滚动流畅（无卡顿）
3. 验证分页功能正常
4. 验证排序/筛选功能（如实现）

性能指标：

• 首屏加载时间 < 2秒
• 表格滚动帧率 > 30fps
• 裁决操作响应时间 < 500ms

---

8.3 兼容性测试

浏览器：

• Chrome 120+
• Edge 120+
• Firefox 120+
• Safari 17+（Mac）

分辨率：

• 1920x1080（常规）
• 1440x900（笔记本）
• 2560x1440（高分屏）

---

📝 九、文档完善（Day 6）

9.1 开发文档

需要补充的文档：

1. 前端代码结构说明（docs/03-业务模块/DC-数据清洗整理/02-技术设计/前端架构设计.md）
2. 组件使用文档（frontend-v2/src/modules/dc/README.md）
3. API对接文档（补充到现有API设计文档）
4. 本开发计划的完成总结（docs/03-业务模块/DC-数据清洗整理/06-开发记录/Tool-B开发完成总结.md）

---

9.2 用户文档（可选）

需要创建的文档：

1. Tool B使用指南（docs/03-业务模块/DC-数据清洗整理/07-用户手册/Tool-B使用指南.md）
2. 常见问题FAQ（docs/03-业务模块/DC-数据清洗整理/07-用户手册/FAQ.md）

---

🎯 十、关键技术要点

10.1 必须遵守的规范

云原生规范 ⭐ 强制

参考：docs/04-开发规范/08-云原生开发规范.md

禁止：

• ❌ 使用fs.writeFile()等本地文件操作
• ❌ 使用全局变量缓存数据
• ❌ 硬编码配置（IP、密钥等）
• ❌ 同步长任务（>10秒）
• ❌ 重复实现平台能力

必须：

• ✅ 使用storage服务存储文件
• ✅ 使用cache服务缓存数据
• ✅ 使用环境变量配置
• ✅ 异步任务 + 进度轮询
• ✅ 复用平台基础设施

---

10.2 复用策略

后端复用（参考）

// ✅ 正确：复用平台能力
import { storage } from '@/common/storage';
import { logger } from '@/common/logging';
import { cache } from '@/common/cache';
import { LLMFactory } from '@/common/llm/adapters/LLMFactory';

前端复用（需实现）

// 复用ASL模块的组件和Hook
import { usePolling } from '@/shared/hooks/usePolling';
import { FileUploader } from '@/shared/components/FileUploader';
import { ProgressBar } from '@/shared/components/ProgressBar';

---

10.3 状态管理

推荐方案：React Query（ASL模块使用）

// 使用React Query管理API调用
import { useQuery, useMutation } from '@tanstack/react-query';

// 获取任务进度
const { data: progress } = useQuery({
  queryKey: ['task-progress', taskId],
  queryFn: () => fetch(`/api/v1/dc/tool-b/tasks/${taskId}/progress`).then(res => res.json()),
  refetchInterval: 5000, // 每5秒轮询
  enabled: !!taskId && status === 'processing',
});

// 裁决冲突
const resolveMutation = useMutation({
  mutationFn: ({ itemId, resolvedData }) =>
    fetch(`/api/v1/dc/tool-b/items/${itemId}/resolve`, {
      method: 'POST',
      body: JSON.stringify({ resolvedData }),
    }),
  onSuccess: () => {
    queryClient.invalidateQueries(['task-items', taskId]);
    message.success('裁决成功');
  },
});

---

10.4 TypeScript类型定义

统一类型文件：frontend-v2/src/modules/dc/types/toolB.ts

// 健康检查结果
export interface HealthCheckResult {
  status: 'good' | 'bad';
  emptyRate: number;
  avgLength: number;
  totalRows: number;
  estimatedTokens: number;
  message: string;
}

// 模板定义
export interface Template {
  id: string;
  diseaseType: string;
  reportType: string;
  displayName: string;
  fields: Field[];
}

export interface Field {
  id: string;
  name: string;
  desc: string;
  width?: string;
}

// 任务状态
export interface Task {
  id: string;
  projectName: string;
  status: 'pending' | 'processing' | 'completed' | 'failed';
  totalCount: number;
  processedCount: number;
  cleanCount: number;
  conflictCount: number;
  failedCount: number;
  totalTokens: number;
  totalCost: number;
}

// 验证行
export interface VerifyRow {
  id: string;
  rowIndex: number;
  originalText: string;
  fullText: string;
  results: Record<string, {
    A: string;
    B: string;
    chosen: string | null;
  }>;
  status: 'clean' | 'conflict' | 'resolved';
  conflictFields: string[];
}

---

📊 十一、风险评估与应对

11.1 技术风险

风险	概率	影响	应对措施
数据库表未创建	中	高	立即执行npx prisma db push验证
后端API未测试	中	高	开发前先用REST Client测试6个端点
性能问题（大数据量）	低	中	预留TanStack Table迁移方案
Excel解析失败	低	中	使用xlsx库，增加错误处理
LLM调用超时	低	中	后端已实现重试机制

---

11.2 时间风险

风险	概率	影响	应对措施
Step 4开发超时	中	高	预留2天（9小时），可拆分子任务
集成测试发现问题	中	中	预留1天缓冲时间
原型与需求不符	低	高	开发前与产品确认原型

---

11.3 依赖风险

风险	概率	影响	应对措施
后端API变更	低	高	使用TypeScript类型，编译时检查
平台能力Bug	低	中	已完整测试，风险低
设计变更	低	中	组件化设计，易于修改

---

🎉 十二、预期成果

12.1 交付物清单

代码：

• Portal工作台页面（完整）
• Tool B 5个Step页面（完整）
• 共享组件库（TaskList、AssetLibrary、ConflictCell等）
• API服务封装（toolBApi.ts、portalApi.ts）
• TypeScript类型定义（完整）
• 样式文件（TailwindCSS + Ant Design）

文档：

• 前端架构设计文档
• 组件使用文档
• API对接文档
• 开发完成总结
• 用户使用指南（可选）

测试：

• 端到端测试报告
• 性能测试报告
• 兼容性测试报告

---

12.2 功能完整性

Portal工作台：

• ✅ 3个工具卡片（Tool B可用）
• ✅ 最近任务列表（实时轮询）
• ✅ 数据资产库（Tab切换）

Tool B - 病历结构化机器人：

• ✅ Step 1: Excel上传 + 健康检查
• ✅ Step 2: 智能模板配置（3个预设模板）
• ✅ Step 3: 双盲提取进度监控
• ✅ Step 4: 冲突验证网格（支持裁决）
• ✅ Step 5: 结果导出（Excel + 流转）

---

12.3 代码质量

代码规范：

• ✅ 遵守云原生开发规范
• ✅ TypeScript类型安全
• ✅ ESLint无错误
• ✅ 代码注释完善

性能指标：

• ✅ 首屏加载 < 2s
• ✅ 表格滚动流畅
• ✅ 裁决响应 < 500ms
• ✅ 内存占用 < 200MB

用户体验：

• ✅ 流畅的5步流程
• ✅ 实时进度反馈
• ✅ 直观的冲突验证界面
• ✅ 友好的错误提示

---

🚀 十三、下一步行动

13.1 立即执行（Day 0）

1. 验证数据库表

cd AIclinicalresearch/backend
npx prisma db push --skip-generate
npx prisma studio  # 可视化验证

2. 测试后端API

# 启动后端服务
npm run dev

# 使用REST Client测试6个API端点
# 或使用Postman/Insomnia

3. Git提交计划

# 建议每完成一个Phase就提交
git commit -m "feat(dc): Complete Portal page (Phase 1)"
git commit -m "feat(dc/tool-b): Complete Step1&2 (Phase 2)"
git commit -m "feat(dc/tool-b): Complete Step4 conflict grid (Phase 4)"

---

13.2 开发启动（Day 1）

任务1：创建Portal页面骨架

cd frontend-v2/src/modules/dc
mkdir -p pages components hooks services types

# 创建Portal.tsx
touch pages/Portal.tsx

# 创建路由配置
# 修改 index.tsx

任务2：实现3个工具卡片

# 创建ToolCard组件
touch components/ToolCard.tsx

任务3：实现任务列表（使用Mock数据）

# 创建TaskList组件
touch components/TaskList.tsx

# 创建useRecentTasks Hook
touch hooks/useRecentTasks.ts

---

13.3 持续跟进

每日检查点：

• 代码是否Git提交
• Todo列表是否更新
• 遇到的问题是否记录
• API调用是否正常

每周检查点：

• 功能完成度是否符合预期
• 是否需要调整计划
• 是否需要额外资源

---

📞 十四、联系与支持

14.1 技术支持

遇到问题时：

1. 查阅平台基础设施文档（backend/src/common/README.md）
2. 查阅云原生开发规范（docs/04-开发规范/08-云原生开发规范.md）
3. 参考ASL模块代码（frontend-v2/src/modules/asl/）
4. 查看后端API代码（backend/src/modules/dc/tool-b/）

14.2 代码审查

提交前自检：

• 是否遵守云原生规范
• 是否复用平台能力
• TypeScript类型是否完整
• 是否有TODO/FIXME注释
• 是否有console.log（应使用logger）

---

🎯 十五、总结

核心目标

完成DC模块Tool B的前端开发，实现从文件上传到结果导出的完整5步流程，特别是冲突验证网格这一核心功能。

关键成功因素

1. ✅ 后端已100%完成，前端可专注UI和交互
2. ✅ 平台能力完善，可直接复用，无需重复开发
3. ✅ 设计文档齐全，有清晰的原型和需求
4. ✅ 参考模块成熟，ASL模块可作为参考
5. ✅ 架构方案明确，采用方案A（独立Portal）

预期收益

• 用户价值：提供AI驱动的病历结构化能力，双模型交叉验证提高数据质量
• 技术价值：完整的前端模块化架构，可复用组件库
• 商业价值：Tool B可独立销售，满足医疗数据处理需求

---

开发计划制定完成！ ✅

下一步：验证数据库表 → 测试后端API → 开始Phase 1（Portal页面开发）

预计完成时间：5-6个工作日

祝开发顺利！ 🚀