wangyizhe/his
1
3
Fork 0
Code Issues Pull Requests 2 Actions Packages Projects Releases Wiki Activity
Files
7251c79b9c1caa37b5a735c07897418e1032b2e4
his/AGENTS.md

5.9 KiB
Executable File
Raw Blame History

OpenHIS - AI Agent Development Guide

项目概览

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

构建和运行命令

后端（Java/Spring Boot）

# 构建整个项目
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）

# 安装依赖
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，父类改了对不对）
  • ❌ 只测了新增，没测编辑已有数据的回显和修改再保存

执行细则

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