# omni_parse

**Repository Path**: Vimer_test/omni_parse

## Basic Information

- **Project Name**: omni_parse
- **Description**: 去水印小程序后端服务
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2026-07-16
- **Last Updated**: 2026-10-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# omni_parse

> 去水印小程序后端服务 —— Rust + Axum + PostgreSQL 实现的多平台视频/图集解析、CDK 兑换、操作记录与全局配置中台。

## 项目状态

| 阶段 | 内容 | 状态 |
| :--- | :--- | :--- |
| 阶段 0 | 基础设施（workspace、迁移、Docker、CI） | ✅ 完成 |
| 阶段 1 | MVP 主链路（登录/解析/CDK/记录/配置） | ✅ 完成 |
| 阶段 2 | `omni_extractor` 自研解析引擎替换（9 平台） | ✅ 完成 |
| 阶段 3 M7-A | AI 工具链·图片压缩 + 对象存储抽象 | ✅ 完成 |
| 阶段 3 M7-B | AI 工具链·TTS + AI 文案（外部接口池） | ✅ 完成 |
| 阶段 3 M7-C/D | OCR + 去水印（本地 ONNX） | ✅ 完成 |
| 阶段 4 | 管理后台（SoybeanAdmin + 数据看板 + CDK 批量） | ⏳ 计划中 |
| 阶段 5 | 上线加固（合规 / 监控 / 压测 / 提审） | ⏳ 计划中 |

详见 [docs/03-项目落地计划.md](docs/03-项目落地计划.md)，发版记录见 [CHANGELOG.md](CHANGELOG.md)。

## 技术栈

- **语言**：Rust 1.85+（stable）
- **Web 框架**：Axum 0.7 + Tower
- **数据库**：PostgreSQL 16（SeaORM 1.1 + sea-query builder）
- **缓存**：Redis 7（`ConnectionManager` 异步连接池）
- **对象存储**：MinIO 本地 / 腾讯云 COS 生产
- **鉴权**：jsonwebtoken 9（双套 secret：用户 30 天 / 管理员 7 天）
- **日志**：tracing + tracing-subscriber（env-filter）

## Workspace 结构

```
omni_parse/
├── crates/
│   ├── app/         # HTTP 服务入口 + 路由装配 + handlers
│   ├── core/        # 通用错误码、响应封装、JWT、中间件、AppState
│   ├── config/      # AppConfig + GlobalConfigService（DB+Redis 缓存）
│   ├── user/        # 微信登录、协议同意、用户信息
│   ├── quota/       # 额度查询、CDK 兑换、扣减返还
│   ├── parse/       # 平台识别 + CompositeParser（本地 extractor + 外部接口池）
│   ├── record/      # 操作记录保存/列表/删除/收藏/7天清理
│   ├── media/       # AI 工具（图片压缩/TTS/AI 文案 + 本地 ONNX：OCR、LaMa 去水印）
│   ├── admin/       # 管理后台（阶段 4）
│   ├── migration/   # SeaORM 迁移（13 个，含 seed）
│   └── extractor/   # omni-extractor：Rust 原生视频解析引擎（7 平台，阶段 2）
├── docs/
│   ├── 01-后台需求文档.md
│   ├── 02-视频解析引擎落地文档.md
│   └── 03-项目落地计划.md
├── CHANGELOG.md
├── docker-compose.yml
└── Cargo.toml
```

## 快速开始

### 1. 环境准备

```bash
# 需要 Rust 1.85+ 和 Docker
rustc --version    # rustc 1.85.0+
docker --version   # Docker 24+
```

### 2. 启动依赖服务

```bash
docker compose up -d
# PostgreSQL 16  -> 127.0.0.1:5432
# Redis 7        -> 127.0.0.1:6379
# MinIO          -> 127.0.0.1:9000 (API) / 9001 (控制台)
```

### 3. 配置环境变量

```bash
cp .env.example .env
# 按需修改 WX_APP_ID / WX_APP_SECRET 等
```

### 4. 应用数据库迁移

```bash
cargo run -p omni-migration -- up
# 查看状态: cargo run -p omni-migration -- status
# 重置:    cargo run -p omni-migration -- refresh
```

迁移会创建 10 张业务表 + 预置 global_config 键值 + 4 个测试 CDK 码：
- `TEST-CDK-30D-0001` / `TEST-CDK-30D-0002`（30 天）
- `TEST-CDK-90D-0001`（90 天）
- `TEST-CDK-365D-0001`（365 天）

### 4.5 下载本地 AI 模型（M7-C/D，可选）

OCR 与图片去水印使用本地 ONNX 模型，不进 git。需要时执行：

```bash
bash scripts/fetch_models.sh
# 国内网络可用镜像：HF_ENDPOINT=https://hf-mirror.com bash scripts/fetch_models.sh
```

下载约 215MB 到 `models/`（LaMa 199MB + PP-OCRv4 det/rec + CTC 字典）。
未下载时服务正常启动，对应接口返回「模型未加载」标准错误（模型加载失败不会阻塞启动）。

```bash
# 端到端冒烟（真实模型推理验证）
cargo run -p omni-media --example local_inference_smoke
```

### 5. 启动服务

```bash
cargo run -p omni-app
# 默认监听 0.0.0.0:8080
```

### 6. 验证

```bash
curl http://127.0.0.1:8080/health
# {"code":200,"message":"ok","data":{"status":"up","version":"0.1.0","timestamp":"..."}}
```

## API 路由总表

| 鉴权 | 方法 | 路径 | 说明 |
| :--- | :--- | :--- | :--- |
| 公开 | GET | `/health` | 健康检查 |
| 公开 | GET | `/` | 服务信息 |
| 公开 | POST | `/api/user/login` | 微信小程序登录 |
| 公开 | GET | `/api/config/global` | 全局配置下发 |
| 用户鉴权 | POST | `/api/user/agree` | 同意协议 |
| 用户鉴权 | GET | `/api/user/info` | 用户信息 |
| 用户+协议 | GET | `/api/quota/status` | 额度查询 |
| 用户+协议 | POST | `/api/quota/redeem` | CDK 兑换 |
| 用户+协议 | POST | `/api/parse/single` | 单条解析 |
| 用户+协议 | GET | `/api/record/list` | 记录列表（filter/page/page_size） |
| 用户+协议 | POST | `/api/record/save` | 保存记录 |
| 用户+协议 | POST | `/api/record/delete` | 删除记录 |
| 用户+协议 | POST | `/api/record/favorite` | 收藏/取消 |
| 用户+协议 | POST | `/api/image/compress` | 图片压缩（M7-A，multipart/form-data） |
| 用户+协议 | POST | `/api/image/ocr` | OCR 文案提取（M7-C，本地 PP-OCRv4） |
| 用户+协议 | POST | `/api/image/watermark-remove` | 图片去水印（M7-D，本地 LaMa） |
| 用户+协议 | POST | `/api/audio/tts` | TTS 配音（M7-B） |
| 用户+协议 | POST | `/api/ai/title` | AI 标题生成（M7-B） |
| 用户+协议 | POST | `/api/ai/rewrite` | AI 文案改写（M7-B） |
| 用户+协议 | POST | `/api/ai/script` | AI 脚本创作（M7-B） |
| 公开 | GET | `/static/*` | 静态文件服务（处理后图片/音频，开发期） |

所有响应统一封装：
```json
{ "code": 200, "message": "ok", "data": {} }
```

## 开发

### 代码质量检查

```bash
cargo fmt --all                  # 格式化
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace --lib     # 单元测试（16 个，无需 DB）
```

### 集成测试

集成测试需要 Docker 依赖运行，默认 `#[ignore]`：

```bash
docker compose up -d
cargo test -p omni-app --test api_flow -- --ignored
```

覆盖闭环：
- 普通用户主流程（建用户→同意协议→查额度→保存记录→列表→收藏→删除）
- CDK 兑换流程（兑换→身份升级→重复兑换失败）
- 鉴权失败场景（无 token / 错误 token → 401）
- 全局配置下发（公开接口 + 健康检查）

### 迁移管理

```bash
cargo run -p omni-migration -- up        # 应用所有迁移
cargo run -p omni-migration -- down      # 回滚最新一批
cargo run -p omni-migration -- refresh   # 重置（drop + 重建）
cargo run -p omni-migration -- status    # 查看状态
```

## 关键设计

- **统一错误处理**：`AppError` 枚举（Biz / Db / Redis / Internal）+ `IntoResponse` 自动转 JSON
- **双套 JWT**：用户 30 天 / 管理员 7 天，独立 secret
- **三层中间件**：`auth_user`（JWT 校验）→ `require_agreed`（协议校验）→ handler
- **跨 crate 事务**：CDK 兑换使用 `&impl ConnectionTrait` 支持事务内执行 raw SQL
- **Redis 缓存策略**：解析结果 30 分钟、全局配置 5 分钟、CDK 用户记录永久保留
- **SeaORM 迁移**：使用 sea-query builder API（非 raw SQL），PG 专有语法仅在 GIN 索引和 ON CONFLICT 处用 raw SQL
- **本地解析优先 + 外部接口兜底**：`parse::CompositeParser` 按 `parse_api.provider_type` 分发，本地 `omni_extractor`（provider_type=2）失败时自动降级到外部 HTTP 接口（provider_type=1），对调用方透明
- **本地 ONNX 推理（M7-C/D）**：`media::local` 的 `ModelManager` 启动预加载模型常驻内存，`Semaphore` 限并发；`LocalTools` 编排本地优先、`model_fallback_enabled` 控制外部兜底；推理放 `spawn_blocking`，模型加载失败不阻塞启动

## 文档

- [docs/01-后台需求文档.md](docs/01-后台需求文档.md) - 后端需求规格
- [docs/02-视频解析引擎落地文档.md](docs/02-视频解析引擎落地文档.md) - `omni_extractor` 落地设计
- [docs/03-项目落地计划.md](docs/03-项目落地计划.md) - 整体执行路线图
- [crates/extractor/README.md](crates/extractor/README.md) - `omni-extractor` crate 文档
- [CHANGELOG.md](CHANGELOG.md) - 发版记录

## License

MIT