# Python-24-Steam

**Repository Path**: sanxiadaer/python-24-steam

## Basic Information

- **Project Name**: Python-24-Steam
- **Description**: hello world
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 0
- **Created**: 2026-08-10
- **Last Updated**: 2026-08-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Python-24 Steam · AI 内容审核系统

> **FastAPI + Vue 3 前后端分离的内容安全智能审核平台** — 敏感词规则引擎 + 多模型协同研判，自动给出「通过 / 拦截 / 转人工」结论；审核员多人协同复审，管理员统一维护模型、策略与账号。

本项目为小组课程 / 实训作品，配套文档见 `docs/`（`需求规格说明书.docx`、`技术设计文档.docx`、`通用需求规格说明书.docx`、`接口文档.md` 等）。

---

## 项目介绍

面向**业务接入方**的内容安全智能审核平台。业务用户提交文本 / 图片 / 视频内容，系统通过敏感词规则引擎与多个 AI 模型协同研判，自动得出「通过 / 拦截 / 转人工」结论；审核员对可疑内容进行人工复审（视频多人投票）；管理员在此之上统一维护模型、审核策略与账号。

内置三种角色：

| 角色 | 说明 |
| ---- | ---- |
| **管理员 admin** | 维护 AI 模型、配置审核策略与敏感词库、管理用户 / 审核员账号、查看操作日志与全局统计 |
| **审核员 reviewer** | 处理自动分派到个人的待复审任务（视频多人协同投票），查看审核记录与工作量统计 |
| **业务用户 user** | 自助注册 / 登录，提交内容发起 AI 审核，查看我的任务、管理个人 API 密钥 |

## 功能特性

### AI 智能审核
- **多模型协同**：敏感词规则引擎（RULE）+ 大模型（LLM）+ 图像模型（CV）按审核策略加权 / 取最大聚合出风险分与结论。
- **多维判定**：命中敏感词自动拦截；风险分落入阈值区间自动转人工；文本 / 图片 / 视频三类内容分流处理。
- **批量审核**：业务用户一次提交多条内容，AI 逐条给出建议，支持批量确认。

### 人工复审协作
- **自动分派**：可疑内容由后端按审核员池自动分派（非自领），视频默认多人（3 人）协同审核。
- **多数票判定**：每人一票，按通过 / 拦截票数多数决，平票回退 AI 判定，全程可追溯。
- **个人工作台**：复审队列轮询（scope=all/mine/pool）、违规项目标签（广告引流 / 低俗 / 暴力 / 虚假信息等）、本次会话通过 / 拦截统计。

### 账号与权限
- **注册 / 登录**：bcrypt 密码哈希 + JWT（HS256，默认有效期 2 小时），登录防爆破（连续失败锁定）。
- **双重守卫**：前端按 `meta.roles` 白名单控制页面，后端接口再按角色依赖二次校验。
- **个人 API 密钥**：业务用户申请 / 管理 API 密钥（`/api/v1/api/keys`）。

### 管理后台（admin）
- **账号管理**：用户 / 审核员账号的创建、封禁 / 解封、重置密码、启停与删除。
- **模型管理**：AI 模型注册、启用 / 禁用、阈值调整、敏感词库热加载（reload）。
- **策略管理**：内置策略模板（标准 / 严格文本、图片）与自定义策略的启停、配置（模型权重 + 聚合方式 + 阈值）。
- **操作日志**：管理员关键操作全程留痕，支持按模块 / 关键字检索。

### 看板与体验
- **角色化看板**：管理员全局概览、审核员个人工作量、业务用户任务统计，ECharts 时间趋势柱形图。
- **双主题**：深 / 浅色主题跟随系统并记忆，`html.dark` 运行时全站换肤。

## 技术栈

| 分层 | 技术 | 说明 |
| ---- | ---- | ---- |
| 前端框架 | Vue 3.5 + Vite 8 + Pinia 4 + Vue Router | `<script setup>` Composition API |
| UI 组件 | Element Plus + SCSS | 深 / 浅色双主题，`html.dark` 换肤 |
| 图表 | ECharts | 工作台看板柱形图 / 趋势图 |
| HTTP 客户端 | Axios | 内置 Mock 与真实后端一键切换（`VITE_USE_MOCK`） |
| 后端框架 | FastAPI + Uvicorn + Pydantic v2 | 自带 `/docs` / `/redoc` 文档 |
| 数据库 / ORM | MySQL 8 + SQLAlchemy 2.0 + PyMySQL | 库名 `ai_audit`，10+ 张表 |
| 鉴权 | python-jose（JWT）+ bcrypt | HS256，有效期可配，登录防爆破 |
| AI 审核 | 敏感词规则引擎 + 智谱 LLM + YOLOv8 图像 | 策略化多模型加权聚合 |
| 文件上传 | multipart 分块 + `/static` 静态挂载 | 按年 / 月分目录落盘 `uploads/` |

## 项目结构

```
python-24-steam/
├─ frontend/                      # Vue 3 前端
│  └─ src/
│     ├─ api/                     # axios 接口封装 + Mock
│     ├─ components/              # 图表、主题开关等通用组件
│     ├─ layouts/                 # 侧边栏 / 顶栏 / 主布局
│     ├─ router/                  # 路由 + 角色守卫
│     ├─ stores/                  # Pinia（登录态）
│     ├─ styles/                  # SCSS 全局样式与主题变量
│     ├─ utils/                   # 主题、格式化等工具
│     └─ views/                   # 各角色页面
├─ backend/                       # FastAPI 后端
│  ├─ app/
│  │  ├─ api/v1/                  # REST 路由（auth/dashboard/review/admin/tasks/keys/upload）
│  │  ├─ core/                    # 安全、配置、统一响应与异常
│  │  ├─ crud/                    # 数据访问层
│  │  ├─ models/                  # SQLAlchemy ORM
│  │  ├─ schemas/                 # Pydantic 请求 / 响应模型
│  │  └─ services/                # 业务逻辑（审核 / 模型 / 敏感词 / 统计）
│  ├─ scripts/                    # 建表 / 初始化 / 敏感词导入
│  ├─ uploads/                    # 上传文件存储（.gitignore 排除）
│  ├─ main.py                     # FastAPI 入口
│  └─ schema_v1.0.sql             # 数据库建表脚本
├─ docs/                          # 需求 / 设计 / 接口文档
├─ dev.bat                        # 一键启动脚本
├─ README.md                      # 本文件
└─ README.en.md                   # 英文说明
```

## 环境要求

| 工具 | 版本 | 备注 |
| ---- | ---- | ---- |
| Python | 3.13+ | 建议使用 `venv` 虚拟环境 |
| Node.js | 20.19+ / 22.12+ | Vite 8 要求（推荐 20 LTS / 22 LTS） |
| npm | 9+ | 或 pnpm |
| MySQL | 8.0 | 服务名 `MySQL80`，含数据库 `ai_audit` |

## 快速开始

### 1. 克隆与进入项目
```bash
git clone <your-repo-url>
cd python-24-steam
```

### 2. 初始化数据库
```bash
mysql -u root -p < backend/schema_v1.0.sql
```
脚本会自动创建数据库 `ai_audit` 与全部表，并预置 3 个 AI 模型、3 套审核策略模板及示例敏感词。也可改用 `backend/scripts/` 下的 `create_tables.py` / `init_data.py`。

### 3. 配置并启动后端（端口 8000）
```bash
cd backend
python -m venv .venv
.\.venv\Scripts\Activate.ps1                 # Windows PowerShell；macOS/Linux: source .venv/bin/activate
pip install -r requirements.txt
copy .env.example .env                       # 编辑 .env 填写数据库密码 / JWT 密钥
.\.venv\Scripts\python.exe main.py           # 或 uvicorn main:app --reload --port 8000
```
启动后可访问：
- **Swagger 文档**：http://127.0.0.1:8000/docs
- **Redoc**：http://127.0.0.1:8000/redoc
- **健康检查**：http://127.0.0.1:8000/

### 4. 配置并启动前端（端口 5173）
另开一个终端：
```bash
cd frontend
npm install
npm run dev    # ➜ Local: http://localhost:5173/
```
开发模式下 `vite.config.js` 已将 `/api` 与 `/static` 代理到 `http://127.0.0.1:8000`，无需处理跨域。

### 5. 一键启动（可选）
项目根目录提供 `dev.bat`，自动检测端口并同时拉起前后端两个服务窗口。

### 6. 构建生产版本
```bash
cd frontend
npm run build       # 产物输出到 frontend/dist
npm run preview     # 本地预览构建结果
```

## 使用流程

### 业务用户（user）
1. 注册 / 登录后进入「AI 智能审核」，上传文本 / 图片 / 视频内容提交审核。
2. 在「我的任务」查看审核进度与结果，可对任务 **加急**。
3. 在「API 密钥」创建个人调用密钥；在「工作台概览」查看自己的统计。

### 审核员（reviewer）
1. 由管理员创建的审核员账号登录。
2. 在「人工复审」处理自动派发的待审任务，选择通过 / 拦截并标记违规标签。
3. 在「审核记录」回顾历史判定；工作台查看本次会话通过 / 拦截统计。

### 管理员（admin）
1. 使用预置管理员账号（admin / admin123）登录。
2. 在「模型管理 / 审核策略」配置审核链路与阈值，在「敏感词库」维护规则引擎词库。
3. 在「用户账号 / 审核员账号」维护人员与权限，在「操作日志」审计关键操作。
4. 在「工作台概览」查看全局统计。

> 开发环境默认开启前端 Mock（`VITE_USE_MOCK=true`），登录注册等接口走模拟数据；生产（`npm run build`）默认关闭 Mock，对接真实后端。

## API 速查

> 统一响应格式：`{ "code": 0, "message": "ok", "data": {...} }`。「鉴权」列 = 是（登录）/ 管理员 / 审核员。需鉴权接口在请求头携带 `Authorization: Bearer <token>`。

### 认证
| 方法 | 路径 | 鉴权 | 说明 |
| ---- | ---- | ---- | ---- |
| POST | `/api/v1/auth/register` | 否 | 业务用户自助注册 |
| POST | `/api/v1/auth/login` | 否 | 登录，返回 JWT |

### 看板
| 方法 | 路径 | 鉴权 | 说明 |
| ---- | ---- | ---- | ---- |
| GET | `/api/v1/dashboard/overview` | 是 | 按角色返回工作台统计概览 |

### AI 审核 / 人工复审（review）
| 方法 | 路径 | 鉴权 | 说明 |
| ---- | ---- | ---- | ---- |
| POST | `/api/v1/review/ai` | 是 | AI 智能审核（敏感词规则引擎） |
| POST | `/api/v1/review/ai/confirm` | 是 | AI 批量确认审核 |
| POST | `/api/v1/review/audit` | 审核员 | 人工复审（视频多人多数票） |
| GET | `/api/v1/review/queue` | 审核员 | 复审队列分页（scope=all/mine/pool） |
| GET | `/api/v1/review/violation-types` | 审核员 | 视频违规项目可选项 |
| GET | `/api/v1/review/records` | 审核员 | 我的审核记录 |
| GET | `/api/v1/review/session-count` | 审核员 | 本次会话已审核数 |
| GET | `/api/v1/review/session-pass-block` | 审核员 | 本次会话通过 / 拦截统计 |
| POST | `/api/v1/review/queue/clear` | 审核员 | 清空已审任务 |

### 我的任务（tasks）
| 方法 | 路径 | 鉴权 | 说明 |
| ---- | ---- | ---- | ---- |
| GET | `/api/v1/tasks` | 是 | 我的任务（分页 / 筛选 / 排序） |
| GET | `/api/v1/tasks/{id}` | 是 | 任务详情 |
| PATCH | `/api/v1/tasks/{id}/urgent` | 是 | 加急 / 取消加急 |

### 管理员（admin）
| 方法 | 路径 | 鉴权 | 说明 |
| ---- | ---- | ---- | ---- |
| GET / POST | `/api/v1/admin/accounts` | 管理员 | 账号查询 / 创建 |
| PUT | `/api/v1/admin/accounts/{id}` | 管理员 | 更新账号 |
| POST | `/api/v1/admin/accounts/{id}/ban` · `unban` | 管理员 | 封禁 / 解封 |
| POST | `/api/v1/admin/accounts/{id}/reset-password` | 管理员 | 重置密码 |
| PATCH | `/api/v1/admin/accounts/{id}/status` | 管理员 | 修改状态 |
| DELETE | `/api/v1/admin/accounts/{id}` | 管理员 | 删除账号 |
| GET / POST | `/api/v1/admin/reviewers` | 管理员 | 审核员列表 / 创建 |
| GET / POST | `/api/v1/admin/models` | 管理员 | 模型查询 / 创建 |
| POST | `/api/v1/admin/models/{id}/toggle` | 管理员 | 启用 / 禁用 |
| DELETE | `/api/v1/admin/models/{id}` | 管理员 | 删除模型 |
| POST | `/api/v1/admin/models/{id}/reload` | 管理员 | 重载模型（敏感词库热加载） |
| GET / POST | `/api/v1/admin/strategies` | 管理员 | 策略查询 / 创建 |
| PATCH | `/api/v1/admin/strategies/{id}/status` | 管理员 | 策略启停 |
| PUT | `/api/v1/admin/strategies/{id}/config` | 管理员 | 更新策略配置 |
| DELETE | `/api/v1/admin/strategies/{id}` | 管理员 | 删除策略（预置不可删） |
| GET | `/api/v1/admin/logs` | 管理员 | 操作日志（按模块 / 关键字） |

### 个人 API 密钥（keys）
| 方法 | 路径 | 鉴权 | 说明 |
| ---- | ---- | ---- | ---- |
| GET / POST | `/api/v1/api/keys` | 是 | 密钥列表 / 创建 |
| PUT | `/api/v1/api/keys/{id}` | 是 | 重命名密钥 |
| DELETE | `/api/v1/api/keys/{id}` | 是 | 删除密钥 |

### 上传
| 方法 | 路径 | 鉴权 | 说明 |
| ---- | ---- | ---- | ---- |
| POST | `/api/v1/upload` | 是 | 上传文件（multipart，≤100MB），返回 /static URL |

> 完整请求 / 响应 Schema 见 Swagger `/docs` 或 `docs/接口文档.md`。

## 环境变量（`backend/.env`）

```dotenv
# ===== 数据库（MySQL）=====
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=你的数据库密码
DB_NAME=ai_audit

# ===== JWT =====
JWT_SECRET_KEY=请替换为≥32位的随机密钥
JWT_ALGORITHM=HS256                       # 签名算法
ACCESS_TOKEN_EXPIRE_SECONDS=7200          # Token 有效期，默认 2 小时

# ===== 登录防爆破 =====
MAX_LOGIN_ATTEMPTS=5
LOCK_MINUTES=30
```

前端数据源切换（`frontend/.env.development` / `.env.production`）：

```dotenv
VITE_USE_MOCK=true            # true=Mock 数据，false=对接真实后端
VITE_API_BASE_URL=/api/v1     # 接口基础路径
```

## 开发小贴士

1. **Mock 切换**：开发环境默认 `VITE_USE_MOCK=true`，登录注册等走模拟数据；生产（`npm run build`）默认关闭 Mock。
2. **调试审核**：后端启动日志会打印敏感词加载数量；DevTools → Network 观察 `/api/v1/review/ai` 等请求。
3. **双重守卫**：前端 `router/guards.js` 用 `meta.roles` 拦截无权限页面，后端再用角色依赖二次校验。
4. **Token 有效期**：默认 2 小时，可用 `ACCESS_TOKEN_EXPIRE_SECONDS` 调整。
5. **上传目录**：文件落在 `backend/uploads/yyyy/MM/`，经 `/static` 访问；`uploads/` 已在 `.gitignore` 中。
6. **UTF-8 编码**：Windows 下请确保 `.py` / `.js` / `.vue` 源文件为 UTF-8，避免 GBK 乱码或编译报错。

## 常见问题

**Q: 登录后接口返回 401 / Token 失效？**
A: Token 默认有效期 2 小时；请重新登录获取新 Token，并确认请求头为 `Authorization: Bearer <token>`。

**Q: MySQL 连接失败？**
A: 确认 MySQL 服务（`MySQL80`）已启动、`backend/.env` 中 `DB_PASSWORD` 正确、且已导入 `schema_v1.0.sql`。

**Q: AI 审核结果为空或提示「无有效模型」？**
A: 确认数据库 `ai_model` 表存在启用状态的模型（建表脚本已预置 3 个），且策略配置引用了正确的 `model_id`。

**Q: 上传没反应？**
A: 上传需登录（JWT）；确认已登录、`/static` 代理已配置、文件不超过 100MB。

**Q: 深浅色主题不生效？**
A: 主题跟随系统（`prefers-color-scheme`）并记忆在 localStorage；手动切换后以手动为准。

## 参与贡献

1. Fork 本仓库
2. 新建 `Feat_xxx` 分支
3. 提交代码
4. 新建 Pull Request

## License

本项目仅用于学习与课程实训演示，具体授权方式请团队另行确定。