feat: 添加AI开发规范自动加载配置 — 支持所有AI编码工具

单一信源设计: - RULES.md: 项目唯一规范信源(218行,覆盖铁律+后端+前端规范) 多工具适配(7个配置文件): - AGENTS.md: Codex CLI / Claude Code 自动读取 - .cursorrules: Cursor IDE 自动读取 - .github/copilot-instructions.md: GitHub Copilot 自动读取 - .windsurfrules: Windsurf/Codeium 自动读取 - .clinerules: Cline 自动读取 - .aider.conf.yml: Aider 自动读取 - .qwenrules: Qwen Coder/通义灵码自动读取子目录 AGENTS.md 同步更新引用 RULES.md
2026-06-06 09:46:15 +08:00
parent 3578a24254
commit e8af9ea40a
10 changed files with 336 additions and 83 deletions
--- a/.aider.conf.yml
+++ b/.aider.conf.yml
@@ -0,0 +1,4 @@
+# Aider configuration for HealthLink-HIS
+# Aider reads instructions from the files listed below
+instruction-files:
+  - RULES.md
--- a/.clinerules
+++ b/.clinerules
@@ -0,0 +1,3 @@
+# HealthLink-HIS Cline Rules
+
+Read RULES.md in the project root. It contains all iron rules and development standards for this project.
--- a/.cursorrules
+++ b/.cursorrules
@@ -0,0 +1,17 @@
+# HealthLink-HIS AI Development Rules
+
+Read and follow RULES.md in the project root. It contains all iron rules and development standards.
+
+## Key Rules
+- All code changes must pass compilation tests before commit
+- Database changes must use Flyway migration scripts
+- Follow the layered architecture: Controller → AppService → Service → Mapper → Entity
+- API prefix: /healthlink-his/api/v1/
+- Package: com.healthlink.his
+- Backend: Spring Boot 4.0.6, JDK 25, MyBatis-Plus 3.5.16
+- Frontend: Vue 3, Vite, Element Plus, Pinia
+
+## File Structure
+- Backend: healthlink-his-server/
+- Frontend: healthlink-his-ui/
+- Docs: MD/ (all specs in MD/specs/)
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,11 @@
+# HealthLink-HIS — GitHub Copilot Instructions
+
+Read RULES.md in the project root for complete development standards.
+
+## Quick Reference
+- Backend: healthlink-his-server/ (Spring Boot 4.0.6, JDK 25, MyBatis-Plus 3.5.16)
+- Frontend: healthlink-his-ui/ (Vue 3, Vite, Element Plus)
+- Package: com.healthlink.his
+- API prefix: /healthlink-his/api/v1/
+- All DB changes via Flyway: healthlink-his-domain/src/main/resources/db/migration/
+- Test before commit: mvn clean compile -DskipTests && npm run build:dev
--- a/.qwenrules
+++ b/.qwenrules
@@ -0,0 +1,9 @@
+# HealthLink-HIS Development Rules
+
+Read RULES.md in the project root for all development standards and iron rules.
+
+This is a hospital information system (HIS) project.
+Backend: healthlink-his-server/ (Spring Boot 4.0.6, JDK 25)
+Frontend: healthlink-his-ui/ (Vue 3, Vite, Element Plus)
+Package: com.healthlink.his
+Always follow the iron rules defined in RULES.md.
--- a/.windsurfrules
+++ b/.windsurfrules
@@ -0,0 +1,9 @@
+# HealthLink-HIS Development Rules
+
+Read RULES.md in the project root for all development standards and iron rules.
+
+Backend: Spring Boot 4.0.6 + JDK 25 + MyBatis-Plus 3.5.16
+Frontend: Vue 3 + Vite + Element Plus + Pinia
+Package: com.healthlink.his
+API prefix: /healthlink-his/api/v1/
+DB migrations: Flyway scripts in healthlink-his-domain/src/main/resources/db/migration/
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -0,0 +1,26 @@
+# HealthLink-HIS — AI 开发规范
+
+> 🤖 本文件由 Codex CLI、Claude Code 等工具自动读取。
+> 完整规范请阅读 **[RULES.md](RULES.md)**，必须严格遵守。
+
+## 快速铁律
+
+1. **修改完必须测试** — `mvn clean compile -DskipTests` + `npm run build:dev`
+2. **Flyway 迁移** — 新建表/字段必须走 Flyway 脚本
+3. **测试通过才提交** — 编译+测试全通过才能 commit
+4. **API路径对齐** — 后端 `/healthlink-his/api/v1/`，前端同步
+5. **先分解再行动** — 非平凡任务先出计划
+6. **文档在 MD 目录** — 大写下划线命名，含元数据块
+
+## 项目结构
+
+- 后端: `healthlink-his-server/` (Spring Boot 4.0.6 + JDK 25)
+- 前端: `healthlink-his-ui/` (Vue 3 + Vite + Element Plus)
+- 文档: `MD/` (30个规范文档)
+
+## 详细规范
+
+→ 完整铁律: `MD/specs/IRON_RULES.md`
+→ 后端规范: `MD/specs/BACKEND_DEVELOPMENT_STANDARD.md`
+→ 前端规范: `MD/specs/FRONTEND_DEVELOPMENT_STANDARD.md`
+→ 本文档完整版: `RULES.md`
--- a/RULES.md
+++ b/RULES.md
@@ -0,0 +1,218 @@
+# 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 等）均引用本文件。修改规范请只修改本文件。
--- a/healthlink-his-server/AGENTS.md
+++ b/healthlink-his-server/AGENTS.md
@@ -1,73 +1,28 @@
-# HealthLink-HIS 铁律
+# HealthLink-HIS 后端开发规范

-## 铁律 #1: 修改完必须测试
-**任何代码修改后，必须完成以下测试才能提交：**
+> 🤖 本文件供 AI 工具自动读取。完整规范见 **[../../RULES.md](../../RULES.md)**

-### 白盒测试
- `mvn clean compile` 编译通过
- 单元测试通过（如有）
+## 铁律速查

-### 黑盒测试
- 启动应用，验证无启动报错
- 测试关键接口（登录、核心业务接口）
- 验证请求响应正确
+1. **修改完必须测试** — `mvn clean compile -DskipTests`
+2. **Flyway 迁移** — 新建表/字段必须走 Flyway
+3. **测试通过才提交** — 编译+测试全通过才能 commit
+4. **API路径对齐** — `/healthlink-his/api/v1/`
+5. **先分解再行动** — 非平凡任务先出计划
+6. **文档在 MD 目录** — 大写下划线命名

-### 冒烟测试
- 应用正常启动（端口监听）
- 健康检查接口返回正常
- 基础 CRUD 操作正常
+## 快速命令

-## 铁律 #2: Flyway 迁移
-但凡遇到有新建表和字段的，通过 Flyway 框架去实现。
-
-## 铁律 #3: 先分解再行动
-任何非平凡任务先出 plan 再执行。
-
-## 铁律 #4: 验证后信
-每次修改后必须验证编译通过，不信记忆。
-
-## 铁律 #5: 文档统一管理
-**所有文档必须存储在 `MD/` 目录中，遵循以下规范：**
-
-### 目录结构
-```
-MD/
-├── architecture/    # 架构设计
-├── development/     # 开发计划与记录
-├── standards/       # 国家/行业标准
-├── specs/           # 技术规范与流程
-├── bugs/            # Bug分析与修复记录
-├── guides/          # 使用指南
-└── upgrade/         # 升级记录
+```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
 ```

-### 命名规范
- 文件名使用**大写英文+下划线**（如 `GRADE3A_DETAILED_DESIGN.md`）
- 不使用中文作文件名
- 不使用空格分隔单词
- 版本号标注在文件名末尾（如 `_V2`）
+## 详细规范

-### 格式要求
- 文档头部必须包含元数据块（文档类型、版本、日期）
- 代码块必须标注语言类型
- 表格使用标准Markdown格式
-
-### 详细规范
-参见 `MD/DOCUMENTATION_STANDARD.md`
-
-## 铁律 #6: 测试通过后才提交
-**代码修改必须通过完整测试后才能提交到远程仓库。**
-
-## 铁律 #7: 前后端API路径对齐
-**前后端API路径必须保持一致。**
- 后端接口路径统一前缀：`/healthlink-his/`
- 接口变更必须同步更新前后端代码
- 新增接口必须在 Swagger 文档中注册
-
-## 铁律 #8: 规范文档统一管理
-**所有铁律和规范文档存放在 `MD/specs/` 目录中：**
- `MD/specs/IRON_RULES.md` — 执行铁律（完整版）
- `MD/specs/BACKEND_DEVELOPMENT_STANDARD.md` — 后端开发规范
- `MD/specs/FRONTEND_DEVELOPMENT_STANDARD.md` — 前端开发规范
- `MD/specs/BACKEND_CHECKLIST.md` — 后端发布检查清单
- `MD/specs/FRONTEND_CHECKLIST.md` — 前端发布检查清单
+→ 完整铁律: `MD/specs/IRON_RULES.md`
+→ 后端规范: `MD/specs/BACKEND_DEVELOPMENT_STANDARD.md`
+→ 后端清单: `MD/specs/BACKEND_CHECKLIST.md`
+→ 根目录完整规范: `RULES.md`
--- a/healthlink-his-ui/AGENTS.md
+++ b/healthlink-his-ui/AGENTS.md
@@ -1,25 +1,26 @@
 # HealthLink-HIS 前端开发规范

-## 铁律 #1: 修改完必须测试
- `npm run build:dev` 构建成功
- ESLint 无错误
- 页面无控制台报错
- 核心业务页面功能正常
+> 🤖 本文件供 AI 工具自动读取。完整规范见 **[../../RULES.md](../../RULES.md)**

-## 铁律 #2: 前后端API路径对齐
- API路径统一前缀：`/healthlink-his/api/v1/`
- 接口变更必须同步更新前后端代码
+## 铁律速查

-## 铁律 #3: 文档统一管理
- 所有文档存储在 `MD/` 目录中
- 命名规范：大写英文+下划线
+1. **修改完必须测试** — `npm run build:dev` + `npm run lint`
+2. **API路径对齐** — `/healthlink-his/api/v1/`
+3. **测试通过才提交** — 构建+测试全通过才能 commit
+4. **文档在 MD 目录** — 大写下划线命名

-## 铁律 #4: 测试通过后才提交
- `npm run build:dev` 构建成功
- `npm run lint` 无错误
- 功能测试通过
+## 快速命令
+
+```bash
+npm run dev            # 开发模式
+npm run build:dev      # 构建
+npm run lint           # 代码检查
+npm run test:run       # 单元测试
+```

 ## 详细规范
- 前端开发规范: `MD/specs/FRONTEND_DEVELOPMENT_STANDARD.md`
- 前端检查清单: `MD/specs/FRONTEND_CHECKLIST.md`
- 执行铁律: `MD/specs/IRON_RULES.md`
+
+→ 完整铁律: `MD/specs/IRON_RULES.md`
+→ 前端规范: `MD/specs/FRONTEND_DEVELOPMENT_STANDARD.md`
+→ 前端清单: `MD/specs/FRONTEND_CHECKLIST.md`
+→ 根目录完整规范: `RULES.md`