# 技术架构设计

> 目标：支撑“网站 + 对外 API + 计费”的商用闭环。产品范围见 `docs/prd.md`，计费口径见 `docs/billing.md`。

## 系统架构图

```
                       ┌───────────────────────────────┐
                       │ CDN (静态资源/下载可选加速)    │
                       └──────────────┬────────────────┘
                                      │
                               ┌──────▼──────┐
                               │ Nginx/Caddy │
                               │ TLS/反向代理 │
                               └──────┬──────┘
          ┌───────────────────────────┼───────────────────────────┐
          │                           │                           │
          ▼                           ▼                           ▼
 ┌─────────────────┐        ┌─────────────────┐        ┌─────────────────┐
 │ Web 前端 (Vue3) │        │ API 服务 (Axum) │        │ Admin 前端(Vue3)│
 │ 上传/结果/账单   │        │ 认证/计费/接口   │        │ 运营/风控/配置    │
 └─────────────────┘        └───────┬─────────┘        └─────────────────┘
                                    │
                 ┌──────────────────┼──────────────────┐
                 │                  │                  │
                 ▼                  ▼                  ▼
        ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
        │ PostgreSQL (DB) │  │ Redis (缓存/队列)│  │ 对象存储 (S3)    │
        │ 用户/任务/账单/用量│  │ Streams/RateLimit│  │ 原图/压缩结果     │
        └─────────┬───────┘  └───────┬─────────┘  └─────────┬───────┘
                  │                  │                     │
                  │                  ▼                     │
                  │           ┌───────────────┐            │
                  │           │ Worker (Rust) │            │
                  │           │ 压缩/计量/回写  │            │
                  │           └───────────────┘            │
                  │                                        │
                  ▼                                        ▼
        ┌─────────────────┐                      ┌─────────────────┐
        │ 支付渠道/网关     │◄──────Webhooks───────│ API(Webhook处理) │
        │ Stripe           │                      │ 订阅/发票/状态   │
        └─────────────────┘                      └─────────────────┘
```

## 核心组件设计

### 0. 服务拆分（推荐）

为避免 CPU 密集的压缩任务影响 API 延迟，建议最小拆分为：
- **API 服务**：认证、限流、计费/订阅、任务编排、回调、签名 URL、管理后台 API。
- **Worker 服务**：执行图片压缩（CPU 密集）、写入结果、落用量账本、推送进度。

本地开发可以合并进一个进程（feature flag）；生产建议分开部署并可独立扩容。

### 1. 压缩引擎

```rust
// 压缩配置
pub enum CompressionLevel {
    /// 高压缩比 - 有损压缩，文件最小
    High,
    /// 中等压缩 - 平衡模式
    Medium,
    /// 低压缩比 - 无损/近无损，质量优先
    Low,
}

pub struct CompressionConfig {
    pub level: CompressionLevel,
    pub output_format: Option<ImageFormat>,  // 可选转换格式
    pub max_width: Option<u32>,              // 可选调整尺寸
    pub max_height: Option<u32>,
    pub preserve_metadata: bool,             // 是否保留元数据（默认 false）
}
```

### 2. 压缩策略

| 格式 | 高压缩比（有损） | 低压缩比（无损） | 使用库 |
|------|-----------------|-----------------|--------|
| PNG | pngquant 量化到 256 色 | oxipng 无损优化 | `imagequant` + `oxipng` |
| JPEG | mozjpeg quality=60 | mozjpeg quality=90 | `mozjpeg` |
| WebP | lossy quality=75 | lossless | `webp` |
| AVIF | quality=50 | quality=90 | `ravif` |

```rust
// 压缩核心逻辑
pub trait ImageCompressor: Send + Sync {
    async fn compress(&self, input: &[u8], config: &CompressionConfig) -> Result<Vec<u8>>;
    fn supported_formats(&self) -> Vec<ImageFormat>;
}

pub struct PngCompressor;
pub struct JpegCompressor;
pub struct WebpCompressor;
pub struct AvifCompressor;

// 统一压缩入口
pub struct CompressionEngine {
    compressors: HashMap<ImageFormat, Box<dyn ImageCompressor>>,
}

impl CompressionEngine {
    pub async fn compress(&self, input: &[u8], config: &CompressionConfig) -> Result<CompressionResult> {
        let format = detect_format(input)?;
        let compressor = self.compressors.get(&format)
            .ok_or(Error::UnsupportedFormat)?;

        let output = compressor.compress(input, config).await?;

        Ok(CompressionResult {
            original_size: input.len(),
            compressed_size: output.len(),
            format,
            data: output,
        })
    }
}
```

### 3. 任务处理模型

支持两种模式：

#### 同步模式（小文件/单文件）
```
请求 -> 压缩 -> 直接返回结果
```

#### 异步模式（大文件/批量）
```
请求 -> 创建任务 -> 返回任务ID
         ↓
     后台Worker处理
         ↓
     客户端轮询/WebSocket通知
         ↓
     下载结果
```

```rust
pub enum TaskStatus {
    Pending,
    Processing,
    Completed,
    Failed,
}

pub struct CompressionTask {
    pub id: Uuid,
    pub user_id: Option<Uuid>,      // 游客为空
    pub session_id: Option<String>, // 游客会话（Cookie）
    pub status: TaskStatus,
    pub files: Vec<FileTask>,
    pub config: CompressionConfig,
    pub created_at: DateTime<Utc>,
    pub completed_at: Option<DateTime<Utc>>,
}

pub struct FileTask {
    pub id: Uuid,
    pub original_name: String,
    pub original_size: u64,
    pub compressed_size: Option<u64>,
    pub status: TaskStatus,
    pub error: Option<String>,
}
```

### 4. 用户认证系统

```rust
// JWT Claims
#[derive(Serialize, Deserialize)]
pub struct Claims {
    pub sub: Uuid,          // 用户ID
    pub role: UserRole,     // 用户角色
    pub exp: i64,           // 过期时间
}

pub enum UserRole {
    User,
    Admin,
}

// API Key 认证
pub struct ApiKey {
    pub id: Uuid,
    pub user_id: Uuid,
    pub key_prefix: String, // 前缀索引（仅展示用）
    pub key_hash: String,   // 推荐：HMAC-SHA256(key, server_pepper) 或 sha256+pepper
    pub name: String,
    pub permissions: Vec<Permission>,
    pub rate_limit: u32,    // 每分钟请求数
    pub created_at: DateTime<Utc>,
    pub last_used_at: Option<DateTime<Utc>>,
}

pub enum Permission {
    Compress,
    BatchCompress,
    ReadStats,
    BillingRead,   // 查看账单/用量（可选）
    WebhookManage, // 管理 Webhook（可选）
}
```

### 5. 限流与配额（Rate Limit & Quota）

用途区分：
- **限流**：保护服务（超出返回 HTTP `429`）
- **配额**：试用/计费限制（超出返回 HTTP `402` / `QUOTA_EXCEEDED`）

默认建议（最终以 `system_config` + 套餐 `plans.*` 为准）：
- 匿名试用：`10 req/min` + `10 units/day` + `5MB/文件` + `5 文件/批量`
- 登录用户：`60 req/min`；文件大小/批量/保留期/周期额度由套餐决定
- API Key：`100 req/min`（可配置）；文件大小/批量/周期额度由套餐/Key 覆盖决定

### 6. 用量计量与计费（Metering & Billing）

计量口径见 `docs/billing.md`，架构上建议：
- Worker 在每个文件成功输出后写入 `usage_events`（账本明细），并更新 `usage_periods`（按订阅周期聚合）。
- API 在创建任务/接收同步压缩请求时做**配额预检**（快速失败），Worker 做**最终扣减**（账本落地，保证一致性）。
- 对外 API 强烈建议支持 `Idempotency-Key`；DB 侧存储“幂等记录 + 响应摘要”，避免重复扣减与重复任务。

### 7. 支付回调（Webhooks）

Stripe 通常通过 webhook 推送订阅/支付状态变更：
- API 服务提供 `/webhooks/{provider}` 入口，**验签 + 幂等 + 可重放**。
- webhook 事件入库后异步处理（避免回调超时），更新订阅/发票状态，并写审计日志。

## 核心依赖

```toml
[dependencies]
# Web 框架
axum = "0.7"
tokio = { version = "1", features = ["full"] }
tower = "0.4"
tower-http = { version = "0.5", features = ["cors", "fs", "compression"] }

# 图片处理
image = "0.25"
oxipng = "9"
imagequant = "4"           # PNG 有损压缩（pngquant 核心）
mozjpeg = "0.10"           # JPEG 压缩
webp = "0.3"               # WebP 编解码
ravif = "0.11"             # AVIF 编码

# 数据库
sqlx = { version = "0.7", features = ["runtime-tokio", "postgres", "uuid", "chrono"] }

# Redis
redis = { version = "0.24", features = ["tokio-comp"] }

# 认证
jsonwebtoken = "9"
argon2 = "0.5"             # 密码哈希

# 工具
uuid = { version = "1", features = ["v4", "serde"] }
chrono = { version = "0.4", features = ["serde"] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
thiserror = "1"
tracing = "0.1"
tracing-subscriber = "0.3"

# 配置
config = "0.14"
dotenvy = "0.15"
```

## 性能考虑

### 1. 并发处理
- 使用 Tokio 异步运行时
- 图片压缩使用 `spawn_blocking` 避免阻塞异步线程
- 可配置 Worker 线程数

```rust
// 在独立线程池中执行 CPU 密集型压缩
let result = tokio::task::spawn_blocking(move || {
    compress_image_sync(&data, &config)
}).await??;
```

### 2. 内存管理
- 流式处理大文件
- 限制并发压缩任务数
- 压缩完成后立即清理临时文件

### 3. 缓存策略
- Redis 缓存用户会话
- 可选：相同图片哈希缓存结果（去重）

## 安全考虑

1. **输入验证**：检查文件魔数，不仅依赖扩展名
2. **文件大小限制**：防止 DoS
3. **像素/维度限制**：防止“图片炸弹”（解码后超大）
4. **路径遍历防护**：存储时使用 UUID 命名
5. **SQL 注入防护**：使用参数化查询（SQLx 自动处理）
6. **XSS 防护**：前端输出转义
7. **CSRF 防护**：SameSite Cookie + Token
8. **速率限制**：防止滥用
9. **默认移除元数据**：避免泄露定位/设备信息（除非用户明确开启保留）

## 可扩展性

### 水平扩展
```
                    ┌─────────────┐
                    │ Load Balancer│
                    └──────┬──────┘
           ┌───────────────┼───────────────┐
           ▼               ▼               ▼
     ┌──────────┐    ┌──────────┐    ┌──────────┐
     │ API 实例1 │    │ API 实例2 │    │ API 实例3 │
     └──────────┘    └──────────┘    └──────────┘
           │               │               │
           └───────────────┼───────────────┘
                           ▼
                  ┌─────────────────┐
                  │ 共享 PostgreSQL │
                  │ 共享 Redis      │
                  │ 共享 S3 存储    │
                  └─────────────────┘
```

### 后续可添加功能
- 消息队列（RabbitMQ/NATS）处理异步任务
- 分布式任务调度
- CDN 加速下载