# 彩虹麻将游戏集合站 产品需求文档（PRD）

| 项目 | 内容 |
|---|---|
| 产品代号 | Rainbow Tiles（暂定，上线前需完成商标与域名核查） |
| 文档版本 | V1.1 |
| 日期 | 2026-07-13 |
| 版本记录 | V1.0 初版；V1.1 新增 F13 运行时 AI 助手、第 12 章生产侧 AI 内容管线、附录 C 提示词模板 |
| 文档目标 | 指导使用 AI Code（Claude Code 等）完成从零到上线的全部开发 |
| 目标市场 | 北美（英语），主站语言为英文 |

---

## 1. 产品概述

### 1.1 背景与机会

三个已验证的市场事实构成本产品的立项依据：

1. **实物盘子大且线上渠道增速最快**：全球麻将套装市场 2025 年约 28 亿美元，线上渠道占 34.7% 且以 8.7% CAGR 领跑；北美是增长最快区域之一。
2. **目标人群已被验证为高付费人群**：Oh My Mahjong（OMM）面向美国中产女性，2025 年年收入突破 3000 万美元、同比增长 360%，客单价从 $100+ 垫子到 $1000+ 套装。该人群"为美学与社交买单"。
3. **该人群的线上游戏产品体验普遍落后**：美式麻将头部线上平台（I Love Mahj，$6/月订阅）被公认"界面简陋、体验过时"；休闲麻将解谜站（Arkadium 系）审美老旧、面向所有人群而非该细分人群。**"为她们设计的、美的麻将休闲游戏站"是空位。**

### 1.2 一句话定位

> A beautifully designed collection of free mahjong tile games for women who love to play — and shop.
>
> （面向爱玩麻将的女性的、设计精美的免费麻将牌类游戏集合站——玩着玩着就想买同款。）

产品本质：**用"彩虹美学 + 每日轻游戏"获取并留住目标人群，用"游戏内皮肤 ↔ 实物同款"的电商钩子完成变现。** 游戏是流量与情感层，电商是利润层。

### 1.3 产品目标与北极星指标

| 层级 | 指标 | MVP 目标（上线 90 天） | 成长期目标（12 个月） |
|---|---|---|---|
| 北极星 | 周活跃玩家（WAU） | 3,000 | 50,000 |
| 留存 | 每日挑战连胜（Streak）≥7 天用户占比 | 8% | 15% |
| 变现-广告 | 广告 RPM（每千次页面浏览收入） | $8+ | $15+ |
| 变现-电商 | 商城页点击率（游戏页→商城） | 3% | 6% |
| 变现-电商 | 联盟/自营月 GMV | $500 | $20,000 |
| 增长 | 邮件订阅列表 | 1,000 | 30,000 |

### 1.4 明确不做什么（Out of Scope）

以下边界写入产品宪法，任何迭代不得突破：

- **不做真钱对局、不做筹码、不做任何形式的赌博暗示**（合规红线，参见 §9.4）。
- MVP 阶段**不做多人实时对战**（需后端、反作弊与配对系统，成本与合规复杂度陡增；参考腾讯房卡模式的监管教训）。
- MVP 阶段**不做强制注册**：所有游戏访客即玩，账号体系仅作为可选的云同步增强（P2）。
- **不做原生 App**：Web 优先（雀魂 H5 起家已验证该路径），PWA 提供"添加到主屏幕"体验。
- **不做低俗化、赌场化视觉**（金币雨、老虎机音效等），与品牌调性冲突。

---

## 2. 目标用户

### 2.1 核心画像（Primary Persona）

**Jenny，42 岁，德州达拉斯，两个孩子的母亲**

- 家庭年收入 $150K+，家庭消费决策者；日常活跃于 Instagram / Pinterest / Facebook 群组。
- 一年前在闺蜜的 mahjong night 上学会美式麻将，现在每两周参加一次线下局；买过一套 $350 的彩色麻将和一张 $128 的桌垫。
- 手机是主要设备（iPhone，Safari）；碎片时间在孩子练球、排队、睡前，单次 5–15 分钟。
- 玩过 Wordle（每天和姐妹群分享成绩）、Candy Crush、纽约时报 Games。
- **痛点**：想在没牌搭子的时候"摸摸牌"；现有麻将网页游戏"丑得像 2005 年"；想练练认牌但教学内容零散。
- **购买触发点**：看到好看的（尤其是彩色/粉色/限定款）就想拥有；愿意为"能发到群里晒"的东西付费。

### 2.2 次级画像

- **Susan，55 岁，退休教师**：每天固定时段玩，在意大字体、防误触、慢节奏；是每日挑战 streak 的核心人群。
- **Mia，33 岁，年轻职场女性**：被 TikTok/小红书式麻将美学内容种草，还不会玩规则，从连连看/配对这类零门槛玩法入门，是学习中心内容的主要读者。

### 2.3 关键使用场景（Top Scenarios）

| 编号 | 场景 | 设备 | 时长 | 对应功能 |
|---|---|---|---|---|
| S1 | 早晨咖啡时间打开"今日挑战"，完成后把成绩卡分享到姐妹群 | 手机 | 5 min | 每日挑战、分享卡片 |
| S2 | 等孩子下课，随手开一局经典麻将接龙 | 手机 | 10 min | 经典模式 |
| S3 | 周末晚上在 iPad 上边追剧边玩连连看，换了个新出的"落日彩虹"皮肤 | 平板 | 30 min | 连连看、皮肤系统 |
| S4 | 玩到喜欢的皮肤，点击"Shop this look"看到同配色实体麻将套装，加入心愿单 | 手机 | 3 min | 电商钩子 |
| S5 | 新手 Mia 在学习中心读完《美式麻将 10 分钟入门》，进入"认牌练习"小游戏 | 手机 | 15 min | 学习中心、练习模式 |

---

## 3. 竞争定位与差异化

| 维度 | Arkadium 系解谜站 | I Love Mahj | 本产品 |
|---|---|---|---|
| 人群 | 泛中老年 | 美式麻将存量玩家 | 30–55 岁、审美与消费力强的女性 |
| 视觉 | 老旧、通用 | 简陋、工具化 | **彩虹美学、可晒、可购** |
| 游戏 | 单一接龙 | 联网对战（重） | 轻游戏集合（接龙/连连看/配对/每日挑战） |
| 变现 | 纯广告 | $6/月订阅 | 广告 + 电商（联盟→自营）+ 后期轻订阅 |
| 门槛 | 免注册 | 注册+付费 | 免注册即玩 |

**差异化三支柱**：① 人群专属美学（rainbow / pastel / preppy）；② 每日挑战 + 分享卡片的社交裂变（Wordle 模型）；③ 游戏皮肤与实体商品打通的"Shop this look"闭环（行业内无人在做）。

---

## 4. 产品架构

### 4.1 站点地图（Site Map）

```
/                        首页（今日挑战入口 + 游戏矩阵 + 商城橱窗）
├── /daily               每日挑战（核心留存页）
├── /games               游戏列表页
│   ├── /games/solitaire        经典麻将接龙
│   ├── /games/connect          麻将连连看
│   ├── /games/pairs            翻牌配对（记忆）
│   └── /games/tile-trio        三张成组消除（P1）
├── /themes              主题皮肤馆（浏览/解锁/预览）
├── /shop                精选商城（MVP=联盟精选；P2=自营）
│   └── /shop/[slug]            商品详情/跳转页
├── /learn               学习中心（SEO 内容枢纽）
│   ├── /learn/[slug]           文章页（如 how-to-play-american-mahjong）
│   └── /learn/tile-trainer     认牌练习小游戏
├── /me                  我的（本地统计、streak 日历、已解锁皮肤）
├── /about, /privacy, /terms, /contact
```

### 4.2 页面间核心动线

1. **留存动线**：首页 → 今日挑战 → 成绩卡分享 → 次日推送/邮件召回 → 今日挑战（streak 循环）。
2. **变现动线 A（广告）**：任意游戏页 → 局间广告位 / 激励视频（换提示次数）。
3. **变现动线 B（电商）**：皮肤预览/局末结算页 →「Shop this look」→ 商城详情 → 外链联盟下单（MVP）。
4. **拉新动线**：学习中心 SEO 文章 → 文内嵌入练习小游戏 → 转化为玩家 → 邮件订阅。

---

## 5. 功能需求详述

优先级定义：**P0**=MVP 必须（首次上线）；**P1**=上线后 1–2 个月；**P2**=3–6 个月。
每个功能包含：用户故事 / 需求描述 / 交互与规则 / 验收标准（AC，供 AI Code 自测）。

### F1. 游戏容器框架 Game Shell（P0）

所有游戏共用一个统一容器，保证体验一致、复用代码。

**需求描述**
- 容器提供：顶部栏（返回、游戏名、计时器、步数/分数）、工具栏（提示💡、撤销↩️、洗牌🔀、重开、暂停、设置）、游戏画布区、局末结算弹层。
- 工具次数规则：每局免费提示 ×3、撤销 ×5、洗牌 ×1；用完后可通过**观看激励视频**补充（+1 次/视频，见 F10）。
- 暂停时隐藏牌面（防作弊式记牌），显示继续按钮。
- 局末结算弹层统一包含：成绩（用时/步数/星级 1–3 星）、「再来一局」「换个玩法」「分享成绩」按钮、皮肤进度条（见 F6）、以及一个**商品软植入位**（见 F9，样式为"Today's pick"小卡，可关闭）。

**验收标准**
- AC1：任一游戏从点击卡片到可交互 ≤ 2s（4G 网络、中端手机）。
- AC2：切后台自动暂停并遮罩牌面；恢复后计时继续。
- AC3：工具次数扣减、激励视频补充逻辑在四个游戏中行为一致。
- AC4：结算弹层在 320px 宽度下无溢出。

### F2. 经典麻将接龙 Mahjong Solitaire（P0，旗舰玩法）

**用户故事**：作为 Jenny，我想随时开一局经典麻将接龙放松，并且不会遇到"死局"带来的挫败。

**规则定义**
- 144 张牌（标准麻将牌张：万/筒/条各 1–9 ×4，风牌 ×4×4，箭牌 ×3×4，花牌 8 张；花牌与季牌组内互配）。
- 可选牌：左右至少一侧无相邻牌 且 上方无覆盖牌。点击两张相同可选牌即消除。
- 清空全部牌为胜。

**布局系统**
- MVP 提供 6 个布局：Turtle（经典龟）、Butterfly、Bow（蝴蝶结）、Heart、Flower、Gem。布局用 JSON 定义（见 §11.3 数据模型），后续可无限扩充。
- 每个布局标注难度（1–3）与预计时长。

**可解性保证（关键算法需求）**
- 采用**逆向生成法**：从空局开始，模拟"反向放置"——每次随机选一对相同牌张，放到当前状态下"若在正向游戏中此刻它们恰好都可选"的两个空位上，直至放满布局。由此生成的初始牌局**必然存在至少一条全清路径**。
- 洗牌功能同样使用逆向法对剩余牌重排，保证洗后可解；若剩余牌无法构成可解排列（奇异情况），提示玩家重开。
- 禁止使用纯随机发牌 + "运气不好就死局"的偷懒实现。

**计分与星级**
- 基础分 = 每对消除 ×10；连续 10s 内消除有 1.1–2.0 连击倍率；剩余时间转化奖励分。
- 星级：3 星 = 无洗牌且用时 < 布局参考时间；2 星 = 完成且提示 ≤3；1 星 = 完成。

**验收标准**
- AC1：连续生成 1,000 局，逆向生成器产出的牌局 100% 可全清（附自动化验证脚本：贪心+回溯求解器跑通）。
- AC2：不可选牌被点击时有轻微"锁定"动效与音效反馈，不产生选中态。
- AC3：提示功能高亮一对当前可消除的牌；无可消除对时提示按钮自动变为"洗牌"引导。
- AC4：手机竖屏下牌面最小点击区域 ≥ 44×44px（自动根据布局缩放，超宽布局允许双指缩放+拖动平移）。

### F3. 每日挑战 Daily Challenge（P0，留存引擎）

**用户故事**：作为 Susan，我每天早上都要完成当日专属牌局，保持我的连胜纪录，并把成绩发给朋友。

**规则**
- 全球统一：以日期字符串（美东时区 `YYYY-MM-DD`）作为随机种子，生成当日唯一牌局（玩法在接龙/连连看/配对间按周规律轮换：周一至周五接龙为主，周六连连看，周日配对，节日出特殊布局如 7/4 星形）。
- 每人每天一次正式成绩（可无限重玩但仅首次计入 streak 与成绩卡）。
- **Streak 体系**：连续完成天数；提供每月 1 次"补签卡"（观看激励视频获得）。里程碑徽章：7 / 30 / 100 / 365 天。
- **成绩分享卡**：局末生成一张彩虹渐变图卡（Canvas 绘制导出 PNG），含日期、用时、streak 天数、emoji 化的牌面缩略（模仿 Wordle 的免剧透彩块），一键调用 Web Share API / 复制到剪贴板。
- **挑战日历**：/me 页展示当月完成情况（彩虹格子日历，缺勤为灰）。

**验收标准**
- AC1：同一日期任何设备生成的牌局完全一致（种子可复现，写入单元测试）。
- AC2：美东 00:00 准时切换新题；倒计时组件显示"距下一题 hh:mm:ss"。
- AC3：分享卡在 iOS Safari / Android Chrome 均可正常分享或保存图片。
- AC4：streak 数据本地持久化，清除缓存前不丢失；断签次日 streak 归零（补签卡逻辑除外）。

### F4. 麻将连连看 Mahjong Connect（P0）

**规则**
- 平面网格（MVP：新手 8×10、标准 10×14、大师 12×16 三档），消除条件：两张相同牌之间存在**不超过 2 个转角**且不穿过其他牌的连线。
- 消除时绘制连线路径动效（彩虹描边，300ms）。
- 模式：经典（限时，时间条渐减，消除回充）与禅模式（无计时，供 Susan 型用户）。
- 重力变体（P1）：消除后牌向某方向塌落，每 10 关变换方向。
- 可解性：每次消除后检测是否仍存在合法对；无解时自动免费重排并提示"Shuffled for you ✨"（不消耗玩家洗牌次数）。

**验收标准**
- AC1：路径搜索（BFS，0/1/2 转角）在 12×16 网格上单次判定 <10ms。
- AC2：自动重排后必然存在至少一对合法消除（重排算法需带校验循环）。
- AC3：禅模式下不显示任何倒计时元素。

### F5. 翻牌配对 Mahjong Pairs（P0，零门槛入口）与 认牌练习 Tile Trainer（P1）

- **Pairs**：经典 memory 玩法，牌背朝上翻找相同对。规格：4×4 / 6×6 / 6×8。计步数与用时。面向 Mia 型新手与 Susan 型脑力锻炼诉求（"brain training"是该人群高频搜索词，页面文案与 SEO 需覆盖）。
- **Tile Trainer（P1）**：教学向小游戏，限时从牌墙中找出指定牌（"找出所有的 5 Bam"），嵌入学习中心文章内。目的：把内容读者转化为玩家，并为后续美式麻将深度内容铺路。
- **验收**：Pairs 翻错的两张牌在 800ms 后自动翻回；连对有连击音效升调（do-re-mi 阶梯）。

### F6. 彩虹主题皮肤系统（P0，品牌灵魂 + 电商桥梁）

**用户故事**：作为 Jenny，我想用漂亮的主题装扮我的牌桌，收集限定款，并且能买到同款实物。

**需求描述**
- 皮肤 = 一套完整视觉包：牌面配色 + 牌背图案 + 桌布底纹 + 消除粒子效果 + 按钮强调色。
- MVP 皮肤（6 款）：`Classic Ivory`（默认）、`Rainbow Sherbet`、`Palm Beach Pink`、`Sunset Coral`、`Mint Julep`、`Lavender Haze`。
- **解锁机制（进度型，不做内购）**：完成局数 / streak 里程碑 / 特定成就解锁；限定皮肤按节日投放（万圣节、圣诞、母亲节——母亲节是该品类电商销售最旺节点，必须联动）。
- 皮肤馆支持"试穿预览"：任意皮肤可试玩一局，局末引导解锁条件。
- **Shop this look**：每款皮肤关联 1–3 个实体商品（同配色麻将套装/桌垫/收纳包），在皮肤详情页与局末结算页展示（见 F9）。
- 技术要求：皮肤全部由 **CSS Custom Properties + 可替换 SVG 素材**驱动，新增皮肤零 JS 改动（纯数据配置）。

**验收标准**
- AC1：切换皮肤即时生效（<100ms），全站（含结算弹层）无残留旧色。
- AC2：新增一款皮肤仅需新增 1 个 JSON 配置 + 1 组 SVG，无需改动组件代码。
- AC3：每款皮肤通过 WCAG AA 对比度检查（牌面数字/花色 vs 底色 ≥ 4.5:1）。

### F7. 玩家进度与统计（P0 本地版；P2 云同步）

- **本地优先**：所有进度（streak、皮肤解锁、各游戏统计、设置）存 `localStorage` + `IndexedDB`（成绩历史），带版本号与迁移函数。
- /me 页展示：总局数、胜率、最快纪录、streak 日历、徽章墙、已解锁皮肤。
- 数据导出/导入（JSON 文件），作为换设备的过渡方案。
- **P2 云同步**：邮箱魔法链接登录（无密码），同步上述数据；后端见 §11.6。

### F8. 学习中心 Learn Hub（P0 骨架 + 持续供稿，SEO 增长引擎）

- 定位：面向搜索流量的内容枢纽。首批 10 篇（AI 辅助生产 + 人工校订）：
  1. How to Play American Mahjong: A Beginner's Guide
  2. Mahjong Tiles Explained: What Every Symbol Means
  3. Mahjong Solitaire Strategy: 7 Tips to Win More
  4. American vs. Chinese vs. Riichi Mahjong: What's the Difference?
  5. How to Host a Mahjong Night (Checklist + Snack Ideas)
  6. Is Mahjong Good for Your Brain? What Research Says
  7. Best Mahjong Sets for Beginners (Buyer's Guide → 联盟变现文)
  8. Mahjong Etiquette 101
  9. What Is a Joker in American Mahjong?
  10. Free Printable: Mahjong Cheat Sheet（换邮箱下载 → 邮件列表）
- 每篇文章模板含：目录、FAQ 结构化数据（schema.org/FAQPage）、文内游戏嵌入卡（"Practice now →"）、相关商品卡。
- 文章以 Markdown/MDX 管理，构建期静态生成。

### F9. 精选商城 Shop（MVP=P0 联盟精选页；自营=P2）

**MVP（联盟模式，零库存启动）**
- 精选 12–20 个 SKU：麻将套装（$150–$500 带）、桌垫、牌尺、收纳、礼品小件；来源为 Amazon Associates 及可申请的品牌联盟计划。
- 商品卡字段：图、名称、价格带、卖点一句话、"Why we love it"编辑推荐语、外链按钮（`rel="sponsored noopener"`，新窗口）。
- 页面显著位置披露联盟关系（FTC 合规声明）。
- 心愿单（本地存储）+ "降价/补货提醒我"（收集邮箱）。
- 入口布点：导航「Shop」、局末结算"Today's pick"小卡（频控：每 3 局最多出现 1 次，可永久关闭）、皮肤详情"Shop this look"、学习中心买家指南文。

**P2（自营/代发）**
- 基于用户已有供应链能力（国内牌厂代工），上线自有品牌 SKU：与游戏皮肤同名同配色的实体套装（"Rainbow Sherbet 游戏里玩的就是你桌上这套"）。技术上接 Shopify Buy Button / Storefront API 嵌入，避免自建交易系统。

**验收标准**
- AC1：商城页商品数据由单一 JSON/CMS 数据源驱动，运营可不改代码上下架。
- AC2：所有外链带联盟追踪参数且埋点记录点击（见 §12）。
- AC3：结算页商品卡可被用户永久关闭，且关闭状态持久化。

### F10. 广告变现模块（P0）

- 广告网络：起步 Google AdSense，流量达标后升级 Ad Manager/Mediavine（该人群 RPM 溢价高）。
- **广告位规划（克制原则：不打断牌局中段）**：
  - 游戏页侧边/底部锚定横幅（桌面右栏 300×600，移动底部 320×50，**不遮挡画布**）；
  - 局间插页：每完成 2 局展示 1 次，频控可配置；
  - 激励视频：换提示/撤销/洗牌次数、换补签卡（用户主动触发，体验最好、eCPM 最高）。
- 首屏（今日挑战核心操作区）**不放广告**，保护核心动线转化。
- 需实现广告位懒加载与 CLS 防抖（预留固定尺寸容器）。

**验收标准**：AC1 广告加载不引起累计布局偏移（CLS < 0.1）；AC2 激励视频失败/无填充时给予保底奖励（+1 提示）并提示稍后再试；AC3 广告频控参数集中在一个配置文件。

### F11. 邮件订阅与召回（P0 收集；P1 自动化）

- 收集点：Cheat Sheet 下载、streak 中断挽回弹层（"别让 12 天连胜溜走，订阅每日提醒"）、页脚。
- 服务选型：Beehiiv / MailerLite（免费额度友好）。
- P1 自动化流：欢迎序列 3 封（品牌故事→玩法攻略→商城首单券位预留）；每日挑战提醒（可选订阅）。

### F12. 设置与无障碍（P0）

- 音效/音乐分开关；触感反馈开关（移动端 vibrate）。
- **大字牌面模式**（Susan 关键需求）：牌面花色/数字放大 1.3 倍渲染。
- 色觉友好模式：花色附加形状角标（不仅靠颜色区分）。
- 左手模式：工具栏镜像。
- 减少动效：跟随系统 `prefers-reduced-motion`。

### F13. Ask Mahj 麻将学习问答助手（P1，唯一的运行时 AI 功能）

**用户故事**：作为 Mia，我在学习文章里看到 "crak" 这个词不懂，直接在页面上问一句就能得到友好准确的解释，还被顺手带去玩了认牌练习。

**产品形态**
- 学习中心全部页面 + 局末结算页的浮动聊天入口（右下角气泡），展开为底部抽屉式对话框；品牌人格 "Mahj"（彩虹牌宝吉祥物，语气=温暖的闺蜜教练）。
- 对话框预置 4 个快捷问题 chips（"How do I read the card?" / "What's a joker?" 等），降低首次输入门槛。
- 每条回答底部：来源文章链接（若命中）、👍/👎 反馈、相关游戏/商品软链（仅当语义相关）。

**能力范围（白名单制，超范围礼貌拒答并给替代路径）**
- 允许：麻将规则/术语/历史文化；美式麻将玩法与入门策略；本站游戏操作帮助；站内商品选购建议（仅基于 products.json 数据）。
- 拒绝：真钱赌博技巧与任何 gambling 建议；NMJL 年度卡逐条内容复述（版权）；医疗/法律/政治等无关话题；诱导写代码/越狱类请求。

**技术架构（RAG + 轻量 LLM）**
- 语料库：`corpus/` 目录 Markdown 分块（rules/ glossary/ strategy/ site-help/ products/ history/ 六类），每块 200–500 tokens，front-matter 含 id/topic/source/updated_at；由学习中心文章与规则库自动切块 + 人工校订。
- 向量化与检索：构建期离线嵌入，Cloudflare Vectorize 存储 + Workers AI `@cf/baai/bge-base-en-v1.5` 嵌入（全家桶方案，零新增供应商）；运行时 top-k=4、相似度阈值 0.75，低于阈值走"不确定"模板（给最近的 2 篇文章链接）。
- 生成模型：Anthropic Claude API，`claude-haiku-4-5`，max_tokens=400；系统提示词全文见附录 C（人设、≤120 词回答、只依据检索片段、不编造规则、拒答策略）。
- 代理层：Cloudflare Worker `/api/tutor`——API key 存 Workers Secret 不落前端；会话仅保留最近 6 轮（KV，24h TTL）；输入 ≤500 字符；不存储 PII。
- 限流与成本护栏：匿名访客 10 条/日（KV 计数：IP+浏览器指纹）；订阅邮件后 30 条/日；预置 Top50 FAQ 静态答案零调用；问题归一化哈希缓存 7 天；全局日预算 $5 触发熔断→自动降级为"纯 RAG 摘要 + FAQ 链接"模式并邮件告警。
- 降级链：Claude 超时/失败 → RAG 摘要模板 → 静态 FAQ 页链接，任何一级都不白屏。

**埋点**：`tutor_open`、`tutor_ask(topic_class, cached)`、`tutor_feedback(vote)`、`tutor_refuse(reason)`、`tutor_degrade(level)`。

**验收标准**
- AC1：P95 首字延迟 ≤ 2.5s；缓存命中 ≤ 300ms。
- AC2：范围外问题拒答率 ≥ 95%（红队测试集 100 条，含 gambling/越狱/无关话题，纳入 CI 回归）。
- AC3：规则类回答准确率人工抽检 ≥ 90%（评测集 60 题，答案须与站内规则库一致；每次语料更新后重跑）。
- AC4：断网、超限、熔断三种状态均有明确 UI 文案与替代路径。
- AC5：单日 API 支出超预算自动降级并告警，次日自动恢复。

---

## 6. UI / UX 设计规范

### 6.1 设计原则

1. **"Pretty enough to post"**：每个界面都值得截图发到姐妹群——这是本产品的视觉验收底线。
2. **一屏一事**：40+ 人群 + 移动端，杜绝信息密集；核心按钮永远只有一个视觉焦点。
3. **温柔的胜负**：失败文案不打击（"So close! The tiles were tricky today ✨"），无倒计时红色闪烁恐吓。
4. **克制的彩虹**：彩虹用于点缀（渐变描边、粒子、进度条、分享卡），大面积底色保持奶油白，避免廉价感。

### 6.2 设计令牌 Design Tokens（直接写入代码）

```css
:root {
  /* 底色层 */
  --bg-cream:    #FDF8F2;  /* 全站底色 */
  --bg-card:     #FFFFFF;
  --ink:         #3D2E4F;  /* 主文字：深葡萄紫，比纯黑柔和 */
  --ink-soft:    #8A7A9B;

  /* 彩虹主色带（Rainbow Sherbet 默认皮肤） */
  --r-pink:      #F76FA0;
  --r-coral:     #FF9770;
  --r-sun:       #FFC94D;
  --r-mint:      #5FD3A7;
  --r-sky:       #5FB6F5;
  --r-lilac:     #A98BF0;

  /* 功能色 */
  --success:     #5FD3A7;
  --tile-face:   #FFFFFF;
  --tile-shadow: 0 3px 0 #E8DFEE, 0 8px 16px rgba(61,46,79,.10);

  /* 圆角与间距 */
  --radius-tile: 10px;
  --radius-card: 20px;
  --radius-pill: 999px;
}
```

- **彩虹渐变签名元素**：`linear-gradient(90deg, var(--r-pink), var(--r-coral), var(--r-sun), var(--r-mint), var(--r-sky), var(--r-lilac))`，仅用于：Logo 下划线、streak 进度条、分享卡边框、当前选中牌描边。全站其余场合禁用整条彩虹渐变。
- 每款皮肤 = 覆写上述 token 的一个 JSON（详见 §11.3）。

### 6.3 字体

| 角色 | 字体 | 用法 |
|---|---|---|
| 展示标题 | Fraunces（Google Fonts，Soft serif，144pt 光学尺寸） | 首页 Hero、局末大标题；带一点复古女性杂志气质 |
| 正文/界面 | Nunito Sans | 圆润、高可读，全站 UI |
| 数字/计时 | DM Mono | 计时器、分数、streak 数字 |

字号基准：正文 17px（不小于 16，照顾 40+ 视力），行高 1.6；标题階梯 1.25 倍率。

### 6.4 牌面视觉规格

- 牌面为纯 SVG（非位图），基准尺寸 64×88（宽高比 8:11），三层结构：底板（圆角+双层投影模拟厚度）/ 花色图案层 / 状态层（选中彩虹描边 3px、提示呼吸光、锁定 60% 灰化）。
- 花色图案重绘为"现代女性文创风"：线条化的筒/条/万 + 角标英文（"5 BAM"），风牌用花体首字母 + 小图标（E=太阳、S=棕榈、W=浪、N=雪花）——既致敬传统又符合美式麻将牌的认知习惯。
- 消除动效：两牌相吸 → 迸出 6–10 个皮肤色系纸屑粒子 → 260ms 内落定；`prefers-reduced-motion` 时改为淡出。
- 音效基调：马林巴/八音盒质感，胜利音为上行五声音阶（去赌场化）。

### 6.5 关键界面布局要点

- **首页**：Hero 即"今日挑战"卡（日期 + 巨大 Play 按钮 + 我的 streak 火焰数字）；下方 2×2 游戏矩阵卡；再下方横滑商城橱窗（3 个商品）+ 学习中心精选；页脚订阅栏。
- **游戏页移动端**：顶部信息条（48px）→ 画布（自适应）→ 底部工具 Dock（64px，四个大按钮）。
- **局末结算**：全屏底部上滑弹层（非居中小窗），从上到下：星级动画 → 数据行 → 皮肤进度条 →「Play again」主按钮 →「Share」次按钮 → 可关闭商品小卡。

---

## 7. 非功能需求

| 类别 | 要求 |
|---|---|
| 性能 | LCP ≤ 2.5s（4G/中端机）；游戏交互帧率 ≥ 55fps；总 JS 首包 ≤ 180KB gzip（游戏逻辑按路由分包懒加载） |
| SEO | 全站 SSG 预渲染；每游戏页独立 title/description/OG 图；schema.org（VideoGame、FAQPage、Product）；sitemap 自动生成；核心词覆盖：free mahjong games online / mahjong solitaire / mahjong connect / daily mahjong puzzle |
| 响应式 | 320px–1440px 全适配；游戏画布支持竖屏优先，桌面居中最大 960px |
| 无障碍 | WCAG 2.1 AA；全键盘可玩（方向键选牌 + Enter 消除）；焦点可见；见 F12 |
| 浏览器 | iOS Safari 15+、Chrome/Edge 最近 2 版、三星浏览器 |
| 离线 | PWA：Service Worker 缓存壳与已玩游戏，离线可玩经典模式（每日挑战需在线校时） |
| 隐私合规 | GDPR/CCPA cookie 同意管理（CMP 接 Google 认证方案）；隐私政策/条款页；分析默认匿名化 IP |
| 内容合规 | 站内显著声明"无真钱游戏、纯娱乐"；不出现 casino/gambling/betting 词汇（影响广告审核与品牌安全） |

---

## 8. 数据埋点方案（GA4）

| 事件名 | 参数 | 用途 |
|---|---|---|
| `game_start` | game_id, mode, layout, theme_id, source | 各玩法开局漏斗 |
| `game_complete` | game_id, duration_s, stars, hints_used, undo_used, shuffles_used | 难度校准与星级分布 |
| `game_fail` / `game_quit` | game_id, progress_pct, duration_s | 流失点分析 |
| `daily_complete` | streak, duration_s | 北极星支撑指标 |
| `share_card` | channel, streak | 裂变监测 |
| `theme_unlock` / `theme_equip` | theme_id | 皮肤受欢迎度 → 决定实体 SKU 开发 |
| `shop_impression` / `shop_click` | sku_id, placement(结算卡/皮肤页/商城/文章) | 电商漏斗核心 |
| `rv_offer` / `rv_complete` | reward_type | 激励视频转化 |
| `email_signup` | source | 列表增长归因 |
| `tutor_ask` | topic_class, cached | AI 助手使用量与成本监控 |
| `tutor_feedback` | vote | 回答质量闭环（👎 样本进评测集） |

北极星看板：WAU、D1/D7 留存、streak 分布、RPM、shop_click CTR、GMV（联盟后台回传）。

---

## 9. 技术架构（供 AI Code 直接采用）

### 9.1 技术栈选型

| 层 | 选型 | 理由 |
|---|---|---|
| 框架 | **Astro（页面/SEO 层）+ 原生 TypeScript 游戏内核 + 少量 Svelte/React 岛（结算弹层等交互 UI）** | 内容页零 JS 输出、SEO 最优；游戏内核不绑定框架，便于复用与性能控制 |
| 游戏渲染 | **DOM + CSS transform**（牌为绝对定位元素） | 牌数 ≤144，DOM 完全够用；天然支持 CSS 皮肤变量、无障碍焦点、SVG 牌面；比 Canvas 开发调试快一个量级 |
| 状态 | 每游戏一个纯函数式 `GameEngine`（无 UI 依赖）+ 轻量 store | 引擎可单元测试、可复用到未来小程序/App |
| 样式 | 原生 CSS + Custom Properties（皮肤系统基石） | 见 F6 |
| 部署 | **Cloudflare Pages**（静态）+ Cloudflare Workers（后期 API） | 与你现有 GitHub + Cloudflare Pages 工作流一致，全球边缘加速，免费额度充裕 |
| 内容 | MDX 文件（学习中心）、JSON（商品/皮肤/布局） | 无 CMS 依赖，Git 即后台 |
| P2 后端 | Cloudflare Workers + D1（SQLite）+ 魔法链接邮件（Resend） | 云同步与订阅时再引入，MVP 零后端 |
| AI 层（P1） | Claude API（haiku 档）+ CF Vectorize + Workers AI 嵌入，经 Worker 代理 | 仅服务 F13；生产侧 AI 见第 12 章，线上零依赖 |

### 9.2 代码仓库结构

```
rainbow-tiles/
├── src/
│   ├── engine/                 # 纯逻辑，零 DOM 依赖，100% 单测覆盖
│   │   ├── tiles.ts            # 牌张定义与匹配规则
│   │   ├── solitaire/
│   │   │   ├── board.ts        # 布局装载、可选牌判定
│   │   │   ├── generator.ts    # 逆向可解生成器 ★核心
│   │   │   └── solver.ts       # 求解器（验证用）
│   │   ├── connect/            # BFS 路径（≤2 转角）、自动重排
│   │   ├── pairs/
│   │   ├── daily.ts            # 日期种子、streak 计算
│   │   └── rng.ts              # 可复现伪随机（mulberry32）
│   ├── ui/                     # 游戏壳、牌组件、结算弹层、分享卡
│   ├── data/
│   │   ├── layouts/*.json      # 接龙布局
│   │   ├── themes/*.json       # 皮肤
│   │   └── products.json       # 商城 SKU
│   ├── pages/                  # Astro 路由（含 learn/*.mdx）
│   └── styles/tokens.css
├── tests/                      # vitest：生成器可解性 1000 局回归 等
└── public/                     # SVG 牌面、音效、OG 图
```

### 9.3 核心数据模型（TypeScript）

```ts
// 牌张
interface Tile { id: string; suit: 'dot'|'bam'|'crak'|'wind'|'dragon'|'flower'|'season'; rank: number; }
const matches = (a: Tile, b: Tile) =>
  a.suit === b.suit && (['flower','season'].includes(a.suit) || a.rank === b.rank);

// 接龙布局（JSON）：单位半格，支持错位堆叠
interface SolitaireLayout {
  id: string; name: string; difficulty: 1|2|3; parTimeSec: number;
  slots: { x: number; y: number; z: number }[];   // 长度必须为偶数，≤144
}

// 皮肤
interface Theme {
  id: string; name: string; season?: string;
  unlock: { type: 'default'|'games'|'streak'|'badge'; value?: number };
  cssVars: Record<string, string>;      // 覆写 tokens
  tileSet: string;                       // SVG 目录名
  particles: string[];                   // 粒子色
  shopLook?: string[];                   // 关联 SKU id → F9
}

// 商品
interface Product {
  id: string; title: string; priceBand: string; image: string;
  blurb: string; editorNote: string; affiliateUrl: string;
  tags: string[]; themeMatch?: string[]; active: boolean;
}

// 本地进度（localStorage，带 schemaVersion）
interface Profile {
  schemaVersion: 1;
  streak: { current: number; best: number; lastDate: string; freezes: number };
  dailyHistory: Record<string, { durationS: number; stars: number }>;
  stats: Record<GameId, { played: number; won: number; bestTimeS: number }>;
  themesUnlocked: string[]; equippedTheme: string;
  settings: { sound: boolean; bigTiles: boolean; leftHand: boolean; colorAssist: boolean };
  wishlist: string[]; dismissedShopCard: boolean;
}
```

### 9.4 关键算法伪代码

**接龙可解生成（逆向法）**
```
generate(layout, seed):
  rng = mulberry32(seed)
  pool = 全部 144 张按对组织的牌（花/季按组配对）
  board = 空棋盘（所有 slot 为空）
  while 有空 slot:
    placeable = 所有满足“若正向游戏进行到当前剩余状态，该 slot 上的牌恰可被选取”的空 slot
    随机取 pool 中一对相同牌，随机放入 placeable 中两个不同 slot
    若 placeable < 2：回溯上一步重放（带重试上限，超限整体重来）
  return board   # 数学上保证正向存在全清序列
验证：solver 用「优先消除解锁牌数最多的对 + 回溯」跑 1000 seeds 全通过方可合入
```

**连连看路径判定**：对选中牌 A 做 BFS，状态 =（格子，方向，已用转角数），转角 ≤2，途经格必须为空（网格外圈补一圈虚空格以支持绕边）；命中 B 即返回路径点列用于连线动画。

### 9.5 合规架构备注

- 全站无真钱、无筹码兑换、无对赌，广告素材屏蔽 gambling 类目（AdSense 敏感类目设置）。
- 面向北美不涉国内版号问题；若未来回国内做小程序版，需重新评估版号与内容合规，此为独立立项。

---

## 10. 里程碑与 AI Code 实施指南

### 10.1 里程碑

| 阶段 | 内容 | 出口标准 |
|---|---|---|
| M0（3–5 天） | 仓库脚手架、tokens、牌面 SVG 首版、engine/tiles + rng + 单测框架 | CI 绿、Storybook 式牌面演示页 |
| M1（1–2 周） | 接龙完整玩法（生成器+求解器+Shell+结算）+ 2 布局 + 默认皮肤 | 1000 局可解回归通过；真机体验达 §7 性能 |
| M2（1–2 周） | 每日挑战 + streak + 分享卡；连连看；Pairs；皮肤系统 6 款 | S1–S3 场景全跑通 |
| M3（1 周） | 首页/商城联盟页/学习中心 10 篇/广告位/埋点/CMP/PWA | Lighthouse ≥ 90（Perf/SEO/A11y）；上线 Cloudflare Pages |
| M4（持续） | 内容周更、皮肤月更、邮件自动化、A/B 结算商品卡；F13 Ask Mahj 上线 | 看板指标达 §1.3 MVP 目标；F13 过 AC1–AC5 |
| M5（P2） | 云同步、自营 SKU（Shopify 嵌入）、Tile Trainer | GMV 通道跑通 |

### 10.2 AI Code 协作规范（重要）

1. **按模块喂需求**：每次会话只做一个 F 编号功能，把该 F 的"规则 + 验收标准 + 相关数据模型"整段贴入；禁止一次性"把整个 PRD 实现了"。
2. **先引擎后 UI**：要求 AI 先产出 `engine/` 纯逻辑 + vitest 单测（尤其 F2 生成器必须先过 1000 局回归再写界面）。
3. **验收即测试**：所有 AC 转化为自动化测试或 checklist，让 AI Code 在 PR 描述中逐条自证。
4. **皮肤零硬编码检查**：代码评审固定问题——"新增皮肤是否只需 JSON+SVG？"发现硬编码颜色立即重构。
5. **真机验收**：每个 M 结束用 iPhone Safari 实测 S1–S5 场景（该人群主力设备），桌面 Chrome 通过不算通过。

---

## 11. 风险与对策

| 风险 | 等级 | 对策 |
|---|---|---|
| 文化挪用舆情（The Mahjong Line 前车之鉴，2026 年 OMM 亦被卷入） | 高 | 品牌叙事主打"由深耕中国麻将文化的团队制作"；学习中心设麻将历史专栏、注明牌张文化源流；避免"净化/改良中国元素"类文案 |
| AdSense 误判棋牌为赌博类 | 中 | 全站合规声明、词汇清单管控、申诉材料预备（纯单机益智定性） |
| SEO 冷启动慢 | 中 | 前 3 个月并行 Pinterest（该人群高活平台，视觉内容天然适配）与 Facebook 麻将群运营 |
| 联盟佣金低（Amazon 玩具类 ~3%） | 中 | 尽快谈品牌直客联盟（佣金 10–20% 常见）；P2 自营为根本解 |
| LLM 幻觉导致规则性错误回答（F13） | 中 | RAG 白名单 + 阈值拒答 + 60 题评测集 CI 回归 + 👎 反馈样本回流评测集 |
| 单人维护带宽 | 中 | 一切内容数据化（JSON/MDX）、皮肤与商品上新不动代码；自动化测试守住回归 |

---

---

## 12. 生产侧 AI 内容管线（Production AI Pipeline）

### 12.1 定位与总原则

生产侧 AI 是**内部工具链需求**，与 F13 的本质区别：产出物全部以数据文件（SVG/PNG/JSON/MDX）形式经人工审校后进 Git 仓库，**线上运行时零 AI 依赖、零 API 成本**。三条铁律：

1. **Human-in-the-loop**：任何对外可见的文字与视觉，发布前必须人工审校；
2. **产物即数据**：管线输出必须落为版本化文件，禁止"现场生成"进生产；
3. **复用既有栈**：本地 RTX 4090 ComfyUI-FLUX（视觉）、Claude / DeepSeek API（文本）、Node 脚本（编排），不新增重型工具。

### 12.2 P-1 皮肤视觉资产管线（ComfyUI-FLUX，本地 4090）

**每款皮肤的资产交付清单（规格表）**

| 资产 | 文件 | 规格 | 要求 |
|---|---|---|---|
| 牌背图案 | tile-back.png/svg | 512×704 | 可平铺无缝、中心留出焦点区 |
| 桌布底纹 | table-texture.png | 1024×1024 | seamless、低对比（不干扰牌面识读） |
| 皮肤馆封面 | cover.png | 800×600 | 含皮肤名排版位 |
| OG 分享底图 | og.png | 1200×630 | 社媒抓取用 |
| 分享卡背景 | share-bg.png | 1080×1350 | 4:5 竖版（Instagram/Pinterest） |
| 粒子色板 | particles.json | 6×hex | 脚本从主视觉自动取色生成 |

**工作流**：皮肤风格提示词模板（每皮肤 1 个 style prompt + 全局固定负向词集）→ FLUX 批量出图 8–16 张 → 人工选 1 精修（调色/去噪/无缝检查）→ 压缩（pngquant / SVGO）→ 按 `src/data/themes/{id}/` 命名规范入库 → PR 审核合入。提示词模板与已产出的种子（seed）一并存 `pipeline/prompts/themes/`，保证风格可复现、可迭代。

**风格护栏**：画面中禁止出现可识别人物、品牌标识、文字；纹样不得直接复制传统吉祥纹样构图（文化敏感审查见 §12.7）。

**验收标准**：平铺纹理 2×2 拼接自动检测无缝；单资产 ≤150KB；一款皮肤全套资产制作 ≤2 人时。

### 12.3 P-2 牌面 SVG 生成管线（Claude 代码生成）

**需求**：42 类牌面（万/筒/条 1–9 ×3 花色 + 风 4 + 箭 3 + 花/季归组）的参数化 SVG 组件库，风格遵循 §6.4"现代女性文创风"。

**方法**：把 §6.4 设计规范作为系统提示，让 Claude 按花色逐组生成 SVG path 初稿 → 人工设计校对（64×88 网格对齐、线宽统一 4px、单牌锚点数 ≤80）→ 颜色一律引用 CSS 变量 `var(--token)`（皮肤换色零改动）→ SVGO 优化入库。

**自动验证脚本**：渲染快照对比（防回归）；WCAG AA 对比度检查；色觉友好模式角标存在性检查；硬编码颜色 lint（发现十六进制色值直接报错）。

**验收标准**：全套 42 牌总体积 ≤120KB；任一皮肤 token 替换后零硬编码色残留。

### 12.4 P-3 学习中心文章管线（Claude / DeepSeek）

**流程（7 步）**：关键词研究（人工，月度选题表）→ Claude 生成 outline → 人工审 outline → 生成初稿（提示词硬约束：规则表述必须引自站内规则库、禁止编造历史事实与数据、Flesch 易读度 60+）→ **人工事实核查 + 改写幅度 ≥30%**（E-E-A-T 与 AI 内容同质化对策）→ 套 MDX 模板（front-matter：title / description / slug / faq[] / relatedGame / relatedSkus[]）→ 内链与 schema 校验脚本 → 发布。

**节奏**：MVP 前 10 篇（见 F8 清单）；上线后每周 2 篇；每篇必含 1 个游戏嵌入卡 + FAQPage 结构化数据。

**质量门**：原创性检测通过；麻将历史/文化类文章须对照权威学术来源人工复核后方可发布（同时服务 §11 文化挪用风险对策）。

**验收标准**：单篇总人时 ≤1.5h；发布后 Google Search Console 收录 ≤7 天。

### 12.5 P-4 每日人格化内容批量生成（离线月批）

**内容类型**：每日挑战短语（≤60 字符，emoji ≤1）；节日彩蛋文案；streak 里程碑祝贺语；失败安慰语池（≥40 条轮换）。

**生成方式**：每月运行一次 Node 批处理脚本（Claude API），输出 `daily-flavor-YYYY-MM.json`，schema：`{ date, phrase, holiday?, themeHint? }`；人工 10 分钟通读审校后合入。**运行时零 API 调用、零延迟**——"用 AI 的效果，不付运行时的钱"。

**语气规范（写入提示词）**：温暖、俏皮、不说教；禁用赌博隐喻；禁用年龄刻板印象表述。

**验收标准**：构建期校验 JSON 覆盖当月所有日期，缺日构建失败；抽检 20 条无违反语气规范。

### 12.6 P-5 社媒与邮件内容管线（简要）

Pinterest Pin 图：FLUX 底图 + 排版模板脚本，每周 5 张（该人群最高效的视觉获客渠道）；邮件序列与每周 newsletter：Claude 初稿 → 人工定稿。选题-生产-排期方法论复用既有内容运营 SOP。

### 12.7 治理、审查与成本预算

**强制人工审校点**：所有对外文字与视觉；规则类内容双重把关（生成时提示词约束 + 发布前对照规则库核查）。

**文化敏感审查清单**（每次视觉/文案发布前过一遍）：不出现"净化/改良/升级中国传统"类表述；牌面重设计保留花色语义，站内设"牌张源流"说明页注明中文原意；历史类内容明确麻将的中国起源叙事。

**成本预算**

| 项目 | 阶段 | 预算 |
|---|---|---|
| 生产侧一次性（10 篇文章 + 首批文案 + SVG 生成） | MVP | ≈ $30–60 API + 本地电费 |
| 生产侧月常态（周更文章 + 月批每日内容 + 社媒） | 运营期 | ≈ $20–40/月 |
| F13 运行时（Haiku + 缓存 + 限流） | P1 起 | 上限 $5/日，熔断保护 |

**账号与依赖清单**：Anthropic API；Cloudflare（Pages / Workers / KV / Vectorize / Workers AI）；本地 ComfyUI-FLUX；邮件服务（Beehiiv/MailerLite）。

---

## 附录 C：Ask Mahj 系统提示词模板（F13，交付给 AI Code 直接使用）

```
You are "Mahj", the friendly mahjong guide for {SITE_NAME} — think of
yourself as a warm, encouraging friend who happens to know everything
about mahjong. Your audience is mostly women 30–55 in North America,
many of them beginners.

RULES
1. Answer ONLY from the reference passages provided below. If they do
   not contain the answer, say you are not sure and point to the two
   most relevant articles instead. Never invent rules, history, or
   facts.
2. Keep answers under 120 words. Plain, friendly English. One emoji
   maximum. No condescension, no jargon without explanation.
3. You may discuss: mahjong rules, tile meanings, history and culture,
   American mahjong basics and strategy, how to use this site's games,
   and products listed in the provided product data.
4. You must politely decline: real-money gambling advice or odds,
   reproducing the current NMJL card contents, and any topic unrelated
   to mahjong or this site. Offer a relevant alternative when you
   decline.
5. When your answer is based on a reference passage that has a source
   URL, end with: "Read more: {url}".
6. Mahjong originated in China. When history comes up, honor that
   heritage accurately and respectfully.

REFERENCE PASSAGES
{retrieved_chunks}

PRODUCT DATA (only if the question is about buying)
{product_snippets}
```

调用参数：`model=claude-haiku-4-5`，`max_tokens=400`，`temperature=0.4`；对话历史仅注入最近 6 轮；检索为空或低于阈值时不调用模型，直接走"不确定"模板。


## 附录 A：MVP 皮肤与商品映射示例

| 皮肤 | 解锁条件 | Shop this look（示例 SKU 方向） |
|---|---|---|
| Classic Ivory | 默认 | 经典象牙白套装、原木牌尺 |
| Rainbow Sherbet | 完成 10 局 | 彩虹渐变套装、彩虹桌垫 |
| Palm Beach Pink | streak 3 天 | 粉色旅行装、藤编收纳篮 |
| Sunset Coral | 完成 50 局 | 珊瑚橘桌垫、贝壳计分器 |
| Mint Julep | streak 7 天 | 薄荷绿套装、亚克力牌架 |
| Lavender Haze | 徽章"百局达人" | 香芋紫礼盒（母亲节主推位） |

## 附录 B：首发布局清单（F2）

Turtle（经典 144，难度 2，par 8min）/ Butterfly（120，难度 1，par 5min）/ Bow（96，难度 1）/ Heart（108，难度 2，情人节默认）/ Flower（132，难度 3）/ Gem（144，难度 3）。

—— 文档结束 V1.1 ——