96 lines
9.7 KiB
Markdown
96 lines
9.7 KiB
Markdown
# 当前项目专属文档
|
||
|
||
本目录保存只适用于当前项目的业务背景、架构边界、外部系统约束和实现决策。
|
||
|
||
这些文档可以作为后续项目参考，但不应整份复制到新项目。新项目可复用内容应优先沉淀到 `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 和校验口径；当前代码尚未按 V4 改造。 |
|
||
| `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。 |
|
||
|
||
## 集成契约
|
||
|
||
| 文档 | 状态 | 中文说明 |
|
||
| --- | --- | --- |
|
||
| `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 页面前端对接指南。 |
|
||
|
||
## 执行计划
|
||
|
||
| 文档 | 状态 | 中文说明 |
|
||
| --- | --- | --- |
|
||
| `../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 主流程、后端数据模型和接口改造尚未落地，开发前需要继续形成 V4 主流程方案。
|
||
- 前端展示 / 编辑字段以 2026-07-11 P0 冻结基线中的前端字段表、0712 字段控件说明和 `requirements/M002-task-field-control-contract-v1.md` 为白名单和控件契约基线；后端完整校验和 OPERA 映射仍以任务卡完整矩阵、0711 runtime 契约和后端规则为准。
|
||
- 时间点语义以 `backend-time-design.md` 为准；数据库时间点按 UTC 理解，API 返回带 `Z` 的 UTC 时间，页面再按酒店或用户时区展示。
|