Implement compression quota refunds and admin manual subscription

docs/prd.md

@@ -0,0 +1,162 @@
+# 产品需求文档（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. 待完成清单（上线前必须定稿）
+- 法务页面：隐私政策、服务条款、数据保留与删除说明。（已提供模板，建议上线前法务审核）