# contract-sense

**Repository Path**: elfbobo_admin_admin/contract-sense

## Basic Information

- **Project Name**: contract-sense
- **Description**: 这是一个合同智能分析系统，采用前后端分离的微服务架构：
  - 前端：Next.js + React，提供合同上传、AI 对话分析界面
  - 后端：FastAPI (Python)，处理合同解析、AI 推理、数据存储
  - 网关：Go API Gateway + Nginx，负责 JWT 认证、限流、请求转发
  - AI 引擎：集成大语言模型，支持合同条款提取、风险识别、智能问答

- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-04-24
- **Last Updated**: 2026-04-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ContractSense

> 基于 AI 的智能合同分析平台，秒级识别合同风险、提取关键条款。
>
> **在线演示**: http://111.229.178.2

---

## 项目简介

**ContractSense** 是一款面向企业和法律从业者的智能合同分析平台，基于 AI 大语言模型技术，帮助用户在数秒内识别合同风险、提取关键要素、生成专业审查报告。

### 核心价值

| 价值 | 说明 |
|------|------|
| 快速分析 | 1-2 分钟内完成全篇风险识别 |
| 精准识别 | 高/中/低三级风险分类，附带法律依据和修改建议 |
| 数据安全 | 256 位 SSL 加密传输，用户数据严格隔离 |
| 专业可靠 | 基于数千份法律文档训练的 AI 模型 |

---

## 技术栈

### 前端

- [Next.js 15](https://nextjs.org/) - React 全栈框架
- [Tailwind CSS](https://tailwindcss.com/) - 原子化 CSS 框架
- [Lucide React](https://lucide.dev/) - 图标库

### 网关层

- [Go + Gin](https://gin-gonic.com/) - 统一网关与鉴权
- [JWT](https://jwt.io/) - Token 认证
- 一次鉴权，后端无需重复验证

### 后端

- [FastAPI](https://fastapi.tiangolo.com/) - 高性能异步 Web 框架
- [SQLAlchemy](https://sqlalchemy.org/) - ORM 框架
- [SQLite](https://sqlite.org/) - 轻量级数据库
- [Alembic](https://alembic.sqlalchemy.org/) - 数据库迁移

### AI 与部署

- [DeepSeek API](https://www.deepseek.com/) - AI 模型服务
- [Docker Compose](https://docs.docker.com/compose/) - 容器编排
- [Nginx](https://nginx.org/) - 反向代理

---

## 系统架构

请求流程：Client -> Nginx -> Go Gateway -> Backend/Frontend

```
+----------+     +--------+     +-----------+     +---------+
|  Client  |---->|  Nginx |---->|Go Gateway |---->| Backend |
+----------+     +--------+     |  (鉴权)   |     |(FastAPI)|
                                +----+------+     +---------+
                                     |
                                     v
                                +---------+
                                |Frontend |
                                |(Next.js)|
                                +---------+
```

**核心特点**：

| 特性 | 说明 |
|------|------|
| 统一鉴权 | Gateway 层 JWT 验证，Backend 无需重复鉴权 |
| 白名单机制 | `/api/auth/login`、`/api/auth/register` 无需认证 |
| 限流保护 | 基于 IP 的请求限流（默认 100 RPS） |
| 反向代理 | API 请求转发 Backend，静态资源转发 Frontend |

---


## 项目结构

```
contract-sense/
+-- frontend/                     # Next.js 前端应用
|   +-- app/                      # 页面路由
|   +-- features/                 # 功能模块（认证/合同/分析/对话）
|   +-- components/               # 公共组件
|   +-- styles/                   # 全局样式
|   +-- lib/                      # 工具函数
|
+-- gateway/                      # Go 网关（统一鉴权）
|   +-- cmd/main.go               # 入口文件
|   +-- internal/
|   |   +-- config/               # 配置加载
|   |   +-- middleware/auth.go    # JWT 鉴权中间件
|   |   +-- middleware/ratelimit.go # IP 限流中间件
|   |   +-- proxy/                # 反向代理
|   |   +-- router/               # 路由配置
|   +-- go.mod
|
+-- backend/                      # FastAPI 后端应用
|   +-- app/
|   |   +-- api/                  # API 路由
|   |   +-- models/               # 数据模型
|   |   +-- repositories/         # 数据访问层
|   |   +-- services/             # 业务逻辑层
|   |   +-- agents/               # AI Agent
|   |   +-- core/                 # 核心配置
|   +-- alembic/                  # 数据库迁移
|   +-- scripts/                  # 运维脚本
|   +-- tests/                    # 测试用例
|
+-- nginx/                        # Nginx 配置
|   +-- nginx.conf                # 反向代理配置
|
+-- docs/                         # 项目文档
+-- docker-compose.yml            # Docker 编排
+-- README.md
```

---

## 快速开始

### 环境要求

- Docker & Docker Compose

### 一键启动

```bash
# 1. 克隆项目
git clone https://gitee.com/jun-jia-zhangE/contract-sense.git
cd contract-sense

# 2. 配置环境变量
cp backend/.env.example backend/.env
# 编辑 backend/.env，填写 DeepSeek API Key

# 3. 一键启动
docker compose up -d

# 4. 查看日志
docker compose logs -f

# 5. 访问应用
# 前端：http://<服务器IP>
# API 文档：http://<服务器IP>/api/docs
```

### 首次使用

启动后访问 `http://<服务器IP>`，点击「注册」创建账户即可开始使用。

---

## 配置说明

### 环境变量

#### Backend（backend/.env）

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `DEEPSEEK_API_KEY` | DeepSeek API 密钥 | **必填** |
| `DEEPSEEK_BASE_URL` | DeepSeek API 地址 | `https://api.deepseek.com/v1` |
| `DEEPSEEK_MODEL` | AI 模型 | `deepseek-chat` |
| `DATABASE_URL` | 数据库连接 | 自动使用 SQLite |

#### Gateway（docker-compose.yml）

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `JWT_SECRET` | JWT 签名密钥 | `your-secret-key-change-in-production` |
| `GATEWAY_PORT` | 网关端口 | `8080` |
| `BACKEND_URL` | 后端地址 | `http://backend:8000` |
| `FRONTEND_URL` | 前端地址 | `http://frontend:3000` |

> 生产环境请修改 `JWT_SECRET` 为安全密钥

### .env 示例

```bash
# backend/.env
DEEPSEEK_API_KEY=sk-your-api-key-here
DEEPSEEK_BASE_URL=https://api.deepseek.com/v1
DEEPSEEK_MODEL=deepseek-chat
DEBUG=false
```

---

## API 文档

启动后端服务后，访问以下端点查看 API 文档：

- **Swagger UI**: http://<服务器IP>/api/docs
- **ReDoc**: http://<服务器IP>/api/redoc

### 核心接口

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/auth/login` | POST | 用户登录 |
| `/api/auth/register` | POST | 用户注册 |
| `/api/contracts/upload` | POST | 上传合同 |
| `/api/contracts/` | GET | 获取合同列表 |
| `/api/contracts/{id}` | GET | 获取合同详情 |
| `/api/contracts/{id}/analysis` | GET | 获取分析结果 |
| `/api/contracts/task/{task_id}/status` | GET | 查询任务状态 |
| `/api/quota/quota` | GET | 查询额度使用 |

### 接口测试示例

使用 [HTTPie](https://httpie.io/) 测试接口（比 curl 更友好）：

```bash
# 安装 HTTPie（可选）
pip install httpie
# 或
brew install httpie

# 注册用户
http POST <服务器IP>/api/auth/register \
  username=testuser \
  email=test@example.com \
  password=test123456

# 登录获取 Token
http POST <服务器IP>/api/auth/login \
  username=testuser \
  password=test123456

# 使用 Token 访问受保护接口
http <服务器IP>/api/contracts/ \
  "Authorization:Bearer <your_token>"
```

---

## 测试

```bash
# 后端测试
cd backend
pytest tests/ -v --cov=app

# 前端测试
cd frontend
npm test
```

---

## 贡献指南

欢迎提交 Issue 和 Pull Request！

1. Fork 本项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

---

## 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

---

## 更新日志

### v1.2.0 (2026-04)

- 新增 Go Gateway 网关层，统一鉴权与反向代理
- 鉴权只需一次，后端无需重复验证
- 新增基于 IP 的请求限流
- AI 聊天窗口支持移动端适配、全屏切换、尺寸调整

### v1.1.0 (2026-03)

- 新增合同模板库功能
- 新增合同分享功能
- 新增新手引导

### v1.0.0 (2026-01)

- 基础合同上传与 AI 分析
- 风险识别（高/中/低三级）
- 合同要素提取
- AI 智能问答

---

## 联系方式

| 平台 | 链接 |
|------|------|
| Gitee | [@jun-jia-zhang](https://gitee.com/jun-jia-zhang) |
| 邮箱 | zhangjiajun_dev@163.com |


---

<div align="center">

**ContractSense** - 让合同审查更简单

如果这个项目对你有帮助，请给一个 Star 支持！

</div>