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

docs/superpowers/plans/2026-07-17-m009-manual-invoice-backend.md

@@ -0,0 +1,29 @@
+# M009 Manual Invoice 后端 CP2 实现计划
+
+## 目标
+
+落地 `POST /api/reservation/invoices/manual-generations`，支持手工填写 Proforma Invoice 后生成 Excel、转换 PDF、上传 OSS，并写入生成记录和审计。
+
+## 范围
+
+- 新增 `workflow_reservation_invoice_generation` 表，记录生成状态、请求 payload、计算金额、Excel / PDF OSS Key、创建人和安全错误摘要。
+- 新增 Reservation Invoice 后端模块，保持 `control`、`service`、`service.impl`、`domain`、`mapper`、`repository`、`common.request/result/dto/enums` 分层。
+- 新增权限码 `RESERVATION_INVOICE_GENERATE`，加入预订操作员和系统管理员授权。
+- 使用受控 Excel 模板 `templates/reservation-invoice/proforma-invoice-v1.xlsx`，由后端写入用户字段和金额公式。
+- 复用 `ExcelToPdfConverter` 和 `ObjectStorageService`，不让前端直接调用 M008 调试转换接口。
+- 接口要求 Bearer 登录、权限码和酒店访问权；`task_id` / `order_id` 第一版可为空，传入时校验对象酒店归属。
+
+## 不做
+
+- 不做发票历史列表和详情。
+- 不做任务 / 订单预填接口。
+- 不做客户联系人目录维护后台。
+- 不做真实财务入账、收款核销、税务发票编号。
+- 不做前端页面。
+
+## 验证
+
+1. 新增 MockMvc 测试覆盖成功生成、缺少登录、缺少权限、字段校验失败。
+2. Mock `ExcelToPdfConverter` 和 `ObjectStorageService`，确认传入转换的是后端生成的 xlsx 字节，PDF 上传 Key 使用 `reservation-invoices/{hotel_id}/...`。
+3. 校验生成记录入库，响应返回 `invoice_generation_id`、`pdf_url`、`pdf_object_key`、`generated_excel_object_key` 和服务端计算 totals。
+4. 运行新增测试和相关后端测试。