hyb-oa/.trellis/tasks/05-28-business-attachment-governance-v1/design.md

业务附件受控入库 V1 设计

实施策略

本轮采用“增强现有附件模型 + 共享常量/校验 + 下载审计”的方式，不新建独立文件中心。

原因：

• 现有业务已经有报销附件、采购附件、付款回单附件和票据池，直接增强可降低迁移风险。
• 统一大表会牵涉跨业务数据迁移、权限重写和前端重构，当前 V1 不需要一次性完成。
• 先把状态、敏感级别、附件类型和下载审计打齐，后续如需统一 business_attachments 视图或表，再基于真实使用频率演进。

数据设计

统一字段

优先给已有业务附件表补字段：

• governance_status：附件治理状态，默认 approved 或业务现状兼容值。
• sensitivity_level：敏感级别，默认 internal。
• attachment_type：附件类型，默认 other。
• reviewed_by / reviewed_at / review_note：复核信息。
• archived_by / archived_at / archive_note：归档信息。
• download_policy：下载策略，默认 standard。

如果某表已有相似字段，则复用或做映射，不重复制造语义。

迁移与回滚口径

本轮迁移只新增列和索引，不改写既有附件文件、不迁移存储位置、不删除历史数据。

如上线后必须回滚应用代码，旧代码可忽略新增列继续运行；如必须回滚数据库结构，先确认没有依赖这些字段的新代码在线，再按新增索引和新增列的反向顺序删除。本轮不执行数据库重置、不重写迁移历史。

下载审计

优先复用现有审计日志机制；若现有日志无法表达附件下载，则新增轻量附件下载审计表，字段至少包括：

• 操作者
• 业务类型和业务 ID
• 附件模型/附件 ID
• 动作：preview/download
• 原因或用途
• IP/User-Agent 摘要
• 时间

API 设计

V1 不强制新建独立 /business-attachments API。先在现有业务 API 上增强：

• 上传接口接受可选 attachmentType、sensitivityLevel。
• 列表/详情接口返回治理字段。
• 下载接口接受可选 reason，敏感级别较高时要求填写。
• 服务端统一调用附件治理 helper 做状态、敏感级别和下载审计处理。

前端设计

遵循现有页面，不做大视觉重构：

• 附件列表增加紧凑标签：状态、类型、敏感级别。
• 下载入口对敏感附件提示填写用途或原因。
• 普通用户不展示无权限动作；服务端仍做最终校验。
• 企业微信消息仍只放 OA 链接和脱敏摘要，不携带附件。

权限边界

• 业务负责人、审批人、财务、合同/项目负责人按业务关系查看原文附件。
• 普通员工只能看自己相关业务或授权协作范围。
• 管理员不自动获得业务审批权；技术排障需最小化授权并留痕。
• 源码、密钥、Secret、完整配置、完整账号凭据和完整本地路径禁止入库。

分批落地

1. 后端 schema/helper/migration/test。
2. 报销、采购、付款回单 API 兼容增强。
3. 前端附件列表展示治理字段。
4. 下载审计与敏感下载原因。
5. 通过验证后再评估合同/项目专用附件入口和 EA-DOC 自动索引。

本轮实现记录

• 已增强 PurchaseAttachment、ReimbursementAttachment、PaymentBatchReceiptAttachment，补齐治理状态、敏感级别、附件类型、复核/归档和下载策略字段。
• 已新增共享附件治理 helper，统一上传字段解析、默认值映射、前后端展示标签和敏感下载用途判断。
• 已复用 AuditLog 记录报销附件、采购附件和付款回单下载；付款回单默认 confidential + reason_required，下载必须填写用途。
• 已在报销详情、移动报销详情、采购详情、移动采购详情和付款批次回单区显示紧凑治理标签。