# 📄 合同管理模块 (Contracts)

合同管理模块，提供合同的创建、查询、更新和删除功能，支持合同支付、财务日志、合同提醒等功能。

## 📚 模块概述

本模块负责管理法律服务合同的完整生命周期，包括：
- 合同基本信息管理
- 合同支付管理
- 合同财务日志
- 合同提醒管理
- 合同状态管理

## 📁 目录结构

```
contracts/
├── admin/              # Django Admin 配置
│   ├── contract_admin.py           # 合同 Admin
│   ├── contractpayment_admin.py    # 支付 Admin
│   ├── contractfinancelog_admin.py # 财务日志 Admin
│   └── contractreminder_admin.py   # 提醒 Admin
├── api/                # API 接口
│   ├── contract_api.py             # 合同 API
│   ├── contractpayment_api.py      # 支付 API
│   ├── contractfinance_api.py      # 财务 API
│   └── contractreminder_api.py     # 提醒 API
├── services/           # 业务逻辑
│   ├── contract_service.py         # 合同服务
│   └── payment_service.py          # 支付服务
├── models.py           # 数据模型
├── schemas.py          # Pydantic Schemas
└── migrations/         # 数据库迁移
```

## 🚀 快速开始

### 1. Admin 后台

```bash
# 访问合同管理后台
open http://localhost:8000/admin/contracts/
```

### 2. API 使用

```python
import requests
from decimal import Decimal

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

# 创建合同
response = requests.post(BASE_URL, json={
    "name": "法律服务合同",
    "client_id": 1,
    "law_firm_id": 1,
    "assigned_lawyer_id": 1,
    "case_type": "civil",
    "fee_mode": "fixed",
    "fixed_amount": "50000.00",
    "start_date": "2024-01-01",
    "end_date": "2024-12-31",
    "status": "active"
}, headers=headers)

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

# 获取合同详情
response = requests.get(f"{BASE_URL}/{contract_id}", headers=headers)
contract = response.json()["data"]

# 更新合同
response = requests.put(f"{BASE_URL}/{contract_id}", json={
    "status": "completed"
}, headers=headers)

# 添加支付记录
response = requests.post(f"{BASE_URL}/{contract_id}/payments", json={
    "amount": "10000.00",
    "payment_date": "2024-01-15",
    "payment_method": "bank_transfer",
    "notes": "首付款"
}, headers=headers)
```

### 3. Service 层使用

```python
from apps.contracts.services.contract_service import ContractService
from apps.contracts.schemas import ContractCreateSchema
from decimal import Decimal

service = ContractService(
    client_service=ClientService(),
    lawyer_service=LawyerService()
)

# 创建合同
contract = service.create_contract(
    data=ContractCreateSchema(
        name="法律服务合同",
        client_id=1,
        law_firm_id=1,
        assigned_lawyer_id=1,
        case_type="civil",
        fee_mode="fixed",
        fixed_amount=Decimal("50000.00")
    ),
    user=request.user
)

# 获取合同
contract = service.get_contract(contract_id=1, user=request.user)

# 添加支付
payment_service = PaymentService()
payment = payment_service.create_payment(
    contract_id=1,
    amount=Decimal("10000.00"),
    payment_date="2024-01-15",
    user=request.user
)
```

## 🔑 核心功能

### 合同管理
- ✅ 创建、查询、更新、删除合同
- ✅ 合同状态管理（草稿、生效、完成、终止）
- ✅ 合同类型管理（民事、刑事、行政）
- ✅ 收费模式管理（固定费用、风险代理、计时收费）
- ✅ 合同期限管理
- ✅ 合同当事人管理

### 支付管理
- ✅ 添加、编辑、删除支付记录
- ✅ 支付方式管理（银行转账、现金、支票等）
- ✅ 支付日期管理
- ✅ 支付备注
- ✅ 支付统计

### 财务日志
- ✅ 自动记录财务变动
- ✅ 日志类型（收款、退款、调整）
- ✅ 日志金额和余额
- ✅ 日志时间线

### 合同提醒
- ✅ 合同到期提醒
- ✅ 支付提醒
- ✅ 自定义提醒
- ✅ 提醒状态管理

## 📊 数据模型

### Contract (合同)
- `name`: 合同名称
- `client`: 关联客户
- `law_firm`: 关联律所
- `assigned_lawyer`: 指派律师
- `case_type`: 案件类型
- `fee_mode`: 收费模式
- `fixed_amount`: 固定金额
- `start_date`: 开始日期
- `end_date`: 结束日期
- `status`: 合同状态
- `created_by`: 创建人

### ContractPayment (合同支付)
- `contract`: 关联合同
- `amount`: 支付金额
- `payment_date`: 支付日期
- `payment_method`: 支付方式
- `notes`: 备注
- `created_by`: 创建人

### ContractFinanceLog (财务日志)
- `contract`: 关联合同
- `log_type`: 日志类型
- `amount`: 金额
- `balance`: 余额
- `notes`: 备注
- `created_at`: 创建时间

### ContractReminder (合同提醒)
- `contract`: 关联合同
- `reminder_type`: 提醒类型
- `reminder_date`: 提醒日期
- `content`: 提醒内容
- `is_sent`: 是否已发送
- `created_by`: 创建人

## 🔒 权限控制

### 功能级别权限
- `contracts.add_contract`: 创建合同
- `contracts.view_contract`: 查看合同
- `contracts.change_contract`: 修改合同
- `contracts.delete_contract`: 删除合同

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

## 🧪 测试

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

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

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

## 📝 相关文档

- **[models.py](models.py)** - 数据模型定义
- **[schemas.py](schemas.py)** - API Schema 定义
- **[services/contract_service.py](services/contract_service.py)** - 合同服务
- **[services/payment_service.py](services/payment_service.py)** - 支付服务

## 🔗 依赖模块

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

## 🎯 最佳实践

### 1. 使用 Service 层
```python
# ✅ 正确：使用 Service 层
service = ContractService(
    client_service=ClientService(),
    lawyer_service=LawyerService()
)
contract = service.create_contract(data, user)

# ❌ 错误：直接操作 Model
contract = Contract.objects.create(name="合同", client_id=1)
```

### 2. 使用事务管理
```python
# ✅ 正确：使用事务确保数据一致性
from django.db import transaction

@transaction.atomic
def create_contract_with_payment(contract_data, payment_data, user):
    contract = contract_service.create_contract(contract_data, user)
    payment = payment_service.create_payment(
        contract.id, payment_data, user
    )
    return contract, payment
```

### 3. 计算合同余额
```python
# ✅ 正确：使用 Service 层计算
balance = contract_service.get_contract_balance(contract_id)

# ❌ 错误：手动计算
total_paid = sum(p.amount for p in contract.payments.all())
balance = contract.fixed_amount - total_paid
```

### 4. 发送合同提醒
```python
# ✅ 正确：使用提醒服务
from apps.contracts.services.reminder_service import ReminderService

reminder_service = ReminderService()
reminder_service.send_contract_expiry_reminders()
```

## 🐛 常见问题

### Q1: 如何处理风险代理合同？
**A**: 设置 `fee_mode="risk_agency"`，并设置 `risk_ratio` 字段。

### Q2: 如何计算合同已支付金额？
**A**: 使用 `contract_service.get_total_paid(contract_id)` 方法。

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

## 📈 性能优化

- ✅ 使用 `select_related` 预加载关联对象
- ✅ 使用 `prefetch_related` 预加载支付记录
- ✅ 使用 `annotate` 计算聚合数据
- ✅ 使用索引优化查询（合同名称、状态、日期）
- ✅ 使用缓存减少数据库查询

## 💰 财务统计

```python
# 获取合同财务统计
from django.db.models import Sum, Count

stats = Contract.objects.aggregate(
    total_contracts=Count('id'),
    total_amount=Sum('fixed_amount'),
    total_paid=Sum('payments__amount')
)

print(f"合同总数: {stats['total_contracts']}")
print(f"合同总金额: {stats['total_amount']}")
print(f"已收款总额: {stats['total_paid']}")
```

## 🔄 版本历史

- **v1.0.0** (2024-01): 初始版本
- **v1.1.0** (2024-03): 添加支付管理
- **v1.2.0** (2024-06): 添加财务日志
- **v1.3.0** (2024-09): 添加合同提醒