his/RULES.md

HealthLink-HIS — AI 开发规范（自动加载）

🤖 本文件供所有 AI 编码工具自动读取。无论使用 Claude Code、Cursor、Codex CLI、Copilot、Qwen、Cline 还是其他工具，进入本项目后必须遵守以下规范。

---

一、项目概览

属性	值
项目名	HealthLink-HIS（医院信息系统）
后端路径	healthlink-his-server/
前端路径	healthlink-his-ui/
文档路径	MD/
JDK	25 (OpenJDK)
Spring Boot	4.0.6
Vue	3.x + Vite + Element Plus
数据库	PostgreSQL 15+
包名	com.healthlink.his

---

二、铁律（必须遵守，违反即失败）

🔴 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 必须与后端匹配
• 接口变更必须同步更新前后端代码

🟡 P1 铁律 — 强烈建议

铁律5: 先分解再行动

• 修改超过3个文件、涉及多模块、数据库变更，必须先制定计划

铁律6: 验证后信

• 每次修改后必须验证编译通过，不信记忆
• 重新编译命令：mvn clean compile -DskipTests

铁律7: 文档统一管理

• 所有文档存储在 MD/ 目录
• 文件名：大写英文+下划线（如 BACKEND_CHECKLIST.md）
• 文档头部必须包含元数据块（文档类型、版本、日期）

铁律8: 规范文档在 MD/specs/

• 完整铁律：MD/specs/IRON_RULES.md
• 后端规范：MD/specs/BACKEND_DEVELOPMENT_STANDARD.md
• 前端规范：MD/specs/FRONTEND_DEVELOPMENT_STANDARD.md

---

三、后端开发规范

分层架构

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

统一返回格式

// 成功
AjaxResult.success(data)
// 失败
AjaxResult.error("错误信息")
// 列表
getDataTable(list)

关键约束

• 所有查询使用 LambdaQueryWrapper，禁止字符串拼接 SQL
• @Transactional(rollbackFor = Exception.class) 管理事务
• 所有接口标注 @PreAuthorize 权限控制
• 患者敏感信息（身份证、手机号）在日志中脱敏
• 扩展功能不要修改原有函数签名，新建 Service/AppService

---

四、前端开发规范

技术栈

• 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 路径规范

// 统一前缀 /healthlink-his/api/v1/
export function listXxx(query) {
  return request({ url: '/healthlink-his/api/v1/xxx/list', method: 'get', params: query })
}

组件规范

• 页面组件使用 <script setup> 语法
• 弹窗组件使用 defineExpose({ open }) 暴露打开方法
• 列表必须支持分页（pagination 组件）
• 按钮权限使用 v-hasPermi 指令

关键约束

• 路由懒加载：() => import('@/views/xxx/index.vue')
• 不使用 v-html（除非做 XSS 转义）
• 不在前端硬编码密码、密钥
• onMounted 中注册的事件在 onUnmounted 中移除

---

五、开发流程

1. 分析需求 → 读相关文档(MD/)
2. 制定计划 → update_plan
3. 后端开发 → Controller → AppService → Service → Mapper → Entity → Flyway
4. 后端测试 → mvn test → 接口测试通过
5. 前端开发 → API接口 → 页面组件 → 路由配置
6. 前端测试 → npm run build:dev → 功能验证
7. 提交代码 → git add → git commit(规范格式) → git push

Git Commit 格式

<type>(<scope>): <subject>

type: feat|fix|docs|refactor|test|chore
scope: 模块名(如 registration, billing, pharmacy)

---

六、快速参考命令

# === 后端 ===
export JAVA_HOME=/opt/jdk-25
mvn clean compile -DskipTests          # 编译
mvn install -DskipTests                # 完整构建
mvn test -pl healthlink-his-application -Dtest="XxxTest" -Dsurefire.failIfNoSpecifiedTests=false  # 测试

# === 前端 ===
cd healthlink-his-ui
npm run dev                             # 开发模式
npm run build:dev                       # 构建
npm run lint                            # 代码检查
npm run test:run                        # 单元测试

# === Git ===
git status                              # 查看变更
git add -A                              # 暂存所有
git commit -m "feat(module): description"  # 提交
git push origin develop                 # 推送

---

七、详细规范文档索引

文档	路径	用途
执行铁律	MD/specs/IRON_RULES.md	铁律完整版
后端规范	MD/specs/BACKEND_DEVELOPMENT_STANDARD.md	后端编码标准
前端规范	MD/specs/FRONTEND_DEVELOPMENT_STANDARD.md	前端编码标准
文档规范	MD/DOCUMENTATION_STANDARD.md	文档管理标准
后端清单	MD/specs/BACKEND_CHECKLIST.md	发布前检查
前端清单	MD/specs/FRONTEND_CHECKLIST.md	发布前检查
三甲标准	MD/standards/GRADE3A_HIS_STANDARD.md	三甲医院达标标准
Flyway指南	MD/guides/FLYWAY_USAGE_GUIDE.md	数据库迁移指南

---

⚠️ 警告: 本文件是项目 AI 开发规范的唯一信源。各工具配置文件（AGENTS.md、.cursorrules 等）均引用本文件。修改规范请只修改本文件。