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