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

docs/project/frontend-backend/backend-to-frontend-notes.md

@@ -377,6 +377,28 @@ hotel_id: 可选；用于 OSS 对象路径分组
 - `DOCUMENT_CONVERSION_TIMEOUT` / `DOCUMENT_CONVERSION_FAILED` 通常需要后端排查 LibreOffice、字体、文件格式或临时目录权限。
 - CP2 不会创建转换任务记录，也不会自动处理邮件附件；邮件附件自动派生 PDF 是 M008 后续 checkpoint。
 
+### 5.11 Manual Invoice 手工开票页面接入方向
+
+M009 后端 CP2 已实现：页面可不依赖订单或任务，用户手工填写 / 选择字段后由后端填充 Excel 模板、转换 PDF 并上传 OSS。
+
+前端注意：
+
+- 当前 `invoice.html` 可以作为交互原型和控件参考，但不能直接作为生产页面上线。
+- 第一阶段入口建议是独立页面，例如 `/reservation/invoices/new` 或 `/invoices/new`；不要求必须从任务详情或订单详情进入。
+- 无订单 / 无任务时，页面按 `source_type=MANUAL` 提交，`task_id` 和 `order_id` 可以为空。
+- 从任务进入时，后续可以使用 `GET /api/reservation/tasks/{taskId}` 的 `fields[]`、草稿或确认 payload 预填；从订单进入时，需要明确选择具体任务或提示仅使用订单摘要，避免一个订单多任务时字段来源不清。
+- Company、Attention、Address、Tel、Email、Booking Date 第一阶段可以按“选择 + Manual 手填”控件处理。
+- Company、Attention、Address、Tel、Email 是一组收件方联系人档案，不是五个互相独立字段；选择 Company 后应刷新 Attention 候选，选择 Attention 后应带出 Address、Tel、Email。Booking Date 展示在同一区域，但不属于联系人档案，应作为 `document.booking_date` 独立提交。
+- 第一阶段已确认三组客户 / 旅行社种子数据：`LIAN_TAI` / `LIAN TAI TRAVEL (THAILAND) CO., LTD.` + `Khun Ann`；`QBD` / `Q.B.D. TRAVEL GROUP CO., LTD` + `Jitdanun Panaphuchong`；`HANATOUR` / `HANATOUR TD CO., LTD.` + 7 个联系人。完整数据以 `docs/project/requirements/M009-manual-invoice-generation-v1.md` 为准。
+- Room Type、Room Rate、Extra Bed 建议也预留“选择 + 可手填 / 可覆盖”能力，后续接 PMS 房型、Rate Code 或价格配置。
+- Amount、Sub-Total、VAT、Total 是只读计算字段；前端可展示预览，但最终金额以后端计算和模板公式为准。
+- 酒店名称、Tax ID、法人主体、银行账户、Logo 和固定付款文案不应作为每张 Invoice 的手工输入；第一阶段可由模板或酒店发票配置提供。
+- 正式业务生成接口为 `POST /api/reservation/invoices/manual-generations`，需要 Bearer token、酒店访问权和 `RESERVATION_INVOICE_GENERATE` 权限。
+- 第一版后端只支持 `source_type=MANUAL`，`task_id` / `order_id` 可以为空；传入时后端会反查对象所属酒店；如果两者同时传入，任务必须属于该订单，否则返回 `RESERVATION_INVOICE_CONTEXT_MISMATCH`。
+- 第一版后端最多支持 10 条费用明细；超过 10 条会返回 `RESERVATION_INVOICE_VALIDATION_FAILED`。
+- 第一版暂未提供 Invoice 历史列表、详情查询、任务 / 订单预填接口和客户联系人目录查询接口；前端客户 / 联系人候选可先按 M009 文档中的种子数据实现。
+- 前端不得直接调用 `POST /api/system/document-conversions/excel-to-pdf` 来完成业务开票；该接口是 M008 调试 / 后台工具能力，受 access key 控制，不具备业务开票审计和权限边界。
+
 ## 6. 不给前端直接调用的接口
 
 - `POST /api/system/reservation/demo-data` 只用于 dev/test 联调造数，不是生产业务页面接口；访问口令不能进入前端代码。