# 产品需求文档（PRD）- ImageForge

目标：做一个接近商用的图片压缩网站 + 对外 API + 计费系统（可订阅/可计量）。

> 本文只描述“做什么/做到什么程度”。技术实现细节在 `docs/architecture.md`、`docs/api.md`、`docs/database.md`、`docs/deployment.md`、`docs/ui.md`。

---

## 1. 产品定位

### 1.1 一句话
提供高质量、稳定、可规模化的图片压缩服务：既能让普通用户在网页上批量压缩，也能让开发者通过 API Key 集成到 CI/CD 或业务系统，并按使用量/套餐计费。

### 1.2 核心价值
- **效果**：压缩比与画质控制可预期（可选有损/无损/近无损）。
- **体验**：网站拖拽即用、批量任务、可下载 ZIP、历史可追溯。
- **工程化**：对外 API 稳定、可观测、可限流、可计量、可计费。
- **安全合规**：默认去除隐私元数据、明确保留期限、支持删除。

### 1.3 非目标（明确不做/后做）
- 图像编辑（裁剪/滤镜/水印）不作为核心能力（后续可扩展）。
- CDN 图片处理（按 URL 在线压缩、自动适配）不作为首期必须。
- 视频/动图（GIF/APNG）暂不纳入首期（除非强需求）。

---

## 2. 用户与角色

### 2.1 用户类型
- **游客（Anonymous）**：无需注册即可试用网站压缩（强限制、短保留）。
- **注册用户（User）**：使用网站 + 管理 API Key + 查看用量/发票。
- **企业/团队用户（Team，可选）**：多人协作、共享额度、角色权限（可作为 V1+）。
- **管理员（Admin）**：风控、配置、用户/任务/账单审核、运营数据。

### 2.2 典型场景
- 设计师：批量压缩并打包下载，保留 7 天内历史。
- 开发者：CI 里调用 API，在发布前批量压缩静态资源。
- 运营：导出周期用量、查看节省带宽、按部门拆分账单（团队版）。

---

## 3. 功能范围（按模块）

### 3.1 网站压缩（Web）
- 拖拽/选择图片（单次多文件）。
- 压缩参数：
  - 压缩率：1-100（数值越大压缩越强）。
  - 输出格式：保持原格式。
  - 可选：限制宽高（等比缩放）。
  - 可选：是否保留元数据（默认不保留）。
- 结果展示：
  - 逐文件：原始大小、压缩后大小、压缩率、状态、下载。
  - 汇总：总节省、下载 ZIP、失败文件原因。
- 历史记录：
  - 最近任务列表（可筛选：日期/格式/状态）。
  - 可再次下载（未过期）、或重新发起压缩（使用相同参数）。
- 游客试用：
  - 自动创建匿名会话（Cookie），只允许较小文件/较少数量。
  - 到期自动清理，不提供“历史”永久保存。

### 3.2 对外 API（Developer API）
- API Key：创建/禁用/轮换/权限范围（最小权限）。
- 压缩接口：
  - 同步单图（可返回二进制或下载链接）。
  - 批量/大文件异步任务（任务状态、下载 ZIP）。
  - 可选：Webhook 回调（替代轮询/WS，用于服务端集成）。
- 工程化能力：
  - 幂等（Idempotency-Key），避免重复扣费/重复任务。
  - 配额与用量头信息（本订阅周期已用/剩余/上限）。
  - 速率限制（标准 `Retry-After` + 速率头）。

### 3.3 计费与用量（Billing & Metering）
详见 `docs/billing.md`，PRD 层面要求：
- 具备 **套餐**（Free/Pro/Business）与 **配额**（每订阅周期压缩次数、文件大小/批量上限、保留期等）。
- 具备 **订阅** 生命周期：试用、激活、到期、欠费、取消、恢复。
- 具备 **发票**（Invoice）与 **支付记录**（Payment）可追溯。
- 具备 **用量计量**：以“成功压缩的文件数”为主计量单位（可扩展到字节、转换格式等）。
- 具备 **风控策略**：异常调用/盗刷/滥用限制与告警。

### 3.4 管理后台（Admin）
- 用户管理：冻结/解冻、限流覆盖、手动调整套餐/额度、查看登录/调用记录。
- 任务管理：查看任务队列/失败原因、取消任务、重试。
- 计费管理：查看订阅与发票、手动赠送额度、处理退款（首期可做“手动退款登记”）。
- 系统配置：全局限流、文件限制、保留期、功能开关（注册开关等）。
- 监控面板：QPS、延迟、错误率、队列长度、CPU/内存、S3/DB/Redis 状态。

---

## 4. 套餐与配额（建议默认值，可调）

> 这些是“产品默认建议”，最终可在上线前确认并固化到配置/数据库。

| 项 | Free | Pro | Business |
|---|---:|---:|---:|
| 每周期压缩次数（成功文件数） | 500 | 10,000 | 100,000+ |
| 单文件大小上限 | 5 MB | 20 MB | 50 MB |
| 单次批量上限 | 10 | 50 | 200 |
| 并发（建议） | 2 | 8 | 32 |
| 结果保留期 | 24 小时 | 7 天 | 30 天 |
| API 访问 | ❌ | ✅ | ✅ |
| Webhook | ❌ | ✅ | ✅ |
| SSO/团队 | ❌ | ❌ | 可选 |

周期定义（用于“本周期已用/剩余/重置时间”的展示与扣减）：
- **Pro/Business（付费）**：按 Stripe 订阅周期（`current_period_start` ~ `current_period_end`），不是自然月。
- **Free（未订阅）**：按自然月重置（UTC+8）。

匿名试用（无需登录）：
- 每日 10 次（以成功压缩文件数计，失败不计）
- 日界：自然日（UTC+8），次日 00:00 重置
- 不提供 API Key
- 结果保留 24 小时

计量单位：
- **compression_unit**：每成功压缩 1 个输出文件计 1。
- 对于批量任务：按文件粒度计量；失败文件不计量。
- 幂等：同一个 Idempotency-Key 重试不重复计量。

---

## 5. 关键体验与质量指标（NFR）

### 5.1 性能与稳定性（建议目标）
- 99% 的同步单图压缩在 3s 内完成（小图、常见格式）。
- 批量任务在可预期时间内完成（提供进度/预估）。
- 系统可水平扩展：API 与 Worker 可独立扩容。

### 5.2 安全与合规（必须）
- 默认移除 EXIF 等隐私元数据（可配置允许保留，但需明确提示）。
- 上传内容按保留期自动删除，且支持用户主动删除。
- API Key 仅创建时显示一次；支持轮换与禁用。
- 具备基础风控：IP/账号/API Key 限流、异常突增告警。

---

## 6. MVP / V1 里程碑建议

### MVP（可上线收费的最小闭环）
- 网站压缩（同步 + 批量异步）+ 下载/ZIP + 历史（登录用户）。
- API Key + 同步单图（直接返回二进制）+ 异步批量（任务/下载）。
- 用量计量 + 套餐配额（Free/Pro）+ 订阅（至少一种支付渠道）+ 发票列表。
- 管理后台：用户/任务/配置/用量查看 + 手动赠送额度。

### V1+（商用增强）
- Webhook + SDK（TS/Python/Go）+ OpenAPI 自动生成。
- 团队/组织、多 Key 管理、细粒度权限、IP 白名单。
- 企业发票/税务字段、对公转账/线下支付流程。
- 风控升级：验证码、黑名单、设备指纹、异常画像。

---

## 7. 已确认口径（开工前）
- 支付渠道：Stripe
- 计费策略：硬配额（超额返回 `QUOTA_EXCEEDED` / HTTP 402）
- 配额周期：按订阅周期（非自然月）
- 匿名试用：支持（每日 10 次），不提供 API Key
- Free 套餐 API：不开放（仅 Pro/Business 可创建 API Key）
- 邮件服务：注册需邮箱验证 + 密码重置（SMTP，预置多服务商模板）
- 默认语言：中文

## 8. 待完成清单（上线前必须定稿）
- 法务页面：隐私政策、服务条款、数据保留与删除说明。（已提供模板，建议上线前法务审核）