266 lines
11 KiB
Markdown
266 lines
11 KiB
Markdown
# TH Hotel 后端开发规范
|
||
|
||
## 1. 文档定位
|
||
|
||
本文整理 TH Hotel 当前后端开发约定，供本项目后端开发和其他 agent 协作参考。
|
||
|
||
本文是当前项目专属补充，不应整份复制到其他项目。可复用的通用后端规则应沉淀到 `docs/import/reusable/backend-development-guidelines.md`。
|
||
|
||
本项目后端是酒店多部门 AI 业务流程与 Case 协同平台的服务端。这里的 AI 只表示调用外部
|
||
模型或 Agent 能力提供方并消费其结构化结果；本项目不开发模型、Prompt 优化平台、Agent
|
||
Runtime、Planner、Memory 或通用工具调用框架。
|
||
|
||
## 2. 技术栈
|
||
|
||
以 `server/pom.xml` 为准，当前后端技术栈如下：
|
||
|
||
| 类别 | 当前选择 |
|
||
| --- | --- |
|
||
| Java | Java 17 LTS，语法版本 Java 17 |
|
||
| 框架 | Spring Boot 3.5.15 |
|
||
| Web | Spring MVC |
|
||
| 构建 | Maven Wrapper |
|
||
| 外部 HTTP | Spring `RestClient` 优先 |
|
||
| 数据库 | MySQL 8.0+ |
|
||
| ORM / Mapper | MyBatis-Plus 3.5.16，Spring Boot 3 使用 `mybatis-plus-spring-boot3-starter` |
|
||
| 数据库迁移 | Flyway |
|
||
| OpenAPI | springdoc-openapi 2.8.17 |
|
||
| 测试 | JUnit 5、Spring Boot Test、H2 MySQL Mode |
|
||
|
||
升级 Java、Spring Boot、MyBatis-Plus、springdoc 或 Flyway 前，必须先做兼容性验证。
|
||
|
||
Maven 编译配置应显式使用 `maven.compiler.release=17`，并开启参数名保留，例如 `parameters=true`。除非单独确认升级方案，否则不得使用 Java preview 特性或 Java 21 / Java 25 专属语法。
|
||
|
||
引入 MyBatis-Plus 后，不再额外引入 `mybatis-spring-boot-starter`、`MyBatis-Spring` 或重复的原生 MyBatis starter，避免 starter 版本差异造成运行期问题。
|
||
|
||
## 3. 后端分层与包边界
|
||
|
||
推荐边界：
|
||
|
||
```text
|
||
platform
|
||
├── ai
|
||
├── audit
|
||
├── evidence
|
||
├── message
|
||
├── operation
|
||
├── receipt
|
||
└── system
|
||
|
||
workflows
|
||
└── reservation
|
||
|
||
integrations
|
||
├── ai
|
||
├── document
|
||
├── external
|
||
├── messaging
|
||
└── ohip
|
||
```
|
||
|
||
中文说明：
|
||
|
||
| 层级 | 中文职责 | 依赖规则 |
|
||
| --- | --- | --- |
|
||
| `platform` | 平台通用能力层，保存消息、证据、AI 调用审计、Operation、Receipt、审计等部门中立能力 | 可以被业务流程调用，不能反向依赖预订部等具体业务流程 |
|
||
| `workflows` | 业务流程层，保存具体部门或业务线的流程编排，当前优先是预订流程 | 可以依赖 `platform` 和稳定端口，不直接依赖外部系统 DTO |
|
||
| `integrations` | 外部系统适配层，隔离 OHIP、SuperAgent、AgentBus 等外部协议和认证细节 | 可以实现平台或业务端口，不能把外部 DTO 泄漏到领域模型 |
|
||
|
||
后续输出包结构、目录树、数据模型、字段映射或接口示例时，必须补充中文说明，说明每层职责、依赖方向、可调用对象和禁止事项，不能只依赖英文命名表达含义。
|
||
|
||
职责规则：
|
||
|
||
- `platform` 保存部门中立能力，例如消息、证据、AI 调用审计、Operation、Receipt、审计。
|
||
- `workflows` 保存部门业务流程，当前明确的是 `reservation`。
|
||
- `integrations` 保存外部系统适配器，例如 OHIP、SuperAgent、AgentBus。
|
||
- 平台核心不得依赖预订部专有字段。
|
||
- 部门工作流可以依赖平台核心，平台核心不能反向依赖部门模块。
|
||
- 外部系统 DTO、Oracle DTO、Provider DTO、领域模型和 API Response 必须分离。
|
||
- Oracle DTO 或生成代码只能位于 `integrations.ohip`，不得进入平台领域模型。
|
||
|
||
## 4. Controller / Service / Repository 规则
|
||
|
||
- Controller 只做 HTTP 契约、参数校验、权限入口和响应映射。
|
||
- Controller 不直接访问 Mapper。
|
||
- Controller 不直接调用外部适配器。
|
||
- Application Service 编排事务、领域对象、Repository 和外部端口。
|
||
- Domain 对象表达稳定业务语义，不引入 HTTP、JSON、MyBatis 或外部 Provider 细节。
|
||
- Repository 是领域侧持久化接口。
|
||
- Infrastructure / Persistence 负责 Entity、Mapper 和数据库细节。
|
||
- 外部调用通过端口和 Adapter 隔离，业务层不依赖厂商 SDK 或厂商 DTO。
|
||
|
||
## 5. 数据建模规则
|
||
|
||
必须分别建模以下业务标识，不能共用模糊字段：
|
||
|
||
```text
|
||
caseId
|
||
blockId
|
||
reservationId
|
||
confirmationNumber
|
||
groupCode
|
||
```
|
||
|
||
其他规则：
|
||
|
||
- 房型、房量、人数、金额、日期必须使用结构化字段，不只保存展示字符串。
|
||
- 状态使用稳定英文代码，中文和英文只用于显示。
|
||
- 动态参数必须有稳定 `fieldKey` 和可国际化 `labelKey`。
|
||
- 不能把某一种语言的显示文本当作接口契约或业务判断依据。
|
||
- 至少区分外部提供方建议值、人工确认值、最终执行值。
|
||
- Receipt 生成后不可覆盖修改；纠错通过新记录表达。
|
||
- Task 执行必须支持幂等、并发版本校验和审计。
|
||
|
||
## 6. SourceMessage / AI / Task 边界
|
||
|
||
- `SourceMessage` 表示 Email、LINE、附件等渠道输入的原始来源事实。
|
||
- AI 抽取输出的业务事件不是来源消息，也不是正式 Task。
|
||
- 一条 SourceMessage 可以产生多个 AI Task Result、多个候选或多张 Task。
|
||
- Task 与 SourceMessage、AI MessageEvent、Evidence 通过来源关联建模。
|
||
- 不得用单个 `createdFromEventId` 固化一对一关系。
|
||
- Case 匹配不明确时，必须创建可持久化、可审计的 Preflight / Need Manual Review 对象。
|
||
- 只有人工关联已有 Case 或确认新增 Case 后，才创建正式 TaskCard。
|
||
- Preflight / Need Manual Review 被拒绝或终止后不得删除，必须保留来源、候选版本、处理人、原因和时间。
|
||
|
||
## 7. AI / Agent Provider 边界
|
||
|
||
- 业务模块只依赖 `AiCapabilityPort` 一类稳定调用契约。
|
||
- SuperAgent、模型 ID、Agent ID、认证配置位于 Adapter 层。
|
||
- 真实 Provider 返回内容不得直接生成 Recognition、Case、Task、Operation、Receipt 或 OHIP 写入。
|
||
- Provider 输出只能作为建议或证据。
|
||
- 所有会引起业务写操作的参数必须经过规则校验和人工确认。
|
||
- 平台可记录 provider、capability、request id、版本、耗时和用量，但不实现模型训练、Prompt 优化或 Agent 编排。
|
||
|
||
## 8. AgentBus 边界
|
||
|
||
- AgentBus 是消息入口适配器，不是 AI Provider。
|
||
- 实时 AgentBus 链路只写 `platform_source_message_inbox`。
|
||
- 不直接生成 `platform_message_event`、Evidence、Recognition、Case、Task、Operation、Receipt 或 OHIP 写入。
|
||
- 不自动发送 ACK、`task.result` 或客户回复。
|
||
- SourceMessage Inbox 到 MessageEvent / Evidence 必须通过受控 replay。
|
||
- 原始 frame 本地采样默认关闭，生产不常态保存 raw frame。
|
||
|
||
## 9. OHIP / OPERA Cloud 边界
|
||
|
||
开发任何 OHIP 页面或执行器前，必须先更新字段映射文档，明确：
|
||
|
||
- 页面字段
|
||
- 领域字段
|
||
- 内部 API 字段
|
||
- OHIP 字段或 JSONPath
|
||
- 来源接口和版本
|
||
- 是否必填
|
||
- fallback
|
||
- Sandbox 验证状态
|
||
- UAT 三方核对状态
|
||
|
||
禁止根据字段名猜 Oracle API 字段。未通过官方文档或真实响应确认的内容必须标记为“待确认”。
|
||
|
||
浏览器不得直接调用 OHIP。OHIP Secret 只能由后端环境变量或部署平台 Secret 注入。
|
||
|
||
## 10. 数据库与 Flyway 规范
|
||
|
||
- 新建表和改表必须通过 Flyway migration。
|
||
- 已发布 migration 禁止直接修改。
|
||
- 修正注释、索引或约束必须新增 migration。
|
||
- 每张业务表必须有中文表级 `COMMENT`。
|
||
- 每个业务字段必须有中文字段级 `COMMENT`。
|
||
- SQL 文件应使用中文行注释划分表、索引、约束等主要结构。
|
||
- 注释必须说明业务含义、来源或代码值范围。
|
||
- 禁止使用“字段1”“备用字段”等模糊注释。
|
||
- 业务时间以 UTC 写入数据库，API 层负责返回 ISO 8601。
|
||
- JSON 字段只用于扩展元数据，不替代需要查询、约束或索引的正式列。
|
||
|
||
## 11. 后端代码注释规范
|
||
|
||
后端 Java 代码必须提供必要且准确的中文注释：
|
||
|
||
- 架构文档、设计文档、目录结构、数据模型、字段映射和接口示例必须优先使用中文说明业务含义。
|
||
- 领域对象、应用服务、外部适配器、Controller、配置属性和复杂参数对象应说明业务含义、边界或调用约束。
|
||
- 复杂流程、幂等键、并发控制、事务边界、错误转换、外部系统字段映射和安全脱敏逻辑必须说明原因。
|
||
- 注释不得只复述类名、方法名或字段名。
|
||
- 不得用“TODO 待完善”替代真实说明。
|
||
- 生成新后端代码时必须同步生成中文注释。
|
||
- 修改旧代码时，应补齐触达代码的必要中文注释。
|
||
|
||
## 12. 安全与日志
|
||
|
||
Secret 只能通过 `.env`、环境变量或部署平台 Secret 注入。仓库只提交无真实值的 `.env.example`。
|
||
|
||
禁止提交：
|
||
|
||
- 真实酒店凭证
|
||
- Oracle Client Secret、Application Key、Integration Password
|
||
- SuperAgent API Key
|
||
- AgentBus Token
|
||
- Cookie、Access Token
|
||
- 真实客户邮件、附件 URL、个人数据
|
||
- 完整支付信息
|
||
|
||
日志必须脱敏：
|
||
|
||
- Authorization、Cookie
|
||
- Client Secret、Integration Password、Application Key
|
||
- 客人姓名、邮箱、电话、证件信息
|
||
- 支付卡和账务敏感数据
|
||
- 原始消息正文、HTML、附件 URL
|
||
|
||
## 13. 配置规范
|
||
|
||
- Spring Boot 不会自动读取 `.env`，本地启动需由 shell、IDE、容器或部署平台注入环境变量。
|
||
- 本地开发可复制根目录 `.env.example` 为 `.env`，真实值只留本机。
|
||
- `TH_HOTEL_DB_URL` 包含 `&` 时必须加引号。
|
||
- 后端 Secret 不得放入前端 `VITE_*`。
|
||
- 生产环境应拆分 ConfigMap / 非敏感环境变量与 Secret / 密钥管理系统。
|
||
|
||
## 14. API 设计规范
|
||
|
||
- API 返回稳定代码，不返回中文或英文文本作为前端业务判断依据。
|
||
- 动态表单字段使用稳定 `fieldKey` 和可国际化 `labelKey`。
|
||
- 错误响应不得回显 Secret、原始正文、附件 URL 或个人信息。
|
||
- 写接口必须考虑幂等、并发版本、审计和失败恢复。
|
||
- 外部写操作结果不明确时，禁止盲目重试。
|
||
- 调试接口必须默认关闭，并使用独立访问密钥。
|
||
|
||
## 15. 测试与检查命令
|
||
|
||
后端最低检查：
|
||
|
||
```bash
|
||
cd server
|
||
./mvnw test
|
||
./mvnw verify
|
||
```
|
||
|
||
聚焦开发时可先运行相关测试：
|
||
|
||
```bash
|
||
cd server
|
||
./mvnw -Dtest=SomeFocusedTest test
|
||
```
|
||
|
||
如果命令尚未配置或因环境问题无法运行，必须明确说明，不能假装通过。
|
||
|
||
## 16. Git 与协作流程
|
||
|
||
- 改动前说明目标、范围和将修改的文件。
|
||
- 每次只处理一个模块或一个纵向切片。
|
||
- 需求基准变化时，先做差异和影响分析。
|
||
- 修改接口前确认领域模型和数据映射。
|
||
- 不修改与当前任务无关的用户变更。
|
||
- 修改后运行项目已配置的检查命令。
|
||
- Git commit message 使用中文，清楚说明本次提交的业务或技术变更。
|
||
|
||
## 17. 后端提交前检查清单
|
||
|
||
- [ ] 是否遵守 platform / workflows / integrations 分层？
|
||
- [ ] Controller 是否没有直接访问 Mapper 或外部 Adapter？
|
||
- [ ] 外部 DTO 是否没有进入领域模型？
|
||
- [ ] 写接口是否有幂等、版本或审计设计？
|
||
- [ ] Flyway SQL 是否有规范中文注释？
|
||
- [ ] Java 复杂逻辑是否有必要中文注释？
|
||
- [ ] 是否没有提交真实 Secret 或客户数据？
|
||
- [ ] 是否没有把 Provider 输出直接当业务事实？
|
||
- [ ] 是否运行了 `./mvnw test` 或说明了无法运行原因？
|
||
- [ ] 是否运行了 `./mvnw verify` 或说明了无法运行原因？
|