# AIEditorRSP Product Contract + Acceptance Checklist

- task_id: t_4a630234
- owner: 墨策
- site: https://aieditorrsp.net/
- repo: /root/projects/aieditorrsp
- source brief: /root/.hermes/reports/aieditorrsp-product-closeout-20260604/owner-feedback-brief.md
- generated_at: 2026-06-04

## 0. PM verdict

🟡 CONDITIONAL GO。

当前站点已经具备“上传 → prompt → generate → result/action”的产品骨架，但还不能算完整上线闭环。Owner 点名的问题必须按 P0 合同修完后，才允许进入墨测 Re-QA 和墨投 paid readiness。

最大风险不是功能不存在，而是状态不完整：未登录、Free 可用、Free 耗尽、Pro/paid、loading/error、logout、checkout 跳转、数据上报没有统一状态机，导致用户不知道自己是谁、还能用几次、下一步该付费还是登录。

## 1. 当前实测与代码审查事实

### 已验证存在

- 生产 URL 可访问：`/`、`/pricing`、`/prompt-library`、`/ai-photo-prompt-editor` 均返回 200。
- `/api/credits` 返回 200 JSON，包含 authenticated、plan、daily_limit、free_remaining、paid_remaining、remaining、paid_enabled、checkout、recommended_actions。
- `/api/auth/logout` 已存在，GET 会清 session cookie 并 302 回 return_to，POST 返回 `{ ok: true }`。
- 首页工具区已有上传控件、prompt textarea、style prompt、Generate button、result status。
- `ProductPreviewEditor.tsx` 已实现上传后本地 preview URL、file meta、Remove image、生成 loading、成功 result preview、Download/Open/Copy/Try another/Edit prompt。
- quota error 下已出现 Upgrade / Buy credit pack / Sign in action card。
- Prompt Library 页面已有 Copy prompt / Apply to editor，并通过 localStorage + 跳转到 `/ai-photo-prompt-editor`。
- Layout 已挂 Plausible、GA4、Clarity 的条件脚本和 `trackAieRsp` bridge。

### 当前仍不满足 Owner P0 的点

- Header 没有可发现 logout。登录后 `AuthStatusLink` 只进入 `/pricing`，未提供 Logout / Account menu / Manage billing 的明确动作。
- Header 右上角状态机不完整：anonymous 时显示 `Sign in + 0 free edits left`，但没有同屏 Upgrade/Pricing 强 CTA；free_exhausted 状态没有独立视觉处理。
- `AuthStatusLink` 没有 loading/error UI。credit fetch 失败时仍默认为 Sign in，用户无法知道是未登录还是状态读取失败。
- Pro/paid 状态没有明确“Pro badge / renewal / manage / logout”组合，只显示 plan + credits + Upgrade/Billing。
- 首页首屏桌面 1366x768 实测：hero section 高约 745px，editor console 左侧占约 600px、高约 631px。首屏工具区仍压过文案，工具卡密度高，style prompt + result status 仍在首屏内制造纵向负担。
- 移动端实测：首屏直接进入大型 console，Hero 文案弱，Prompt Templates/How it works 以下内容过长；账户状态只能通过 menu 进入，不利于付费路径。
- Analytics bridge 当前事件名为 `tool_start` / `tool_result` / `pricing_cta_click`，没有完全覆盖 brief 要求的 upload_image、generate_click、generate_success、quota_exhausted、pricing_click、checkout_start、logout_click、login_success。
- 数据/投放 readiness 仍依赖后台可查，不得仅凭前端脚本判定通过。

## 2. Product principle

产品主路径必须被设计成一个明确闭环：

```text
find prompt
  → upload image
  → see source preview
  → generate preview
  → see result preview
  → download / copy prompt / try another
  → if quota blocked: sign in / upgrade / buy credits / pricing / checkout
```

任何状态下，用户都必须能回答 4 个问题：

1. 我现在是否登录？
2. 我现在是什么 plan / 还有多少 credits？
3. 我下一步能不能生成？
4. 如果不能，我该登录、升级、买 credits，还是等待错误恢复？

## 3. Global state machine

### 3.1 State definitions

#### anonymous

触发条件：`credits.authenticated=false`。

必须展示：
- Header：Sign in + Free credits badge + Pricing/Upgrade CTA。
- Editor：可使用 free quota；Generate 前不强登录。
- Pricing：明确“Sign in required before checkout”。
- 如果 `free_remaining=0`，自动进入 `free_exhausted` 视觉状态，而不是普通 anonymous。

允许动作：
- Sign in
- View pricing
- Generate if free_remaining > 0
- Upgrade / Buy credits：若未登录，先走 Google login，return_to checkout/pricing。

禁止：
- 只显示 Sign in，不显示 credits/upgrade。
- 把 anonymous free quota 文案写成“无限免费”。

#### free_ok

触发条件：`authenticated=true` 且 `plan=free` 且 `remaining>0`。

必须展示：
- Header：avatar/initials + Free plan + remaining credits + Upgrade CTA + Account menu。
- Account menu：Manage account / Pricing / Logout。
- Editor：Generate 可用；生成成功后刷新 credits。

允许动作：
- Generate
- Upgrade to Pro
- Buy credit pack
- Logout

#### free_exhausted

触发条件：`remaining=0` 或 API 返回 `FREE_QUOTA_USED` / `LOGIN_REQUIRED`。

必须展示：
- Header：Free exhausted badge + Upgrade button。
- Editor result area：quota action card，标题必须是行动导向，例如 `Credits needed to continue`。
- Action card 按状态展示：
  - anonymous：Sign in / Upgrade to Pro / View pricing
  - signed-in free：Upgrade to Pro / Buy credit pack / View pricing
- CTA 必须是真按钮，不得只有说明文字。

必须埋点：
- `quota_exhausted`
- `pricing_click`
- `checkout_start`（进入 checkout route 时）

#### pro_paid

触发条件：`authenticated=true` 且 `plan in [pro, paid, monthly, yearly]` 或 `paid_remaining>0`。

必须展示：
- Header：avatar/name/email + Pro/Paid badge + total credits + Manage + Logout。
- Editor：Generate 可用；结果区不显示 Upgrade 主 CTA，只保留次级 Buy credits 或 Manage billing。
- Pricing：当前 plan 高亮；避免继续强推同一 plan。

#### loading

触发条件：credits/auth/me/checkout 状态请求中，或 generate pending。

必须展示：
- Header skeleton：固定宽度，不跳动，不把 Sign in 当默认状态。
- Editor：Generate button disabled，显示 progress/status，防重复提交。
- Result area：明确 1/3、2/3、3/3 或同等状态。

禁止：
- loading 期间重复点击 generate 触发多次请求。
- credits loading 时把状态误展示为 anonymous。

#### error

触发条件：credits/auth/generate/checkout 请求失败、provider unavailable、backend unavailable。

必须展示：
- Header：`Account state unavailable` 小型错误状态 + Retry，不要伪装成 Sign in。
- Editor：错误 code + 人类可读解释 + next action。
- Provider error：说明“未扣 credits / no credits charged before usable provider result”。
- Checkout error：回到 pricing，并展示具体 plan/action。

必须埋点：
- `account_state_error`
- `generate_error`
- `checkout_error`

## 4. P0 acceptance checklist

P0 必须全部通过，否则不得进入 paid readiness。

### P0-A. Header account / membership / credits / upgrade state machine

验收标准：
- anonymous：Header 同屏可见 Sign in、free credits、Pricing/Upgrade。若 free=0，显示 `0 free edits left` + 强 Upgrade/Pricing CTA。
- free_ok：Header 显示用户身份、Free plan、remaining credits、Upgrade button。
- free_exhausted：Header 显示 quota exhausted 状态，Upgrade 不只是文字链接，要是高优先级按钮。
- pro_paid：Header 显示 Pro/Paid badge、credits、Manage/Account、Logout。
- loading：Header 有 skeleton，不跳动，不误判为 anonymous。
- error：Header 有 `Account unavailable` + retry/refresh，不伪装成 Sign in。
- mobile：Menu 内同样覆盖以上状态，不能只保留 desktop。

### P0-B. Logout

验收标准：
- 登录状态下 desktop 和 mobile 都能发现 Logout。
- 点击 Logout 调 `/api/auth/logout` 或同等 route。
- 登出后 session cookie 清空，UI 回到 anonymous，credits 刷新，受保护 entitlement 不再显示。
- 埋点 `logout_click` 发出。
- Logout 不应藏在 pricing 页面深处。

### P0-C. Free quota exhausted paid CTA

验收标准：
- API 返回 `FREE_QUOTA_USED` / `LOGIN_REQUIRED` 时，result area 必须出现 action card。
- anonymous action：Sign in、View pricing、Upgrade to Pro。
- signed-in free action：Upgrade to Pro、Buy credit pack、View pricing。
- CTA 点击路径最终进入 login/pricing/checkout，不得死链。
- 文案必须说清“继续生成需要登录/升级/买 credits”。
- 埋点覆盖 `quota_exhausted`、`pricing_click`、`checkout_start`。

### P0-D. Upload source image preview

验收标准：
- 选择 JPG/PNG/WebP 后，工具区立即展示源图缩略图。
- 展示 filename、size、type。
- Replace image 可重新选择。
- Remove image 可清空 preview/file/status。
- 生成中禁止 remove/replace 或给出明确 disabled。
- 移动端缩略图不能撑爆首屏。
- 埋点 `upload_image`，props 至少含 file_type、file_size_bucket、surface。

### P0-E. Result preview / download / copy / retry

验收标准：
- 生成成功后 inline 展示 result preview image。
- 同区可见 Download image、Open full size、Copy prompt、Try another style、Edit prompt。
- Download 指向可下载/可打开的 URL。
- Copy prompt 成功有反馈。
- 失败时显示错误 code、说明、下一步，不得空白。
- 埋点 `generate_click`、`generate_success`、`generate_error`。

### P0-F. First-screen tool ratio

验收标准：
- Desktop 1366/1440/1280：Hero 文案和工具区左右平衡。工具区不能高到压掉首屏主要价值说明。
- Desktop 首屏必须同时可见：H1、subhead、primary CTA、上传入口、prompt textarea、Generate、基础 account/credits 状态。
- Style prompt 选择可保留，但不得让首屏工具区超过视觉重心；可改成横向紧凑 chips 或折叠。
- Result status 初始态必须紧凑，不需要大卡占位。
- Mobile 390/430：先看到价值承诺 + 上传/Generate 主路径；不要让 console 风格装饰占满首屏。

### P0-G. Prompt Library → editor

验收标准：
- 每张 prompt card 有 Copy prompt 和 Apply to editor。
- Apply 后进入 editor，textarea 自动填充对应 prompt。
- Editor 里有“from library”的来源状态或 selected template 反馈。
- Copy 成功有 visible toast/状态。
- 埋点 `prompt_copy`、`prompt_apply_to_editor`。

### P0-H. Data / paid readiness product dependencies

验收标准：
- 所有产品 CTA 都有稳定 selector / data attribute，便于 QA 和埋点验证。
- 核心事件名统一：
  - `page_view`
  - `login_success`
  - `logout_click`
  - `upload_image`
  - `prompt_copy`
  - `prompt_apply_to_editor`
  - `generate_click`
  - `generate_success`
  - `generate_error`
  - `quota_exhausted`
  - `pricing_click`
  - `checkout_start`
- GA4/Plausible/Clarity 只要任一后台不可查，数据链路写 partial，不得声明 paid ready。
- 投放前必须能追踪从 ad click / UTM 到 pricing/checkout 的路径。

## 5. P1 acceptance checklist

P1 不阻止 Re-QA，但阻止 Scale/paid spend。

- Pricing 页面按当前 account state 高亮：anonymous、free、pro_paid 不同 CTA。
- Checkout 前置页解释 Stripe、credits、refund、provider failure 不扣 credit。
- Result preview 增加 before/after 对照或 source/result 并排。
- Prompt Library 支持 search/filter 后仍能 apply 到 editor，并保留 query/category 信息进入埋点。
- Header Account menu 增加 receipt/billing/account links，如果后端暂未支持，要清楚标 `Manage billing` / `Contact support`。
- Mobile sticky bottom CTA：Upload/Generate/Pricing 根据状态切换。
- Error copy 区分 provider_not_configured、network_error、quota、unsafe_prompt、file_too_large。

## 6. P2 acceptance checklist

P2 可后续迭代。

- Prompt templates 增加“best for / preserves / avoid”结构化字段，并在 editor 内可编辑。
- 增加 saved prompt history，但默认不保存用户图片。
- 增加 result share/copy link，但必须先完成权限和隐私边界。
- 增加 pricing FAQ 的 paid readiness 解释和 ad landing variant。
- 增加 onboarding checklist：upload → generate → download → upgrade。

## 7. Downstream interfaces

### 给墨影 UX/视觉

交付要求：
- Header account component 的 6 状态视觉稿：anonymous/free_ok/free_exhausted/pro_paid/loading/error。
- Desktop + mobile 两套 header/account/menu 状态。
- Quota exhausted action card。
- Upload preview card。
- Result preview/action card。
- 首页首屏比例重排方案：1366/1440/1280 + 390/430。

验收：
- 一屏内能看清身份、额度、主任务、下一步 CTA。
- Upgrade 是按钮级视觉，不是普通文字。
- Logout 可发现但不抢主 CTA。

### 给墨枢 Auth / entitlement / checkout 数据合同

必须确认/补齐：
- `/api/credits` 返回字段稳定：authenticated、user/account、plan、daily_limit、free_remaining、paid_remaining、remaining、paid_enabled、checkout、recommended_actions、state。
- 建议新增 `state` 枚举：anonymous/free_ok/free_exhausted/pro_paid/loading/error。
- `/api/auth/logout` GET/POST 可用，清 cookie 后返回正确 return_to。
- Checkout route 对 anonymous：先 login 再回 checkout/pricing；对 signed-in：创建 Stripe session。
- Checkout start 必须可埋点或在 route 前触发 client event。
- 不做真实卡支付测试；live payment 需孟健确认。

### 给墨界 Frontend implementation

必须实现：
- Header AccountState component，覆盖 6 状态和 mobile menu。
- Logout button/link + click tracking + refresh credits。
- Quota exhausted card 强 CTA。
- Upload preview + meta + replace/remove。
- Result preview + download/copy/try another/edit。
- Prompt Library apply-to-editor 自动填充 textarea。当前 localStorage 写入后，editor 必须读取并清理/标注来源。
- 核心事件统一命名，补 data attributes。
- 首屏工具区压缩：style strip/result idle/status 改紧凑，降低 initial console 高度。

验收命令：
- `npm run build`
- production smoke: `/` `/pricing` `/prompt-library` `/ai-photo-prompt-editor` `/api/credits`
- Browser smoke: desktop 1366/1440/1280，mobile 390/430。

### 给墨测 QA

必须按真实用户任务验收，不只看页面存在：

1. anonymous with free_remaining>0：上传图片 → 看到 source preview → generate → loading disabled → result/或 provider error。
2. anonymous with free_remaining=0：generate → quota card → Sign in/Pricing/Upgrade 可达。
3. signed-in free_ok：Header 身份/credits → generate → credits refresh → logout。
4. signed-in free_exhausted：Header exhausted + upgrade CTA → checkout/login path。
5. pro_paid：Header Pro/Paid + credits + Manage + Logout；不再主推同 plan。
6. prompt library：copy prompt + apply to editor，textarea 正确填充。
7. mobile 390/430：首屏主任务可完成，menu 内账号状态可用。
8. analytics：确认事件发出，不要求所有后台实时入账，但要区分脚本/网络/API/dashboard。

### 给墨投 Paid readiness

NO_GO spend until all conditions pass:

- P0-A/B/C/D/E/F/G/H 全部通过。
- GA4 可查 page_view + core events。
- Plausible stats 可查或精确 blocker 已解除。
- Clarity dashboard 可查 session/recording 或精确 blocker 已解除。
- GSC/Bing/Ahrefs Site Audit 基础状态不阻塞 ad landing。
- UTM ledger 可追踪 ad click → editor/pricing/checkout_start。
- Pricing/checkout/legal/refund copy 已通过合规基本检查。

允许动作：
- 输出 paid readiness verdict。
- 输出小额测试前置清单。

禁止动作：
- 启动广告。
- 改预算。
- 真实花费。
- 真实卡支付。

## 8. Required implementation sequence

1. 墨影：先给 account/header + quota/result/upload/first-screen 的视觉状态稿。
2. 墨枢：确认 auth/logout/credits/checkout 数据合同。
3. 墨界：按合同实现，commit/push/deploy。
4. 墨析/墨引：补 GA4/GSC/Bing/Ahrefs/Plausible/Clarity/UTM 证据。
5. 墨测：按 8 条真实用户任务 Re-QA。
6. 墨投：只在 P0 + 数据链路通过后给 paid readiness；不花钱。

若为了速度并行：墨枢数据合同可与墨影视觉并行；墨界代码必须等二者至少给出可实现口径，避免返工。

## 9. NOT-DO / safety boundary

- 不做真实广告花费。
- 不做真实卡支付。
- 不对外发布外链/社区内容。
- 不 drop/delete 生产 D1 数据。
- 不承诺无限生成。
- 不承诺 perfect face/product preservation。
- 不默认保存用户上传图片或 prompt history，除非隐私和权限边界明确。
- 不把前端脚本存在当作 GA4/Plausible/Clarity 后台数据已通过。

## 10. Final product acceptance gate

只有同时满足以下条件，墨策才给产品闭环 GO：

- P0-A 到 P0-H 全部通过。
- 生产 smoke 通过。
- Header 6 状态有 desktop/mobile 证据。
- Upload/source preview 和 result preview 有截图证据。
- Logout 有真实点击证据。
- Free exhausted CTA 有真实错误态或 mock 状态证据。
- Prompt Library apply-to-editor 有浏览器证据。
- 数据事件发出证据齐全，后台可查状态由墨析单独判定。

结论：当前合同不是“建议清单”，是下游验收闸门。任何实现若缺 logout、缺状态机、缺 quota 强 CTA、缺图片预览、缺 result preview/download/copy、缺 prompt apply、或首屏比例仍压迫，都不能算完成。