diff --git a/docs/plans/2026-05-01-ai-legal-assistant-design.md b/docs/plans/2026-05-01-ai-legal-assistant-design.md new file mode 100644 index 0000000..310e926 --- /dev/null +++ b/docs/plans/2026-05-01-ai-legal-assistant-design.md @@ -0,0 +1,606 @@ +# AI 法律助手系统设计文档 + +**版本**: 1.0 +**日期**: 2026-05-01 +**作者**: AI 开发团队 + +--- + +## 1. 背景与目标 + +### 1.1 背景 + +法律服务行业正经历数字化转型，传统法律工作模式存在效率低、知识管理困难、合同流程繁琐等问题。AI 技术的发展为法律工作自动化提供了可能。 + +### 1.2 目标 + +构建一个 AI 法律助手系统，提供以下核心能力： +- 法律法规智能检索与问答 +- 深度法律研判分析 +- 案件评审辅助 +- 合同全生命周期管理 +- 电子签名服务 + +### 1.3 成功标准 + +| 指标 | 目标值 | +|------|--------| +| 法律检索响应时间 | < 3 秒 | +| 合同审查效率提升 | > 50% | +| 系统可用性 | > 99% | +| 单机支持并发用户 | 20 人 | + +--- + +## 2. 范围与非范围 + +### 2.1 范围（MVP） + +- 法律法规检索与智能问答 +- 基础法律研判（法条引用、案例分析） +- 案件信息管理与评审记录 +- 合同模板管理与在线编辑 +- 电子签名（简化版，无 CA 证书） +- 用户权限管理 + +### 2.2 非范围（二期） + +- 多租户支持 +- 高可用集群部署 +- 移动端 APP +- 对接国家法律法规数据库 API +- CA 证书集成 +- 语音交互 + +--- + +## 3. 系统架构 + +### 3.1 整体架构 + +``` +┌────────────────────────────────────────────────────────────────┐ +│ 前端层 (Vue 3 SPA) │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐│ +│ │ 法律检索 │ │ 法律研判 │ │ 案件评审 │ │ 合同管理 │ │电子签名││ +│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └────────┘│ +└────────────────────────────────────────────────────────────────┘ + │ HTTP/WebSocket +┌────────────────────────────────────────────────────────────────┐ +│ API 网关层 (FastAPI) │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ 认证中间件 │ 请求限流 │ 日志记录 │ 异常处理 │ │ +│ └──────────────────────────────────────────────────────────┘ │ +└────────────────────────────────────────────────────────────────┘ + │ +┌────────────────────────────────────────────────────────────────┐ +│ 业务服务层 │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ +│ │ 法律服务 │ │ 研判服务 │ │ 案件服务 │ │ 合同服务 │ │ +│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ +│ │ 签名服务 │ │ 用户服务 │ │ 文件服务 │ │ +│ └──────────┘ └──────────┘ └──────────┘ │ +└────────────────────────────────────────────────────────────────┘ + │ +┌────────────────────────────────────────────────────────────────┐ +│ AI 能力层 │ +│ ┌──────────────────────┐ ┌──────────────────────────────┐ │ +│ │ LLM 服务 (外部 API) │ │ Embedding 服务 (外部 API) │ │ +│ │ - 对话补全 │ │ - 文本向量化 │ │ +│ │ - 法律问答 │ │ - 相似度检索 │ │ +│ └──────────────────────┘ └──────────────────────────────┘ │ +└────────────────────────────────────────────────────────────────┘ + │ +┌────────────────────────────────────────────────────────────────┐ +│ 数据存储层 │ +│ ┌──────────────────────┐ ┌──────────────────────────────┐ │ +│ │ SQLite (关系数据) │ │ sqlite-vss (向量检索) │ │ +│ │ - 用户/权限 │ │ - 法律法规向量 │ │ +│ │ - 合同/案件 │ │ - 案例向量 │ │ +│ │ - 签名记录 │ │ - 合同条款向量 │ │ +│ └──────────────────────┘ └──────────────────────────────┘ │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ 文件存储 (本地文件系统) │ │ +│ │ - 合同 PDF/Word │ │ +│ │ - 签名文件 │ │ +│ └──────────────────────────────────────────────────────────┘ │ +└────────────────────────────────────────────────────────────────┘ +``` + +### 3.2 技术栈 + +| 层级 | 技术选型 | 版本 | 说明 | +|------|----------|------|------| +| 前端 | Vue 3 + TypeScript + Vite | 3.4+ | SPA 单页应用 | +| UI 组件 | Element Plus | 2.5+ | 企业级 UI 组件库 | +| 后端框架 | FastAPI | 0.110+ | 高性能异步 Python 框架 | +| ORM | SQLAlchemy | 2.0+ | 异步 ORM 支持 | +| 数据库 | SQLite | 3.40+ | 关系型数据库 | +| 向量检索 | sqlite-vss | 0.1+ | SQLite 向量扩展 | +| LLM | OpenAI API 兼容接口 | - | 支持多厂商切换 | +| Embedding | text-embedding-3-small | - | 或国内等效模型 | +| 文件存储 | 本地文件系统 | - | 可选 MinIO | +| 容器化 | Docker + docker-compose | - | 一键部署 | + +--- + +## 4. 核心模块设计 + +### 4.1 法律法规引擎 + +#### 4.1.1 功能描述 +- 法律法规数据导入与管理 +- 智能检索（关键词 + 语义相似度） +- 法条问答 + +#### 4.1.2 数据模型 + +```python +class Law(Base): + """法律法规表""" + id: int # 主键 + title: str # 标题 + law_type: str # 类型：法律/法规/规章/司法解释 + promulgation_date: date # 颁布日期 + effective_date: date # 生效日期 + status: str # 状态：有效/废止/修订 + issuing_authority: str # 颁布机关 + content: str # 全文内容 + embedding: List[float] # 向量嵌入（存储在向量表） + created_at: datetime + updated_at: datetime + +class LawArticle(Base): + """法条表""" + id: int + law_id: int # 所属法律 + article_number: str # 条号 + content: str # 条款内容 + embedding: List[float] # 向量嵌入 +``` + +#### 4.1.3 检索流程 + +``` +用户查询 → 文本向量化 → 向量相似度检索 → Top-K 法条 → LLM 生成回答 +``` + +### 4.2 法律研判引擎 + +#### 4.2.1 功能描述 +- 基于法条的法律分析 +- 案例参考推荐 +- 研判报告生成 + +#### 4.2.2 数据模型 + +```python +class LegalAnalysis(Base): + """法律研判记录""" + id: int + user_id: int + title: str # 研判主题 + case_description: str # 案情描述 + legal_basis: JSON # 法律依据（法条列表） + analysis_content: str # 研判内容 + conclusion: str # 结论 + created_at: datetime + +class Case(Base): + """案例库""" + id: int + title: str # 案例标题 + case_number: str # 案号 + court: str # 审理法院 + case_type: str # 案由类型 + judgment_date: date # 判决日期 + facts: str # 事实认定 + judgment: str # 判决结果 + reasoning: str # 裁判理由 + embedding: List[float] # 向量嵌入 +``` + +### 4.3 案件评审系统 + +#### 4.3.1 功能描述 +- 案件信息管理 +- 评审意见记录 +- 评审流程跟踪 + +#### 4.3.2 数据模型 + +```python +class CaseReview(Base): + """案件评审""" + id: int + case_id: int # 关联案例 + reviewer_id: int # 评审人 + review_type: str # 类型：初审/复审/终审 + opinion: str # 评审意见 + score: int # 评分（可选） + status: str # 状态：待审/通过/驳回 + created_at: datetime + +class CaseReviewFlow(Base): + """评审流程""" + id: int + case_id: int + current_step: int # 当前步骤 + total_steps: int # 总步骤 + status: str # 流程状态 +``` + +### 4.4 合同管理系统 + +#### 4.4.1 功能描述 +- 合同模板管理 +- 合同创建与编辑 +- 合同审批流程 +- 合同归档与检索 + +#### 4.4.2 数据模型 + +```python +class ContractTemplate(Base): + """合同模板""" + id: int + name: str + contract_type: str # 合同类型 + content: str # 模板内容（支持变量占位符） + variables: JSON # 变量定义 + created_by: int + created_at: datetime + +class Contract(Base): + """合同""" + id: int + template_id: int # 模板来源 + title: str + contract_number: str # 合同编号 + party_a: str # 甲方 + party_b: str # 乙方 + content: str # 合同内容 + status: str # 状态：草稿/审批中/已签署/已归档 + effective_date: date + expiry_date: date + file_path: str # 文件存储路径 + created_by: int + created_at: datetime + +class ContractApproval(Base): + """合同审批""" + id: int + contract_id: int + approver_id: int + status: str # 待审/通过/驳回 + comment: str + approved_at: datetime +``` + +### 4.5 电子签名服务 + +#### 4.5.1 功能描述 +- 签名请求创建 +- 签名验证（简化版） +- 签名记录审计 + +#### 4.5.2 数据模型 + +```python +class SignatureRequest(Base): + """签名请求""" + id: int + contract_id: int + requester_id: int # 发起人 + signer_name: str # 签署人姓名 + signer_email: str # 签署人邮箱 + status: str # 待签/已签/已拒绝/已过期 + token: str # 签名令牌（唯一） + expires_at: datetime # 过期时间 + created_at: datetime + +class Signature(Base): + """签名记录""" + id: int + request_id: int + signer_name: str + signature_data: str # 签名数据（Base64 图片或坐标） + ip_address: str # 签署 IP + user_agent: str # 浏览器信息 + signed_at: datetime + verification_hash: str # 验证哈希（文档指纹） + +class SignatureAudit(Base): + """签名审计日志""" + id: int + signature_id: int + action: str # 动作类型 + details: JSON + created_at: datetime +``` + +#### 4.5.3 签名流程 + +``` +发起签名请求 → 生成签名令牌 → 发送邮件通知 → 签署人打开链接 → +绘制签名 → 计算文档哈希 → 保存签名记录 → 通知发起人 +``` + +--- + +## 5. API 设计 + +### 5.1 RESTful API 规范 + +基础路径：`/api/v1` + +认证方式：JWT Bearer Token + +### 5.2 核心 API 列表 + +#### 法律法规模块 + +| 方法 | 路径 | 描述 | +|------|------|------| +| GET | `/laws` | 法律法规列表 | +| POST | `/laws` | 创建法律法规 | +| GET | `/laws/{id}` | 获取详情 | +| POST | `/laws/search` | 智能检索 | +| POST | `/laws/qa` | 法律问答 | + +#### 法律研判模块 + +| 方法 | 路径 | 描述 | +|------|------|------| +| POST | `/analyses` | 创建研判 | +| GET | `/analyses` | 研判列表 | +| GET | `/analyses/{id}` | 研判详情 | +| POST | `/analyses/generate` | AI 生成研判 | + +#### 案件评审模块 + +| 方法 | 路径 | 描述 | +|------|------|------| +| GET | `/cases` | 案件列表 | +| POST | `/cases` | 创建案件 | +| POST | `/cases/{id}/reviews` | 提交评审 | +| GET | `/cases/{id}/reviews` | 评审记录 | + +#### 合同管理模块 + +| 方法 | 路径 | 描述 | +|------|------|------| +| GET | `/contracts` | 合同列表 | +| POST | `/contracts` | 创建合同 | +| PUT | `/contracts/{id}` | 更新合同 | +| POST | `/contracts/{id}/submit` | 提交审批 | +| POST | `/contracts/{id}/approve` | 审批合同 | + +#### 电子签名模块 + +| 方法 | 路径 | 描述 | +|------|------|------| +| POST | `/signatures/request` | 发起签名 | +| GET | `/signatures/{token}` | 获取签名页 | +| POST | `/signatures/{token}/sign` | 执行签名 | +| GET | `/signatures/{id}/verify` | 验证签名 | + +--- + +## 6. 用户权限设计 + +### 6.1 角色定义 + +| 角色 | 权限范围 | +|------|----------| +| admin | 系统管理员，全部权限 | +| lawyer | 律师，法律法规检索、研判、案件评审、合同管理 | +| reviewer | 评审人，仅案件评审 | +| client | 客户，查看自己的合同、执行签名 | + +### 6.2 权限矩阵 + +| 功能模块 | admin | lawyer | reviewer | client | +|----------|-------|--------|----------|--------| +| 用户管理 | ✓ | ✗ | ✗ | ✗ | +| 法律检索 | ✓ | ✓ | ✓ | ✗ | +| 法律研判 | ✓ | ✓ | ✗ | ✗ | +| 案件管理 | ✓ | ✓ | ✓ | ✗ | +| 合同管理 | ✓ | ✓ | ✗ | 查看 | +| 电子签名 | ✓ | ✓ | ✗ | ✓ | + +--- + +## 7. 错误处理 + +### 7.1 错误码规范 + +| 错误码 | 含义 | +|--------|------| +| 10001 | 参数校验失败 | +| 10002 | 资源不存在 | +| 20001 | 认证失败 | +| 20002 | 权限不足 | +| 30001 | LLM 服务异常 | +| 30002 | 向量检索异常 | +| 40001 | 签名已过期 | +| 40002 | 签名已失效 | + +### 7.2 统一响应格式 + +```json +{ + "code": 0, + "message": "success", + "data": { ... } +} +``` + +错误响应： +```json +{ + "code": 20001, + "message": "认证失败，请重新登录", + "data": null +} +``` + +--- + +## 8. 测试策略 + +### 8.1 单元测试 + +- 覆盖所有业务逻辑层 +- 使用 pytest + pytest-asyncio +- Mock 外部 API 调用 +- 目标覆盖率 > 80% + +### 8.2 集成测试（二期） + +- API 端到端测试 +- 数据库集成测试 + +### 8.3 测试命令 + +```bash +# 运行所有单元测试 +pytest tests/unit -v + +# 运行覆盖率报告 +pytest tests/unit --cov=app --cov-report=html +``` + +--- + +## 9. 部署架构 + +### 9.1 单机部署 + +``` +┌─────────────────────────────────────┐ +│ 物理机/虚拟机 │ +│ ┌───────────────────────────────┐ │ +│ │ Nginx (反向代理) │ │ +│ │ :80/:443 │ │ +│ └───────────────────────────────┘ │ +│ │ │ +│ ┌───────────────────────────────┐ │ +│ │ FastAPI 应用 (Uvicorn) │ │ +│ │ :8000 │ │ +│ └───────────────────────────────┘ │ +│ │ │ +│ ┌───────────────────────────────┐ │ +│ │ SQLite + 向量扩展 + 文件存储 │ │ +│ └───────────────────────────────┘ │ +└─────────────────────────────────────┘ +``` + +### 9.2 Docker 部署 + +```yaml +# docker-compose.yml +version: '3.8' +services: + web: + build: . + ports: + - "8000:8000" + volumes: + - ./data:/app/data + - ./uploads:/app/uploads + environment: + - DATABASE_URL=sqlite:///./data/legal_assistant.db + - LLM_API_KEY=${LLM_API_KEY} + - LLM_API_BASE=${LLM_API_BASE} + - EMBEDDING_API_KEY=${EMBEDDING_API_KEY} +``` + +--- + +## 10. 安全设计 + +### 10.1 认证与授权 + +- JWT Token 认证，有效期 24 小时 +- Refresh Token 有效期 7 天 +- 敏感操作需要二次验证 + +### 10.2 数据安全 + +- 密码使用 bcrypt 加密存储 +- 敏感配置通过环境变量注入 +- 文件上传类型白名单限制 + +### 10.3 API 安全 + +- 请求频率限制（每分钟 60 次） +- SQL 注入防护（ORM 参数化查询） +- XSS 防护（输入过滤 + 输出编码） + +--- + +## 11. 目录结构 + +``` +legal-assistant/ +├── backend/ # 后端代码 +│ ├── app/ +│ │ ├── api/ # API 路由 +│ │ │ ├── v1/ +│ │ │ │ ├── laws.py +│ │ │ │ ├── analyses.py +│ │ │ │ ├── cases.py +│ │ │ │ ├── contracts.py +│ │ │ │ └── signatures.py +│ │ ├── models/ # 数据模型 +│ │ ├── schemas/ # Pydantic 模型 +│ │ ├── services/ # 业务逻辑 +│ │ ├── core/ # 核心配置 +│ │ │ ├── config.py +│ │ │ ├── security.py +│ │ │ └── database.py +│ │ └── main.py # 应用入口 +│ ├── tests/ # 测试代码 +│ │ └── unit/ +│ ├── alembic/ # 数据库迁移 +│ ├── requirements.txt +│ └── Dockerfile +├── frontend/ # 前端代码 +│ ├── src/ +│ │ ├── views/ +│ │ ├── components/ +│ │ ├── api/ +│ │ ├── stores/ +│ │ └── router/ +│ ├── package.json +│ └── Dockerfile +├── docker-compose.yml +├── .env.example +└── README.md +``` + +--- + +## 12. 风险与缓解 + +| 风险 | 影响 | 缓解措施 | +|------|------|----------| +| LLM API 不可用 | 法律问答功能不可用 | 增加重试机制和降级策略（返回检索结果） | +| 向量检索性能 | 检索响应慢 | 数据量增大后考虑迁移到专业向量库 | +| 签名法律效力 | 用户误解 | 明确告知用户本系统签名不具备法律效力 | +| 数据丢失 | 业务中断 | 定期备份 SQLite 数据库文件 | + +--- + +## 13. 里程碑 + +| 阶段 | 内容 | 预计时间 | +|------|------|----------| +| MVP | 核心功能实现 + 单元测试 | 2 周 | +| 二期 | 高级功能 + 性能优化 | 2 周 | + +--- + +**设计文档完成，等待用户批准后进入实现计划阶段。**