# 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 周 |

---

**设计文档完成，等待用户批准后进入实现计划阶段。**