docs:表格列配置实现文档

docs/实现/表格列配置功能.md

@@ -0,0 +1,967 @@
+# 表格列配置功能 - 实现文档
+
+## 1. 概述
+
+本文档记录了 Worklist 和 History 等页面表格的列配置功能实现，支持通过配置信息动态控制表格显示的列，而不是显示所有35个列。
+
+## 2. 需求背景
+
+### 2.1 业务场景
+
+在 Worklist 和 History 页面，表格默认显示所有35个列，导致：
+- 表格过宽，需要大量横向滚动
+- 用户难以快速找到关键信息
+- 不同用户对列的需求不同
+- 无法根据业务场景灵活调整
+
+### 2.2 核心需求
+
+**主要功能**：
+- ✅ 支持配置哪些列显示、哪些列隐藏
+- ✅ 支持配置列的显示顺序
+- ✅ 支持配置列的宽度
+- ✅ 支持从远程 API 获取配置
+- ✅ API 失败时自动回退到本地默认配置
+- ✅ 不同表格（worklist/history）使用独立配置
+- ✅ 向后兼容：无配置时显示所有列
+
+**技术要求**：
+- 配置可来自本地硬编码或远程 API
+- 远程配置失败时有回退机制
+- 配置通过 props 传递给表格组件
+- 支持多表格独立配置
+
+---
+
+## 3. 架构设计
+
+### 3.1 端口适配器模式（Port-Adapter Pattern）
+
+采用端口适配器模式实现灵活的配置源切换：
+
+```
+┌─────────────────────────────────────────────┐
+│         配置源（可切换）                      │
+│  ┌──────────────┐    ┌──────────────┐       │
+│  │ 本地硬编码    │    │  远程 API    │       │
+│  └──────────────┘    └──────────────┘       │
+└─────────────┬──────────────┬────────────────┘
+              │              │
+              ↓              ↓
+    ┌──────────────────────────────────┐
+    │  IColumnConfigProvider (端口)    │
+    │  - getColumnConfig()            │
+    │  - getAllColumnConfigs()        │
+    │  - isAvailable()                │
+    └──────────────────────────────────┘
+              ↓
+    ┌──────────────────────────────────┐
+    │  ColumnConfigService (领域服务)   │
+    │  - 策略模式                      │
+    │  - 主提供者 + 回退提供者          │
+    │  - 自动切换                      │
+    └──────────────────────────────────┘
+              ↓
+    ┌──────────────────────────────────┐
+    │  父组件 (worklist.tsx)            │
+    │  - 获取配置                      │
+    │  - 通过 props 传递               │
+    └──────────────────────────────────┘
+              ↓
+    ┌──────────────────────────────────┐
+    │  WorklistTable 组件               │
+    │  - 根据配置过滤列                │
+    │  - 根据配置排序列                │
+    │  - 应用列宽                      │
+    └──────────────────────────────────┘
+```
+
+### 3.2 数据流
+
+```
+应用启动
+    ↓
+父组件 useEffect
+    ↓
+columnConfigService.getColumnConfig('worklist')
+    ↓
+    ├─→ 尝试主提供者 (RemoteColumnConfigAdapter)
+    │   ├─→ 成功 → 返回远程配置
+    │   └─→ 失败 ↓
+    │
+    └─→ 回退提供者 (LocalColumnConfigAdapter)
+        └─→ 返回本地配置
+    ↓
+父组件接收配置 → setState
+    ↓
+通过 props 传递给 WorklistTable
+    ↓
+WorklistTable.visibleColumns (useMemo)
+    ├─→ 配置为空 → 显示所有35列
+    └─→ 配置不为空 → 过滤 + 排序 + 应用宽度
+    ↓
+渲染表格
+```
+
+---
+
+## 4. 技术实现
+
+### 4.1 类型定义
+
+**文件**：`src/config/tableColumns/types/columnConfig.ts`
+
+```typescript
+/**
+ * 单个列的配置
+ */
+export interface ColumnConfig {
+  key: string;           // 列标识（对应 dataIndex）
+  visible: boolean;      // 是否显示
+  order: number;         // 显示顺序
+  width?: number;        // 列宽（可选）
+  fixed?: 'left' | 'right'; // 固定列（可选）
+}
+
+/**
+ * 表格名称类型
+ */
+export type TableName = 'worklist' | 'history' | 'archive' | 'output';
+
+/**
+ * 表格列配置
+ */
+export interface TableColumnConfig {
+  tableName: TableName;
+  columns: ColumnConfig[];
+  version?: string;      // 配置版本
+  updatedAt?: string;    // 更新时间
+}
+
+/**
+ * 完整的配置响应
+ */
+export interface ColumnConfigResponse {
+  data: TableColumnConfig[];
+  success: boolean;
+  message?: string;
+}
+```
+
+### 4.2 端口接口
+
+**文件**：`src/config/tableColumns/ports/IColumnConfigProvider.ts`
+
+```typescript
+import { TableColumnConfig, TableName } from '../types/columnConfig';
+
+export interface IColumnConfigProvider {
+  /**
+   * 获取指定表格的列配置
+   */
+  getColumnConfig(tableName: TableName): Promise<TableColumnConfig>;
+
+  /**
+   * 获取所有表格的配置
+   */
+  getAllColumnConfigs(): Promise<TableColumnConfig[]>;
+
+  /**
+   * 检查提供者是否可用
+   */
+  isAvailable(): Promise<boolean>;
+}
+```
+
+### 4.3 本地适配器实现
+
+**文件**：`src/config/tableColumns/adapters/LocalColumnConfigAdapter.ts`
+
+```typescript
+export class LocalColumnConfigAdapter implements IColumnConfigProvider {
+  private readonly defaultConfigs: Map<TableName, TableColumnConfig>;
+
+  constructor() {
+    this.defaultConfigs = new Map([
+      // worklist 的默认列配置
+      ['worklist', {
+        tableName: 'worklist',
+        columns: [
+          { key: 'PatientID', visible: true, order: 1, width: 120 },
+          { key: 'PatientName', visible: true, order: 2, width: 150 },
+          { key: 'StudyID', visible: true, order: 3, width: 120 },
+          { key: 'AccessionNumber', visible: true, order: 4, width: 150 },
+          { key: 'StudyStatus', visible: true, order: 5, width: 100 },
+          { key: 'Modality', visible: true, order: 6, width: 100 },
+          { key: 'StudyStartDatetime', visible: true, order: 7, width: 180 },
+          { key: 'PatientAge', visible: true, order: 8, width: 80 },
+          { key: 'PatientSex', visible: true, order: 9, width: 80 },
+          // 其他列默认隐藏 (visible: false)
+        ],
+        version: '1.0.0',
+      }],
+      // history 的默认列配置
+      ['history', {
+        tableName: 'history',
+        columns: [
+          { key: 'StudyID', visible: true, order: 1, width: 120 },
+          { key: 'PatientName', visible: true, order: 2, width: 150 },
+          { key: 'StudyDescription', visible: true, order: 3, width: 200 },
+          { key: 'StudyStartDatetime', visible: true, order: 4, width: 180 },
+          { key: 'IsExported', visible: true, order: 5, width: 100 },
+          { key: 'StudyStatus', visible: true, order: 6, width: 100 },
+        ],
+        version: '1.0.0',
+      }],
+    ]);
+  }
+
+  async getColumnConfig(tableName: TableName): Promise<TableColumnConfig> {
+    const config = this.defaultConfigs.get(tableName);
+    if (!config) {
+      throw new Error(`No default config found for table: ${tableName}`);
+    }
+    return Promise.resolve(config);
+  }
+
+  async getAllColumnConfigs(): Promise<TableColumnConfig[]> {
+    return Promise.resolve(Array.from(this.defaultConfigs.values()));
+  }
+
+  async isAvailable(): Promise<boolean> {
+    return Promise.resolve(true); // 本地配置总是可用
+  }
+}
+```
+
+**设计特点**：
+- 使用 Map 存储多表格配置
+- 默认显示9个核心列
+- 本地配置总是可用（isAvailable 返回 true）
+
+### 4.4 远程适配器实现
+
+**文件**：`src/config/tableColumns/adapters/RemoteColumnConfigAdapter.ts`
+
+```typescript
+export class RemoteColumnConfigAdapter implements IColumnConfigProvider {
+  private configCache: Map<TableName, TableColumnConfig> = new Map();
+  private cacheExpiry: number = 5 * 60 * 1000; // 5分钟缓存
+  private lastFetchTime: number = 0;
+
+  async getColumnConfig(tableName: TableName): Promise<TableColumnConfig> {
+    // 如果缓存有效，直接返回
+    if (this.isCacheValid() && this.configCache.has(tableName)) {
+      return this.configCache.get(tableName)!;
+    }
+
+    // 否则从API获取
+    await this.fetchAndCacheConfigs();
+    
+    const config = this.configCache.get(tableName);
+    if (!config) {
+      throw new Error(`No config found for table: ${tableName}`);
+    }
+    return config;
+  }
+
+  async getAllColumnConfigs(): Promise<TableColumnConfig[]> {
+    if (!this.isCacheValid()) {
+      await this.fetchAndCacheConfigs();
+    }
+    return Array.from(this.configCache.values());
+  }
+
+  async isAvailable(): Promise<boolean> {
+    try {
+      await this.fetchAndCacheConfigs();
+      return true;
+    } catch (error) {
+      console.error('Remote config provider unavailable:', error);
+      return false;
+    }
+  }
+
+  private async fetchAndCacheConfigs(): Promise<void> {
+    try {
+      const response = await fetchTableColumnConfig();
+      
+      if (response.success && response.data) {
+        this.configCache.clear();
+        response.data.forEach(config => {
+          this.configCache.set(config.tableName, config);
+        });
+        this.lastFetchTime = Date.now();
+      }
+    } catch (error) {
+      throw new Error(`Failed to fetch remote config: ${error}`);
+    }
+  }
+
+  private isCacheValid(): boolean {
+    return Date.now() - this.lastFetchTime < this.cacheExpiry;
+  }
+}
+```
+
+**设计特点**：
+- 实现5分钟缓存机制，减少 API 调用
+- isAvailable 通过尝试获取配置来判断可用性
+- 失败时抛出错误，触发回退机制
+
+### 4.5 API 调用
+
+**文件**：`src/API/tableColumnConfig.ts`
+
+```typescript
+import axios from './interceptor';
+import { ColumnConfigResponse } from '../config/tableColumns/types/columnConfig';
+
+/**
+ * 获取表格列配置
+ */
+export async function fetchTableColumnConfig(): Promise<ColumnConfigResponse> {
+  const response = await axios.get<ColumnConfigResponse>(
+    '/api/config/table-columns'
+  );
+  return response.data;
+}
+```
+
+**API 端点**：`GET /api/config/table-columns`
+
+**响应格式**：
+```json
+{
+  "success": true,
+  "data": [
+    {
+      "tableName": "worklist",
+      "columns": [
+        { "key": "PatientID", "visible": true, "order": 1, "width": 120 },
+        { "key": "PatientName", "visible": true, "order": 2, "width": 150 }
+      ],
+      "version": "1.0.0",
+      "updatedAt": "2025-10-07T10:00:00Z"
+    }
+  ]
+}
+```
+
+### 4.6 领域服务（策略模式 + 回退机制）
+
+**文件**：`src/config/tableColumns/domain/ColumnConfigService.ts`
+
+```typescript
+export class ColumnConfigService {
+  private primaryProvider: IColumnConfigProvider;
+  private fallbackProvider: IColumnConfigProvider;
+
+  constructor(
+    primaryProvider?: IColumnConfigProvider,
+    fallbackProvider?: IColumnConfigProvider
+  ) {
+    // 默认：优先使用远程，回退到本地
+    this.primaryProvider = primaryProvider || new RemoteColumnConfigAdapter();
+    this.fallbackProvider = fallbackProvider || new LocalColumnConfigAdapter();
+  }
+
+  /**
+   * 获取表格列配置
+   * 优先使用主提供者，失败则回退到备用提供者
+   */
+  async getColumnConfig(tableName: TableName): Promise<TableColumnConfig> {
+    try {
+      if (await this.primaryProvider.isAvailable()) {
+        return await this.primaryProvider.getColumnConfig(tableName);
+      }
+    } catch (error) {
+      console.warn('Primary provider failed, using fallback:', error);
+    }
+
+    // 回退到备用提供者
+    return await this.fallbackProvider.getColumnConfig(tableName);
+  }
+
+  /**
+   * 切换提供者
+   */
+  switchProvider(provider: IColumnConfigProvider): void {
+    this.primaryProvider = provider;
+  }
+}
+
+// 导出单例
+export const columnConfigService = new ColumnConfigService();
+```
+
+**设计特点**：
+- 策略模式：可运行时切换提供者
+- 回退机制：主提供者失败自动使用备用
+- 单例导出：全局共享服务实例
+
+### 4.7 导出模块
+
+**文件**：`src/config/tableColumns/index.ts`
+
+```typescript
+// 类型定义
+export * from './types/columnConfig';
+
+// 端口接口
+export * from './ports/IColumnConfigProvider';
+
+// 适配器
+export * from './adapters/LocalColumnConfigAdapter';
+export * from './adapters/RemoteColumnConfigAdapter';
+
+// 领域服务
+export * from './domain/ColumnConfigService';
+export { columnConfigService } from './domain/ColumnConfigService';
+```
+
+---
+
+## 5. 组件改造
+
+### 5.1 WorklistTable 组件
+
+**文件**：`src/pages/patient/components/WorklistTable.tsx`
+
+#### 新增接口定义
+
+```typescript
+interface WorklistTableProps {
+  columnConfig?: ColumnConfig[]; // ⭐ 新增：列配置（可选）
+  worklistData: Task[];
+  filters?: WorkFilter;
+  page?: number;
+  pageSize?: number;
+  selectedIds: string[];
+  handleRowClick: (record: Task) => void;
+  handleRowDoubleClick: (record: Task) => void;
+}
+```
+
+#### 核心逻辑：根据配置过滤和排序列
+
+```typescript
+const WorklistTable: React.FC<WorklistTableProps> = ({
+  columnConfig = [], // 接收配置，默认为空数组
+  worklistData,
+  selectedIds,
+  handleRowClick,
+  handleRowDoubleClick,
+}) => {
+  // 根据传入的配置过滤和排序列
+  const visibleColumns = useMemo(() => {
+    // 如果没有配置，显示所有列（保持当前行为）
+    if (columnConfig.length === 0) {
+      return columnsDef.map(col => ({
+        ...col,
+        width: 150,
+      }));
+    }
+
+    // 根据配置过滤出可见的列
+    return columnsDef
+      .filter(col => {
+        const config = columnConfig.find(c => c.key === col.dataIndex);
+        return config?.visible ?? false;
+      })
+      .map(col => {
+        const config = columnConfig.find(c => c.key === col.dataIndex);
+        return {
+          ...col,
+          width: config?.width ?? 150,
+        };
+      })
+      .sort((a, b) => {
+        const orderA = columnConfig.find(c => c.key === a.dataIndex)?.order ?? 999;
+        const orderB = columnConfig.find(c => c.key === b.dataIndex)?.order ?? 999;
+        return orderA - orderB;
+      });
+  }, [columnConfig]);
+
+  // 列可调整大小的逻辑
+  const [columns, setColumns] = useState<TableColumnsType<DataType>>(visibleColumns);
+
+  useEffect(() => {
+    setColumns(visibleColumns);
+  }, [visibleColumns]);
+
+  // ... 其他代码
+};
+```
+
+**关键点**：
+- 使用 `useMemo` 优化性能，只在配置变化时重新计算
+- 支持向后兼容：配置为空时显示所有列
+- 三步处理：过滤 → 应用宽度 → 排序
+
+### 5.2 父组件集成
+
+**文件**：`src/pages/patient/worklist.tsx`
+
+#### 导入依赖
+
+```typescript
+import { columnConfigService } from '@/config/tableColumns';
+import { ColumnConfig } from '@/config/tableColumns/types/columnConfig';
+```
+
+#### 状态管理
+
+```typescript
+const WorklistPage: React.FC = () => {
+  const [columnConfig, setColumnConfig] = useState<ColumnConfig[]>([]); // 列配置状态
+
+  // 获取列配置
+  useEffect(() => {
+    columnConfigService
+      .getColumnConfig('worklist')
+      .then(config => {
+        setColumnConfig(config.columns);
+      })
+      .catch(error => {
+        console.error('Failed to load worklist column config:', error);
+        // 失败时使用空配置，表格会显示所有列
+        setColumnConfig([]);
+      });
+  }, []);
+
+  return (
+    <WorklistTable
+      columnConfig={columnConfig} // ⭐ 传递配置
+      worklistData={worklistData}
+      selectedIds={selectedIds}
+      handleRowClick={handleRowClick}
+      handleRowDoubleClick={handleRowDoubleClick}
+    />
+  );
+};
+```
+
+---
+
+## 6. 完整的 35 个列定义
+
+```typescript
+const columnsDef = [
+  { title: 'StudyInstanceUID', dataIndex: 'StudyInstanceUID' },
+  { title: 'StudyID', dataIndex: 'StudyID' },
+  { title: 'SpecificCharacterSet', dataIndex: 'SpecificCharacterSet' },
+  { title: 'AccessionNumber', dataIndex: 'AccessionNumber' },
+  { title: 'PatientID', dataIndex: 'PatientID' },
+  { title: 'PatientName', dataIndex: 'PatientName' },
+  { title: 'DisplayPatientName', dataIndex: 'DisplayPatientName' },
+  { title: 'PatientSize', dataIndex: 'PatientSize' },
+  { title: 'PatientAge', dataIndex: 'PatientAge' },
+  { title: 'PatientSex', dataIndex: 'PatientSex' },
+  { title: 'AdmittingTime', dataIndex: 'AdmittingTime' },
+  { title: 'RegSource', dataIndex: 'RegSource' },
+  { title: 'StudyStatus', dataIndex: 'StudyStatus' },
+  { title: 'RequestedProcedureID', dataIndex: 'RequestedProcedureID' },
+  { title: 'PerformedProtocolCodeValue', dataIndex: 'PerformedProtocolCodeValue' },
+  { title: 'PerformedProtocolCodeMeaning', dataIndex: 'PerformedProtocolCodeMeaning' },
+  { title: 'PerformedProcedureStepID', dataIndex: 'PerformedProcedureStepID' },
+  { title: 'StudyDescription', dataIndex: 'StudyDescription' },
+  { title: 'StudyStartDatetime', dataIndex: 'StudyStartDatetime' },
+  { title: 'ScheduledProcedureStepStartDate', dataIndex: 'ScheduledProcedureStepStartDate' },
+  { title: 'StudyLock', dataIndex: 'StudyLock' },
+  { title: 'OperatorID', dataIndex: 'OperatorID' },
+  { title: 'Modality', dataIndex: 'Modality' },
+  { title: 'Views', dataIndex: 'Views' },
+  { title: 'Thickness', dataIndex: 'Thickness' },
+  { title: 'PatientType', dataIndex: 'PatientType' },
+  { title: 'StudyType', dataIndex: 'StudyType' },
+  { title: 'QRCode', dataIndex: 'QRCode' },
+  { title: 'IsExported', dataIndex: 'IsExported' },
+  { title: 'IsEdited', dataIndex: 'IsEdited' },
+  { title: 'WorkRef', dataIndex: 'WorkRef' },
+  { title: 'IsAppended', dataIndex: 'IsAppended' },
+  { title: 'CreationTime', dataIndex: 'CreationTime' },
+  { title: 'MappedStatus', dataIndex: 'MappedStatus' },
+  { title: 'IsDelete', dataIndex: 'IsDelete' },
+];
+```
+
+---
+
+## 7. 测试方案
+
+详见：`docs/测试/表格列配置功能测试方案.md`
+
+### 7.1 核心测试场景
+
+1. **TC-WL-COL-01**: 使用本地配置显示列
+2. **TC-WL-COL-02**: 使用远程API配置显示列
+3. **TC-WL-COL-03**: API失败时回退到本地配置
+4. **TC-WL-COL-04**: 验证特定列的显示/隐藏
+5. **TC-WL-COL-05**: 验证列的显示顺序
+6. **TC-WL-COL-06**: 验证列宽配置
+7. **TC-WL-COL-07**: 无配置时显示所有列（向后兼容）
+
+### 7.2 E2E 测试文件
+
+- `cypress/e2e/patient/worklist/column-config.cy.ts`
+- `cypress/support/mock/handlers/columnConfig.ts`
+- `cypress/support/pageObjects/WorklistPage.ts`（扩展）
+
+---
+
+## 8. 相关文件清单
+
+### 8.1 新增文件（10个）
+
+| 文件路径 | 作用 |
+|---------|------|
+| `src/config/tableColumns/types/columnConfig.ts` | 类型定义 |
+| `src/config/tableColumns/ports/IColumnConfigProvider.ts` | 端口接口 |
+| `src/config/tableColumns/adapters/LocalColumnConfigAdapter.ts` | 本地适配器 |
+| `src/config/tableColumns/adapters/RemoteColumnConfigAdapter.ts` | 远程适配器 |
+| `src/config/tableColumns/domain/ColumnConfigService.ts` | 领域服务 |
+| `src/config/tableColumns/index.ts` | 导出模块 |
+| `src/API/tableColumnConfig.ts` | API调用 |
+| `cypress/support/mock/handlers/columnConfig.ts` | Mock handlers |
+| `cypress/e2e/patient/worklist/column-config.cy.ts` | E2E测试 |
+| `docs/测试/表格列配置功能测试方案.md` | 测试文档 |
+
+### 8.2 修改文件（3个）
+
+| 文件路径 | 修改内容 |
+|---------|---------|
+| `src/pages/patient/components/WorklistTable.tsx` | 添加 columnConfig prop，实现列过滤和排序逻辑 |
+| `src/pages/patient/worklist.tsx` | 获取列配置并传递给 WorklistTable |
+| `cypress/support/pageObjects/WorklistPage.ts` | 添加列相关测试方法 |
+
+---
+
+## 9. History 页面扩展指南
+
+要为 History 页面添加相同功能，只需：
+
+### 步骤 1：修改 HistoryList.tsx
+
+```typescript
+import { columnConfigService } from '@/config/tableColumns';
+import { ColumnConfig } from '@/config/tableColumns/types/columnConfig';
+
+const HistoryList: React.FC = () => {
+  const [columnConfig, setColumnConfig] = useState<ColumnConfig[]>([]);
+
+  useEffect(() => {
+    columnConfigService
+      .getColumnConfig('history')  // ⭐ 使用 'history'
+      .then(config => {
+        setColumnConfig(config.columns);
+      })
+      .catch(error => {
+        console.error('Failed to load history column config:', error);
+        setColumnConfig([]);
+      });
+  }, []);
+
+  return (
+    <WorklistTable  // 或者 HistoryTable
+      columnConfig={columnConfig}
+      // ... 其他 props
+    />
+  );
+};
+```
+
+### 步骤 2：配置默认列
+
+在 `LocalColumnConfigAdapter.ts` 中已经包含 history 的默认配置：
+
+```typescript
+['history', {
+  tableName: 'history',
+  columns: [
+    { key: 'StudyID', visible: true, order: 1, width: 120 },
+    { key: 'PatientName', visible: true, order: 2, width: 150 },
+    { key: 'StudyDescription', visible: true, order: 3, width: 200 },
+    { key: 'StudyStartDatetime', visible: true, order: 4, width: 180 },
+    { key: 'IsExported', visible: true, order: 5, width: 100 },
+    { key: 'StudyStatus', visible: true, order: 6, width: 100 },
+  ],
+  version: '1.0.0',
+}]
+```
+
+---
+
+## 10. 优势与特点
+
+### 10.1 架构优势
+
+1. **灵活切换**：端口适配器模式支持运行时切换配置源
+2. **容错机制**：远程配置失败自动回退到本地
+3. **独立配置**：不同表格使用各自的配置，互不影响
+4. **向后兼容**：无配置时显示所有列，不影响现有功能
+5. **易于扩展**：新增表格只需添加配置，无需修改核心代码
+
+### 10.2 性能优化
+
+1. **缓存机制**：远程配置缓存5分钟，减少 API 调用
+2. **useMemo**：列计算使用 useMemo，避免不必要的重渲染
+3. **按需加载**：只在组件初始化时获取配置
+
+### 10.3 用户体验
+
+1. **精简显示**：只显示关键列，提升可读性
+2. **自定义顺序**：重要列靠前显示
+3. **合适宽度**：每列设置合适宽度，减少调整需求
+4. **回退保障**：配置失败不影响使用
+
+---
+
+## 11. 注意事项
+
+### 11.1 配置格式要求
+
+- `key` 必须与 `columnsDef` 中的 `dataIndex` 完全匹配
+- `order` 应该从 1 开始连续编号
+- `visible: false` 的列不会显示，无论 order 值如何
+
+### 11.2 API 要求
+
+- 响应必须包含 `success` 和 `data` 字段
+- `data` 是数组，每个元素是一个表格的配置
+- 支持一次返回多个表格的配置
+
+### 11.3 向后兼容
+
+- 当 `columnConfig` 为空数组时，显示所有35个列
+- 这确保了在配置缺失或加载失败时，系统仍然可用
+
+### 11.4 缓存策略
+
+- 远程配置缓存5分钟
+- 如需立即更新配置，需要刷新页面或重启应用
+- 可根据业务需求调整 `cacheExpiry` 值
+
+---
+
+## 12. 未来改进建议
+
+### 12.1 用户自定义
+
+允许用户在 UI 中自定义列配置：
+- 拖拽调整列顺序
+- 点击切换列显示/隐藏
+- 调整列宽后保存到配置
+- 重置为默认配置
+
+### 12.2 配置管理界面
+
+提供独立的配置管理页面：
+- 可视化编辑列配置
+- 预览配置效果
+- 导入/导出配置文件
+- 版本控制
+
+### 12.3 更多配置项
+
+扩展配置支持：
+- 列的对齐方式（左对齐/居中/右对齐）
+- 列的数据格式化
+- 列的排序功能开关
+- 列的过滤功能开关
+- 固定列（fixed: 'left' | 'right'）
+
+### 12.4 性能优化
+
+- 虚拟滚动：大量数据时只渲染可见行
+- 懒加载：分批加载数据
+- 请求合并：批量获取多个表格配置
+
+### 12.5 多租户支持
+
+- 不同用户/角色使用不同配置
+- 用户级别配置覆盖系统级别配置
+- 配置权限管理
+
+---
+
+## 13. 常见问题（FAQ）
+
+### Q1: 为什么选择端口适配器模式？
+
+**A**: 端口适配器模式提供了以下优势：
+1. **灵活性**：可以轻松切换配置源（本地/远程/数据库等）
+2. **可测试性**：可以注入 Mock 提供者进行单元测试
+3. **解耦**：业务逻辑不依赖具体的配置来源
+4. **扩展性**：新增配置源只需实现接口，无需修改现有代码
+
+### Q2: 为什么使用 props 传递配置而不是 Redux？
+
+**A**: 考虑因素：
+1. **职责分离**：配置获取是父组件的职责，表格组件只负责渲染
+2. **灵活性**：不同父组件可以传递不同的配置
+3. **测试简单**：测试时直接传入 Mock 配置即可
+4. **避免全局状态污染**：配置是组件级别的，不需要全局共享
+
+### Q3: 为什么有本地配置还需要远程配置？
+
+**A**: 两者各有用途：
+- **本地配置**：作为默认值和回退方案，确保系统在任何情况下都可用
+- **远程配置**：支持动态调整、多环境部署、用户自定义等高级功能
+
+### Q4: 如何添加新的表格配置？
+
+**A**: 只需两步：
+1. 在 `LocalColumnConfigAdapter.ts` 的 Map 中添加新表格的默认配置
+2. 在父组件中调用 `columnConfigService.getColumnConfig('新表格名')`
+
+### Q5: 配置失败会影响用户使用吗？
+
+**A**: 不会。系统有三层保障：
+1. 远程配置失败自动回退到本地配置
+2. 本地配置失败（理论上不会发生）返回空数组
+3. 空数组时表格显示所有列（向后兼容）
+
+---
+
+## 14. 参考资料
+
+### 14.1 设计模式
+
+- **端口适配器模式**（Ports and Adapters / Hexagonal Architecture）
+- **策略模式**（Strategy Pattern）
+- **单例模式**（Singleton Pattern）
+
+### 14.2 相关技术
+
+- [React useMemo](https://react.dev/reference/react/useMemo)
+- [TypeScript Generics](https://www.typescriptlang.org/docs/handbook/2/generics.html)
+- [Ant Design Table](https://ant.design/components/table-cn)
+
+### 14.3 项目内部文档
+
+- 测试方案：`docs/测试/表格列配置功能测试方案.md`
+- 其他实现文档：`docs/实现/`
+
+---
+
+## 15. 更新记录
+
+| 日期 | 修改人 | 修改内容 |
+|------|--------|----------|
+| 2025/10/10 | - | 创建文档，完整记录表格列配置功能实现 |
+
+---
+
+## 附录 A：完整代码示例
+
+### A.1 使用示例
+
+```typescript
+// 在任何需要表格配置的页面中
+import { useState, useEffect } from 'react';
+import { columnConfigService } from '@/config/tableColumns';
+import { ColumnConfig } from '@/config/tableColumns/types/columnConfig';
+
+const MyTablePage: React.FC = () => {
+  const [columnConfig, setColumnConfig] = useState<ColumnConfig[]>([]);
+
+  useEffect(() => {
+    columnConfigService
+      .getColumnConfig('worklist') // 或 'history'
+      .then(config => setColumnConfig(config.columns))
+      .catch(error => {
+        console.error('Failed to load column config:', error);
+        setColumnConfig([]); // 使用空配置作为回退
+      });
+  }, []);
+
+  return (
+    <MyTable 
+      columnConfig={columnConfig}
+      // ... 其他 props
+    />
+  );
+};
+```
+
+### A.2 自定义提供者
+
+```typescript
+import { IColumnConfigProvider } from '@/config/tableColumns';
+
+// 创建数据库提供者
+class DatabaseColumnConfigAdapter implements IColumnConfigProvider {
+  async getColumnConfig(tableName: TableName): Promise<TableColumnConfig> {
+    // 从数据库获取配置
+    const config = await database.getTableConfig(tableName);
+    return config;
+  }
+
+  async getAllColumnConfigs(): Promise<TableColumnConfig[]> {
+    return await database.getAllTableConfigs();
+  }
+
+  async isAvailable(): Promise<boolean> {
+    return await database.isConnected();
+  }
+}
+
+// 使用自定义提供者
+const customService = new ColumnConfigService(
+  new DatabaseColumnConfigAdapter(),  // 主提供者
+  new LocalColumnConfigAdapter()      // 回退提供者
+);
+```
+
+---
+
+## 附录 B：配置示例
+
+### B.1 最小配置
+
+```typescript
+{
+  tableName: 'worklist',
+  columns: [
+    { key: 'PatientID', visible: true, order: 1 },
+    { key: 'PatientName', visible: true, order: 2 }
+  ]
+}
+```
+
+### B.2 完整配置
+
+```typescript
+{
+  tableName: 'worklist',
+  columns: [
+    { 
+      key: 'PatientID', 
+      visible: true, 
+      order: 1, 
+      width: 120,
+      fixed: 'left'
+    },
+    { 
+      key: 'PatientName', 
+      visible: true, 
+      order: 2, 
+      width: 150
+    },
+    { 
+      key: 'StudyStatus', 
+      visible: true, 
+      order: 3, 
+      width: 100,
+      fixed: 'right'
+    }
+  ],
+  version: '1.0.0',
+  updatedAt: '2025-10-10T12:00:00Z'
+}
+```
+
+---
+
+**文档结束**