需求名称：文档加解密功能（通用技术方案模板示例）
材料来源：通用技术方案模板-文档加解密示例.pdf（10 页）
整理日期：2026-09-29

一、需求背景
合同审查、文档解析、原文预览、结果导出等业务都会涉及用户文档的存储。合同文档通常包含
商业条款、金额、客户信息、个人信息等敏感内容。如果原始文件长期以明文方式保存在对象存储
或共享文件系统中，一旦出现存储介质泄露、越权访问或运维误操作，会带来较高的数据安全风险。
因此需要在现有文件存储链路中增加文档加解密能力：上传时加密落盘，读取时自动解密，对上层
业务尽量保持无感。

二、当前现状
1. 用户上传 Word、PDF 等合同文件。
2. 后端将文件保存到对象存储或共享文件系统。
3. 文档解析、OCR、合同审查、预览、下载等服务读取该文件。
4. 审查结果文件或带批注 Word 再次写入存储，供用户下载。
主要不足：
- 文件可能以明文落盘，存储层泄露风险较高。
- 多个业务模块可能直接读取底层存储路径，后续统一改造难度大。
- 历史明文文件已经存在，不能要求一次性全部迁移。
- 加密能力启用后应尽量不影响现有上传、预览、解析和下载流程。

三、设计目标
- 加密落盘：新上传或新生成的文档以密文形式存储。
- 自动解密：业务读取文件时自动获得明文流。
- 业务少改造：前端和文档处理业务尽量沿用现有调用方式。
- 兼容历史文件：已存在的明文文件仍可被正常读取。
- 支持灰度：通过配置开关控制是否对新增文件启用加密。
非目标：
- 不设计完整 KMS 平台，只预留密钥接入方式。
- 不做历史文件批量迁移。
- 不改变文档解析、OCR、审查、导出等业务逻辑。
- 不扩展到文档内容脱敏、权限审批等其他安全能力。

四、总体方案
在系统中新增统一的文档存储访问层 DocumentStorageService。业务模块不再直接读写底层文件
路径，而是通过该服务完成文件保存和读取。
写入时，判断加密开关是否开启。开启时对文件流加密并将密文写入存储；关闭时按原逻辑写入明文。
读取时，先读取文件头判断是否为系统加密文件。如果是密文则解密后返回明文流；如果是历史明文
则直接返回原文件流。
技术选型：AES-256-GCM 算法；文件头写入固定魔数 XMDC；每个文件生成独立 nonce；使用 GCM
auth tag 做完整性校验；密钥优先来自配置中心或 KMS，开发环境可用环境变量；灰度控制配置项
doc_encrypt.enabled。选择 AES-256-GCM 的原因：算法成熟、同时提供加密与完整性校验、支持
流式处理，适合文档上传、下载和后台解析场景。

五、核心流程
1. 文件上传加密流程：用户上传动作不变；上传接口接收文件后调用统一存储服务；存储服务获取
密钥、生成随机 nonce、执行文件流加密；加密后文件写入存储，数据库记录文件路径、加密状态、
算法版本和 key_id。
2. 文件读取解密流程：业务服务只通过 doc_id 读取文件，不直接拼接存储路径；存储服务根据文件
头魔数判断文件类型；密文文件解密后返回明文流；历史明文文件直接返回。
3. 后台任务处理流程：部分解析或格式转换组件依赖本地文件路径，可在任务目录生成临时明文文件，
任务结束后清理。临时明文只用于任务处理，不作为长期存储；任务目录与正式存储目录隔离；结果
文件重新通过统一存储服务写入。

六、模块拆分
- DocumentStorageService：统一文档读写入口，屏蔽底层加解密差异。
- Encryptor：实现 AES-256-GCM 加密和解密。
- KeyProvider：获取密钥或 key_id，后续可对接 KMS。
- FileHeaderCodec：生成和解析加密文件头。
- DocumentMetadataRepository：保存文件路径、加密状态、算法版本、key_id 等元数据。
- TempFileManager：管理任务处理过程中的临时明文文件。

七、数据设计
文件元数据表增加字段：doc_id、storage_path、file_name、file_size、encrypted、algorithm、
encryption_version、key_id、created_at。
密文文件头包含：magic（固定魔数 XMDC）、version、algorithm、key_id、nonce、auth_tag。

八、接口设计
- 上传接口：POST /api/documents（multipart/form-data），响应返回 doc_id、encrypted、file_name。
- 下载接口：GET /api/documents/{doc_id}/download；接口层校验用户是否有文件访问权限，调用
  DocumentStorageService.open(doc_id)，密文由服务端自动解密后返回，前端下载到的仍是原始格式文件。
- 内部读取接口：后台解析、预览、审查等服务统一使用 DocumentStorageService.open(doc_id)，
  返回明文文件流，或适用于必须读取本地路径组件的临时明文文件路径。

九、开发计划
方案设计 → 数据设计（增加文件加密元数据字段）→ 存储服务改造（新增统一文档读写入口）→
加密能力开发（文件加密、文件头写入、密文保存）→ 解密能力开发（文件头识别、密文解密、历史
明文兼容）→ 密钥接入（配置中心、环境变量或 KMS）→ 业务接入（上传、下载、解析、预览、导出
改为调用统一存储服务）→ 联调验证（上传、读取、解析、下载主链路）。

十、可行性说明
- 对现有业务影响小：加解密集中在统一存储服务，下游拿到的仍是明文流，核心逻辑不需要重写。
- 历史文件可兼容：通过文件头判断，无魔数按明文处理，避免一次性迁移。
- 支持渐进式启用：doc_encrypt.enabled 控制新增文件是否加密，即使开关关闭，读取链路仍保留
密文识别和解密能力。
- 后续扩展空间充足：文件头保留 version、algorithm、key_id，可支持密钥轮换、算法升级、多组织
不同密钥。
