ystp/docs/prd.md

产品需求文档（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（压缩后体积占原图比例，数值越小压缩越强，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. 待完成清单（上线前必须定稿）

• 法务页面：隐私政策、服务条款、数据保留与删除说明。（已提供模板，建议上线前法务审核）