# 患者注册路由说明

## 概述

根据软件框架V2文档的要求，我们为第一个页面（用户注册页面-扫码）创建了独立的路由。这个路由专门处理患者的自助注册功能，适用于现场排队等候的场景。

**重要说明**：系统中只有两种用户类型：
- **患者用户**：通过扫码注册，使用就诊号+身份证后六位登录
- **管理员用户**：通过管理后台创建，用于系统管理

## 路由信息

- **路由**: `/api/v3/register`
- **方法**: POST
- **文件位置**: `app/routers/register.py`

## 功能特点

### 1. 独立的路由系统
- 患者注册功能完全独立于管理员注册
- 使用独立的数据库表 `patient_info`
- 独立的JWT令牌生成和验证

### 2. 完整的患者信息字段
根据软件框架V2文档，支持以下字段：

**必需字段**:
- `medical_record_number`: 就诊号（将作为登录用户名）
- `id_last_six`: 身份证后六位（将作为登录密码）
- `name`: 姓名
- `gender`: 性别
- `dominant_hand`: 利手
- `diagnosis`: 诊断
- `dob`: 出生年月（格式: YYYY-MM-DD）
- `height_cm`: 身高(cm)
- `weight_kg`: 体重(kg)
- `contact`: 联系方式

**可选字段**:
- `inpatient_number`: 住院号
- `bed_number`: 床号
- `education_level`: 教育程度
- `education_years`: 教育年数
- `remarks`: 备注

### 3. 数据验证
- 必需字段验证
- 数据类型验证（数字、日期格式）
- 重复注册检查（就诊号唯一性）

### 4. 自动登录
- 注册成功后自动生成JWT令牌
- 返回完整的用户信息
- 无需额外登录步骤

## 数据库设计

### patient_info 表结构
```sql
CREATE TABLE patient_info (
    id SERIAL PRIMARY KEY,
    user_id VARCHAR(50) UNIQUE NOT NULL,
    medical_record_number VARCHAR(50) UNIQUE NOT NULL,
    id_last_six VARCHAR(6) NOT NULL,
    name VARCHAR(100) NOT NULL,
    gender VARCHAR(10) NOT NULL,
    dominant_hand VARCHAR(10) NOT NULL,
    diagnosis TEXT,
    dob DATE,
    height_cm INTEGER,
    weight_kg DECIMAL(5,2),
    contact VARCHAR(20),
    inpatient_number VARCHAR(50),
    bed_number VARCHAR(20),
    education_level VARCHAR(50),
    education_years INTEGER,
    remarks TEXT,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);
```

### user_info 表结构（简化后）
```sql
CREATE TABLE user_info (
    id SERIAL PRIMARY KEY,
    username VARCHAR(50) UNIQUE NOT NULL,
    email VARCHAR(255) UNIQUE NOT NULL,
    hashed_password VARCHAR(255) NOT NULL,
    department VARCHAR(100),
    position VARCHAR(100),
    is_admin BOOLEAN DEFAULT TRUE,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);
```

## 用户类型说明

### 患者用户
- **注册方式**: 扫码自助注册
- **登录方式**: 就诊号 + 身份证后六位
- **数据存储**: `patient_info` 表
- **权限**: 普通用户权限，可进行测试

### 管理员用户
- **注册方式**: 管理后台创建
- **登录方式**: 用户名 + 密码
- **数据存储**: `user_info` 表（简化后只存储管理员）
- **权限**: 管理员权限，可查看所有测试记录

## 登录支持

患者用户可以通过以下方式登录：
- **用户名**: 就诊号
- **密码**: 身份证后六位

登录接口 `/api/v3/login` 已更新，支持患者用户登录。

## 响应格式

### 成功响应
```json
{
    "status": "success",
    "code": 200,
    "data": {
        "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
        "token_type": "Bearer",
        "is_admin": false,
        "user_info": {
            "user_id": "user-abc-123",
            "medical_record_number": "J0012345",
            "name": "张三",
            "gender": "男",
            "dominant_hand": "右",
            "diagnosis": "无",
            "dob": "1960-01-15",
            "height_cm": 175,
            "weight_kg": 70.5,
            "contact": "13800138000",
            "inpatient_number": "Z67890",
            "bed_number": "503",
            "education_level": "本科",
            "education_years": 16,
            "remarks": ""
        }
    },
    "message": "注册成功并自动登录"
}
```

### 错误响应示例

**重复注册**:
```json
{
    "status": "error",
    "code": 400,
    "message": "Username Already Exists",
    "error_details": {
        "type": "duplicate_username",
        "description": "该就诊号已被注册"
    }
}
```

**参数验证失败**:
```json
{
    "status": "error",
    "code": 400,
    "message": "Invalid Parameters",
    "error_details": {
        "type": "validation_error",
        "description": "参数验证失败",
        "fields": {
            "dob": "出生日期格式必须是 YYYY-MM-DD",
            "height_cm": "身高必须是数字"
        }
    }
}
```

## 测试

使用提供的测试脚本 `test_register.py` 可以验证注册功能：

```bash
python test_register.py
```

测试包括：
1. 患者注册功能
2. 患者登录功能
3. 重复注册检查

## 集成说明

### 1. 路由注册
在 `app/main.py` 中已添加：
```python
from app.routers import register
app.include_router(register.router, prefix="/api/v3")
```

### 2. 数据库初始化
在应用启动时会自动初始化患者数据库表：
```python
await register.init_register_database()
```

### 3. 登录支持
`app/routers/auth.py` 中的登录接口已更新，支持患者用户登录。

## 数据库架构优势

### 1. 表结构分离
- `user_info` 表：专门存储管理员用户，结构简化
- `patient_info` 表：专门存储患者用户，包含完整的医疗信息

### 2. 安全性提升
- 管理员和患者数据完全分离
- 不同的认证方式（bcrypt vs 身份证后六位）
- 独立的权限管理

### 3. 维护性增强
- 表结构清晰，职责明确
- 便于后续功能扩展
- 数据查询和统计更方便

## 注意事项

1. **安全性**: 身份证后六位作为密码，在生产环境中应考虑更安全的认证方式
2. **数据验证**: 前端应进行适当的数据验证，后端提供二次验证
3. **错误处理**: 所有错误都有详细的错误信息，便于前端处理
4. **令牌管理**: JWT令牌有效期为7天，可根据需要调整
5. **用户类型**: 系统中只有患者和管理员两种用户类型，概念要清晰
6. **数据库**: 确保两个表都正确创建和初始化

## 后续开发

1. 可以考虑添加患者信息的更新接口
2. 可以添加患者信息的查询接口（管理员权限）
3. 可以添加患者数据的导出功能
4. 可以添加更复杂的密码策略
5. 可以添加患者和管理员之间的关联查询