鲨鱼辣椒
f4aa01e1f9
verify / booking-verify (push) Has been cancelled
补齐C1正文资料交付和C2配额分类规则，完善Proposal人工任务、固定图片过滤及邮件附件展示。 修正失败终态与恢复上限，增加关闭状态的通知组件，永久保留处理历史并完善筛选分页。 同步相关页面修复、迁移、测试和项目记录。 验证：后台复用同源码clean verify结果1155通过/10条件跳过；前端262项及生产构建通过；敏感资料和提交路径检查通过。
170 lines
7.8 KiB
Markdown
170 lines
7.8 KiB
Markdown
# TH Hotel Simple
|
||
|
||
TH Hotel Simple 是一个前后端分离的酒店业务协同项目。当前后端优先建设平台级 SourceMessage Inbox，用于接收 AgentBus 邮件来源事实，并为后续 AI 识别、人工复核、Case / Task 流程提供可追溯输入。
|
||
|
||
当前本地测试状态（2026-09-10）：5178/8082已统一加载Proposal人工任务、C1正文资料交付、来源图片过滤、失败收尾和历史永久保留，保留附件下载及人工办理能力。旧测试数据已按用户要求备份清空，可配置最新C1/C2后继续测试；外部通知发送关闭且自动触发尚未接通。详细状态以[项目当前状态](PROJECT_STATE.md)为准。
|
||
|
||
## 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。
|
||
6. `docs/project/ai-nses-project-overlay.md`：本项目在 AI-NSES 之上的需求门禁、V4 核心概念守门、需求追踪和 agent 交接规则。
|
||
|
||
可复用 AI-NSES 标准位于 `docs/import/reusable/ai-native-software-engineering-standard.md`，模板目录位于 `docs/import/reusable/ai-native-templates/`。通用标准保持可迁移；TH Hotel 的 V4 需求门禁和项目私有规则以项目级 Overlay 为准。
|
||
|
||
## 目录说明
|
||
|
||
```text
|
||
CONTEXT.md
|
||
项目长期上下文入口，记录产品目标、技术栈、系统组成、业务领域和外部系统边界。
|
||
|
||
PROJECT_STATE.md
|
||
项目当前状态入口，记录当前 checkpoint、优先级、Known Issues 和 Next Steps。
|
||
|
||
client/
|
||
后续前端应用目录。前端只调用本项目后端，不直接访问 AgentBus、SuperAgent、OHIP、数据库或任何 Secret。
|
||
|
||
server/
|
||
后端 Spring Boot 服务目录。后端负责数据库、外部系统适配、业务规则、安全脱敏和审计边界。
|
||
|
||
mcp-server/
|
||
SuperAgent MCP 方案入口指针。当前不单独部署 MCP 服务，运行时代码内嵌在 `server/`，对外资料包位于 `docs/project/integrations/superagent-mcp/`。
|
||
|
||
docs/
|
||
项目文档、可复用规范、当前项目需求和外部系统接入记录。当前项目文档总索引见 `docs/project/README.md`。
|
||
```
|
||
|
||
## 后端命令
|
||
|
||
本 checkpoint 固定本地验证基线为 JDK 17（见 `server/.java-version`）。
|
||
|
||
```bash
|
||
cd server
|
||
./mvnw test
|
||
./mvnw verify
|
||
./mvnw spring-boot:run
|
||
```
|
||
|
||
中文说明：
|
||
|
||
- `./mvnw test`：运行后端单元测试和 Spring 集成测试。
|
||
- `./mvnw verify`：运行 Maven verify 阶段，用于提交前完整检查。
|
||
- `./mvnw spring-boot:run`：本地启动后端服务，默认端口为 `8080`。
|
||
|
||
后端 Maven 测试在 JVM 启动时默认启用 `-Djava.awt.headless=true`，图片读写、缩放和绘制在后台完成，避免 macOS 测试进程进入 Dock 并抢走当前应用焦点。该参数由 `server/pom.xml` 的 Surefire 配置提供，不依赖 Spring 初始化后再设置。
|
||
|
||
## 前端命令
|
||
|
||
本 checkpoint 固定本地验证基线为 Node 24 与 pnpm 11（见 `client/.node-version` 和 `client/package.json`）。
|
||
|
||
```bash
|
||
cd client
|
||
pnpm install
|
||
pnpm dev
|
||
pnpm typecheck
|
||
pnpm test
|
||
pnpm lint
|
||
pnpm build
|
||
```
|
||
|
||
中文说明：
|
||
|
||
- `pnpm install`：安装前端依赖。
|
||
- `pnpm dev`：启动 5178 最终员工工作台，默认地址为 `http://127.0.0.1:5178`。
|
||
- `pnpm typecheck`：运行 Vue / TypeScript 类型检查。
|
||
- `pnpm test`：运行前端单元测试。
|
||
- `pnpm lint`：运行 ESLint 检查。
|
||
- `pnpm build`：执行类型检查并构建生产产物。
|
||
|
||
### 本地安全运行与员工工作台
|
||
|
||
后端默认启用 `local` profile，只使用进程内 H2；本地启动不会连接远程数据库、AgentBus 或 SuperAgent。需要连接开发环境时，必须显式启用 `dev` profile，并由部署环境提供 `TH_HOTEL_DEV_DB_URL`、`TH_HOTEL_DEV_DB_USERNAME`、`TH_HOTEL_DEV_DB_PASSWORD` 三个环境变量；任一缺失会在启动阶段失败。
|
||
|
||
前端最终运行入口是 `http://127.0.0.1:5178/`。员工工作台只保留三个一级入口：
|
||
|
||
- `/reservation/tasks`：待处理任务。
|
||
- `/reservation/orders`：预订记录。
|
||
- `/agentbus/eml-replay`：AgentBus EML 全流程回放。
|
||
|
||
本机 loopback 的 5178 开发模式暂时按项目联合调试约定跳过前端登录拦截；它不会伪造 token，也不会绕过后端 API 的认证与授权。生产构建仍使用正式鉴权。
|
||
|
||
如需查看已经迁入 5178 数据模型的合成演示数据，可使用 `pnpm dev:5178:fixtures`。fixture 模式与 production bundle 隔离，不包含旧原型路由或浏览器假回放。
|
||
|
||
本地联调指定后端示例：
|
||
|
||
```bash
|
||
VITE_API_PROXY_TARGET=http://127.0.0.1:8080 pnpm --dir client dev
|
||
```
|
||
|
||
中文说明：Reservation 查询默认不再依赖前端环境变量传 `hotel_id`。单酒店阶段后端从 `platform_hotel` 唯一 `ACTIVE` 酒店解析系统酒店；登录后前端可按 `/api/auth/me` 的当前选中酒店传可选 `hotel_id`，后端仍会校验访问权限。`VITE_RESERVATION_HOTEL_ID` 仅保留为本地夹具或临时覆盖，不作为生产业务事实来源。
|
||
|
||
AgentBus EML 全流程回放使用同一个员工工作台入口：
|
||
|
||
```text
|
||
http://127.0.0.1:5178/agentbus/eml-replay
|
||
```
|
||
|
||
中文说明：页面只调用本项目后端的受控回放 API；AgentBus、SuperAgent、对象存储和数据库凭据全部保留在后端或部署 Secret 中，不得写入 `VITE_*`、源码、localStorage、sessionStorage、URL、错误上报或普通日志。
|
||
|
||
## SuperAgent MCP
|
||
|
||
当前 MCP 采用后端内嵌方式，不需要额外部署独立服务。启用示例：
|
||
|
||
```bash
|
||
cd server
|
||
MCP_ENABLED=true MCP_AUTH_TOKEN=test-token MCP_ENABLE_SUBMIT_TASK_RESULTS=false ./mvnw spring-boot:run
|
||
```
|
||
|
||
中文说明：SuperAgent 通过 `POST /mcp` 调用 5 个 MCP tools。写入工具由 `MCP_ENABLE_SUBMIT_TASK_RESULTS`
|
||
单独控制，生产启用前需要单独确认。MCP 单次请求体默认限制为 10MB，可通过 `MCP_MAX_BODY_BYTES`
|
||
调整。
|
||
|
||
### 测试数据库配置
|
||
|
||
默认 `test` profile 使用 H2 MySQL Mode，便于本地和 CI 在没有 MySQL 的情况下运行：
|
||
|
||
```bash
|
||
cd server
|
||
./mvnw test
|
||
```
|
||
|
||
如需使用真实 MySQL 测试库，可启用 `test-mysql` profile，并通过环境变量注入连接信息：
|
||
|
||
```bash
|
||
cd server
|
||
TH_HOTEL_TEST_DB_URL="jdbc:mysql://127.0.0.1:3306/th_hotel_test?useUnicode=true&characterEncoding=utf8&useSSL=false&allowPublicKeyRetrieval=true&serverTimezone=UTC" \
|
||
TH_HOTEL_TEST_DB_USERNAME=th_hotel_test \
|
||
TH_HOTEL_TEST_DB_PASSWORD=your-local-password \
|
||
./mvnw test -Dspring.profiles.active=test,test-mysql
|
||
```
|
||
|
||
中文说明：`test-mysql` 仅用于连接本地或 CI 的测试库，不能填写真实酒店库、真实客户数据或生产凭证。
|
||
|
||
## 当前健康检查
|
||
|
||
```text
|
||
GET /api/health
|
||
```
|
||
|
||
返回后端最小健康状态，用于本地开发、部署探活和前端连通性验证。
|
||
|
||
## M001 SourceMessage Inbox
|
||
|
||
当前实现 checkpoint 聚焦：
|
||
|
||
- AgentBus Outlook payload 映射为平台稳定捕获命令。
|
||
- SourceMessage Inbox 幂等落库。
|
||
- 正文、HTML、原始 payload 和媒体 URL 分表保存。
|
||
- 列表和普通详情接口只返回安全摘要。
|
||
- `/api/source-messages/{id}/original` 通过受控访问 key 读取原文，并写入访问审计。
|
||
- AgentBus WebSocket 长连接默认关闭；开启后先接收入站 frame 并写入 SourceMessage Inbox，M007 可在配置开启时异步创建 SuperAgent dispatch run。
|
||
- `/api/system/agentbus-probe` 返回 AgentBus 连接状态和安全计数器，不返回 Token 或原始 frame。
|
||
- 缺少外部邮件 ID 的 payload 保存为 `FAILED`，错误摘要不暴露正文或 Secret。
|
||
|
||
后续 checkpoint 再明确 SourceMessage Replay 到 MessageEvent / Evidence，以及具体业务页面展示位置。
|