huangting/th-hotel-simple
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
eda3e7087366a406667d1916b166473e8d3d05d3
th-hotel-simple/docs/project/backend-development-guidelines.md
andy 1046e4ef74 整理项目文档索引和规范说明
2026-07-10 23:49:49 +08:00

18 KiB
Raw Blame History

TH Hotel 后端开发规范

1. 文档定位

本文整理 TH Hotel 当前后端开发约定，供本项目后端开发和其他 agent 协作参考。

本文是当前项目专属补充，不应整份复制到其他项目。可复用的通用后端规则应沉淀到 docs/import/reusable/backend-development-guidelines.md。

本项目后端是酒店多部门 AI 业务流程与 Case 协同平台的服务端。这里的 AI 只表示调用外部 模型或 Agent 能力提供方并消费其结构化结果；本项目不开发模型、Prompt 优化平台、Agent Runtime、Planner、Memory 或通用工具调用框架。

当前项目时间存储、接口返回、酒店时区展示和本地业务日期边界统一参考 docs/project/backend-time-design.md。

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. 后端分层与包边界

推荐边界：

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；外部协议转换类应放入具体集成模块的 adapter 包。
  • 平台核心不得依赖预订部专有字段。
  • 部门工作流可以依赖平台核心，平台核心不能反向依赖部门模块。
  • 外部系统 DTO、Oracle DTO、Provider DTO、领域模型和 API Response 必须分离。
  • Oracle DTO 或生成代码只能位于 integrations.ohip，不得进入平台领域模型。
  • 外部协议到内部命令或 DTO 的转换类使用 Adapter、Converter 等能表达适配语义的后缀，不使用 Mapper 命名，避免和 MyBatis Mapper 混淆。

当前项目后端模块内部目录强制按以下结构组织：

<module>
├── control
├── service
│   └── impl
├── domain
├── mapper
├── repository
└── common
    ├── dto
    ├── request
    ├── result
    └── enums

中文说明：

目录 中文职责 放置内容
control HTTP 入口层 Controller 具体实现类，只处理请求契约、参数校验和响应映射
service 服务契约层 Service 接口，只表达模块对外提供的稳定业务能力
service.impl 服务实现层 Service 实现类，负责编排事务、幂等、Repository 和外部端口
domain 数据实体层 Entity 类，字段必须有中文注释，不能与 Response 或外部 DTO 混用
mapper MyBatis 访问层 Mapper 类和语义化 Mapper 方法，Controller 与 Service 不直接跨层暴露 Mapper
repository 持久化封装层 Repository 接口和具体实现，对 Service 屏蔽 Mapper 与数据库细节
common.dto 通用数据载体层 模块内部跨层传递的 DTO、快照、草稿等数据载体
common.request 请求模型层 Controller、Service 或外部适配器输入侧的 Request、Command、Query 条件
common.result 结果模型层 Service 或 Controller 输出侧的 Result、分页结果、操作结果
common.enums 模块枚举层 本模块稳定业务枚举、状态码和失败原因枚举

后续生成或移动 Java 代码时必须严格遵守上述目录，不再新增 api、application、persistence 等同义包来承载这些职责，除非先更新本规范并说明迁移原因。已有或迁移来的 application 包中的 Request、Result、DTO 类，应按语义移动到对应模块的 common.request、common.result、common.dto。如果类职责或目录归属不明确，必须先询问再继续。

4. Controller / Service / Repository 规则

  • Controller 只做 HTTP 契约、参数校验、权限入口和响应映射。
  • Controller 不直接访问 Mapper。
  • Controller 不直接调用外部适配器。
  • Service 接口位于 service 包，表达模块对外提供的稳定业务能力。
  • Service 实现类位于 service.impl 包，编排事务、Entity、Repository 和外部端口。
  • Request、Command、Query 条件位于 common.request 包。
  • Result、分页结果、操作结果位于 common.result 包。
  • 跨层 DTO、Snapshot、Draft 等通用数据载体位于 common.dto 包。
  • Entity 位于 domain 包，表达数据库表字段与业务含义，不与 DTO、Response 或外部 Provider DTO 混用。
  • Mapper 位于 mapper 包，只负责本模块数据库表访问和语义化查询方法。
  • Repository 位于 repository 包，负责封装 Mapper 和数据库细节，作为 Service 的持久化边界。
  • 外部调用通过端口和 Adapter 隔离，业务层不依赖厂商 SDK 或厂商 DTO。
  • 外部协议适配类位于对应 integrations.<capability>.<provider>.adapter 包，负责把外部 DTO 或 JSON 转换为内部稳定命令。
  • 生成或迁移代码前必须先阅读本规范并查看同模块既有代码习惯；如果放置目录、类名后缀或依赖方向不确定，先询问再实现。

5. 数据建模规则

必须分别建模以下业务标识，不能共用模糊字段：

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”“备用字段”等模糊注释。
  • 新建 MySQL 表必须显式指定存储引擎、字符集和排序规则，默认使用 ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin COMMENT='...'。
  • 本项目字符串字段默认大小写敏感，包含用户名、展示名、邮件主题、菜单名称、状态筛选、外部 ID、哈希、Token、nonce、幂等键、业务代码等。这样可以避免 MySQL 默认大小写不敏感 collation 把 X 和 x 之类的外部 opaque id 误判为同一个值。
  • 已有表通过 V13__make_existing_string_columns_case_sensitive.sql 统一转为 utf8mb4_bin；后续新增表或新增字符串列不能重新退回默认 *_ci collation。
  • 如果某个功能确实需要大小写不敏感搜索，不应改变整表默认 collation，应在查询层使用规范化字段、搜索索引、LOWER()/归一化值或专门搜索方案实现，并在需求文档和 migration 注释中写明原因。
  • 新建表推荐模板：
CREATE TABLE example_table (
    id BIGINT NOT NULL COMMENT '内部主键 ID',
    external_id VARCHAR(256) NULL COMMENT '外部系统 ID，按大小写敏感保存和比较',
    created_at DATETIME(6) NOT NULL COMMENT '记录创建 UTC 时间',
    PRIMARY KEY (id),
    KEY idx_example_external_id (external_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin COMMENT='示例业务表';
  • 业务时间点以 UTC 写入数据库，API 层负责返回带 Z 的 ISO 8601 UTC 时间，例如 2026-07-08T03:00:00Z。
  • 新增 API 响应 DTO 中的时间点字段优先使用 OffsetDateTime；从数据库 LocalDateTime 快照输出到接口时，应通过 UtcTimeFormatter 转换，禁止直接把无时区 LocalDateTime 暴露给前端或 SuperAgent。
  • 酒店本地业务日期，例如入住日期、离店日期、营业日，优先使用 LocalDate 或明确酒店时区语义的字段，不和 UTC 时间点混用。
  • JSON 字段只用于扩展元数据，不替代需要查询、约束或索引的正式列。

11. 后端代码注释规范

后端 Java 代码必须提供必要且准确的中文注释：

  • 架构文档、设计文档、目录结构、数据模型、字段映射和接口示例必须优先使用中文说明业务含义。
  • 领域对象、应用服务、外部适配器、Controller、配置属性和复杂参数对象应说明业务含义、边界或调用约束。
  • control、service、service.impl 中的方法必须有中文注释，说明业务动作、调用边界、幂等或安全约束。
  • mapper 中 MyBatis-Plus 自带继承方法不强制补中文注释；不要为了重命名 selectById、insert、updateById 等自带方法而写薄 default 包装。本项目自定义的语义化查询、写入、更新方法应根据业务复杂度合理补充中文注释。
  • domain 中 Entity 的每个字段必须有中文注释，说明字段业务含义、来源、代码值范围或安全限制。
  • repository 中对外暴露的方法必须有中文注释，说明持久化语义和是否返回安全字段。
  • 复杂流程、幂等键、并发控制、事务边界、错误转换、外部系统字段映射和安全脱敏逻辑必须说明原因。
  • 注释不得只复述类名、方法名或字段名。
  • 不得用“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. 测试与检查命令

后端最低检查：

cd server
./mvnw test
./mvnw verify

聚焦开发时可先运行相关测试：

cd server
./mvnw -Dtest=SomeFocusedTest test

默认 test profile 使用 H2 MySQL Mode，保证普通测试不依赖本机 MySQL。需要连接真实测试 MySQL 时，使用 test,test-mysql profile，并通过 TH_HOTEL_TEST_DB_URL、TH_HOTEL_TEST_DB_USERNAME、TH_HOTEL_TEST_DB_PASSWORD 注入测试库连接信息。测试 MySQL 只能使用本地或 CI 测试库，不得连接生产库或包含真实酒店、客户、支付数据的数据库。

如果命令尚未配置或因环境问题无法运行，必须明确说明，不能假装通过。

16. Git 与协作流程

  • 改动前说明目标、范围和将修改的文件。
  • 每次只处理一个模块或一个纵向切片。
  • 需求基准变化时，先做差异和影响分析。
  • 修改接口前确认领域模型和数据映射。
  • 不修改与当前任务无关的用户变更。
  • 修改后运行项目已配置的检查命令。
  • Git commit message 使用中文，清楚说明本次提交的业务或技术变更。

17. 后端提交前检查清单

  • 是否遵守 platform / workflows / integrations 分层？
  • 模块内部是否遵守 control / service / service.impl / domain / mapper / repository / common.dto / common.request / common.result / common.enums 目录规则？
  • Controller 是否没有直接访问 Mapper 或外部 Adapter？
  • Request、Result、DTO 是否放在 common.request、common.result、common.dto，而不是混在 service 或临时 application 包？
  • control、service、service.impl、repository 方法是否有中文注释？
  • Mapper 自定义语义化方法是否按复杂度合理补充中文注释，且未为了 MyBatis-Plus 自带继承方法强行加无意义注释？
  • 外部协议适配类是否放在 integrations.<capability>.<provider>.adapter，并避免使用 Mapper 命名混淆 MyBatis Mapper？
  • Entity 字段是否有中文注释？
  • 外部 DTO 是否没有进入领域模型？
  • 写接口是否有幂等、版本或审计设计？
  • Flyway SQL 是否有规范中文注释？
  • Java 复杂逻辑是否有必要中文注释？
  • 是否没有提交真实 Secret 或客户数据？
  • 是否没有把 Provider 输出直接当业务事实？
  • 是否运行了 ./mvnw test 或说明了无法运行原因？
  • 是否运行了 ./mvnw verify 或说明了无法运行原因？