From 980a3a25358a990cd5c7bd2fffa5eae4f197aff0 Mon Sep 17 00:00:00 2001 From: andy Date: Fri, 17 Jul 2026 13:13:47 +0700 Subject: [PATCH] =?UTF-8?q?=E5=86=8D=E6=AC=A1=E6=8F=90=E4=BA=A4=E4=B8=80?= =?UTF-8?q?=E4=B8=8B=E4=BB=A3=E7=A0=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 22 +- CONTEXT.md | 81 ++++ PROJECT_STATE.md | 59 +++ README.md | 18 + .../ReservationTaskDetailPanel.vue | 453 +++++++++++++++--- client/src/i18n/locales/en-US.ts | 6 + client/src/i18n/locales/th-TH.ts | 6 + client/src/i18n/locales/zh-CN.ts | 6 + .../tests/reservationTaskDetailPanel.spec.ts | 84 ++++ client/src/tests/reservationViews.spec.ts | 5 +- .../reservation/ReservationOrderListView.vue | 6 - docs/import/reusable/README.md | 3 + ...ai-native-software-engineering-standard.md | 276 +++++++++++ .../ai-native-templates/ADR.template.md | 40 ++ .../ai-native-templates/AGENTS.template.md | 39 ++ .../ARCHITECTURE.template.md | 31 ++ .../ai-native-templates/CONTEXT.template.md | 50 ++ .../DOMAIN_OBJECT.template.md | 27 ++ .../PROJECT_STATE.template.md | 39 ++ .../reusable/ai-native-templates/README.md | 21 + .../ai-native-templates/SPEC.template.md | 49 ++ .../ai-native-templates/WORKFLOW.template.md | 37 ++ docs/project/README.md | 12 + docs/project/ai-native-adoption.md | 80 ++++ .../project/backend-development-guidelines.md | 50 +- .../frontend-to-backend-api-requests.md | 7 +- ...gent-agentbus-project-integration-guide.md | 11 +- .../M001-source-message-inbox-prd.md | 24 +- .../M003-identity-access-hotel-menu-v1.md | 12 +- ...M006-system-admin-management-console-v1.md | 2 +- .../control/SourceMessageController.java | 63 ++- .../SourceMessageControllerAdvice.java | 4 +- .../SourceMessageConversationService.java | 8 +- .../service/SourceMessageOriginalService.java | 10 +- .../SourceMessageConversationServiceImpl.java | 43 +- .../SourceMessageOriginalServiceImpl.java | 22 +- .../ReservationTaskControllerAdvice.java | 17 +- .../identity/control/AuthControllerTest.java | 1 + .../control/SourceMessageControllerTest.java | 40 +- ...ontendReadAuthorizationControllerTest.java | 119 +++++ .../ReservationDemoDataControllerTest.java | 3 +- 41 files changed, 1699 insertions(+), 187 deletions(-) create mode 100644 CONTEXT.md create mode 100644 PROJECT_STATE.md create mode 100644 docs/import/reusable/ai-native-software-engineering-standard.md create mode 100644 docs/import/reusable/ai-native-templates/ADR.template.md create mode 100644 docs/import/reusable/ai-native-templates/AGENTS.template.md create mode 100644 docs/import/reusable/ai-native-templates/ARCHITECTURE.template.md create mode 100644 docs/import/reusable/ai-native-templates/CONTEXT.template.md create mode 100644 docs/import/reusable/ai-native-templates/DOMAIN_OBJECT.template.md create mode 100644 docs/import/reusable/ai-native-templates/PROJECT_STATE.template.md create mode 100644 docs/import/reusable/ai-native-templates/README.md create mode 100644 docs/import/reusable/ai-native-templates/SPEC.template.md create mode 100644 docs/import/reusable/ai-native-templates/WORKFLOW.template.md create mode 100644 docs/project/ai-native-adoption.md diff --git a/AGENTS.md b/AGENTS.md index b106a11..03dd9e4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,15 +5,21 @@ 本文件是当前项目的协作入口，供开发者和 coding agent 在动手前阅读。 - 可复用迁移规范统一位于 `docs/import/reusable/`。 +- AI-NSES 通用标准位于 `docs/import/reusable/ai-native-software-engineering-standard.md`。 +- AI-NSES 模板目录位于 `docs/import/reusable/ai-native-templates/`。 - 通用可复用规范位于 `docs/import/reusable/general-development-guidelines.md`。 - 前端细则参考 `docs/import/reusable/frontend-development-guidelines.md`。 - 后端细则参考 `docs/import/reusable/backend-development-guidelines.md`。 - 后端基础结构、ID、审计字段、分页和 Mapper 规范参考 `docs/import/reusable/backend-base-structure-pagination-guidelines.md`。 - Java 代码规范参考 `docs/import/reusable/alibaba-java-coding-guidelines-summary.md`。 - SuperAgent 与 AgentBus 可移植集成经验参考 `docs/import/reusable/integrations/superagent-agentbus-portable-integration-guide.md`。 +- 项目长期上下文入口位于 `CONTEXT.md`。 +- 当前项目状态入口位于 `PROJECT_STATE.md`。 - 当前项目专属文档总索引位于 `docs/project/README.md`。 +- 当前项目 AI-NSES 落地说明位于 `docs/project/ai-native-adoption.md`。 - 当前项目专属后端规范位于 `docs/project/backend-development-guidelines.md`。 - 当前项目时间设计说明位于 `docs/project/backend-time-design.md`。 +- 当前项目接口暴露、权限和审计边界位于 `docs/project/security-access-control-boundary.md`。 - 当前项目专属前端规范位于 `docs/project/frontend-development-guidelines.md`。 - 当前项目前后端协作入口位于 `docs/project/frontend-backend/README.md`。 - 当前项目 SuperAgent 与 AgentBus 接入记录位于 `docs/project/integrations/superagent-agentbus-project-integration-guide.md`。 @@ -32,6 +38,7 @@ - 遇到不确定的技术栈、目录、接口契约或数据模型，先确认再继续。 - 新项目初始化或技术栈升级前，必须检查前端、后端、构建工具、测试工具和运行时版本兼容性。 - 输出分层结构、目录树、数据模型、字段映射或接口示例时，必须补充中文说明，不能只依赖英文命名表达业务含义。 +- 完成 Feature 或 checkpoint 后，必须按 AI-NSES 检查 Domain、Architecture、Workflow、ADR、Spec、Project State 和安全边界文档是否需要更新；如果没有文档变化，明确说明 `No documentation changes required.`。 ## 3. 分支与提交 @@ -46,6 +53,8 @@ 本项目是前后端都有的全栈项目，目录应保持职责清晰： +- `CONTEXT.md`：项目长期上下文入口。 +- `PROJECT_STATE.md`：当前项目状态入口，允许高频更新。 - `client/`：前端应用。 - `server/`：后端服务。 - `mcp-server/`：SuperAgent MCP 方案入口指针；当前不单独部署 MCP 服务，运行时代码内嵌在 `server/`，对外资料包位于 `docs/project/integrations/superagent-mcp/`。 @@ -78,6 +87,7 @@ - 后端负责数据库、Secret、外部系统适配、业务规则、审计和安全脱敏。 - 接口字段使用稳定代码，不使用中文或英文显示文案做业务判断。 - 接口变更前先确认字段映射、前后端影响和测试范围。 +- 新增或修改接口时，必须同步确认调用方类型、鉴权方式、权限码、酒店隔离、敏感数据返回和审计要求，并更新 `docs/project/security-access-control-boundary.md` 及相关前后端或第三方契约文档。 ## 7. 后端架构边界 @@ -121,6 +131,7 @@ - 仓库只提交无真实值的 `.env.example`。 - 禁止提交真实酒店凭证、客户数据、Token、Cookie、API Key、数据库密码或支付信息。 - 日志、错误响应和测试夹具不得暴露 Token、Secret、原始邮件正文、附件 URL 或个人敏感信息。 +- Debug、Demo、Replay、Probe 等系统调试接口必须默认关闭或受控开放，不得因为前端页面存在就作为普通业务能力暴露。 - `.DS_Store`、构建产物、依赖目录、IDE 临时文件和本地样本目录应忽略。 ## 10. 测试与验证 @@ -135,9 +146,14 @@ Coding agent 开始任务前应先读取： 1. `AGENTS.md` -2. `README.md`，如果存在 -3. `docs/` 中与当前任务相关的文档 -4. 当前代码结构和最近 Git 状态 +2. `CONTEXT.md` +3. `PROJECT_STATE.md` +4. `README.md`，如果存在 +5. `docs/project/README.md` +6. `docs/` 中与当前任务相关的文档 +7. 当前代码结构和最近 Git 状态 + +涉及接口、权限、审计、酒店隔离或敏感数据返回的改动，开始前必须阅读 `docs/project/security-access-control-boundary.md`，完成后同步更新该文档和相关前后端或第三方契约。 改文件前要说明计划；完成后要说明改了什么、如何验证、还有哪些风险或未完成项。 diff --git a/CONTEXT.md b/CONTEXT.md new file mode 100644 index 0000000..b9ec257 --- /dev/null +++ b/CONTEXT.md @@ -0,0 +1,81 @@ +# TH Hotel Simple 项目上下文 + +## 1. 产品目标 + +TH Hotel Simple 是一个前后端分离的酒店业务协同项目。 + +当前核心目标是把来自 AgentBus、SuperAgent 和后续酒店系统的业务输入，沉淀为可追溯、可查询、可人工复核的结构化数据，为酒店预订、任务处理、邮件原文读取、外部 AI 协作和后续 PMS / OHIP 集成打基础。 + +## 2. 当前系统组成 + +| 目录 | 中文说明 | +| --- | --- | +| `client/` | 前端应用。负责页面展示、人工操作、调试入口和调用本项目后端。前端不直接访问 AgentBus、SuperAgent、OHIP、数据库或任何 Secret。 | +| `server/` | 后端 Spring Boot 服务。负责数据库、业务规则、外部系统适配、权限、安全脱敏、审计和接口契约。 | +| `mcp-server/` | SuperAgent MCP 方案入口指针。当前不单独部署 MCP 服务，MCP 运行时代码内嵌在 `server/`。 | +| `docs/` | 项目文档、需求、架构边界、导入资料、可复用规范和第三方契约。 | + +## 3. 技术栈 + +### 后端 + +- Java 17，语法和编译 release 均按 17。 +- Spring Boot 3.5.15。 +- Maven Wrapper。 +- MyBatis-Plus 3.5.16。 +- Flyway。 +- MySQL，测试场景可使用 H2 MySQL Mode 或 test-mysql profile。 +- Spring Validation、springdoc-openapi、Angus Mail、Aliyun OSS、Apache POI。 + +### 前端 + +- Vue 3.5。 +- TypeScript 6。 +- Vite 8。 +- Pinia 3。 +- PrimeVue 4、PrimeIcons 7。 +- Vue Router 5、Vue I18n 11。 +- Vitest 4、ESLint 10、vue-tsc 3。 +- Node.js >= 22.13.0。 + +## 4. 当前业务领域 + +- SourceMessage：外部消息来源事实，当前主要承接 AgentBus 邮件 JSON。 +- Email / Message Conversation：邮件和邮件会话，用于历史邮件查询、正文读取和会话级任务查询。 +- Reservation Case / Task：预订相关订单、任务卡、人工复核和任务结果。 +- Identity / Access / Hotel / Menu：登录、用户、角色、权限、酒店授权和动态菜单底座。 +- Debug EML：受控调试入口，用于上传 EML 并触发 SuperAgent 调试链路。 +- Manual Invoice：手工开票生成能力，包含 Excel 模板、PDF 转换和 OSS 输出。 + +## 5. 外部系统与边界 + +| 外部系统 | 当前定位 | 契约入口 | +| --- | --- | --- | +| AgentBus | 消息入口适配器。实时入口必须先落 SourceMessage Inbox。 | `docs/project/integrations/superagent-agentbus-project-integration-guide.md` | +| SuperAgent | 外部 AI / Agent 能力提供方。返回内容只能作为建议、证据或审计结果。 | `docs/project/integrations/superagent-api-contract.md` | +| SuperAgent MCP | SuperAgent 调用本项目能力的 MCP 映射，当前内嵌在后端服务。 | `docs/project/integrations/superagent-mcp/README.md` | +| Aliyun OSS | 调试 EML、附件或生成文件的对象存储。 | 相关配置和安全边界见项目文档与后端配置 | +| OHIP / PMS | 后续酒店系统集成方向。当前不允许前端直接访问。 | 后续 Spec / ADR 明确 | + +## 6. 当前开发方向 + +当前项目正在从普通项目文档结构，逐步落地 AI-NSES 文档入口： + +- `AGENTS.md` 规定 Agent 如何工作。 +- `CONTEXT.md` 说明项目长期背景。 +- `PROJECT_STATE.md` 记录当前阶段状态。 +- `docs/project/README.md` 作为当前项目专属文档索引。 +- `docs/import/reusable/` 保存可迁移到其他项目的通用规范。 + +业务开发仍以 `docs/project/requirements/` 和 `docs/project/integrations/` 下的当前有效文档为准。 + +## 7. 新 Agent 阅读顺序 + +1. `AGENTS.md` +2. `CONTEXT.md` +3. `PROJECT_STATE.md` +4. `README.md` +5. `docs/project/README.md` +6. 与当前任务相关的需求、接口、安全、前后端协作或集成文档 + +涉及接口、权限、审计、酒店隔离或敏感数据返回时，必须额外阅读 `docs/project/security-access-control-boundary.md`。 diff --git a/PROJECT_STATE.md b/PROJECT_STATE.md new file mode 100644 index 0000000..326abfc --- /dev/null +++ b/PROJECT_STATE.md @@ -0,0 +1,59 @@ +# TH Hotel Simple 项目当前状态 + +| 项 | 内容 | +| --- | --- | +| 最近更新 | 2026-07-17 | +| 当前分支 | `feature/huangting` | +| 当前阶段 | 项目文档标准化与业务能力迭代并行 | +| 当前重点 | 按 AI-NSES 建立新 Agent 可快速进入项目的文档入口 | + +## 1. 当前 Checkpoint + +- 名称：`checkpoint-docs-ai-native-entry` +- 状态：In Progress，等待本次文档改动 Review。 +- 目标：新增 AI-NSES 通用标准、模板目录、项目上下文、项目当前状态和本项目采用说明。 +- 边界：只改文档，不搬迁历史文档，不删除文档，不改代码。 + +## 2. 当前优先级 + +1. 先把 AI-NSES 的入口文档落地，让新 Agent 不依赖聊天记录也能理解项目。 +2. 保持 `docs/project/README.md`、`CONTEXT.md`、`PROJECT_STATE.md` 三个入口之间一致。 +3. 后续开发继续以当前有效的 M002 V3 / P0.1、字段控件契约、SuperAgent 契约和安全边界文档为准。 + +## 3. 已确认事实 + +- 本项目是前后端分离项目，根目录使用 `client/` 和 `server/`，不是 AI-NSES 示例里的通用 `src/` 单目录结构。 +- 可复用规范放在 `docs/import/reusable/`，当前项目专属文档放在 `docs/project/`。 +- AgentBus 是消息入口适配器，SuperAgent 是外部 AI / Agent 能力提供方，二者不能直接成为业务事实来源。 +- 后端时间点按 UTC 存储和返回，页面再按酒店或用户时区展示。 +- 新增 MySQL 表默认要求 `utf8mb4_bin`，避免外部 opaque id、Token、状态码和业务代码被大小写不敏感比较误判。 + +## 4. Known Issues + +- 现有历史文档暂不按 AI-NSES 目录大搬迁，先通过索引和采用说明建立映射关系。 +- `docs/import/` 下按日期导入的资料是输入材料，不等同于当前权威开发契约；当前开发应优先看 `docs/project/README.md` 标记为当前有效或权威契约的文档。 +- 后续每完成一个 Feature 或 Checkpoint，需要更新本文件，避免项目状态继续沉淀在聊天记录里。 + +## 5. Next Steps + +- Review 本次 AI-NSES 文档入口改动。 +- 确认通过后，可按后续具体需求继续进入业务开发。 +- 后续新增重要功能时，优先在 `docs/project/requirements/` 或未来 `docs/specs/` 中形成 Spec，再实现代码。 + +## 6. 文档同步提醒 + +每次 Feature 完成后检查： + +- Domain 是否需要更新。 +- Architecture 是否需要更新。 +- Workflow 是否需要更新。 +- ADR 是否需要新增。 +- Spec 或需求文档是否需要更新状态。 +- `PROJECT_STATE.md` 是否需要更新。 +- 接口、安全、权限、审计和酒店隔离文档是否需要同步。 + +如果没有文档变化，明确说明： + +```text +No documentation changes required. +``` diff --git a/README.md b/README.md index b7e79c1..740afd9 100644 --- a/README.md +++ b/README.md @@ -2,9 +2,27 @@ TH Hotel Simple 是一个前后端分离的酒店业务协同项目。当前后端优先建设平台级 SourceMessage Inbox，用于接收 AgentBus 邮件来源事实，并为后续 AI 识别、人工复核、Case / Task 流程提供可追溯输入。 +## AI-NSES 文档入口 + +新成员或新的 AI Agent 进入项目时，建议按以下顺序阅读： + +1. `AGENTS.md`：项目协作与开发规范。 +2. `CONTEXT.md`：项目目标、技术栈、系统组成和业务边界。 +3. `PROJECT_STATE.md`：当前 checkpoint、优先级、Known Issues 和 Next Steps。 +4. `docs/project/README.md`：当前项目专属文档总索引。 +5. `docs/project/ai-native-adoption.md`：本项目如何采用 AI-NSES。 + +可复用 AI-NSES 标准位于 `docs/import/reusable/ai-native-software-engineering-standard.md`，模板目录位于 `docs/import/reusable/ai-native-templates/`。 + ## 目录说明 ```text +CONTEXT.md +项目长期上下文入口，记录产品目标、技术栈、系统组成、业务领域和外部系统边界。 + +PROJECT_STATE.md +项目当前状态入口，记录当前 checkpoint、优先级、Known Issues 和 Next Steps。 + client/ 后续前端应用目录。前端只调用本项目后端，不直接访问 AgentBus、SuperAgent、OHIP、数据库或任何 Secret。 diff --git a/client/src/components/reservation/ReservationTaskDetailPanel.vue b/client/src/components/reservation/ReservationTaskDetailPanel.vue index 49d3b3b..2d6e542 100644 --- a/client/src/components/reservation/ReservationTaskDetailPanel.vue +++ b/client/src/components/reservation/ReservationTaskDetailPanel.vue @@ -49,21 +49,27 @@ -
-

{{ t('task.evidence') }}

-
+
+
-
{{ t('task.sourceMessageId') }}
-
- {{ detail.source_message_id || '-' }} -
-
-
-
{{ t('task.sourceSubject') }}
-
- {{ detail.source_subject ?? t('task.sourceSummaryPending') }} -
+

{{ t('task.sourceEmailPreview') }}

+

{{ detail.source_subject ?? t('task.sourceSummaryPending') }}

+ + {{ t('task.sourceEmailFullConversation') }} · {{ t('common.endpointMissing') }} + + + {{ t('task.sourceEmailFullConversation') }} + +
+
{{ t('task.sourceSender') }}
{{ detail.source_sender_summary ?? '-' }}
@@ -72,53 +78,41 @@
{{ t('task.sourceReceivedAt') }}
{{ formatReservationDateTime(detail.source_received_at) }}
-
-
- -
-

{{ t('task.routeInfo') }}

-
-
{{ t('task.systemTaskType') }}
-
- {{ formatReservationTaskCard(t, detail.system_task_type) }} - {{ detail.system_task_type }} -
-
-
-
{{ t('task.taskCardType') }}
-
- {{ formatReservationTaskCardLabel(t, detail) }} - {{ detail.task_card_type }} -
-
-
-
{{ t('task.resultType') }}
-
{{ detail.result_type ? formatReservationResultType(t, detail.result_type) : '-' }}
-
-
-
{{ t('task.aiTaskType') }}
-
{{ detail.ai_task_type || '-' }}
-
-
-
{{ t('task.taskSubtype') }}
-
{{ detail.task_subtype ? formatReservationRouteCode(t, detail.task_subtype) : '-' }}
-
-
-
{{ t('task.routeCode') }}
+
{{ t('task.sourceMessageId') }}
- {{ detail.route_code || '-' }} + {{ detail.source_message_id || '-' }}
-
{{ t('task.systemProcessCategory') }}
-
{{ detail.system_process_category ? formatReservationSystemProcessCategory(t, detail.system_process_category) : '-' }}
-
-
-
{{ t('task.reviewStatus') }}
-
{{ detail.review_status || '-' }}
+
{{ t('conversation.messageCount') }}
+
{{ detail.conversation_message_count ?? '-' }}
+
+
+

{{ t('task.sourceEmailExcerpt') }}

+

{{ sourceEmailExcerpt ?? t('task.sourceEmailNoExcerpt') }}

+
+
+

{{ t('task.sourceEmailAttachments') }}

+
    +
  • +