ctms/docs/plans/2026-05-27-etmf-design.md

eTMF Module Design

背景

当前系统已有文件版本管理能力，包括 documents、document_versions、文件上传下载、分发、回执、权限和审计。/etmf 路由目前是占位页，并已复用 documents:read 权限。

eTMF 第一阶段需要同时满足两个目标：

• 合规归档视图：按 TMF 标准目录检查项目级和中心级文件归档状态。
• 文件管理入口：项目成员可以按目录上传、查找、下载、维护版本。

推荐方案

采用“TMF 目录树模板 + 文档元数据挂载”模型。前端呈现为目录结构，但后端不把 eTMF 当作真实文件夹系统，而是用目录节点表达归档标准，用现有文档实体承载文件和版本。

该方案保留文件夹式使用体验，同时支持合规检查、缺失项统计、中心维度对比和后续报表扩展。

核心模型

eTMF 目录节点

新增 etmf_nodes 表，表达项目内 eTMF 目录树。

建议字段：

• id
• study_id
• parent_id
• code
• name
• description
• scope_type: GLOBAL 或 SITE
• required
• expected_doc_type
• sort_order
• is_active
• created_at
• updated_at

约束：

• 同一项目、同一父节点下 code 唯一。
• 节点软停用，不物理删除，避免历史文档失去归档上下文。
• 第一阶段不做自定义模板版本管理，只提供项目内节点树。

文档挂载

复用现有 documents 表，新增 etmf_node_id 外键。

规则：

• documents.etmf_node_id 为空表示普通文件版本管理文档。
• documents.etmf_node_id 非空表示该文档归档到 eTMF 节点。
• 项目级节点对应 documents.site_id = null。
• 中心级节点对应 documents.site_id 有值。

第一阶段不新增独立 eTMF 文件表，避免重复存储文件元数据和版本逻辑。

状态计算

eTMF 状态优先通过查询计算，不在第一阶段持久化冗余状态。

节点状态：

• NOT_REQUIRED: 非必需节点且无文档。
• MISSING: 必需节点没有匹配文档。
• UPLOADED: 有文档但没有生效版本。
• EFFECTIVE: 至少一个匹配文档存在当前生效版本。
• INACTIVE: 节点停用。

中心级节点按中心分别计算状态。项目级节点只计算项目维度。

后端接口

新增 eTMF API，挂载在现有 v1 router 下。

建议接口：

• GET /api/v1/etmf/tree?study_id=... 返回节点树、每个节点汇总状态和文档数量。
• GET /api/v1/etmf/nodes/{node_id}/documents?site_id=... 返回节点下文档列表，复用 DocumentSummary。
• POST /api/v1/etmf/nodes 创建节点。
• PATCH /api/v1/etmf/nodes/{node_id} 更新节点名称、排序、必需性、适用范围。
• POST /api/v1/etmf/nodes/{node_id}/documents 在节点下创建文档，本质调用现有 create_document，自动带入 etmf_node_id。

第一阶段不做节点移动和批量导入，除非后续确认需要。

前端体验

替换当前 EtmfPlaceholder.vue。

页面结构：

• 顶部工具栏：中心筛选、状态筛选、刷新、新增目录、新增文档。
• 左侧：eTMF 目录树，显示节点名称、编码、状态标记、缺失提示。
• 中间：当前节点文档列表，展示标题、类型、范围、中心、当前版本、更新时间、操作。
• 右侧：节点详情，展示必需性、适用范围、完成状态、缺失说明、中心完成度摘要。

交互规则：

• 点击目录节点加载该节点文档。
• 创建文档时默认带入当前节点和当前中心筛选。
• 文档详情和版本维护复用现有文档详情页。
• 中心级节点在选择中心后展示该中心归档状态；未选中心时展示中心完成度汇总。

权限和审计

第一阶段复用现有文档权限：

• 查看：documents:read
• 新建文档或目录：documents:create
• 更新文档版本或节点：documents:update
• 删除或停用：documents:delete

审计：

• 文档创建、版本上传、下载、删除继续复用现有文档审计。
• 节点创建、更新、停用新增 ETMF_NODE_CREATED、ETMF_NODE_UPDATED、ETMF_NODE_DISABLED 审计动作。

测试策略

后端：

• 节点树接口按项目隔离。
• 必需节点缺失状态计算正确。
• 中心级节点按 site_id 计算状态。
• CRA 只能看到自身中心范围内的中心级文件。
• 节点下创建文档会写入 etmf_node_id。

前端：

• /etmf 不再展示占位页。
• 节点树加载、节点选择、中心筛选、状态展示。
• 新建文档时携带当前节点。
• 路由权限继续使用 documents:read。

取舍

第一阶段明确不做：

• 电子签名。
• 复杂审批流。
• 模板版本发布。
• 物理文件夹移动。
• 批量导入 TMF 标准目录。

这些能力可以在基础目录树和文档挂载稳定后追加。