# 📁 案件管理模块 (Cases)

案件管理模块，提供案件的创建、查询、更新和删除功能，支持案件当事人、案件日志、案件指派等功能。

## 📚 模块概述

本模块负责管理法律案件的完整生命周期，包括：
- 案件基本信息管理
- 案件当事人管理
- 案件日志记录
- 案件指派管理
- 司法信息管理
- 案号管理

## 📁 目录结构

```
cases/
├── admin/              # Django Admin 配置
│   ├── case_admin.py           # 案件 Admin
│   ├── caseparty_admin.py      # 当事人 Admin
│   ├── caselog_admin.py        # 日志 Admin
│   ├── caseassignment_admin.py # 指派 Admin
│   ├── casenumber_admin.py     # 案号 Admin
│   └── judicialinfo_admin.py   # 司法信息 Admin
├── api/                # API 接口
│   ├── case_api.py             # 案件 API
│   ├── caseparty_api.py        # 当事人 API
│   ├── caselog_api.py          # 日志 API
│   ├── caseassignment_api.py   # 指派 API
│   ├── casenumber_api.py       # 案号 API
│   ├── caseaccess_api.py       # 访问权限 API
│   └── judicialinfo_api.py     # 司法信息 API
├── services/           # 业务逻辑
│   ├── case_service.py         # 案件服务
│   ├── case_log_service.py     # 日志服务
│   └── case_access_service.py  # 访问权限服务
├── models.py           # 数据模型
├── schemas.py          # Pydantic Schemas
├── validators.py       # 数据验证器
└── migrations/         # 数据库迁移
```

## 🚀 快速开始

### 1. Admin 后台

```bash
# 访问案件管理后台
open http://localhost:8000/admin/cases/
```

### 2. API 使用

```python
import requests

BASE_URL = "http://localhost:8000/api/v1/cases"
headers = {"Authorization": "Bearer <your_jwt_token>"}

# 创建案件
response = requests.post(BASE_URL, json={
    "name": "张三诉李四合同纠纷案",
    "contract_id": 1,
    "current_stage": "first_trial",
    "case_type": "civil"
}, headers=headers)

case_id = response.json()["data"]["id"]

# 获取案件详情
response = requests.get(f"{BASE_URL}/{case_id}", headers=headers)
case = response.json()["data"]

# 更新案件
response = requests.put(f"{BASE_URL}/{case_id}", json={
    "current_stage": "second_trial"
}, headers=headers)

# 添加案件日志
response = requests.post(f"{BASE_URL}/{case_id}/logs", json={
    "content": "开庭审理",
    "log_type": "hearing"
}, headers=headers)
```

### 3. Service 层使用

```python
from apps.cases.services.case_service import CaseService
from apps.cases.schemas import CaseCreateSchema

service = CaseService(
    contract_service=ContractService()
)

# 创建案件
case = service.create_case(
    data=CaseCreateSchema(
        name="张三诉李四合同纠纷案",
        contract_id=1,
        current_stage="first_trial"
    ),
    user=request.user
)

# 获取案件
case = service.get_case(case_id=1, user=request.user)

# 更新案件
case = service.update_case(
    case_id=1,
    data=CaseUpdateSchema(current_stage="second_trial"),
    user=request.user
)
```

## 🔑 核心功能

### 案件管理
- ✅ 创建、查询、更新、删除案件
- ✅ 案件阶段管理（侦查、起诉、一审、二审、执行）
- ✅ 案件类型管理（民事、刑事、行政）
- ✅ 案件状态管理（进行中、已结案、已归档）

### 当事人管理
- ✅ 添加、编辑、删除当事人
- ✅ 当事人类型（原告、被告、第三人）
- ✅ 当事人身份（自然人、法人）
- ✅ 当事人联系方式管理

### 案件日志
- ✅ 记录案件重要事件
- ✅ 日志类型分类（开庭、调解、判决等）
- ✅ 日志附件管理
- ✅ 日志时间线展示

### 案件指派
- ✅ 指派律师到案件
- ✅ 指派角色管理（主办律师、协办律师）
- ✅ 指派历史记录

### 司法信息
- ✅ 法院信息管理
- ✅ 法官信息管理
- ✅ 案号管理
- ✅ 开庭时间管理

## 📊 数据模型

### Case (案件)
- `name`: 案件名称
- `contract`: 关联合同
- `current_stage`: 当前阶段
- `case_type`: 案件类型
- `status`: 案件状态
- `created_by`: 创建人

### CaseParty (当事人)
- `case`: 关联案件
- `client`: 关联客户
- `party_type`: 当事人类型（原告/被告/第三人）
- `legal_status`: 法律地位（自然人/法人）

### CaseLog (案件日志)
- `case`: 关联案件
- `content`: 日志内容
- `log_type`: 日志类型
- `created_by`: 创建人
- `created_at`: 创建时间

### CaseAssignment (案件指派)
- `case`: 关联案件
- `lawyer`: 指派律师
- `assigned_by`: 指派人
- `assigned_at`: 指派时间

### JudicialInfo (司法信息)
- `case`: 关联案件
- `court_name`: 法院名称
- `judge_name`: 法官姓名
- `hearing_date`: 开庭日期

### CaseNumber (案号)
- `case`: 关联案件
- `number`: 案号
- `court_level`: 法院级别
- `year`: 年份

## 🔒 权限控制

### 功能级别权限
- `cases.add_case`: 创建案件
- `cases.view_case`: 查看案件
- `cases.change_case`: 修改案件
- `cases.delete_case`: 删除案件

### 对象级别权限
- 案件创建人可以查看和修改自己的案件
- 被指派的律师可以查看和修改案件
- 管理员可以查看和修改所有案件

## 🧪 测试

```bash
# 运行单元测试
cd backend
source venv311/bin/activate
python -m pytest tests/unit/test_cases/ -v

# 运行集成测试
python -m pytest tests/integration/test_case_api/ -v

# 运行属性测试
python -m pytest tests/property/test_case_properties/ -v
```

## 📝 相关文档

- **[SUPERVISING_AUTHORITY_FEATURE.md](SUPERVISING_AUTHORITY_FEATURE.md)** - 监管机关功能说明
- **[models.py](models.py)** - 数据模型定义
- **[schemas.py](schemas.py)** - API Schema 定义
- **[validators.py](validators.py)** - 数据验证器

## 🔗 依赖模块

- **contracts**: 合同模块（案件关联合同）
- **client**: 客户模块（当事人关联客户）
- **organization**: 组织模块（律师、律所）
- **core**: 核心模块（异常、接口、验证器）

## 🎯 最佳实践

### 1. 使用 Service 层
```python
# ✅ 正确：使用 Service 层
service = CaseService(contract_service=ContractService())
case = service.create_case(data, user)

# ❌ 错误：直接操作 Model
case = Case.objects.create(name="案件", contract_id=1)
```

### 2. 权限检查
```python
# ✅ 正确：在 Service 层检查权限
def get_case(self, case_id, user):
    case = Case.objects.get(id=case_id)
    if not self._can_access_case(user, case):
        raise PermissionDenied("无权限访问该案件")
    return case
```

### 3. 使用 Schema 验证
```python
# ✅ 正确：使用 Pydantic Schema
data = CaseCreateSchema(
    name="案件名称",
    contract_id=1,
    current_stage="first_trial"
)
case = service.create_case(data, user)
```

### 4. 记录案件日志
```python
# ✅ 正确：重要操作记录日志
case_log_service.create_log(
    case_id=case.id,
    content="案件已创建",
    log_type="system",
    user=user
)
```

## 🐛 常见问题

### Q1: 如何添加新的案件阶段？
**A**: 在 `models.py` 的 `CASE_STAGES` 中添加新阶段，然后运行迁移。

### Q2: 如何实现案件搜索？
**A**: 使用 `CaseService.list_cases()` 方法，传递搜索参数。

### Q3: 如何导出案件数据？
**A**: 使用 Django Admin 的导出功能，或调用 API 获取数据后处理。

## 📈 性能优化

- ✅ 使用 `select_related` 预加载关联对象
- ✅ 使用 `prefetch_related` 预加载多对多关系
- ✅ 使用索引优化查询（案件名称、案号、状态）
- ✅ 使用缓存减少数据库查询

## 🔄 版本历史

- **v1.0.0** (2024-01): 初始版本
- **v1.1.0** (2024-03): 添加司法信息管理
- **v1.2.0** (2024-06): 添加案号管理
- **v1.3.0** (2024-09): 添加监管机关功能