176 lines
12 KiB
Markdown
176 lines
12 KiB
Markdown
# 项目协作与开发规范
|
||
|
||
## 1. 文档关系
|
||
|
||
本文件是当前项目的协作入口，供开发者和 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`。
|
||
- 当前项目 SuperAgent HTTP 对外接口总契约位于 `docs/project/integrations/superagent-api-contract.md`。
|
||
- 当前项目 SuperAgent MCP 资料包位于 `docs/project/integrations/superagent-mcp/README.md`。
|
||
|
||
如本文件、`docs/project` 与 `docs/import/reusable` 中的通用规范冲突，以本文件和 `docs/project` 的当前项目补充为准。
|
||
|
||
## 2. 工作方式
|
||
|
||
- 先确认目标、边界和验收标准，再写代码。
|
||
- 大改动前先说明目标、范围和预计修改的文件。
|
||
- 每次只做一个明确 checkpoint，不顺手扩展无关功能。
|
||
- 不修改与当前任务无关的用户变更。
|
||
- 不回滚用户自己的改动，除非用户明确要求。
|
||
- 遇到不确定的技术栈、目录、接口契约或数据模型，先确认再继续。
|
||
- 新项目初始化或技术栈升级前，必须检查前端、后端、构建工具、测试工具和运行时版本兼容性。
|
||
- 输出分层结构、目录树、数据模型、字段映射或接口示例时，必须补充中文说明，不能只依赖英文命名表达业务含义。
|
||
- 完成 Feature 或 checkpoint 后，必须按 AI-NSES 检查 Domain、Architecture、Workflow、ADR、Spec、Project State 和安全边界文档是否需要更新；如果没有文档变化，明确说明 `No documentation changes required.`。
|
||
|
||
## 3. 分支与提交
|
||
|
||
- `master` 保持稳定。
|
||
- `develop` 用于集成。
|
||
- `feature/*` 用于具体开发。
|
||
- 当前主要开发分支为 `feature/huangting`。
|
||
- commit message 使用中文，清楚说明本次业务或技术变更。
|
||
- 提交前检查工作区，避免误提交本地文件、Secret、构建产物或真实业务数据。
|
||
|
||
## 4. 项目结构
|
||
|
||
本项目是前后端都有的全栈项目，目录应保持职责清晰：
|
||
|
||
- `CONTEXT.md`：项目长期上下文入口。
|
||
- `PROJECT_STATE.md`：当前项目状态入口，允许高频更新。
|
||
- `client/`：前端应用。
|
||
- `server/`：后端服务。
|
||
- `mcp-server/`：SuperAgent MCP 方案入口指针；当前不单独部署 MCP 服务，运行时代码内嵌在 `server/`，对外资料包位于 `docs/project/integrations/superagent-mcp/`。
|
||
- `docs/`：项目文档、设计文档、导入规范和决策记录。
|
||
- `docs/import/reusable/`：从其他项目迁移来的可复用规范和参考资料，后续新项目可整目录复制。
|
||
- `docs/project/`：当前项目专属业务规则、架构边界和外部系统约束，不作为整包复用资料。
|
||
|
||
前端、后端、文档和接口契约应分目录管理。不要把后端 Secret、外部系统调用或数据库逻辑放入前端。
|
||
|
||
## 5. 低耦合与可维护性
|
||
|
||
项目各功能模块必须保持低耦合、高内聚和高可维护性。新增功能时，应先明确模块边界、输入输出、依赖方向和验收标准，再开始实现。
|
||
|
||
落地要求：
|
||
|
||
- 每个模块只负责一个清晰业务能力，避免把多个业务概念揉进同一个类、组件或服务。
|
||
- 依赖方向必须单向清晰：通用平台能力不能反向依赖具体业务流程。
|
||
- 跨模块调用优先通过 Service、Port、API 契约或事件完成，不直接访问对方 Mapper、Entity 或内部实现。
|
||
- 外部系统能力必须通过 `integrations` Adapter 隔离，业务层只依赖稳定端口。
|
||
- DTO、Entity、Domain、Response、外部系统 DTO 不混用。
|
||
- 公共代码只有在出现真实重复和稳定语义后再抽取，禁止为了“看起来通用”提前做大而全工具类。
|
||
- 单个文件、类、方法或组件过大时，应优先按业务职责拆分。
|
||
- 修改一个功能时，不应迫使无关模块跟着改；如果频繁连锁修改，说明边界需要重新设计。
|
||
- 测试应覆盖模块公开行为和关键边界，避免只测试内部实现细节。
|
||
|
||
## 6. 前后端边界
|
||
|
||
- 前端只负责展示、交互、人工确认、调试入口和调用本项目后端。
|
||
- 前端不得直接调用 OHIP、SuperAgent、AgentBus、数据库或任何持有 Secret 的外部系统。
|
||
- 后端负责数据库、Secret、外部系统适配、业务规则、审计和安全脱敏。
|
||
- 接口字段使用稳定代码，不使用中文或英文显示文案做业务判断。
|
||
- 接口变更前先确认字段映射、前后端影响和测试范围。
|
||
- 新增或修改接口时，必须同步确认调用方类型、鉴权方式、权限码、酒店隔离、敏感数据返回和审计要求，并更新 `docs/project/security-access-control-boundary.md` 及相关前后端或第三方契约文档。
|
||
|
||
## 7. 后端架构边界
|
||
|
||
后端应优先按以下边界组织：
|
||
|
||
- `platform`：部门中立能力，例如消息、证据、AI 调用审计、系统调试、通用任务基础能力。
|
||
- `workflows`：部门业务流程，当前优先考虑 `reservation`。
|
||
- `integrations`：外部系统适配器，例如 SuperAgent、AgentBus、OHIP。
|
||
|
||
平台核心不得依赖部门专有字段；外部系统 DTO、领域模型和 API Response 必须分离。
|
||
|
||
后端 Java 代码默认参考 Alibaba Java Coding Guidelines，并遵守本项目后端开发规范。生成或修改 Java 代码时，应优先保证：
|
||
|
||
- 命名、分层、DTO / Entity / Domain / Response 边界清晰。
|
||
- 分层结构、包结构、数据模型和字段映射必须配中文注释或中文说明，说明每层职责、依赖方向和关键字段含义。
|
||
- 后端模块内部包结构必须保持稳定：`control` 放 Controller 具体实现，`service` 放 Service 接口，`service.impl` 放 Service 实现类，`domain` 放 Entity，`mapper` 放 Mapper，`repository` 放 Repository 接口和具体实现，通用数据载体放在对应模块的 `common.dto`、`common.request`、`common.result`，枚举放在 `common.enums`。
|
||
- 外部系统适配类应放在对应 `integrations.<capability>.<provider>.adapter` 包；外部协议转换类使用 `Adapter`、`Converter` 等后缀，不使用 `Mapper` 命名，避免和 MyBatis Mapper 混淆。
|
||
- `control`、`service`、`service.impl` 中的方法必须有中文注释，说明业务含义、边界或调用约束；`mapper` 中 MyBatis-Plus 自带继承方法不强制加注释，不为了重命名自带方法写薄 default 包装，自定义语义化查询或写入方法应按复杂度合理补充中文注释；`domain` 中 Entity 字段必须有中文注释，说明字段业务含义。
|
||
- 生成代码前必须先参考 `AGENTS.md`、当前项目后端规范和既有代码习惯；遇到类职责或目录归属不确定时，先询问再继续，不能先写完再统一重构。
|
||
- 不写魔法值，稳定业务代码使用常量或枚举。
|
||
- 集合、空值、字符串、时间、金额和 `BigDecimal` 使用安全写法。
|
||
- 后端业务时间点统一按 UTC 处理：数据库 `LocalDateTime` 默认表示 UTC，API 返回时间点字段必须使用带 `Z` 的 ISO 8601 UTC 时间；新增响应 DTO 优先使用 `OffsetDateTime`，从数据库快照输出时使用 `UtcTimeFormatter` 统一转换。
|
||
- 入住日期、离店日期、酒店营业日等酒店本地业务日期不得和 UTC 时间点混用，应使用 `LocalDate` 或明确酒店时区语义的字段。
|
||
- 新增 MySQL 表必须显式使用 `ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin COMMENT='...'`；字符串默认按大小写敏感保存和比较，避免外部 opaque id、哈希、Token、状态码或业务代码因默认不区分大小写而误判。
|
||
- 如某个业务查询确实需要大小写不敏感，应在查询层、搜索列或专门索引中明确实现，并在 migration 和文档中说明原因，不能依赖数据库默认 collation。
|
||
- 异常不吞掉，日志有上下文但不输出 Secret 或个人敏感信息。
|
||
- 写操作考虑幂等、并发版本、事务边界、审计和失败恢复。
|
||
- 复杂业务规则、外部字段映射、脱敏和幂等逻辑必须有必要中文注释。
|
||
|
||
## 8. AgentBus 与 SuperAgent 边界
|
||
|
||
- AgentBus 是消息入口适配器，不是 AI Provider。
|
||
- SuperAgent 是外部 AI / Agent 能力提供方，不是业务事实来源。
|
||
- AgentBus 实时入口必须先落 SourceMessage Inbox；如需推送 SuperAgent，只能通过入库后的受控异步 dispatch / outbox 链路完成，不在 WebSocket 回调内直接生成 Case、Task、Operation、Receipt 或客户回复。
|
||
- SuperAgent 返回内容只能作为建议、证据或审计结果，不能直接改变最终业务状态。
|
||
- 所有业务写操作必须经过规则校验、权限控制、幂等控制和人工确认。
|
||
|
||
## 9. 安全规范
|
||
|
||
- Secret 只放环境变量、本地 `.env` 或部署平台 Secret。
|
||
- 仓库只提交无真实值的 `.env.example`。
|
||
- 禁止提交真实酒店凭证、客户数据、Token、Cookie、API Key、数据库密码或支付信息。
|
||
- 日志、错误响应和测试夹具不得暴露 Token、Secret、原始邮件正文、附件 URL 或个人敏感信息。
|
||
- Debug、Demo、Replay、Probe 等系统调试接口必须默认关闭或受控开放，不得因为前端页面存在就作为普通业务能力暴露。
|
||
- `.DS_Store`、构建产物、依赖目录、IDE 临时文件和本地样本目录应忽略。
|
||
|
||
## 10. 测试与验证
|
||
|
||
- 修改后运行对应模块已有检查命令。
|
||
- 如果检查命令尚未配置或因环境问题无法运行，必须明确说明原因。
|
||
- 不假装测试通过。
|
||
- 优先做小的可验证闭环，再逐步扩展业务能力。
|
||
|
||
## 11. Agent 协作规则
|
||
|
||
Coding agent 开始任务前应先读取：
|
||
|
||
1. `AGENTS.md`
|
||
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`，完成后同步更新该文档和相关前后端或第三方契约。
|
||
|
||
改文件前要说明计划；完成后要说明改了什么、如何验证、还有哪些风险或未完成项。
|
||
|
||
生成或修改代码前，必须先参考当前代码开发规范和同模块既有代码习惯；如果目录归属、类名后缀、依赖方向或注释粒度不确定，先询问用户再继续。
|
||
|
||
## 12. 当前第一个 checkpoint
|
||
|
||
第一个建议 checkpoint：
|
||
|
||
`checkpoint-001-project-skeleton-health`
|
||
|
||
验收标准：
|
||
|
||
- 有清晰的根目录协作规范和项目说明。
|
||
- 后端最小服务可以启动。
|
||
- 前端最小应用可以启动。
|
||
- 后端提供 `GET /api/health`。
|
||
- 前端可以调用后端健康检查并展示状态。
|
||
- 前后端都有明确的启动、测试和构建命令。
|