docs: 增加项目规范和邮件来源入口PRD
This commit is contained in:
andy
265
docs/project/backend-development-guidelines.md
Normal file
265
docs/project/backend-development-guidelines.md
Normal file
@@ -0,0 +1,265 @@
|
||||
# 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` 或说明了无法运行原因？
|
||||
Reference in New Issue
Block a user