👥 客户管理模块 (Client)
客户管理模块，提供客户信息的创建、查询、更新和删除功能，支持客户身份证件管理。
📚 模块概述
本模块负责管理法律服务客户的完整信息，包括：
- 客户基本信息管理
- 客户身份证件管理
- 客户类型管理（自然人/法人）
- 客户联系方式管理
📁 目录结构
client/
├── admin/ # Django Admin 配置
│ ├── client_admin.py # 客户 Admin
│ └── clientidentitydoc_admin.py # 身份证件 Admin
├── api/ # API 接口
│ ├── client_api.py # 客户 API
│ └── clientidentitydoc_api.py # 身份证件 API
├── services/ # 业务逻辑
│ ├── client_service.py # 客户服务
│ └── text_parser.py # 文本解析器
├── models.py # 数据模型
├── schemas.py # Pydantic Schemas
└── migrations/ # 数据库迁移
🚀 快速开始
1. Admin 后台
# 访问客户管理后台
open http://localhost:8000/admin/client/
2. API 使用
import requests
BASE_URL = "http://localhost:8000/api/v1/clients"
headers = {"Authorization": "Bearer <your_jwt_token>"}
# 创建客户
response = requests.post(BASE_URL, json={
"name": "张三",
"client_type": "individual",
"id_number": "110101199001011234",
"phone": "13800138000",
"address": "北京市朝阳区"
}, headers=headers)
client_id = response.json()["data"]["id"]
# 获取客户详情
response = requests.get(f"{BASE_URL}/{client_id}", headers=headers)
client = response.json()["data"]
# 更新客户
response = requests.put(f"{BASE_URL}/{client_id}", json={
"phone": "13900139000"
}, headers=headers)
# 添加身份证件
response = requests.post(f"{BASE_URL}/{client_id}/identity-docs", json={
"doc_type": "id_card",
"doc_number": "110101199001011234",
"doc_image": "base64_encoded_image"
}, headers=headers)
3. Service 层使用
from apps.client.services.client_service import ClientService
from apps.client.schemas import ClientCreateSchema
service = ClientService()
# 创建客户
client = service.create_client(
data=ClientCreateSchema(
name="张三",
client_type="individual",
id_number="110101199001011234",
phone="13800138000"
),
user=request.user
)
# 获取客户
client = service.get_client(client_id=1, user=request.user)
# 更新客户
client = service.update_client(
client_id=1,
data=ClientUpdateSchema(phone="13900139000"),
user=request.user
)
🔑 核心功能
客户管理
- ✅ 创建、查询、更新、删除客户
- ✅ 客户类型管理（自然人、法人）
- ✅ 客户身份证号管理
- ✅ 客户联系方式管理
- ✅ 客户地址管理
- ✅ 客户标记（是否为本所客户）
身份证件管理
- ✅ 添加、编辑、删除身份证件
- ✅ 证件类型（身份证、营业执照、护照等）
- ✅ 证件图片上传
- ✅ 证件有效期管理
文本解析
- ✅ 从文本中提取客户信息
- ✅ 智能识别姓名、电话、地址
- ✅ 批量导入客户
📊 数据模型
Client (客户)
name: 客户姓名/名称client_type: 客户类型（individual/company）id_number: 身份证号/统一社会信用代码phone: 联系电话address: 地址is_our_client: 是否为本所客户created_by: 创建人
ClientIdentityDoc (身份证件)
client: 关联客户doc_type: 证件类型doc_number: 证件号码doc_image: 证件图片issue_date: 签发日期expiry_date: 有效期created_by: 创建人
🔒 权限控制
功能级别权限
client.add_client: 创建客户client.view_client: 查看客户client.change_client: 修改客户client.delete_client: 删除客户
对象级别权限
- 客户创建人可以查看和修改自己的客户
- 管理员可以查看和修改所有客户
- 同组织成员可以查看组织内的客户
🧪 测试
# 运行单元测试
cd backend
source venv311/bin/activate
python -m pytest tests/unit/test_client/ -v
# 运行集成测试
python -m pytest tests/integration/test_client_api/ -v
# 运行属性测试
python -m pytest tests/property/test_client_properties/ -v
📝 相关文档
- models.py - 数据模型定义
- schemas.py - API Schema 定义
- services/text_parser.py - 文本解析器
🔗 依赖模块
- cases: 案件模块（案件当事人关联客户）
- organization: 组织模块（客户归属组织）
- core: 核心模块（异常、接口、验证器）
🎯 最佳实践
1. 使用 Service 层
# ✅ 正确：使用 Service 层
service = ClientService()
client = service.create_client(data, user)
# ❌ 错误：直接操作 Model
client = Client.objects.create(name="张三")
2. 验证身份证号
# ✅ 正确：使用验证器
from apps.client.validators import validate_id_number
try:
validate_id_number("110101199001011234")
except ValidationError as e:
print(f"身份证号无效: {e}")
3. 使用文本解析器
# ✅ 正确：使用文本解析器提取信息
from apps.client.services.text_parser import TextParser
parser = TextParser()
info = parser.parse_client_info(
"张三，电话：13800138000，地址：北京市朝阳区"
)
# info = {"name": "张三", "phone": "13800138000", "address": "北京市朝阳区"}
4. 处理客户类型
# ✅ 正确：根据客户类型处理
if client.client_type == "individual":
# 自然人客户
validate_id_number(client.id_number)
elif client.client_type == "company":
# 法人客户
validate_credit_code(client.id_number)
🐛 常见问题
Q1: 如何批量导入客户？
A: 使用 Django Admin 的导入功能，或调用 API 批量创建。
Q2: 如何处理重复客户？
A: 系统会根据身份证号/统一社会信用代码检查重复，创建前会验证。
Q3: 如何上传身份证件图片？
A: 使用 Base64 编码上传图片，或使用文件上传接口。
📈 性能优化
- ✅ 使用
select_related预加载关联对象 - ✅ 使用索引优化查询（姓名、身份证号、电话）
- ✅ 使用缓存减少数据库查询
- ✅ 批量操作使用
bulk_create
🔄 版本历史
- v1.0.0 (2024-01): 初始版本
- v1.1.0 (2024-03): 添加身份证件管理
- v1.2.0 (2024-06): 添加文本解析功能
- v1.3.0 (2024-09): 优化客户搜索