OpenCollective平台财务表单API内部化技术解析

背景与需求

在OpenCollective平台中，财务表单处理一直依赖外部服务Dropbox Forms。为提升系统自主性和数据安全性，开发团队决定将财务表单功能内部化，构建自主可控的API服务。这一改造涉及数据库结构调整、文件存储优化和权限控制等多个技术层面。

技术实现方案

数据库层改造

核心改动是在LegalDocuments表中新增service字段，用于区分表单来源（opencollective自主服务或dropbox-forms外部服务）。这种设计保证了新旧系统可以平稳过渡，同时支持渐进式迁移。

考虑到数据安全与查询效率的平衡，方案建议对非关键字段（如submitterType、formType）采用明文存储，便于快速检索和展示，而重要信息则保持加密存储。

文件处理流程

1. PDF生成：通过专用服务将表单数据动态生成PDF文档
2. 安全存储：使用改造后的DOCUMENTS_AWS_S3_BUCKET（原EXTERNAL_AWS_S3_BUCKET）进行文件存储
3. 密钥管理：重构了文档加密密钥体系（原external.documentEncryptionKey）

API接口设计

新增submitLegalDocument突变(Mutation)接口，主要功能包括：

• 参数验证：检查账户权限和文档状态
• 业务规则校验：确保不会重复提交已接收(RECEIVED)的文档
• 文件处理流水线：集成PDF生成→S3上传→数据加密全流程

查询接口扩展了Account类型的legalDocuments字段，支持按状态过滤：

• REQUESTED：识别待处理表单
• RECEIVED：获取历史提交记录

系统兼容性保障

项目采用双重保障机制确保平滑过渡：

1. 功能开关：通过feature flag控制新功能的渐进式发布
2. 并行支持：维持旧系统运行直至所有现有表单处理完成

安全考量

方案特别强调数据安全处理：

• 重要字段加密存储
• 严格的权限校验（仅账户管理员可操作）
• 密钥体系独立管理
• 存储桶访问权限隔离

该技术方案不仅提升了系统自主性，也为后续财务管理功能扩展（如基础表单类型支持）奠定了坚实基础。通过模块化设计和渐进式迁移策略，确保系统改造过程对终端用户透明无感知。