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

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