# mediacal

**Repository Path**: rymaker/mediacal

## Basic Information

- **Project Name**: mediacal
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-30
- **Last Updated**: 2026-03-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 医疗报告管理系统 (Medical Treatment Report Management System)

## 📋 项目概述

这是一个完整的医疗报告管理全栈应用，包含学员端和医生端功能。学员可以上传体检报告，医生可以审核报告并给出反馈意见。

## 🏗️ 技术栈

### 前端 (Frontend)
- **框架**: Nuxt 3 (SPA 模式)
- **状态管理**: Pinia
- **路由**: Vue Router (Nuxt 内置)
- **样式**: SCSS
- **HTTP 客户端**: Axios
- **认证**: JWT
- **语言**: JavaScript

### 后端 (Backend)
- **框架**: Express.js
- **语言**: TypeScript
- **ORM**: TypeORM
- **数据库**: MySQL
- **缓存**: Redis
- **文件存储**: FTP
- **认证**: JWT + bcrypt

## 📁 项目结构

```
medicalTreatment/
├── frontend/                      # Nuxt 3 前端项目
│   ├── nuxt.config.ts            # Nuxt 配置文件
│   ├── package.json              # 前端依赖
│   ├── .env.example              # 环境变量模板
│   ├── app.vue                   # 应用入口
│   ├── assets/
│   │   └── scss/
│   │       ├── variables.scss    # SCSS 变量 (颜色、字体、间距等)
│   │       ├── mixins.scss       # SCSS 混合
│   │       ├── reset.scss        # CSS 重置
│   │       ├── global.scss       # 全局样式
│   │       └── animations.scss   # 动画定义
│   ├── api/
│   │   ├── request.js            # Axios 封装 (拦截器、JWT)
│   │   ├── auth.js               # 认证相关 API
│   │   ├── report.js             # 报告相关 API
│   │   └── review.js             # 审核相关 API
│   ├── stores/
│   │   ├── user.js               # 用户状态管理
│   │   ├── report.js             # 报告状态管理
│   │   └── review.js             # 审核状态管理
│   ├── utils/
│   │   ├── jwt.js                # JWT 工具函数
│   │   ├── format.js             # 格式化函数
│   │   └── validate.js           # 表单验证
│   ├── plugins/
│   │   └── axios.js              # Axios 插件
│   ├── layouts/
│   │   └── default.vue           # 默认布局
│   ├── pages/
│   │   ├── index.vue             # 登录页
│   │   ├── upload-report.vue     # 上传报告页 (学员)
│   │   ├── pending-reviews.vue   # 待审核列表 (医生)
│   │   ├── review-feedback.vue   # 审核结果反馈 (学员)
│   │   └── review-detail.vue     # 报告审核详情 (医生)
│   ├── components/
│   │   ├── common/               # 通用组件
│   │   ├── student/              # 学员端组件
│   │   └── doctor/               # 医生端组件
│   └── public/
│       └── images/               # 静态图片资源
│
├── backend/                       # Express 后端项目
│   ├── package.json              # 后端依赖
│   ├── tsconfig.json             # TypeScript 配置
│   ├── .env.example              # 环境变量模板
│   └── src/
│       ├── server.ts             # 服务器入口
│       ├── app.ts                # Express 应用配置
│       ├── config/
│       │   ├── database.ts       # TypeORM 数据库配置
│       │   ├── redis.ts          # Redis 配置
│       │   └── ftp.ts            # FTP 配置
│       ├── entities/
│       │   ├── User.ts           # 用户实体
│       │   ├── Report.ts         # 报告实体
│       │   └── Review.ts         # 审核实体
│       ├── controllers/
│       │   ├── AuthController.ts # 认证控制器
│       │   ├── ReportController.ts # 报告控制器
│       │   └── ReviewController.ts # 审核控制器
│       ├── services/
│       │   ├── AuthService.ts    # 认证服务
│       │   ├── ReportService.ts  # 报告服务
│       │   └── ReviewService.ts  # 审核服务
│       ├── middlewares/
│       │   ├── auth.ts           # JWT 认证中间件
│       │   └── errorHandler.ts   # 错误处理中间件
│       ├── routes/
│       │   └── index.ts          # 路由注册
│       └── utils/
│           ├── jwtUtil.ts        # JWT 工具
│           ├── redisUtil.ts      # Redis 工具
│           ├── ftpUtil.ts        # FTP 工具
│           └── responseUtil.ts   # 响应格式化工具
```

## 🚀 快速开始

### 环境要求

- Node.js >= 18.x
- MySQL >= 8.0
- Redis >= 6.0
- FTP 服务器 (可选，用于文件存储)

### 后端启动

1. 进入后端目录并安装依赖
```bash
cd backend
npm install
```

2. 配置环境变量
```bash
cp .env.example .env
# 编辑 .env 文件，填入数据库、Redis、FTP 等配置
```

3. 启动后端服务
```bash
npm run dev
# 服务运行在 http://localhost:3001
```

### 前端启动

1. 进入前端目录并安装依赖
```bash
cd frontend
npm install
```

2. 配置环境变量
```bash
cp .env.example .env
# 确保 NUXT_PUBLIC_API_BASE 指向后端地址
```

3. 启动开发服务器
```bash
npm run dev
# 应用运行在 http://localhost:3000
```

## 🔐 环境变量配置

### 后端 (.env)
```env
# 服务器
PORT=3001

# 数据库
DB_HOST=localhost
DB_PORT=3306
DB_USERNAME=root
DB_PASSWORD=your_password
DB_DATABASE=medical_treatment

# Redis
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=

# JWT
JWT_SECRET=your_jwt_secret_key
JWT_EXPIRES_IN=7d

# FTP (可选)
FTP_HOST=your_ftp_host
FTP_PORT=21
FTP_USER=your_ftp_user
FTP_PASSWORD=your_ftp_password
FTP_BASE_PATH=/uploads/reports
```

### 前端 (.env)
```env
NUXT_PUBLIC_API_BASE=http://localhost:3001/api
```

## 📝 API 接口规范

### 认证接口
| 方法 | 路径 | 描述 |
|------|------|------|
| POST | `/api/auth/register` | 用户注册 |
| POST | `/api/auth/login` | 用户登录 |
| GET | `/api/auth/profile?id={userId}` | 获取用户信息 |
| PUT | `/api/auth/profile` | 更新用户信息 |

### 报告接口
| 方法 | 路径 | 描述 |
|------|------|------|
| POST | `/api/report/create` | 上传报告 |
| GET | `/api/report/detail?id={reportId}` | 获取报告详情 |
| GET | `/api/report/list?studentId=&page=&pageSize=` | 获取报告列表 |
| GET | `/api/report/pending?status=&priority=&keyword=` | 获取待审核报告 |
| PUT | `/api/report/status` | 更新报告状态 |
| DELETE | `/api/report/remove?id={reportId}` | 删除报告 |

### 审核接口
| 方法 | 路径 | 描述 |
|------|------|------|
| POST | `/api/review/create` | 创建审核记录 |
| GET | `/api/review/detail?id={reviewId}` | 获取审核详情 |
| GET | `/api/review/list?reportId=&page=&pageSize=` | 获取审核列表 |
| PUT | `/api/review/submit` | 提交审核结果 |
| GET | `/api/review/feedback?reportId=` | 获取审核反馈 |

**注意**: 所有接口使用参数接收形式，不使用动态路由段 (如 `[id].ts`)

## 🎨 Class 命名规范

所有 CSS class 遵循以下命名模式，确保唯一性和可维护性：

```
container_页面名称_组件位置_组件功能_功能详情
```

### 示例
- `container_login_page` - 登录页面容器
- `container_login_formCard` - 登录表单卡片
- `container_uploadReport_heroSection` - 上传页面头部区域
- `container_uploadReport_uploadBtn` - 上传按钮
- `container_pendingReviews_reportCard` - 待审核报告卡片
- `container_reviewDetail_form_reviewButton` - 审核详情表单提交按钮

### 规则
1. 每个元素只有一个 class 名称 (动画类除外)
2. 所有 class 名称在项目内唯一，不重复
3. 使用下划线分隔各层级
4. 英文名称采用小驼峰或全小写

## 📄 数据库实体

### User (用户)
```typescript
{
  id: number,           // 主键
  username: string,     // 用户名 (唯一)
  password: string,     // bcrypt 加密
  realName: string,     // 真实姓名
  role: enum,           // student | doctor | team_leader
  avatar: string,       // 头像 URL
  department: string,   // 科室
  grade: string,        // 年级 (学员)
  studentId: string,    // 学号 (学员)
  status: enum,         // active | inactive
  createdAt: Date,
  updatedAt: Date
}
```

### Report (报告)
```typescript
{
  id: number,           // 主键
  studentId: number,    // 外键 -> User
  title: string,        // 报告标题
  reportType: enum,     // physical_exam | lab_test | xray | vaccine | other
  filePath: string,     // FTP 路径
  fileUrl: string,      // 访问 URL
  fileType: enum,       // jpg | png | pdf
  fileSize: number,     // 文件大小 (字节)
  status: enum,         // processing | approved | rejected | pending | archived
  priority: enum,       // normal | high | follow_up
  department: string,   // 科室
  caseId: string,       // 病例 ID
  clarityScore: number, // 清晰度分数
  reviewedBy: number,   // 外键 -> User
  reviewedAt: Date,
  reviewNote: text,     // 审核意见
  createdAt: Date,
  updatedAt: Date
}
```

### Review (审核记录)
```typescript
{
  id: number,           // 主键
  reportId: number,     // 外键 -> Report
  doctorId: number,     // 外键 -> User
  status: enum,         // pending | approved | rejected
  reviewNote: text,     // 审核意见
  rejectReason: string, // 驳回原因
  feedback: text,       // 反馈意见
  createdAt: Date,
  updatedAt: Date
}
```

## ✅ 已完成功能

### 前端
- [x] Nuxt 3 项目配置
- [x] SCSS 样式系统 (变量、混合、动画)
- [x] Axios 封装 (JWT 拦截器)
- [x] Pinia 状态管理 (user, report, review)
- [x] 工具函数 (jwt, format, validate)
- [x] 默认布局 (含加载动画)
- [x] 登录页面 (index.vue)
- [x] 上传报告页面 (upload-report.vue)
- [x] 待审核列表页面 (pending-reviews.vue)
- [x] 审核结果反馈页面框架
- [x] 报告审核详情页面框架

### 后端
- [x] TypeScript + Express 配置
- [x] TypeORM 实体定义
- [x] 数据库/Redis/FTP 配置
- [x] JWT 认证工具
- [x] 响应格式化工具
- [x] 认证中间件
- [x] 错误处理中间件
- [x] 控制器和服务框架

## 🔨 待完成工作

### 前端
- [ ] 通用组件实现 (TopNavBar, BottomNavBar, LoadingSpinner, StatusTag)
- [ ] 学员端组件 (ReportCard, GuidelinesCard, ClarityStatus)
- [ ] 医生端组件 (ReviewCard, StudentProfile, ReportPreview, ReviewForm)
- [ ] 完善页面间路由跳转
- [ ] 添加 Toast 通知系统
- [ ] 优化移动端适配

### 后端
- [ ] 完善所有 Service 业务逻辑
- [ ] 完善所有 Controller 请求处理
- [ ] 实现文件上传到 FTP
- [ ] 实现 Redis 缓存策略
- [ ] 添加请求验证 (express-validator)
- [ ] 添加 API 文档 (Swagger)

## 🎯 设计参考

本项目基于 Figma 设计稿开发:
- 设计稿名称：医生管理
- 主要页面：
  1. 审核结果反馈 (中文)
  2. 上传体检报告 - 学员端
  3. 待审核列表 - 医生端
  4. 报告审核详情 - 医生端

### 设计规范
- **主色**: 绿色渐变 (#006D33 → #07C160)
- **背景**: #F7F9FB
- **卡片背景**: #FFFFFF
- **主文字**: #191C1E
- **次要文字**: #515F74
- **错误色**: #BA1A1A
- **边框圆角**: 12px (卡片), 9999px (徽章)
- **字体**: WenQuanYi Zen Hei (中文), Inter (英文/数字)

## 📞 支持

如有问题，请查看各文件内的详细注释，或联系开发团队。