# 01-需求说明

> 创建日期：2026-08-22
> 最近更新：2026-08-31
> 状态：进行中

## 一、项目目标

用 Python 实现一个后端服务，面向**荷兰 VAT/EPR 申报文档自动化**，替代/迁移原 PHP 系统（法国 VAT 注册、EPR 注册）的文档生成能力。核心能力：

1. 读取 SaaS 业务库（SQL Server），支持双库（源/目标）读写分离。
2. 提供 API 接口访问。
3. 企业文档自动生成：按国家模板进行占位符替换，OCR 补充字段，插入证件照片，合并转 PDF，上传 COS，回写状态。
4. 文件格式转换（docx/doc ↔ pdf）。

## 二、已确认需求

| 项 | 结论 |
| --- | --- |
| 源数据库 | SQL Server（SaaS 业务库，只读；表：`VATBusinessRecord`、`VATRegInfo`、`Base_Customer_Company`、`Base_AnnexesFile`、`Base_Sales_Platform_Shop`） |
| 目标数据库 | 本系统所有（写生成记录，表：`render_record`）；未配置时 SQLite 兜底 |
| 双库关系 | 源/目标（SOURCE/TARGET）读写分离，各自独立连接池 |
| 模板类型 | Office：Word(.docx)、Excel(.xlsx)，外加 PDF；按国家分目录（at/nl） |
| 替换方式 | 占位符：`<<占位符>>`、`{{占位符}}`、`((占位符))`、`《占位符》`；WEEE 模板自动勾选 ☐/☒ 分类 |
| OCR | 腾讯云 OCR（身份证正反面、营业执照），补充「签发城市」「法人性别」；失败不阻断生成 |
| 对象存储 | 腾讯云 COS，上传生成文件并回写 `Base_AnnexesFile` |
| PDF 生成 | docx/xlsx → pdf 依赖本机 Microsoft Office + pywin32；pdf → docx/doc 用 pdf2docx |
| 鉴权 | 暂不需要，后期再加 |

## 三、技术选型

- Web 框架：FastAPI（自动生成 Swagger 文档）
- ORM：SQLAlchemy 2.x（源/目标双引擎 + 连接池）
- 校验：Pydantic v2 + pydantic-settings
- 模板：python-docx / docxcompose / openpyxl / pypdf
- OCR / 存储：tencentcloud-sdk-python-ocr / cos-python-sdk-v5
- 图片 / PDF：pymupdf（PyMuPDF）/ Pillow / pdf2docx
- 数据库驱动：pyodbc（SQL Server）、pymysql、psycopg[binary]
- HTTP 下载：httpx
- 服务器：uvicorn

## 四、后续扩展点（预留）

- SaaS 回写（`render.py` / `ocr_enterprise.py` 中 TODO 待补）
- 更多国家模板与占位符映射（当前 `countries.py` 仅 AT/NL/FR/GB/DE）
- JWT / API Key 鉴权
- Redis 缓存
- 定时任务
- 数据库迁移（Alembic）
- 更多占位符形式与 PDF 全文生成