实现手工发票生成后端接口

docs/project/go-live-notes.md

@@ -19,6 +19,7 @@
 - SuperAgent 查询上下文接口 1、2：支持 HMAC 鉴权的订单上下文查询和对象详情查询。
 - Debug EML 上传到 SuperAgent 调试链路：受控上传 `.eml`、转存阿里云 OSS、写入 SourceMessage Inbox、调用 SuperAgent Open API 并返回调试结果。
 - Excel 转 PDF 手动上传接口：受控上传 `.xls` / `.xlsx`，通过 LibreOffice headless 转 PDF 后上传阿里云 OSS 并返回 PDF URL。
+- Reservation Manual Invoice 后端生成接口：登录用户可通过 `POST /api/reservation/invoices/manual-generations` 手工生成 Proforma Invoice，后端填充受控 Excel 模板、转 PDF、上传 OSS，并写入生成记录和业务审计。
 - 登录权限底座：支持用户名密码登录、登出、当前用户上下文、数据库 session token、可访问酒店、权限码和可见菜单。
 - 系统管理后台 V1：支持用户、角色权限、菜单、酒店和管理操作审计的受控维护接口与前端页面。
 
@@ -35,7 +36,7 @@
 - 现有业务接口强制登录和强制权限拦截。
 - 业务审计 actor 全量迁移到当前登录用户。
 - Debug EML 上传链路不属于生产普通业务页面能力，生产默认关闭；即使已有登录权限，也不要开放给普通用户。
-- Excel 转 PDF 当前只完成手动上传后端接口；邮件附件自动转换、持久化转换任务和 worker 尚未实现。生产默认关闭，启用前必须确认 LibreOffice、字体、OSS、临时目录和访问口令。
+- Excel 转 PDF 当前只完成手动上传后端接口和 M009 Manual Invoice 内部复用；邮件附件自动转换、持久化转换任务和 worker 尚未实现。生产启用前必须确认 LibreOffice、字体、OSS、临时目录和访问口令。
 
 ## 2. 上线前必须确认
 
@@ -223,6 +224,10 @@ SourceMessage 原文和邮件会话完整正文已迁移到登录权限体系：
 - 当前接口只支持 `.xls` / `.xlsx`，不支持 `.xlsm`；后端会校验扩展名和文件头，改后缀的非 Excel 文件会返回受控错误。
 - PDF 上传到阿里云 OSS，返回 `pdf_url`、`object_key`、`pdf_file_name`、`pdf_size_bytes` 和 `duration_millis`。
 - CP2 不落库，不提供转换历史查询；如果需要自动处理邮件附件，应先进入 M008 后续持久化任务和 worker checkpoint。
+- M009 Manual Invoice 不调用上述调试接口，也不使用 `X-TH-Hotel-Document-Conversion-Key`；它通过登录 Bearer token、`RESERVATION_INVOICE_GENERATE` 权限和后端内部转换 Adapter 生成 PDF。
+- M009 Manual Invoice 当前模板资源为 `server/src/main/resources/templates/reservation-invoice/proforma-invoice-v1.xlsx`，部署包必须包含该资源。
+- M009 Manual Invoice 会写入 `workflow_reservation_invoice_generation`，上线前需确认 Flyway 已执行到 V22。
+- M009 Manual Invoice 失败记录也可能保留已上传成功的 Excel / PDF object key；排查或清理 OSS 生成物时应以生成记录为主，不只看 `SUCCEEDED` 状态。
 
 ## 4. 数据库上线注意事项
 
@@ -253,6 +258,10 @@ SourceMessage 原文和邮件会话完整正文已迁移到登录权限体系：
 
 - `server/src/main/resources/db/migration/V20__create_superagent_dispatch_run.sql`
 
+当前 M009 Manual Invoice 相关 migration：
+
+- `server/src/main/resources/db/migration/V22__create_reservation_invoice_generation.sql`
+
 当前 M003 登录权限相关 migration：
 
 - `server/src/main/resources/db/migration/V9__create_identity_access_hotel_menu.sql`
@@ -268,6 +277,7 @@ SourceMessage 原文和邮件会话完整正文已迁移到登录权限体系：
 - 目标数据库为空库或 Flyway history 与当前代码一致。
 - 如果某个环境已经在缺少 V10 的临时提交上执行过 V11 / V12，不能直接用默认 Flyway 策略补跑 V10；应先重建测试库，或按运维窗口明确 out-of-order / repair 策略。
 - V21 会为 `workflow_reservation_order` 增加 `latest_activity_at`，并按订单更新时间和历史任务最新来源 / 创建时间回填一次；上线后订单列表依赖该字段排序，不再在列表查询时聚合全量任务。发布后需要确认 Flyway 已执行到 V21，且订单列表能按最新业务活动倒序返回。
+- V22 会新增 `workflow_reservation_invoice_generation`，用于记录 Manual Invoice 生成状态、Excel / PDF OSS 对象、金额摘要和安全错误摘要；发布后需要确认 `RESERVATION_INVOICE_GENERATE` 权限已由启动同步写入平台权限表，预订操作员或目标角色已拥有该权限。
 - MySQL 版本满足项目要求，默认使用 MySQL 8.0+。
 - migration 在 UAT 或测试库已经跑过。
 - 表和字段中文注释能正常创建。