577 lines
17 KiB
Markdown
577 lines
17 KiB
Markdown
# QWEN.md - 医院绩效考核管理系统
|
||
|
||
Context for AI coding agents working in this repository.
|
||
|
||
---
|
||
|
||
## Project Overview
|
||
|
||
A **Hospital Performance Management System** (医院绩效考核管理系统) designed for a county-level TCM (Traditional Chinese Medicine) hospital. The system provides comprehensive performance assessment management including:
|
||
|
||
- **Department Management** - Hierarchical department structure
|
||
- **Staff Management** - Employee information and tracking
|
||
- **Assessment Indicators** - KPI definition and management
|
||
- **Performance Evaluation** - Assessment workflow with review process
|
||
- **Data Analytics** - Reports, statistics, and trend analysis
|
||
- **Salary Calculation** - Performance-based payroll processing
|
||
|
||
### Tech Stack
|
||
|
||
| Layer | Technology |
|
||
|-------|------------|
|
||
| **Backend** | FastAPI 0.115+ · SQLAlchemy 2.0 (async) · PostgreSQL · Alembic · Pydantic v2 |
|
||
| **Frontend** | Vue 3 (Composition API) · Element Plus · Pinia · Vite · ECharts |
|
||
| **Auth** | JWT (python-jose) · bcrypt password hashing |
|
||
| **Database** | **PostgreSQL 14+** (asyncpg driver) |
|
||
|
||
---
|
||
|
||
## Quick Start
|
||
|
||
### Prerequisites
|
||
- Python 3.10+
|
||
- Node.js 18+
|
||
- PostgreSQL 14+
|
||
|
||
### Backend Setup
|
||
|
||
```bash
|
||
cd backend
|
||
|
||
# Create virtual environment
|
||
python -m venv venv
|
||
venv\Scripts\activate # Windows
|
||
|
||
# Install dependencies
|
||
pip install -r requirements.txt
|
||
|
||
# Configure environment
|
||
copy .env.example .env
|
||
# Edit .env with your database credentials
|
||
|
||
# Create database
|
||
createdb hospital_performance
|
||
|
||
# Run migrations
|
||
alembic upgrade head
|
||
|
||
# Initialize default data (optional)
|
||
python init_db.py
|
||
|
||
# Start server
|
||
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
|
||
```
|
||
|
||
### Frontend Setup
|
||
|
||
```bash
|
||
cd frontend
|
||
|
||
# Install dependencies
|
||
npm install
|
||
|
||
# Start dev server (http://localhost:5173)
|
||
npm run dev
|
||
|
||
# Build for production
|
||
npm run build
|
||
```
|
||
|
||
### Access the Application
|
||
- **Frontend**: http://localhost:5173
|
||
- **API Docs**: http://localhost:8000/api/v1/docs
|
||
- **Health Check**: http://localhost:8000/health
|
||
|
||
### Default Credentials
|
||
- **Username**: `admin`
|
||
- **Password**: `admin123`
|
||
|
||
---
|
||
|
||
## Project Structure
|
||
|
||
```
|
||
hospital-performance/
|
||
├── backend/ # Backend service
|
||
│ ├── app/
|
||
│ │ ├── api/v1/ # API routes
|
||
│ │ │ ├── auth.py # Authentication
|
||
│ │ │ ├── departments.py # Department CRUD
|
||
│ │ │ ├── staff.py # Staff CRUD
|
||
│ │ │ ├── indicators.py # Indicator CRUD
|
||
│ │ │ ├── assessments.py # Assessment workflow
|
||
│ │ │ ├── salary.py # Salary calculation
|
||
│ │ │ ├── stats.py # Statistics & reports
|
||
│ │ │ └── finance.py # Finance management
|
||
│ │ ├── core/ # Core modules
|
||
│ │ │ ├── config.py # Settings management
|
||
│ │ │ ├── database.py # DB connection & session
|
||
│ │ │ ├── security.py # JWT & password hashing
|
||
│ │ │ └── init_db.py # DB initialization
|
||
│ │ ├── models/
|
||
│ │ │ └── models.py # SQLAlchemy ORM models
|
||
│ │ ├── schemas/
|
||
│ │ │ └── schemas.py # Pydantic v2 schemas
|
||
│ │ ├── services/ # Business logic layer
|
||
│ │ │ ├── staff_service.py
|
||
│ │ │ ├── department_service.py
|
||
│ │ │ ├── indicator_service.py
|
||
│ │ │ ├── assessment_service.py
|
||
│ │ │ ├── salary_service.py
|
||
│ │ │ └── stats_service.py
|
||
│ │ ├── utils/ # Utility functions
|
||
│ │ └── main.py # FastAPI app factory
|
||
│ ├── alembic/ # Database migrations
|
||
│ ├── tests/ # Test files (empty)
|
||
│ ├── requirements.txt
|
||
│ └── .env.example
|
||
│
|
||
├── frontend/ # Frontend application
|
||
│ ├── src/
|
||
│ │ ├── api/ # API client (Axios)
|
||
│ │ │ ├── request.js # Axios instance + interceptors
|
||
│ │ │ ├── auth.js
|
||
│ │ │ ├── staff.js
|
||
│ │ │ ├── department.js
|
||
│ │ │ ├── indicator.js
|
||
│ │ │ ├── assessment.js
|
||
│ │ │ ├── salary.js
|
||
│ │ │ └── stats.js
|
||
│ │ ├── stores/ # Pinia stores
|
||
│ │ │ ├── user.js # User state & auth
|
||
│ │ │ └── app.js # App-wide state
|
||
│ │ ├── router/
|
||
│ │ │ └── index.js # Vue Router config
|
||
│ │ ├── views/ # Page components
|
||
│ │ │ ├── Login.vue
|
||
│ │ │ ├── Layout.vue # Main layout with sidebar
|
||
│ │ │ ├── Dashboard.vue
|
||
│ │ │ ├── basic/ # Basic data management
|
||
│ │ │ │ ├── Departments.vue
|
||
│ │ │ │ ├── Staff.vue
|
||
│ │ │ │ └── Indicators.vue
|
||
│ │ │ ├── assessment/ # Assessment management
|
||
│ │ │ │ ├── Assessments.vue
|
||
│ │ │ │ └── AssessmentDetail.vue
|
||
│ │ │ ├── salary/ # Salary management
|
||
│ │ │ │ └── Salary.vue
|
||
│ │ │ ├── reports/ # Reports & analytics
|
||
│ │ │ │ └── Reports.vue
|
||
│ │ │ └── finance/ # Finance management
|
||
│ │ │ └── Finance.vue
|
||
│ │ ├── components/ # Reusable components
|
||
│ │ ├── assets/ # Static assets (SCSS)
|
||
│ │ ├── App.vue
|
||
│ │ └── main.js
|
||
│ ├── dist/ # Production build
|
||
│ ├── package.json
|
||
│ └── vite.config.js
|
||
│
|
||
├── docs/ # Documentation
|
||
│ ├── index.md
|
||
│ ├── architecture.md
|
||
│ ├── database.md
|
||
│ ├── api.md
|
||
│ ├── backend.md
|
||
│ └── frontend.md
|
||
│
|
||
├── AGENTS.md # AI agent guidelines
|
||
└── README.md
|
||
```
|
||
|
||
---
|
||
|
||
## Database Schema
|
||
|
||
**Database**: PostgreSQL 14+
|
||
|
||
### Core Tables
|
||
|
||
| Table | Description |
|
||
|-------|-------------|
|
||
| `departments` | Department hierarchy (tree structure with parent_id) |
|
||
| `staff` | Employee information |
|
||
| `indicators` | Assessment indicators/KPIs |
|
||
| `assessments` | Assessment records (header) |
|
||
| `assessment_details` | Assessment line items (scores per indicator) |
|
||
| `salary_records` | Monthly salary calculations |
|
||
| `users` | System users for authentication |
|
||
|
||
### Key Enums
|
||
|
||
```python
|
||
# Department types
|
||
DeptType: CLINICAL, MEDICAL_TECH, MEDICAL_AUXILIARY, ADMIN, LOGISTICS
|
||
|
||
# Staff status
|
||
StaffStatus: ACTIVE, LEAVE, RESIGNED, RETIRED
|
||
|
||
# Assessment workflow status
|
||
AssessmentStatus: DRAFT → SUBMITTED → REVIEWED → FINALIZED (or REJECTED)
|
||
|
||
# Indicator types
|
||
IndicatorType: QUALITY, QUANTITY, EFFICIENCY, SERVICE, COST
|
||
```
|
||
|
||
### Assessment Workflow
|
||
|
||
```
|
||
┌─────────┐ ┌───────────┐ ┌──────────┐ ┌────────────┐
|
||
│ DRAFT │ → │ SUBMITTED │ → │ REVIEWED │ → │ FINALIZED │
|
||
│ 草稿 │ │ 已提交 │ │ 已审核 │ │ 已确认 │
|
||
└─────────┘ └───────────┘ └──────────┘ └────────────┘
|
||
↓
|
||
┌──────────┐
|
||
│ REJECTED │
|
||
│ 已驳回 │
|
||
└──────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## Development Conventions
|
||
|
||
### Backend (Python/FastAPI)
|
||
|
||
#### Import Order
|
||
```python
|
||
# 1. Standard library
|
||
from datetime import datetime
|
||
from typing import Optional, List
|
||
|
||
# 2. Third-party
|
||
from fastapi import APIRouter, Depends, HTTPException
|
||
from sqlalchemy.ext.asyncio import AsyncSession
|
||
|
||
# 3. Local imports (absolute paths)
|
||
from app.core.database import get_db
|
||
from app.schemas.schemas import StaffCreate
|
||
from app.services.staff_service import StaffService
|
||
```
|
||
|
||
#### Naming Conventions
|
||
- **Files**: `snake_case.py` (e.g., `staff_service.py`)
|
||
- **Classes**: `PascalCase` (e.g., `StaffService`, `StaffCreate`)
|
||
- **Functions/Variables**: `snake_case` (e.g., `get_staff_list`)
|
||
- **Constants**: `UPPER_SNAKE_CASE`
|
||
|
||
#### Pydantic v2 Pattern
|
||
```python
|
||
class StaffResponse(StaffBase):
|
||
"""员工响应"""
|
||
model_config = ConfigDict(from_attributes=True) # Required for ORM mode
|
||
id: int
|
||
status: StaffStatus
|
||
created_at: datetime
|
||
```
|
||
|
||
#### Async Database Pattern
|
||
```python
|
||
async def get_staff_list(db: AsyncSession, page: int = 1, page_size: int = 20):
|
||
offset = (page - 1) * page_size
|
||
result = await db.execute(select(Staff).offset(offset).limit(page_size))
|
||
staff_list = result.scalars().all()
|
||
|
||
count_result = await db.execute(select(func.count()).select_from(Staff))
|
||
total = count_result.scalar()
|
||
|
||
return staff_list, total
|
||
```
|
||
|
||
#### API Response Format
|
||
```python
|
||
# Standard response
|
||
return {
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": result,
|
||
"total": total, # For paginated responses
|
||
"page": page,
|
||
"page_size": page_size
|
||
}
|
||
|
||
# Error response
|
||
raise HTTPException(status_code=404, detail="员工不存在")
|
||
```
|
||
|
||
#### Service Layer Pattern
|
||
```python
|
||
# API route delegates to service
|
||
@router.get("/staff")
|
||
async def get_staff_list(
|
||
db: AsyncSession = Depends(get_db),
|
||
page: int = 1,
|
||
page_size: int = 20
|
||
):
|
||
staff_list, total = await StaffService.get_list(db, page, page_size)
|
||
return {"data": staff_list, "total": total, "page": page, "page_size": page_size}
|
||
```
|
||
|
||
### Frontend (Vue 3/JavaScript)
|
||
|
||
#### Import Order
|
||
```javascript
|
||
// 1. Vue
|
||
import { ref, reactive, onMounted } from 'vue'
|
||
|
||
// 2. Third-party
|
||
import { ElMessage, ElMessageBox } from 'element-plus'
|
||
|
||
// 3. Local (use @ alias)
|
||
import { getStaffList, createStaff } from '@/api/staff'
|
||
import { useUserStore } from '@/stores/user'
|
||
```
|
||
|
||
#### Component Pattern (`<script setup>`)
|
||
```vue
|
||
<script setup>
|
||
import { ref, reactive, onMounted } from 'vue'
|
||
import { ElMessage } from 'element-plus'
|
||
import { getStaffList } from '@/api/staff'
|
||
|
||
// Reactive state
|
||
const loading = ref(false)
|
||
const tableData = ref([])
|
||
const form = reactive({ name: '', status: 'active' })
|
||
|
||
// Functions
|
||
async function loadData() {
|
||
loading.value = true
|
||
try {
|
||
const res = await getStaffList(form)
|
||
tableData.value = res.data || []
|
||
} finally {
|
||
loading.value = false
|
||
}
|
||
}
|
||
|
||
onMounted(() => {
|
||
loadData()
|
||
})
|
||
</script>
|
||
```
|
||
|
||
#### Pinia Store Pattern
|
||
```javascript
|
||
// stores/user.js
|
||
import { defineStore } from 'pinia'
|
||
|
||
export const useUserStore = defineStore('user', () => {
|
||
const token = ref('')
|
||
const userInfo = ref(null)
|
||
|
||
async function login(username, password) {
|
||
const res = await loginApi({ username, password })
|
||
token.value = res.access_token
|
||
localStorage.setItem('token', res.access_token)
|
||
}
|
||
|
||
function logout() {
|
||
token.value = ''
|
||
userInfo.value = null
|
||
localStorage.removeItem('token')
|
||
}
|
||
|
||
return { token, userInfo, login, logout }
|
||
})
|
||
```
|
||
|
||
#### API Layer Pattern
|
||
```javascript
|
||
// api/staff.js
|
||
import request from './request'
|
||
|
||
export function getStaffList(params) {
|
||
return request.get('/staff', { params })
|
||
}
|
||
|
||
export function createStaff(data) {
|
||
return request.post('/staff', data)
|
||
}
|
||
```
|
||
|
||
#### Error Handling
|
||
```javascript
|
||
// User confirmation
|
||
await ElMessageBox.confirm('确定要删除吗？', '提示', { type: 'warning' })
|
||
|
||
// Feedback
|
||
ElMessage.success('操作成功')
|
||
ElMessage.error('操作失败')
|
||
|
||
// Loading state pattern
|
||
try {
|
||
await createStaff(form)
|
||
ElMessage.success('创建成功')
|
||
} finally {
|
||
submitting.value = false
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Key API Endpoints
|
||
|
||
| Method | Endpoint | Description |
|
||
|--------|----------|-------------|
|
||
| POST | `/auth/login` | User login |
|
||
| GET | `/auth/me` | Get current user |
|
||
| GET | `/departments` | List departments |
|
||
| POST | `/departments` | Create department |
|
||
| GET | `/staff` | List staff (paginated) |
|
||
| POST | `/staff` | Create staff |
|
||
| GET | `/indicators` | List indicators |
|
||
| POST | `/assessments` | Create assessment |
|
||
| POST | `/assessments/batch` | Batch create assessments |
|
||
| POST | `/assessments/{id}/submit` | Submit assessment |
|
||
| POST | `/assessments/{id}/review` | Review assessment |
|
||
| POST | `/salary/generate` | Generate salary records |
|
||
| GET | `/stats/department` | Department statistics |
|
||
| GET | `/stats/trend` | Trend analysis |
|
||
|
||
---
|
||
|
||
## Common Tasks
|
||
|
||
### Add a New API Endpoint
|
||
|
||
**Backend:**
|
||
1. Add route in `backend/app/api/v1/<module>.py`
|
||
2. Add service method in `backend/app/services/<module>_service.py`
|
||
3. Add Pydantic schemas in `backend/app/schemas/schemas.py`
|
||
4. Create Alembic migration if DB changes needed
|
||
|
||
**Frontend:**
|
||
1. Add API function in `frontend/src/api/<module>.js`
|
||
2. Create/update view component in `frontend/src/views/`
|
||
3. Add route in `frontend/src/router/index.js`
|
||
|
||
### Database Migration
|
||
|
||
```bash
|
||
cd backend
|
||
|
||
# Generate new migration
|
||
alembic revision --autogenerate -m "Description of changes"
|
||
|
||
# Apply migrations
|
||
alembic upgrade head
|
||
|
||
# Rollback one migration
|
||
alembic downgrade -1
|
||
```
|
||
|
||
### Run Tests (when available)
|
||
|
||
```bash
|
||
cd backend
|
||
pytest
|
||
pytest tests/test_specific.py -v
|
||
pytest -k "test_name" -v
|
||
```
|
||
|
||
---
|
||
|
||
## Architecture Notes
|
||
|
||
### Layered Architecture
|
||
|
||
```
|
||
┌─────────────────────────────────────────┐
|
||
│ Frontend (Vue 3) │
|
||
│ Views → Components → Stores → API │
|
||
└───────────────────┬─────────────────────┘
|
||
│ HTTP/JSON
|
||
▼
|
||
┌─────────────────────────────────────────┐
|
||
│ Backend (FastAPI) │
|
||
│ ┌─────────────────────────────────┐ │
|
||
│ │ API Layer (routes) │ │
|
||
│ └──────────────┬──────────────────┘ │
|
||
│ ▼ │
|
||
│ ┌─────────────────────────────────┐ │
|
||
│ │ Service Layer (business logic) │ │
|
||
│ └──────────────┬──────────────────┘ │
|
||
│ ▼ │
|
||
│ ┌─────────────────────────────────┐ │
|
||
│ │ ORM Layer (SQLAlchemy) │ │
|
||
│ └──────────────┬──────────────────┘ │
|
||
└───────────────────┼─────────────────────┘
|
||
▼
|
||
┌─────────────────────────────────────────┐
|
||
│ Database (PostgreSQL) │
|
||
└─────────────────────────────────────────┘
|
||
```
|
||
|
||
### Authentication Flow
|
||
|
||
1. Client sends credentials to `/auth/login`
|
||
2. Server validates and returns JWT token
|
||
3. Client stores token in `localStorage`
|
||
4. Client includes `Authorization: Bearer {token}` in subsequent requests
|
||
5. Server validates token via `get_current_user` dependency
|
||
6. 401 responses trigger redirect to login page
|
||
|
||
### Salary Calculation Logic
|
||
|
||
```
|
||
Assessment (FINALIZED status)
|
||
↓
|
||
Read performance score
|
||
↓
|
||
Apply performance ratio (from staff.perf_ratio)
|
||
↓
|
||
Calculate: performance_bonus = base_salary × (score/100) × perf_ratio
|
||
↓
|
||
Generate SalaryRecord with total_salary = base + bonus - deduction + allowance
|
||
```
|
||
|
||
---
|
||
|
||
## Troubleshooting
|
||
|
||
### Backend Issues
|
||
|
||
**Database connection error:**
|
||
- Ensure PostgreSQL is running
|
||
- Check `DATABASE_URL` in `.env`
|
||
- Verify database exists: `createdb hospital_performance`
|
||
- Check PostgreSQL credentials (username, password, port)
|
||
|
||
**Migration issues:**
|
||
```bash
|
||
# Check migration status
|
||
alembic current
|
||
|
||
# Show pending migrations
|
||
alembic history
|
||
|
||
# Clear and re-migrate (dev only)
|
||
alembic downgrade base
|
||
alembic upgrade head
|
||
```
|
||
|
||
### Frontend Issues
|
||
|
||
**API requests failing:**
|
||
- Ensure backend is running on port 8000
|
||
- Check proxy config in `vite.config.js`
|
||
- Verify token in localStorage is valid
|
||
|
||
**Build errors:**
|
||
```bash
|
||
# Clean and reinstall
|
||
rm -rf node_modules package-lock.json
|
||
npm install
|
||
```
|
||
|
||
---
|
||
|
||
## Related Documentation
|
||
|
||
- [Architecture](docs/architecture.md) - System architecture overview
|
||
- [Database](docs/database.md) - ER diagrams and table structures
|
||
- [API](docs/api.md) - Detailed API documentation
|
||
- [Backend](docs/backend.md) - Backend development guide
|
||
- [Frontend](docs/frontend.md) - Frontend development guide
|