# compliance-testing

**Repository Path**: zhengxingne/compliance-testing

## Basic Information

- **Project Name**: compliance-testing
- **Description**: 质量检测工具
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-12
- **Last Updated**: 2026-01-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 合规检测工具 (Compliance Tool)

一个基于FastAPI + React的智能合规检测系统，支持ZIP文件目录结构验证、文件内容智能分析和Word报告导出。

## 功能特性

### ✅ 核心功能
- **ZIP文件检测** - 自动解压并验证目录结构
- **实时进度监控** - WebSocket实时推送检测进度（5个步骤）
- **智能内容分析** - 使用LLM分析文件内容合规性
- **Word报告导出** - 一键生成专业的检测报告文档
- **并发处理** - 支持批量文件同时检测

### 🎯 检测流程

```
步骤1: 解压 ZIP 文件 (30%)
  └─ 上传文件并自动解压

步骤2: 检查目录结构 (60%)
  └─ 验证是否符合标准目录要求
  └─ 识别缺少/多余的目录

步骤3: 检查目录内容 (70%)
  └─ 检测空目录
  └─ 统计文件数量

步骤4: 验证目录文件内容 (85%)
  └─ 客户档案验证（关键字匹配）
  └─ 客户互动信息验证（LLM分析）
  └─ 商机截图验证（LLM视觉识别）

步骤5: 检测完成 (100%)
  └─ 综合评分（0-100分）
  └─ 生成检测报告
```

### 📊 评分算法

```python
基础分数 = 100 - (空目录数 × 5)
验证通过率 = 有效目录数 / 总目录数
最终分数 = 基础分数 × 0.5 + 验证通过率 × 100 × 0.5
```

## 技术栈

### 后端
- **FastAPI** - 现代化的Python Web框架
- **WebSocket** - 实时双向通信
- **httpx** - 异步HTTP客户端
- **python-docx** - Word文档生成
- **Pillow** - 图片处理（自动压缩）
- **Google Gemini 3 Flash** - AI模型（via OpenRouter）

### 前端
- **React 18** - UI框架
- **TypeScript** - 类型安全
- **Vite** - 快速构建工具
- **Tailwind CSS** - 样式框架
- **Lucide React** - 图标库

## 快速开始

### 环境要求
- Python 3.8+
- Node.js 18+
- pnpm (推荐) 或 npm

### 1. 安装依赖

**后端**:
```bash
pip install -r requirements.txt
```

**前端**:
```bash
cd web
pnpm install
```

### 2. 配置环境变量

创建 `.env` 文件：
```bash
# AI模型配置
OPENROUTER_API_KEY=your_api_key_here
OPENROUTER_VL_MODEL=google/gemini-3-flash-preview

# 图片处理
IMAGE_MAX_WIDTH=1024
IMAGE_QUALITY=85

# 服务端口
PORT=8000
```

### 3. 启动服务

**后端**:
```bash
python main.py
# 或
uvicorn app.main:app --reload --port 8000
```

**前端**:
```bash
cd web
pnpm dev
```

访问: `http://localhost:5173`

## 使用指南

### 1. 上传文件
- 点击"选择文件"或拖拽ZIP文件到上传区域
- 支持最大1GB的ZIP文件

### 2. 开始检测
- 点击"开始检测"按钮
- 实时查看5个步骤的进度
- 点击步骤卡片查看详细信息

### 3. 下载报告
- 检测完成后，点击"下载报告"按钮
- 自动下载Word格式的检测报告
- 报告包含完整的检测结果和详细分析

## 目录结构

```
├── app/                          # 后端代码
│   ├── api/                      # API路由层
│   │   ├── document_routes.py    # 文档处理
│   │   ├── image_routes.py       # 图片处理
│   │   ├── websocket_routes.py   # WebSocket检测
│   │   ├── directory_routes.py   # 目录验证
│   │   └── report_routes.py      # 报告生成 ⭐新增
│   ├── services/                 # 业务逻辑层
│   │   ├── document_service.py
│   │   ├── image_service.py
│   │   ├── ocr_service.py
│   │   ├── directory_validation_service.py
│   │   └── report_service.py     # 报告服务 ⭐新增
│   ├── config.py
│   └── main.py
├── web/                          # 前端代码
│   ├── src/
│   │   ├── components/
│   │   │   └── compliance/
│   │   │       ├── CheckSteps.tsx
│   │   │       ├── FileUploadCard.tsx
│   │   │       └── ...
│   │   ├── hooks/
│   │   │   └── useZipCheckWebSocket.ts
│   │   ├── views/
│   │   │   └── Compliance.tsx    # 主界面（含下载按钮）⭐更新
│   │   └── ...
│   └── ...
├── docs/                         # 文档
│   ├── compliance-tool-requirements.md
│   └── report-feature.md         # 报告功能文档 ⭐新增
├── requirements.txt
└── README.md
```

## API文档

### WebSocket API

**连接**: `ws://localhost:8000/ws/zip-check/{extract_id}`

**消息格式**:
```json
{
  "step": 1-5,
  "status": "pending|processing|completed|warning|error|skipped",
  "title": "步骤标题",
  "message": "详细消息",
  "progress": 0-100,
  "data": {...}
}
```

### REST API

**生成报告**: `POST /report/generate`

请求体:
```json
{
  "file_name": "项目.zip",
  "file_size": 5242880,
  "score": 85,
  "steps_data": [...]
}
```

响应: Word文档文件流

## 扩展开发

### 添加新的目录类型验证

1. **配置目录类型** (`app/services/directory_validation_service.py`):
```python
DIRECTORY_TYPES["新类型"] = {
    "required_files": {
        "文件模式": {"extensions": [".ext"], "fuzzy": True}
    },
    "validators": {
        "文件模式": "validate_xxx"
    }
}
```

2. **实现验证器**:
```python
@staticmethod
async def validate_xxx(file_path: Path) -> Tuple[bool, str, Dict]:
    # 验证逻辑
    return is_valid, message, details
```

3. **自动集成** - 无需修改其他代码，系统自动调用

详见: [AGENTS.md](./AGENTS.md)

## 性能指标

- **文件上传**: 支持最大1GB
- **检测速度**: 
  - 目录结构检查: < 1秒
  - 文件内容验证: 5-10秒（取决于LLM响应）
  - 报告生成: < 1秒
- **并发支持**: 多文件同时检测
- **报告大小**: 通常30-50KB

## 故障排查

### 后端问题

**LLM调用失败**:
- 检查 `OPENROUTER_API_KEY` 是否配置
- 验证API余额是否充足
- 系统会自动降级到关键词匹配

**文件解压失败**:
- 检查ZIP文件是否损坏
- 验证文件大小是否超限

### 前端问题

**WebSocket连接失败**:
- 确认后端服务已启动
- 检查端口是否被占用
- 查看浏览器控制台错误

**报告下载失败**:
- 检查后端 `/report/generate` 端点
- 验证浏览器是否阻止下载

## 贡献指南

欢迎提交Issue和Pull Request！

## 许可证

MIT License

## 更新日志

### v0.3.0 (2026-01-13) ⭐最新
- ✨ 新增Word报告导出功能
- ✨ 添加下载按钮UI
- 📝 完善文档说明

### v0.2.0
- ✨ WebSocket实时检测
- ✨ 5步骤检测流程
- ✨ LLM智能分析

### v0.1.0
- 🎉 初始版本
- ✨ 基础目录结构检测