# OpenHIS - AI Agent Development Guide

## 项目概览
OpenHIS 是一个医院管理系统，采用 Java 17 + Spring Boot 后端和 Vue 3 + Vite 前端架构。

## 构建和运行命令

### 后端（Java/Spring Boot）
```bash
# 构建整个项目
cd openhis-server-new
mvn clean package -DskipTests

# 运行后端（开发模式）
cd openhis-server-new/openhis-application
mvn spring-boot:run

# 运行特定模块
cd openhis-server-new/[module-name]
mvn spring-boot:run
```

### 前端（Vue 3 + Vite）
```bash
# 安装依赖
cd openhis-ui-vue3
npm install

# 开发服务器
npm run dev

# 生产构建
npm run build:prod

# 测试环境构建
npm run build:test

# 预览构建结果
npm run preview
```

### 测试
项目当前没有配置正式的测试框架。如需添加测试：
- 后端：考虑使用 JUnit 5 + Mockito
- 前端：考虑使用 Vitest + Vue Test Utils

## 代码风格规范

### Java 后端规范
- **Java 版本**: 17
- **框架**: Spring Boot 2.5.15
- **ORM**: MyBatis Plus 3.5.5
- **数据库**: PostgreSQL
- **包结构**:
  - `com.openhis` - 业务逻辑
  - `com.core` - 核心框架
- **命名约定**:
  - 类名：PascalCase（如 `UserController`）
  - 方法名：camelCase（如 `getUserList`）
  - 常量：SCREAMING_SNAKE_CASE
  - 配置文件：kebab-case
- **注解使用**:
  - 使用 `@Slf4j` 替代手动声明 logger
  - 使用 `@Data` 在实体类中
  - 使用 `@Service/@Controller/@Repository` 等 Spring 注解
- **异常处理**:
  - 使用统一的异常处理机制
  - 自定义业务异常继承 `RuntimeException`

### Vue 前端规范
- **框架**: Vue 3 + Composition API
- **UI 库**: Element Plus
- **状态管理**: Pinia
- **路由**: Vue Router 4
- **构建工具**: Vite 5
- **组件命名**: PascalCase
- **文件命名**: kebab-case
- **变量命名**: camelCase
- **常量命名**: SCREAMING_SNAKE_CASE
- **函数命名**:
  - 事件处理：`handle` 前缀
  - 数据获取：`get`/`load` 前缀
  - 提交操作：`submit` 前缀

### 导入顺序
#### Java
1. `java.*`
2. `javax.*`
3. 第三方库
4. `com.core.*`
5. `com.openhis.*`
6. `*.*`（其他包）

#### JavaScript/Vue
1. `vue` 相关
2. 第三方库
3. `@/` 别名导入
4. 相对路径导入

### 代码格式
#### Java
- 缩进：4个空格
- 行长度：120字符
- 左大括号不换行

#### Vue/JavaScript
- 缩进：2个空格
- 字符串：优先使用单引号
- 行长度：100字符

## 关键配置文件

### 后端配置
- 主配置：`openhis-server-new/openhis-application/src/main/resources/application.yml`
- 环境配置：`application-{profile}.yml`
- Maven 父 POM：`openhis-server-new/pom.xml`

### 前端配置
- Vite 配置：`openhis-ui-vue3/vite.config.js`
- 环境变量：`.env.*` 文件
- 路由配置：`openhis-ui-vue3/src/router/index.js`

## 开发约定

### API 设计
- RESTful API 风格
- 统一响应格式
- 使用 Swagger 文档
- 错误码统一管理

### 数据库
- 表名：snake_case
- 字段名：snake_case
- 主键：使用 `id`
- 软删除：使用 `valid_flag` 字段

### 前端组件
- 单一职责原则
- Props 使用 camelCase
- Events 使用 kebab-case
- 使用 Composition API
- 组件文档使用 JSDoc

### 状态管理
- 模块化设计
- 异步操作使用 actions
- 避免在组件中直接修改状态

## 环境变量

### 前端
- `VITE_APP_BASE_API`: API 基础路径
- `VITE_APP_ENV`: 环境标识

### 后端
- `spring.profiles.active`: 激活的配置文件
- `core.name`: 应用名称
- `core.version`: 应用版本

## 安全规范
- 所有 API 接口需要权限验证
- 敏感信息使用环境变量
- SQL 注入防护
- XSS 攻击防护

## 性能优化
- 后端使用连接池（Druid）
- 前端使用路由懒加载
- 图片使用 WebP 格式
- 大列表使用虚拟滚动

## 常用工具类
- 后端：`com.core.common.utils.*`
- 前端：`@/utils/*`

## 注意事项
1. 修改数据库结构需要同步 SQL 脚本
2. 新增功能需要添加权限配置
3. 前端路由需要在权限系统中注册
4. 接口变更需要更新 Swagger 文档
5. 遵循现有代码风格，避免不必要的变化

## 故障排除
- 后端端口：18080
- 前端端口：81
- API 前缀：`/openhis`
- Swagger UI：`/openhis/swagger-ui/index.html`
- Druid 监控：`/openhis/druid/login.html`
## 铁律：全链路修复原则 ⚠️

> 修 Bug / 做需求时，**不得"就事论事"**，必须走通完整的**数据流全链路**：

### 检查清单（每一环都确认）
1. **录入** → 前端有无输入入口？（弹窗、表格行编辑、表单…）
2. **保存** → 前端 → API → 后端 Controller → Service → Entity → DB，**每一个保存入口**都传了该字段吗？（注意多个 Service 实现类可能走不同入口）
3. **查询** → DB → Mapper XML（注意 UNION ALL 子查询要统一加）→ DTO → 前端展示，列和数据绑定都完整吗？
4. **修改** → 已有数据编辑回显 → 修改再保存 → 数据能正确更新吗？
5. **删除/停止/撤回** → 相关状态变更会丢失该字段数据吗？
6. **关联模块** → 上游（如医嘱录入后护士站要看到备注）和下游（如打印、计费、报表）是否也需要同步修改？

### 常见陷阱
- ❌ 只修了「主入口」的保存逻辑，忘了「批量保存」「签发保存」等其他入口
- ❌ 前端加了输入框，后端 Service 没传字段（不同模块可能走不同 Service 实现类）
- ❌ Mapper XML 是 UNION ALL 查询，只改了其中一个子查询，导致列数不匹配或漏加
- ❌ DTO 层级继承关系没检查（如 `RegAdviceSaveDto extends AdviceSaveDto`，父类改了对不对）
- ❌ 只测了新增，没测编辑已有数据的回显和修改再保存

### 执行细则
- 每个字段的新增/修改，先在纸上（或文档里）画出完整的数据流向图再动手
- 提交前逐个环节检查一遍，确保没有断链
- 编译通过不等同于功能正确，必要时做端到端验证