# 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. 运行新增测试和相关后端测试。
