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

docs/project/frontend-backend/README.md

@@ -14,6 +14,7 @@
 | `frontend-to-backend-api-requests.md` | 前端提醒后端需要增加或补齐的接口，包含建议入参和返参草案。 |
 | `debug-eml-page-integration-guide.md` | Debug EML 页面前端对接指南，包含页面结构、上传接口、响应展示、错误处理和安全注意事项。 |
 | `../backend-time-design.md` | 时间设计说明，包含数据库 UTC、API `Z` 时间、酒店时区展示和本地日期筛选规则。 |
+| `../security-access-control-boundary.md` | 接口暴露、权限和审计边界总表，前端判断普通业务、系统管理、Debug 和第三方接口边界时必须参考。 |
 
 ## 3. 当前字段来源分工
 
@@ -39,10 +40,12 @@
 | --- | --- | --- |
 | SuperAgent HTTP 对外总契约 | `docs/project/integrations/superagent-api-contract.md` | 权威契约，包含查询上下文、对象详情、邮件会话任务、邮件会话正文、任务结果通知和统一 HMAC 规则。 |
 | SuperAgent MCP tools | `docs/project/integrations/superagent-mcp/README.md` | MCP 对外交付资料包，tools 字段语义应跟随 SuperAgent HTTP 对外总契约。 |
+| 接口暴露、权限和审计边界 | `docs/project/security-access-control-boundary.md` | 前端判断普通业务、系统管理、Debug、第三方接口、权限码和敏感数据边界的总表。 |
 | SuperAgent 任务结果入站接口 | `docs/project/requirements/M002-superagent-task-result-api-contract.md` | 阶段记录，用于理解 M002 接收 AI 结果的落地细节；如与总契约冲突，以总契约为准。 |
 | SuperAgent 查询上下文接口 1、2 | `docs/project/requirements/M002-ai-query-minimal-fields.md` | 阶段记录，用于理解接口 1、2 的最小字段实现；如与总契约冲突，以总契约为准。 |
 | 订单任务主流程 V3 | `docs/project/requirements/M002-order-task-workflow-v3.md` | 当前开发基线，基于 0711 P0 冻结基线和 0712 P0.1 Parent Group 修订，覆盖 S10/S99、40 路由、方案 C、type-known manual review 同卡解阻和 fail-closed。 |
 | 任务卡字段控件契约 V1 | `docs/project/requirements/M002-task-field-control-contract-v1.md` | 后端已返回 `fields[]` 控件元数据，规定人工复核控件复用和前后端边界；前端待接入。 |
+| Manual Invoice 手工开票生成 | `docs/project/requirements/M009-manual-invoice-generation-v1.md` | 当前有效；后端 CP2 已支持无订单 / 无任务手工填写字段、填 Excel 模板、转 PDF、OSS 输出和生成记录。 |
 | 订单任务主流程 V2 | `docs/project/requirements/M002-order-task-workflow-v2.md` | 已实现阶段记录，保留用于理解当前代码中的 S000/S999、订单任务流转和 OPERA 模拟骨架。 |
 | 后端 checkpoint | `docs/project/requirements/M002-backend-checkpoint-plan.md` | 阶段记录，用于理解后端拆分和验收。 |
 | 前端可用接口与待补接口 | `docs/project/frontend-backend/frontend-to-backend-api-requests.md` | 前后端协作清单，已区分可用、后置和历史候选路径，不替代后端权威契约。 |
@@ -57,6 +60,7 @@
 - 用户 / 权限底座后端 CP1 已完成；前端登录页、动态菜单、管理后台和业务审计 actor 全量迁移仍后置。
 - 真实 OPERA / OHIP 接入后置；当前仅有 OPERA 模拟骨架。
 - 任务卡字段控件契约 V1 后端第一版已完成，任务详情 `fields[]` 已返回 `control_type/edit_scope/write_target/options_source/raw_readonly/control_hint`；前端后续按契约接入，不要硬编码 PMS 房型、Rate Code 或未冻结枚举。
+- Manual Invoice 第一阶段按 M009 推进：后端已提供 `POST /api/reservation/invoices/manual-generations`，页面可以不依赖订单或任务，用户手工填写 / 选择字段后由后端业务接口填充 Excel 模板并生成 PDF；前端不得直接调用 M008 的调试上传转换接口来完成业务开票。
 
 ## 6. 前端开发注意事项
 

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 联调造数，不是生产业务页面接口；访问口令不能进入前端代码。