# HealthLink-HIS — AI 开发规范 (GitHub Copilot)

> 🤖 GitHub Copilot 打开本项目时自动加载此文件。

---

# 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
```

### 统一返回格式
```java
// 成功
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 路径规范
```javascript
// 统一前缀 /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)
```

---

## 六、快速参考命令

```bash
# === 后端 ===
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 等）均引用本文件。修改规范请只修改本文件。

---

> 📅 最后同步: 2026-06-06 09:46 | 源文件: RULES.md | 重新同步: `bash scripts/sync-ai-rules.sh`