# 当前项目专属文档

本目录保存只适用于当前项目的业务背景、架构边界、外部系统约束和实现决策。

这些文档可以作为后续项目参考，但不应整份复制到新项目。新项目可复用内容应优先沉淀到 `docs/import/reusable/`。

## 文档状态约定

- `当前有效`：后续开发和联调优先按该文档执行。
- `权威契约`：同类接口或规则出现重复描述时，以该文档为准。
- `阶段记录`：记录某个 checkpoint 的落地细节，可以辅助理解，但不应覆盖当前有效文档。
- `历史参考`：保留早期讨论背景；若与当前有效文档冲突，以当前有效文档为准。
- `草案`：需求或方案尚未完全落地，开发前需要再次确认。

## 核心入口

| 文档 | 状态 | 中文说明 |
| --- | --- | --- |
| `../../AGENTS.md` | 当前有效 | 项目协作入口，记录 agent 工作方式、分支、目录、前后端边界、安全和测试要求。 |
| `../../CONTEXT.md` | 当前有效 | 项目长期上下文入口，记录产品目标、技术栈、系统组成、业务领域和外部系统边界。 |
| `../../PROJECT_STATE.md` | 当前有效 | 项目当前状态入口，记录当前 checkpoint、优先级、Known Issues 和 Next Steps；允许高频更新。 |
| `../../README.md` | 当前有效 | 项目根说明，记录目录、启动命令、健康检查、Debug EML 和 MCP 基础说明。 |
| `ai-native-adoption.md` | 当前有效 | 本项目采用 AI-NSES 的路径说明，记录标准目录与当前目录的映射关系。 |
| `backend-development-guidelines.md` | 当前有效 | 当前项目后端专属规范。 |
| `backend-time-design.md` | 当前有效 | 当前项目时间设计说明，记录数据库 UTC、API `Z` 时间、酒店时区展示和本地日期边界。 |
| `security-access-control-boundary.md` | 当前有效 | 当前项目接口暴露、权限码、酒店隔离和审计边界总表；新增或修改接口时必须同步。 |
| `frontend-development-guidelines.md` | 当前有效 | 当前项目前端专属规范。 |
| `frontend-backend/README.md` | 当前有效 | 前后端协作入口，记录接口契约来源、字段白名单和当前后置事项。 |
| `go-live-notes.md` | 当前有效 | 当前项目上线注意事项，记录上线前检查、环境变量、安全、AgentBus、验证和回滚。 |

## AI-NSES 与可复用规范

| 文档 | 状态 | 中文说明 |
| --- | --- | --- |
| `../import/reusable/ai-native-software-engineering-standard.md` | 当前有效 | 可复制到其他项目的 AI-NSES 通用标准，定义项目文档结构、文档职责、Feature 生命周期和 AI 工作原则。 |
| `../import/reusable/ai-native-templates/README.md` | 当前有效 | AI-NSES 模板目录索引，包含 AGENTS、CONTEXT、PROJECT_STATE、Domain、Workflow、ADR、Spec 和 Architecture 模板。 |
| `../import/reusable/README.md` | 当前有效 | 可复用迁移规范总索引。 |

## 需求与方案

| 文档 | 状态 | 中文说明 |
| --- | --- | --- |
| `requirements/M001-source-message-inbox-prd.md` | 当前有效 | M001 邮件来源入口 PRD，记录 AgentBus 邮件 JSON 入库、历史查询、原文读取和媒体引用边界。 |
| `requirements/M002-order-task-workflow-v1.md` | 历史参考 | M002 订单任务主流程 V1，已由 V2 承接，保留用于理解早期流程。 |
| `requirements/M002-order-task-workflow-v2.md` | 阶段记录 | M002 订单任务主流程 V2，记录当前已阶段实现的 AI 过渡层、S000/S999 兼容、订单任务流转、任务确认和 OPERA 模拟骨架。 |
| `requirements/M002-order-task-workflow-v3.md` | 当前有效 | M002 订单任务主流程 V3，基于 2026-07-11 P0 冻结基线和 2026-07-12 P0.1 Parent Group 修订，记录 S10/S99、40 路由、方案 C、type-known manual review 同卡解阻和 fail-closed 边界。 |
| `requirements/M002-task-field-control-contract-v1.md` | 当前有效 | M002 任务卡字段控件契约 V1，记录任务详情 `fields[]` 控件元数据、人工复核控件复用和前后端开发边界。 |
| `requirements/M002-v4-agent-callback-field-contract.md` | 当前有效 | M002 V4 Agent 回调字段契约，基于 2026-07-18 业务基线和最新答复，冻结 `source_message`、`order_contexts`、`message_events`、订单级 Basic Information、六类 Event、S10/S99 和校验口径；后端已完成 V4 入站解析、持久化、查询、确认、复核和当前酒店数据库目录校验。 |
| `requirements/M002-v4-order-task-card-domain-model-cp2.md` | 当前有效 | M002 V4 CP2 订单任务与多卡领域模型设计，并记录 CP3-CP8 表结构、入站写入、查询、确认、复核和目录校验已落地状态；CP11 已完成 DB 目录与 lookup API，CP12 已完成前端 lookup 接入，CP13 已完成目录管理后台 CP1，CP14 已完成订单列表 V4 继续处理入口，CP15 已完成 V4 业务审计查询，CP15.1 已完成订单详情 V4 总览后端补齐，当前已停止 V4 普通业务双写旧 `workflow_reservation_task`，并已完成 Room Information 后端展示模型和前端业务化展示第一版，以及 Rooming List 确认自动 DEF 后端联动；已补 OWNER RATE Room Type / Rate Code 目录口径、Payment 附件预览、Rooming List 事项确认卡、V4 复核态卡片交互和可编辑字段白名单文档口径；开发阶段不维护 V2/V3 旧任务兼容，测试数据可重建，生产迁移策略后置。 |
| `requirements/M002-v4-real-catalog-lookup-api-design.md` | 当前有效 | M002 V4 真实目录与 Lookup API 设计及 CP11 / CP13 CP1 实现记录，记录 Account、Market、Source、Room Type、Rate Code 从固定种子导入数据库、前端 lookup API、目录管理后端接口、权限、缓存后置、PMS / OPERA / OHIP 同步后置和失败兜底；已记录 OWNER RATE `RATECODE (2)` 只读整理结论：Room Type 第一阶段收敛为 `RM2`、`RM3`、`RM4`、`SU1`、`SU2`、`SU3`，Rate Code 第一阶段暂不建立 Account 适用关系，Q.B.D / LIAN TAI 清单作为酒店级目录候选。 |
| `requirements/M002-v4-test-machine-smoke-checklist.md` | 当前有效 | M002 V4 测试机冒烟清单，覆盖登录、酒店权限、V4 工作台、订单任务详情、lookup、确认、复核解阻、S10/S99 ack、订单详情 V4 时间线和目录管理 CP1 排查点。 |
| `requirements/M002-superagent-task-result-api-contract.md` | 阶段记录 | M002 SuperAgent 任务结果入站接口契约阶段记录；对外总契约以 `integrations/superagent-api-contract.md` 为准。 |
| `requirements/M002-ai-query-minimal-fields.md` | 阶段记录 | M002 SuperAgent 查询上下文接口 1、2 最小字段落地记录；对外总契约以 `integrations/superagent-api-contract.md` 为准。 |
| `requirements/M002-backend-data-model-design.md` | 阶段记录 | M002 后端数据模型设计，记录 AI 过渡层、订单、任务、任务卡、审计和 OPERA 模拟结果表。 |
| `requirements/M002-backend-checkpoint-plan.md` | 阶段记录 | M002 后端 checkpoint 计划，记录后端实现拆分、交付物和验收标准。 |
| `requirements/M003-identity-access-hotel-menu-v1.md` | 当前有效 | M003 登录、权限、酒店和动态菜单底座方案。 |
| `requirements/M004-debug-eml-superagent-upload-v1.md` | 当前有效 | M004 Debug EML 上传 SuperAgent 调试方案。 |
| `requirements/M005-hotel-context-unification-plan.md` | 当前有效 | M005 酒店上下文统一收口方案。 |
| `requirements/M006-system-admin-management-console-v1.md` | 草案 | M006 系统管理后台方案，覆盖用户、角色、权限、菜单、酒店和用户酒店授权维护。 |
| `requirements/M007-agentbus-superagent-auto-dispatch-v1.md` | 当前有效 | M007 AgentBus 新邮件入库后异步分发 SuperAgent 的后端 V1 方案，当前默认关闭，等待测试机联调。 |
| `requirements/M008-excel-to-pdf-conversion-v1.md` | 当前有效 | M008 Excel 转 PDF 文件转换能力方案，记录 LibreOffice headless、手动上传转换、邮件附件自动派生 PDF 和部署要求；CP2 已实现手动上传后端接口。 |
| `requirements/M009-manual-invoice-generation-v1.md` | 当前有效 | M009 Manual Invoice 手工开票生成方案；后端 CP2 已支持无订单 / 无任务手工填写、填充 Excel 模板、转 PDF、OSS 输出和生成记录。 |
| `requirements/M010-rooming-list-excel-generation-v1.md` | 当前有效 | M010 Rooming List Excel 生成方案；后端 CP1 已支持前端上传来源名单和手工字段，同步生成 `.xlsx` 直接下载，不落库、不上传 OSS。 |
| `requirements/M011-booking-excel-pre-superagent-enrichment-v1.md` | 当前有效 | M011 Booking Excel 附件预处理方案；CP1/CP2/CP3 已支持 Debug EML 和 AgentBus dispatch 调 SuperAgent 前排除人员名单类 Excel、抽取 Booking / 附加费类 Excel 高亮行并追加 `attachment_extractions[]`；测试机 AgentBus 增强已开启，生产默认关闭；CP4 暂不推进。 |

## 集成契约

| 文档 | 状态 | 中文说明 |
| --- | --- | --- |
| `integrations/superagent-api-contract.md` | 权威契约 | 给 SuperAgent 对接方使用的 HTTP 接口总契约，记录查询上下文、对象详情、邮件会话任务、邮件会话正文、任务结果通知和统一 HMAC 规则。 |
| `integrations/superagent-mcp/README.md` | 当前有效 | SuperAgent MCP 资料包入口；MCP tools 是 HTTP 总契约的 MCP 映射说明，不单独替代总契约。 |
| `integrations/superagent-agentbus-project-integration-guide.md` | 当前有效 | 当前项目 SuperAgent 与 AgentBus 验证记录和项目级接入细节。 |
| `../../mcp-server/README.md` | 当前有效 | SuperAgent MCP 方案入口指针；当前不单独部署 MCP 服务，运行时代码内嵌在 `server/`。 |

## 前后端协作

| 文档 | 状态 | 中文说明 |
| --- | --- | --- |
| `frontend-backend/backend-to-frontend-notes.md` | 当前有效 | 后端提醒前端的接口、字段、时间、安全和展示注意事项。 |
| `frontend-backend/frontend-to-backend-api-requests.md` | 当前有效 | 前端提醒后端需要增加或补齐的接口，已区分可用、后置和历史候选路径。 |
| `frontend-backend/debug-eml-page-integration-guide.md` | 当前有效 | Debug EML 页面前端对接指南。 |

## 运维与开发测试操作

| 文档 | 状态 | 中文说明 |
| --- | --- | --- |
| `operations/dev-test-v4-legacy-task-cleanup.md` | 当前有效 | 开发 / 测试环境 V4 停止双写旧任务后的旧 `workflow_reservation_task` 及直接依赖数据清理说明；不适用于生产迁移。 |

## 执行计划

| 文档 | 状态 | 中文说明 |
| --- | --- | --- |
| `../superpowers/plans/2026-07-10-m006-system-admin-v1.md` | 阶段记录 | M006 系统管理后台实现计划，作为执行 checkpoint 参考，不替代需求文档。 |
| `../superpowers/plans/2026-07-17-m009-manual-invoice-backend.md` | 阶段记录 | M009 Manual Invoice 后端 CP2 实现计划，记录本次接口、表、权限、模板和测试范围。 |

## 权威来源说明

- SuperAgent 对外 HTTP 接口以 `integrations/superagent-api-contract.md` 为权威来源。
- SuperAgent MCP 文档以 `integrations/superagent-mcp/` 为对外交付资料包，但字段语义应跟随 HTTP 总契约。
- 接口暴露、权限、酒店隔离和审计边界以 `security-access-control-boundary.md` 为总检查清单；具体 SuperAgent / MCP / AgentBus 请求响应契约仍以 `integrations/` 下对应文档为准。
- AI-NSES 的通用标准以 `../import/reusable/ai-native-software-engineering-standard.md` 为复用来源；本项目采用方式以 `ai-native-adoption.md` 为准。
- M002 V1 只作为历史参考；V2 记录当前阶段实现；后续 M002 新开发以 `requirements/M002-order-task-workflow-v3.md` 为开发基线。
- 2026-07-18 导入的业务基线已形成 `requirements/M002-v4-agent-callback-field-contract.md` 字段契约；M002 V4 入站解析 CP1 已落地，V4 订单任务 + 多卡领域模型设计和关键业务决策见 `requirements/M002-v4-order-task-card-domain-model-cp2.md`；M002 V4 CP3 已落地 V4 订单任务、任务卡、来源通知表结构和 Repository 基线，CP4 已落地普通 V4 业务包和 S10/S99 来源通知入站写入新模型，CP5 已落地工作台、订单任务和来源通知查询接口，CP6/CP7 已落地卡片确认、S10/S99 ack 和复核解阻，CP11 已落地 DB 目录与 lookup API，CP12 已落地前端 lookup 接入，CP13 已落地目录管理后台 CP1，CP14 已落地订单列表 V4 继续处理入口，CP15 已落地 V4 业务审计查询，CP15.1 已落地订单详情 V4 总览后端补齐且前端已接入，Room Information 后端展示模型第一版、前端业务化展示和 Rooming List 确认自动 DEF 后端联动已落地；已确认 Rooming List 卡第一版只做事项确认，`REVIEW_REQUIRED` 保持原业务卡内编辑并统一显示“确认卡片”；OWNER RATE Room Type / Rate Code 目录导入口径已落地，后续仍需测试机联调和真实 PMS / OPERA / OHIP 同步。
- V3 / 旧任务前端展示和编辑字段仍以 2026-07-11 P0 冻结基线中的前端字段表、0712 字段控件说明和 `requirements/M002-task-field-control-contract-v1.md` 为白名单和控件契约基线；V4 订单任务前端展示和编辑字段以 `requirements/M002-v4-order-task-card-domain-model-cp2.md`、后端返回的 `fields[]` 和 V4 前后端协作文档为准。
- 时间点语义以 `backend-time-design.md` 为准；数据库时间点按 UTC 理解，API 返回带 `Z` 的 UTC 时间，页面再按酒店或用户时区展示。