# HealthLink-HIS — AI 开发规范 (Cursor) > 🤖 Cursor IDE 打开本项目时自动加载此文件。 --- # HealthLink-HIS — AI 开发规范（自动加载） > 🤖 **本文件供所有 AI 编码工具自动读取**。无论使用 Claude Code、Cursor、Codex CLI、Copilot、Qwen、Cline 还是其他工具，进入本项目后必须遵守以下规范。 > > **模型决定上限，Harness 决定底线。** --- ## 一、项目概览 | 属性 | 值 | |------|------| | 项目名 | HealthLink-HIS（医院信息系统） | | 后端路径 | `healthlink-his-server/` | | 前端路径 | `healthlink-his-ui/` | | 文档路径 | `MD/` | | JDK | 25 (OpenJDK) | | Spring Boot | 4.0.6 | | MyBatis-Plus | 3.5.16 | | Vue | 3.x + Vite + Element Plus | | 数据库 | PostgreSQL 15+ | | 包名 | `com.healthlink.his` | | 后端端口 | 18082 | | 前端端口 | 81 | --- ## 二、铁律（必须遵守，违反即失败） ### 🔴 P0 铁律 — 不可违反 **铁律1: 修改完必须测试** ``` 后端: mvn clean compile -DskipTests → mvn install -DskipTests → mvn test 前端: npm run build:dev → npm run lint ``` - 白盒：编译通过，无 ERROR - 黑盒：关键接口返回 `{code:200, data:...}`，验证业务逻辑 - 冒烟：应用正常启动，核心流程通畅 **铁律2: Flyway 数据库迁移** - 凡是新建表、新增字段，必须创建 Flyway 迁移脚本 - 路径：`healthlink-his-domain/src/main/resources/db/migration/` - 命名：`V{版本号}__{描述}.sql`（双下划线） - 禁止直接在数据库执行 SQL 不走 Flyway **铁律3: 测试通过后才提交** - 编译 + 测试全部通过后才能 git commit - 不提交未完成的功能、调试代码、临时文件 **铁律4: 前后端API路径对齐** - 后端前缀：`/healthlink-his/api/v1/` - 前端 `request.js` 的 baseURL 必须与后端匹配 - 接口变更必须同步更新前后端代码 **铁律5: 状态值一致性（来自 Bug #574 教训）** - 修改任何状态值前，必须先列出完整的状态流转链路 - 检查项： 1. 枚举定义的值是否正确 2. Service 层设置的状态值是否与枚举一致 3. 查询/列表接口的状态映射是否覆盖所有枚举值 4. 前端 `STATUS_CLASS_MAP` 是否包含新状态 5. 前端过滤条件（如 `v-if`）是否兼容新状态 6. 池/统计表的聚合 SQL 是否包含新状态值 - 禁止：只改一端不检查其他端 **铁律6: 禁止删除源文件（来自 Bug #574 教训）** - 绝对禁止删除项目中已有的 Java/Vue/SQL 源文件 - 文件有编译错误 → 修复错误，不删除文件 - 文件是重复的 → 重构合并，不删除文件 - 文件是 AI 幻觉创建的 → 检查 git baseline 确认后再删除 - 唯一例外：明确由人类确认删除的文件 **铁律7: 禁止修改已有公开方法签名** - 不能删除或重命名已有的 public 方法 - 不能修改已有方法的参数列表 - 需要新增功能时 → 添加新的重载方法 - 需要改行为时 → 修改方法内部实现，不改签名 ### 🟡 P1 铁律 — 强烈建议 **铁律8: 先分解再行动** - 修改超过3个文件、涉及多模块、数据库变更，必须先制定计划 **铁律9: 验证后信** - 每次修改后必须验证编译通过，不信记忆 - 重新编译命令：`mvn clean compile -DskipTests` **铁律10: 文档统一管理** - 所有文档存储在 `MD/` 目录 - 文件名：大写英文+下划线（如 `BACKEND_CHECKLIST.md`） - 文档头部必须包含元数据块（文档类型、版本、日期） --- ## 三、全链路 6 环分析 > ⚠️ **涉及数据库字段的 Bug / 需求，必须走完整链路，不得"就事论事"。** ``` 前端/页面 → Controller → Service → Mapper → DB/SQL → 关联模块 ①录入 ②验证 ③业务 ④持久化 ⑤存储 ⑥联动 ``` ### 每一环必须确认 | 环 | 检查内容 | |----|---------| | ① 录入 | 前端有无输入入口（弹窗、表格行编辑、表单） | | ② 验证 | Controller 参数校验、@Valid、权限控制 | | ③ 业务 | Service 业务逻辑、事务边界、多个 Service 实现类入口 | | ④ 持久化 | Mapper XML、DTO 字段映射、类型转换 | | ⑤ 存储 | 数据库表结构、索引、NOT NULL 约束 | | ⑥ 联动 | 上游（医嘱→护士站）、下游（打印、计费、报表）是否同步 | ### 全链路验证顺序 修复涉及状态流转的问题后，必须按以下顺序验证： 1. **数据库**：确认状态值已正确写入 2. **后端接口**：确认返回的状态映射正确 3. **前端显示**：确认页面显示正确状态文本 4. **前端交互**：确认按钮/操作基于正确状态启用/禁用 5. **统计数据**：确认池/报表统计包含新状态 ### 常见陷阱 - ❌ 只修了「主入口」的保存逻辑，忘了「批量保存」「签发保存」等其他入口 - ❌ 前端加了输入框，后端 Service 没传字段 - ❌ Mapper XML 是 UNION ALL 查询，只改了其中一个子查询 - ❌ DTO 层级继承关系没检查 - ❌ 只测了新增，没测编辑已有数据的回显和修改再保存 --- ## 四、Harness Engineering 方法论 > Harness = 约束 + 反馈 + 控制平面 + 持久执行 ### 4.1 四层约束金字塔 | 层级 | 内容 | 落地方式 | |------|------|---------| | **L1 架构约束** | 接口合约、包结构、命名规范、禁止模式 | 本文件铁律、AGENTS.md | | **L2 代码质量** | 圈复杂度、代码风格、类型提示 | 编译门禁 + ESLint | | **L3 安全约束** | 敏感信息检测、权限检查、输入验证 | 配置不可硬编码 | | **L4 业务规则** | 领域逻辑、数据一致性、事务边界 | 全链路 6 环验证 | **约束优先级**：安全 > 架构 > 质量 > 业务 ### 4.2 三层反馈系统 | 层级 | 速度 | 覆盖范围 | 失败处理 | |------|------|---------|---------| | **L1 编译检查** | <30 秒 | 语法、类型、签名 | 立即阻断，自行修复 | | **L2 数据流验证** | <5 分钟 | 全链路字段、Mapper XML、DTO | 修复后上报 | | **L3 人工审查** | 10-30 分钟 | 架构、设计、业务正确性 | 驳回 / 指导 / 批准 | **反馈设计铁律**： - 反馈必须可行动（指出：文件 + 行号 + 错误类型 + 修复方向） - 反馈越及时越好（L1 即时 → L2 分钟 → L3 小时） - 失败后先回滚到最近检查点，再重试 ### 4.3 控制平面（Agent 协调） ``` ┌─────────────────────────────────────────────┐ │ 战略层（人类主导） │ │ ├── 设定目标、审批关键决策 │ │ └── 异常升级处理 │ ├─────────────────────────────────────────────┤ │ 战术层（Control Plane） │ │ ├── 任务分解 + update_plan │ │ ├── 依赖协调 + 资源分配 │ │ └── 检查点保存 + 恢复 │ ├─────────────────────────────────────────────┤ │ 执行层（Agent 自主） │ │ ├── 代码生成、测试执行 │ │ └── 错误恢复 + 幂等重试 │ └─────────────────────────────────────────────┘ ``` ### 4.4 持久执行 - 每个关键步骤保存检查点（`update_plan` 进度） - 失败后从最新检查点恢复，不从头开始 - 幂等设计：同一操作重复执行结果一致 --- ## 五、质量门禁（5 级） | 级别 | 门禁 | 通过标准 | |------|------|---------| | **L1** | 编译通过 | `mvn clean compile` + `npm run build:dev` 无 ERROR | | **L2** | 测试通过 | 单元测试 + 接口测试全部通过 | | **L3** | DB 审查 | Flyway 脚本规范、SQL 安全、索引合理 | | **L4** | 验收通过 | 核心功能流程完整验证、全链路检查 | | **L5** | 归档完成 | Git commit + 文档更新 + 代码推送 | ### 提交铁律 - L1-L2 必须通过才能 commit - L3（如有DB变更）必须通过才能 push - L4-L5 发布前必须完成 --- ## 六、后端开发规范 ### 分层架构 ``` Controller → AppService → Service → Mapper → Entity 接收请求 编排业务 单表CRUD 数据访问 实体定义 ``` ### 命名规范 | 类型 | 规则 | 示例 | |------|------|------| | Controller | `XxxController` | `RegistrationController` | | AppService | `IXxxAppService` / `XxxAppServiceImpl` | `IRegistrationAppService` | | Service | `IXxxService` / `XxxServiceImpl` | `IRegistrationService` | | Mapper | `XxxMapper` | `RegistrationMapper` | | Entity | `Xxx` | `Registration` | | DTO | `XxxDto` / `XxxQueryDto` | `RegistrationDto` | ### 包结构 ``` com.healthlink.his.web.{module}.controller com.healthlink.his.web.{module}.appservice com.healthlink.his.web.{module}.service com.healthlink.his.web.{module}.mapper com.healthlink.his.web.{module}.dto com.healthlink.his.domain.{module} com.healthlink.his.common.enums ``` ### 统一返回格式 ```java AjaxResult.success(data) // 成功 AjaxResult.error("错误信息") // 失败 getDataTable(list) // 列表 ``` ### 关键约束 - 所有查询使用 `LambdaQueryWrapper`，禁止字符串拼接 SQL - `@Transactional(rollbackFor = Exception.class)` 管理事务 - 所有接口标注 `@PreAuthorize` 权限控制 - 患者敏感信息（身份证、手机号）在日志中脱敏 - **扩展功能不修改原有函数签名**，新建 Service/AppService - 涉及多表写操作的方法标注 `@Transactional` - 事务方法未被同一类内方法直接调用（避免自调用失效） --- ## 七、前端开发规范 ### 技术栈 - Vue 3 + Vite + Element Plus + Pinia + Axios - 基于 RuoYi-Vue3 框架 ### 目录结构 ``` src/api/{module}/ # API接口（kebab-case路径） src/views/{module}/ # 页面组件 src/store/modules/ # Pinia状态管理 src/components/ # 公共组件 ``` ### API 路径规范 ```javascript // 统一前缀 /healthlink-his/api/v1/ export function listXxx(query) { return request({ url: '/healthlink-his/api/v1/xxx/list', method: 'get', params: query }) } ``` ### 组件规范 - 页面组件使用 `