his/CODEBUDDY.md

# CODEBUDDY.md

This file provides guidance to CodeBuddy Code when working with code in this repository.

## Project Overview

This is a comprehensive Hospital Information System (HIS) built with a Java Spring Boot backend and Vue 3 frontend.

- **Backend**: Java 17, Spring Boot 2.5.15, multi-module Maven architecture
- **Frontend**: Vue 3, Vite, Element Plus, Pinia state management
- **Database**: PostgreSQL (recommended v16.2)
- **Cache**: Redis

## Repository Structure

```
.
├── openhis-server-new/          # Backend multi-module Maven project
│   ├── openhis-application/    # Main application module with startup class
│   ├── openhis-domain/          # Business domain modules (administration, clinical, financial, etc.)
│   ├── openhis-common/          # Shared utilities and common code
│   ├── core-admin/             # Core administration module
│   ├── core-framework/         # Framework configuration and security
│   ├── core-system/            # System management module
│   ├── core-quartz/            # Scheduled tasks
│   ├── core-generator/         # Code generation utilities
│   ├── core-common/            # Core utilities
│   └── core-flowable/          # Workflow engine integration
└── openhis-ui-vue3/            # Vue 3 frontend
    ├── src/
    │   ├── api/                # API service layer
    │   ├── components/         # Reusable components
    │   ├── router/             # Vue Router configuration
    │   ├── store/              # Pinia state management
    │   ├── utils/              # Utility functions
    │   └── views/              # Page components
    └── vite/                   # Vite plugins configuration
```

## Build and Development Commands

### Backend (Java)

**Build the entire backend:**
```bash
cd openhis-server-new
mvn clean package -DskipTests
```

**Run the backend application (development):**
```bash
cd openhis-server-new/openhis-application
mvn spring-boot:run
```

**Alternative: Run directly from IDE:**
- Run the main method in `openhis-server-new/openhis-application/src/main/java/com/openhis/OpenHisApplication.java`

**Start scripts:**
- Linux/Mac: `openhis-server-new/start.sh`
- Windows: `openhis-server-new/start.bat`

### Frontend (Vue 3)

**Install dependencies:**
```bash
cd openhis-ui-vue3
npm install
```

**Development server (with hot reload):**
```bash
npm run dev
```
- Runs on port 81 by default
- Proxies `/dev-api` requests to `http://localhost:18080/openhis`

**Build for production:**
```bash
npm run build:prod    # Production build
npm run build:stage   # Staging build
npm run build:test    # Test environment build
npm run build:dev     # Development build
npm run build:spug    # Spug environment build
```

**Preview production build:**
```bash
npm run preview
```

## Architecture Overview

### Backend Architecture

The backend uses a multi-module Maven architecture with clear separation of concerns:

1. **openhis-application**: Entry point with `OpenHisApplication.java` (d:\his\openhis-server-new\openhis-application\src\main\java\com\openhis\OpenHisApplication.java:20)
   - Scans `com.core` and `com.openhis` packages
   - Configures async processing and YAML service configuration
   - Runs on port 18080 with context path `/openhis`

2. **openhis-domain**: Business domain modules organized by medical functionality:
   - `administration`: Administrative functions
   - `appointmentmanage`: Appointment management
   - `check`: Medical examination/checkup
   - `clinical`: Clinical workflows
   - `crosssystem`: Cross-system integration
   - `document`: Document management
   - `financial`: Financial/billing
   - `lab`: Laboratory operations
   - `medication`: Medication management
   - `triageandqueuemanage`: Patient triage and queue management
   - `yb`, `ybcatalog`, `ybelep`: Insurance (Yi Bao) integration
   - `workflow`: Workflow management
   - `jlau`, `nenu`: Additional domain modules
   - `template`: Template management

3. **Core Modules** (com.core package):
   - `core-system`: User, role, menu, and permission management
   - `core-framework`: Security, exception handling, and framework configurations
   - `core-common`: Shared utilities and base classes
   - `core-quartz`: Scheduled task management
   - `core-generator`: Code generation tools
   - `core-flowable`: Workflow engine integration
   - `core-admin`: Administrative functions

4. **openhis-common**: Domain-specific shared code and utilities under `com.openhis.common` package

**Key Technologies:**
- MyBatis-Plus 3.5.5 for ORM with enhanced CRUD operations
- Druid 1.2.27 connection pool with monitoring at `/druid/*`
- Flowable 6.8.0 for workflow management
- LiteFlow 2.12.4.1 for business rule orchestration
- Swagger 3.0.0 for API documentation
- JWT 0.9.1 for authentication
- Hutool 5.3.8 utility library
- Fastjson2 2.0.58 for JSON processing
- Pinyin4j 2.5.1 for Chinese character to Pinyin conversion

### Frontend Architecture

The frontend uses Vue 3 with composition API and modern tooling:

**Key Files:**
- Entry point: `openhis-ui-vue3/src/main.js`
- Router configuration: `openhis-ui-vue3/src/router/index.js`
- Store initialization: `openhis-ui-vue3/src/store/store.js`
- Vite configuration: `openhis-ui-vue3/vite.config.js`

**State Management:**
- Pinia for global state (replaces Vuex)
- Store modules: `app`, `dict`, `permission`, `settings`, `tagsView`, `user`
- Modules located in `openhis-ui-vue3/src/store/modules/`

**Routing:**
- Vue Router 4.3.0
- Two types of routes:
  - `constantRoutes`: Public routes (login, 404, etc.)
  - `dynamicRoutes`: Permission-based routes loaded dynamically
- Route meta fields: `title`, `icon`, `permissions`, `noCache`, `activeMenu`

**API Integration:**
- Axios 0.27.2 for HTTP requests
- Base API URL configured via environment variables (`VITE_APP_BASE_API`)
- Proxy configuration in vite.config.js for development
  - `/dev-api` → `http://localhost:18080/openhis`
  - `/ybplugin` → `http://localhost:5000` (insurance plugin)
- Request/response interceptors in `openhis-ui-vue3/src/utils/request.js`
- API service files organized by module in `openhis-ui-vue3/src/api/`
  - `administration`, `appoinmentmanage`, `monitor`, `system`, `tool`
  - Shared APIs: `home.js`, `login.js`, `menu.js`, `public.js`

**Component Architecture:**
- Element Plus as the UI framework
- Custom components in `openhis-ui-vue3/src/components/`
- Global components registered in main.js:
  - Pagination, TreeSelect, FileUpload, ImageUpload, ImagePreview
  - RightToolbar, Editor, DictTag

## Configuration

### Backend Configuration

**Main configuration file:** `openhis-server-new/openhis-application/src/main/resources/application.yml`

**Environment-specific profiles:**
- `application-dev.yml` - Development environment
- `application-test.yml` - Test environment
- `application-prd.yml` - Production environment

**Key configuration sections:**
- Database: PostgreSQL connection (URL, username, password, pool settings)
- Redis: Cache configuration (host, port, database index)
- Server: Port (18080), context path (/openhis), thread pool
- MyBatis-Plus: Mapper scanning (`com.core.**.domain,com.openhis.**.domain`), type aliases, logical delete
- Logging: Debug levels for com.openhis and com.baomidou.mybatisplus
- Swagger: API documentation at `/swagger-ui/index.html`
- Druid: Database monitoring at `/druid/*` (credentials: openhis/123456)
- Flowable: Workflow engine settings (schema update disabled)
- LiteFlow: Business rule configuration at `config/flow.el.xml`
- Token: JWT configuration (secret, expire time, header)
- File upload: Max file size (10MB), max request size (20MB)

### Frontend Configuration

**Environment files** (in `openhis-ui-vue3/`):
- `.env.dev` - Dev environment
- `.env.development` - Development environment variables
- `.env.staging` - Staging environment variables
- `.env.production` - Production environment variables
- `.env.test` - Test environment variables
- `.env.spug` - Spug environment variables

**Key environment variables:**
- `VITE_APP_TITLE`: Application title (e.g., "医院信息管理系统")
- `VITE_APP_BASE_API`: Backend API base URL (e.g., `/dev-api`)
- `VITE_APP_ENV`: Environment identifier

**Vite configuration:**
- Development server: Port 81, host true, auto-open
- Proxy: `/dev-api` → `http://localhost:18080/openhis`
- Path aliases: `@` → `./src`, `~` → `./`

## Database

**Initialization script:** `数据库初始话脚本（请使用navicat16版本导入）.sql` (located at repository root)
- Use Navicat version 16 to import
- Contains schema and initial demonstration data

**Database connection (dev environment):**
- Type: PostgreSQL
- URL: `jdbc:postgresql://47.116.196.11:15432/postgresql?currentSchema=hisdev`
- Driver: `org.postgresql.Driver`
- Schema: `hisdev`

## Common Development Tasks

### Running Full Stack Locally

**Terminal 1 - Start backend:**
```bash
cd openhis-server-new/openhis-application
mvn spring-boot:run
```

**Terminal 2 - Start frontend:**
```bash
cd openhis-ui-vue3
npm run dev
```

Access the application at:
- Frontend: http://localhost:81
- Backend API: http://localhost:18080/openhis
- Swagger UI: http://localhost:18080/openhis/swagger-ui/index.html
- Druid monitoring: http://localhost:18080/openhis/druid/login.html

### Adding a New Backend Feature

1. Create domain entity in appropriate module under `openhis-domain/[module]/domain/`
2. Create mapper interface in `openhis-domain/[module]/mapper/`
3. Create mapper XML in `openhis-domain/[module]/resources/mapper/` (if custom SQL needed)
4. Create service interface and implementation in `openhis-domain/[module]/service/`
5. Create controller in `openhis-application/src/main/java/com/openhis/web/[module]/`
6. Add MyBatis-Plus annotations if using enhanced features
7. Test endpoints via Swagger UI at `http://localhost:18080/openhis/swagger-ui/index.html`

**Note:** Controllers are organized under `com.openhis.web` by business module (e.g., `web.administration`, `web.clinicalmanage`, `web.patientmanage`, etc.)

### Adding a New Frontend Page

1. Create Vue component in `openhis-ui-vue3/src/views/[module]/`
2. Add API service methods in `openhis-ui-vue3/src/api/`
3. Add route to `openhis-ui-vue3/src/router/index.js` (constantRoutes or dynamicRoutes)
4. Add Pinia store module if state management needed
5. Register global components if reusable

### Testing

**Backend:**
```bash
cd openhis-server-new
mvn test
```

**Frontend:**
- Run unit tests (if configured):
```bash
cd openhis-ui-vue3
npm test
```

## Key Patterns and Conventions

### Backend

- Package structure follows domain-driven design
- Service layer uses `@Service` annotation
- Controllers use `@RestController` with request mapping
- MyBatis-Plus base mapper: `BaseMapper<T>`
- Logical delete field: `validFlag` (1 = active, 0 = deleted)
- Use `@EnableAsync` for async processing
- JWT token stored in `Authorization` header

### Frontend

- Use Vue 3 Composition API (`<script setup>`)
- Element Plus components with Chinese locale (zhCn)
- API calls through centralized request utility in `src/utils/request.js`
- Route-based permission control
- Dictionary data through `useDict()` composable
- Global properties: `$download`, `$downloadGet`, `$parseTime`, `$resetForm`, `$handleTree`, `$formatDateStr`
- CSS in SCSS with global styles in `src/assets/styles/index.scss`
- Registered global components: DictTag, Pagination, TreeSelect, FileUpload, ImageUpload, ImagePreview, RightToolbar, Editor
- Hiprint plugin for printing functionality (window.hiprint)

## Important Files

### Backend
- Startup class: `openhis-server-new/openhis-application/src/main/java/com/openhis/OpenHisApplication.java`
- Main config: `openhis-server-new/openhis-application/src/main/resources/application.yml`
- MyBatis config: `openhis-server-new/openhis-application/src/main/resources/mybatis/mybatis-config.xml`
- Parent POM: `openhis-server-new/pom.xml`

### Frontend
- Entry point: `openhis-ui-vue3/src/main.js`
- Router: `openhis-ui-vue3/src/router/index.js`
- Request utils: `openhis-ui-vue3/src/utils/request.js`
- Vite config: `openhis-ui-vue3/vite.config.js`
- Environment files: `openhis-ui-vue3/.env.*`

## External Integrations

- **PostgreSQL 42.2.27**: Primary database
- **MySQL Connector 9.4.0**: MySQL database support (alternative)
- **Redis**: Caching and session management
- **Flowable 6.8.0**: Workflow engine
- **LiteFlow 2.12.4.1**: Business rule engine
- **Swagger 3.0.0**: API documentation
- **Druid 1.2.27**: Database connection pool and monitoring
- **Element Plus 2.12.0**: Vue 3 UI component library
- **Pinia 2.2.0**: State management
- **Vite 5.0.4**: Build tool and dev server
- **Hutool 5.3.8**: Java utility library
- **Fastjson2 2.0.58**: JSON processing
- **Pinyin4j 2.5.1**: Chinese character to Pinyin conversion
- **iText 5.5.12**: PDF generation
- **Apache POI 4.1.2**: Excel file processing

## Additional Notes

### WebView Integration
- Frontend supports WebView environment (e.g., embedded in desktop applications)
- Chrome WebView integration with C# accessor (`chrome.webview.hostObjects.CSharpAccessor`)
- Mounted to Vue instance as `csAccessor` global property

### File Upload
- Backend upload path: Configured in `core.profile` property (default: `D:/home/uploadPath`)
- Max file size: 10MB per file, 20MB total request
- File upload component: `FileUpload` (global component)

### Authentication
- JWT token stored in `Authorization` header
- Token configuration: `token.secret`, `token.expireTime`, `token.header`
- Password lockout: 5 failed attempts, 10-minute lock time

### Logging
- Backend logs: Configured in `logback.xml`
- Debug logging enabled for: `com.openhis`, `com.baomidou.mybatisplus`, `com.alibaba.druid`
- Druid slow SQL threshold: 1000ms

### Code Generation
- Backend code generator: `core-generator` module
- Access via Swagger or `/tool/gen` route
- Uses Velocity templates in `openhis-application/src/main/resources/vm/`