# PRD：Pro 主题体验倒计时

日期：2026-06-27
状态：8.1.7 已确认方案，进入实现与 QA 回归
目标分支：`codex/appgrid-usage-tips`
目标范围：免费版 + Pro 主题体验
最低系统：macOS 14.0

## 0. 8.1.6 落地口径

- 到期不新增阻塞弹窗，只退出预览并恢复用户真实可用主题。
- 当前预览主题卡片只显示紧凑 `MM:SS`，不显示额外“体验中”字样。
- 倒计时文案不写死 5 分钟，从 `ProThemePreviewState.endsAt` 推导真实剩余时间。
- 29 个语言文件新增 `pro.theme.status.previewCountdown`，统一保留 `%time%` 占位符。

## 0.1 8.1.7 实验增补：暗色炫彩 / 亮色炫彩可调背景

本增补是 8.1.7 的新实验需求。它建立在 8.1.6 的 Pro 主题体验倒计时之上，不改变倒计时、购买、恢复购买、旧付费用户自动获得 Pro、免费预览不写入真实设置等既有口径。

### 0.1.1 产品目标

- 把现有“深蓝”主题升级为更现代的暗色液体渐变视觉，显示名称改为“暗色炫彩”。
- 把现有“炫彩”主题显示名称改为“亮色炫彩”，保留当前明亮、年轻、彩色的初始视觉方向。
- “暗色炫彩”和“亮色炫彩”都纳入 Pro 主题范围，继续复用现有 Pro 预览倒计时和解锁逻辑。
- 两个炫彩主题被选中时，在主题网格下方显示整行调色滑轨。用户拖动滑轨时，只改变 App Grid 背景的液体渐变色彩状态，不改变容器玻璃、图标、标签、拖拽、备注、布局、Pro 状态或购买逻辑。

### 0.1.2 命名与兼容

- UI 显示名变更：
  - `深蓝` -> `暗色炫彩`
  - `炫彩` -> `亮色炫彩`
- 如现有代码已有稳定主题内部 ID，应优先保留内部 ID，只改显示名和视觉 token，避免破坏用户已保存主题、QA 脚本、旧偏好值和回滚路径。
- 多语言必须同步新增或更新 29 个语言的主题显示名。译文应短、自然、可放进主题卡片；长语言允许最多两行，但不得挤掉 Pro 标识和选中状态。

### 0.1.3 调色滑轨

- 滑轨只在选中 `暗色炫彩` 或 `亮色炫彩` 时显示。
- 滑轨位置：主题卡片网格下方的 full-width 附加控制区，不嵌入单个主题卡片，不改变两列卡片高度。
- 滑轨区域建议高度控制在 44-56pt，底部保留至少 24pt 安全空白，不贴近设置窗口底部圆角。
- `暗色炫彩` 的滑轨只能在暗色可读范围内变化：无论拖到哪里，整体仍是深色背景，容器标题、标签、按钮和图标都保持足够对比。
- `亮色炫彩` 的滑轨只能在亮色可读范围内变化：无论拖到哪里，整体仍是明亮、干净、年轻的背景，不退化成暗黑主题。
- 免费用户体验这两个 Pro 主题时，滑轨调整只影响本次临时预览；未解锁 Pro 前不得把滑轨值写入真实持久化设置。
- Pro 用户或旧付费自动 Pro 用户调整滑轨后，滑轨值可以作为真实主题配置持久化。

### 0.1.4 视觉方向

- `暗色炫彩`：深色基底 + 多色液体流动感。它不是纯深蓝，也不是单一紫蓝渐变；应有高级、冷静、现代的色彩层次。
- `暗色炫彩` 默认初始视觉采用方案 1「极夜孔雀」：深青黑底，孔雀蓝与冷翠绿液体光带。滑轨初始位置应对应这套初始状态。
- `亮色炫彩`：明亮基底 + 多色液体流动感。它服务年轻、轻快、漂亮的审美，不应变成暗黑或低饱和灰脏效果。
- 单个容器继续保持统一玻璃面板，不在每个容器内部各自做强烈渐变；渐变主要属于整个 App Grid 背景。
- hover、选中、Pro 标识和滑轨 thumb 的颜色必须跟随主题适配，但不能牺牲可读性。

### 0.1.5 设置页布局调整

- 内容区顶部不再重复显示“主题”标题和“选择应用网格的背景主题。”短说明；Tab 已经表达当前位置，主题卡片和 Pro 状态行应整体上移，减少不必要的纵向滚动。
- 主题页内容整体上移，为底部滑轨留出空间。
- 主题说明文案保持简短，避免在 29 种语言下挤压主题卡片和滑轨。
- 主题卡片网格中，`暗色炫彩` 和 `亮色炫彩` 固定放在最下方最后一排：左侧为 `暗色炫彩`，右侧为 `亮色炫彩`。这两个可调主题在视觉上形成对称分组，下方整行滑轨自然归属于这一组。
- Pro 标识、主题名、选中勾三者不能互相挤压；长语言下优先保护主题名和选中状态。

### 0.1.6 不做范围

- 不改变 App Grid 的布局算法。
- 不改变容器玻璃的独立深浅开关。
- 不改变 Pro 购买流程、价格、恢复购买或旧用户权益。
- 不改变 8.1.6 已落地的倒计时机制。
- 方案确认前不直接落 App 代码；产品已选择方案 1「极夜孔雀」作为默认起点后，本阶段进入实现与 QA。

### 0.1.6a 同批小需求：新用户默认图标大小

- 初次安装、没有已有 `iconSize` 偏好的新用户，默认图标大小改为 `56`。
- 已有用户如果已经保存过图标大小，不做迁移、不覆盖、不重置。
- 该需求与 8.1.7 同批实现和回归，避免为小需求单独走一轮发布级 QA。

### 0.1.7 验收标准

- `PTC-16`：主题页中 `深蓝` 已显示为 `暗色炫彩`，`炫彩` 已显示为 `亮色炫彩`，29 种语言都不存在旧显示名遗漏。
- `PTC-17`：`暗色炫彩` 和 `亮色炫彩` 都按 Pro 主题处理，免费用户仍走 8.1.6 的预览倒计时。
- `PTC-18`：只有选中两个炫彩主题时才显示调色滑轨；其它主题不显示且不占位。
- `PTC-18a`：主题网格最后一排固定为左 `暗色炫彩`、右 `亮色炫彩`，其它主题不会插入这两个卡片之间。
- `PTC-19`：`暗色炫彩` 滑轨任何位置都保持暗色风格和足够文字对比。
- `PTC-20`：`亮色炫彩` 滑轨任何位置都保持亮色风格和足够文字对比。
- `PTC-21`：免费预览期间调色不写入真实主题设置；预览结束或切回免费主题后不残留脏数据。
- `PTC-22`：Pro 用户调色后可持久化，重启 App 后仍保持所选主题和滑轨状态。
- `PTC-23`：macOS 14 下主题页布局不裁切、不出现底部贴边、不因长语言挤压滑轨。
- `PTC-24`：已有保存为旧 `深蓝` / `炫彩` 的用户偏好仍能映射到新显示名和新视觉，不出现空主题或回退默认。
- `PTC-25`：新安装默认 `iconSize=56`；已有 `iconSize` 的用户不被覆盖。
- `PTC-26`：`亮色炫彩` 的默认滑轨位置为最左端；新用户、首次切到该主题、未保存过调色偏好的用户都从最左端初始视觉开始。

## 1. 摘要

为 Pro 主题的免费体验状态增加可见倒计时。

当前免费用户可以点击 Pro 专属主题并临时体验该主题。这个体验有时间限制，但界面没有清楚告诉用户还剩多久。体验结束后，App Grid 会回到用户真实可用的主题；如果用户不知道这是限时体验，很容易误以为主题保存失败、设置丢失，或者 Pro 权益逻辑不稳定。

本需求要求在现有主题页界面中增加一个轻量倒计时。倒计时必须以当前真实体验时长为准。当前已核实的代码基线是：每次 Pro 主题体验 5 分钟。如果后续产品决定调整体验时长，倒计时必须自动反映真实剩余时间，不允许在文案里写死“5 分钟”。

## 2. 当前产品事实

当前产品行为如下：

- 免费主题：默认、深蓝、黑色。
- Pro 主题：粉色、紫色、绿色、蓝色、炫彩。
- 免费用户点击 Pro 主题后，可以进入临时体验。
- 体验中的 Pro 主题不会写入用户真实保存的主题设置。
- 当前体验时长是 5 分钟。
- 体验中点击另一个 Pro 主题，会开始一轮新的体验。
- 体验中点击免费主题，会退出体验并保存该免费主题。
- 体验中购买或恢复 Pro 成功后，当前体验主题应成为用户真实保存的主题。

给研发定位用的当前代码事实：

- 体验时长当前定义为 `5 * 60`。
- QA 可以通过现有 Pro QA override 缩短体验时长。
- 主题页已经有轻量 Pro 状态行。
- 正在体验的 Pro 主题卡片已经有预览标识。

## 3. 问题

当前界面只告诉用户“正在体验 Pro 主题”，但没有告诉用户体验会持续多久、何时结束。

这会带来三个用户可感知问题：

1. 用户无法在体验结束前形成正确预期。
2. 用户可能把自动恢复误判为 bug 或设置保存失败。
3. Pro 转化语境变弱，因为用户没有明确理解“这是临时开放给你体验”。

## 4. 产品目标

### 4.1 用户目标

免费用户应该明确知道：

- 自己正在体验 Pro 主题。
- 这次体验是临时的。
- 当前还剩多少时间。
- 解锁 Pro 后可以继续保留该主题。

### 4.2 产品目标

产品应做到：

- 让 Pro 主题体验状态自解释。
- 降低体验结束时的困惑。
- 保持主题页克制、紧凑、原生。
- 不增加重营销界面，不增加额外决策步骤。

## 5. 不做范围

本需求不包含：

- 不把体验时长从 5 分钟改为 15 分钟。
- 不在开始体验前新增弹窗。
- 不在体验结束时新增阻塞弹窗。
- 不增加进度条、环形计时器、滑杆或大型倒计时组件。
- 不改变 Pro 购买流程。
- 不改变免费主题列表。
- 不改变哪些主题属于 Pro。
- 不改变免费用户的主题持久化规则。
- 不改变 App Grid 主题视觉。
- 不改变容器玻璃、App 图标、布局、拖拽、备注、排序、导入或导出行为。

如果产品决定调整体验时长，应作为独立产品决策处理。本 PRD 只要求倒计时反映真实配置的体验剩余时间。

## 6. 交互需求

### 6.1 主题页状态行

当免费用户正在体验 Pro 主题时，现有主题页 Pro 状态行必须显示剩余时间。

推荐中文显示：

```text
体验中 · 剩余 04:59
```

推荐英文显示：

```text
Previewing · 04:59 left
```

状态行仍应保留 Pro 价值提示，但倒计时必须直接可见，不能依赖 hover、tooltip 或二级面板。

可接受的紧凑中文备选：

```text
Pro 主题体验中 · 04:59
```

```text
剩余 04:59 · 解锁 Pro 后可永久保留
```

### 6.2 当前体验主题卡片

正在体验的 Pro 主题卡片，必须在现有 accessory 区域显示紧凑时间提示。

优先显示：

```text
04:59
```

如果空间允许，可显示：

```text
体验中 04:59
```

倒计时只作用于当前正在体验的 Pro 主题卡片。其它锁定的 Pro 主题继续显示普通 Pro 标识。

### 6.3 时间格式

倒计时格式必须稳定、易扫读：

- 体验剩余时间小于 1 小时时，使用 `MM:SS`。
- 秒数必须补齐两位。
- 示例：`05:00`、`04:59`、`01:05`、`00:09`。
- 不显示小数秒。
- 不显示负数时间。
- 到期后应退出体验状态，不能长期停留在 `00:00`。

以当前 5 分钟基线看，`MM:SS` 足够。如果未来产品把体验时长提高到 59 分钟以上，需另行决定是否改用小时格式。

### 6.4 开始体验

免费用户点击 Pro 主题时：

1. 立即开始主题体验。
2. App Grid 切换为该 Pro 主题效果。
3. 主题页状态行进入体验状态。
4. 被选中的 Pro 主题卡片显示倒计时。
5. 倒计时从真实配置体验时长开始。

当前基线下，初始可见值应接近 `05:00`。

### 6.5 体验中切换 Pro 主题

免费用户已经在体验 Pro 主题 A，此时点击 Pro 主题 B：

1. 体验主题切换为 B。
2. 倒计时为 B 重新开始。
3. A 的主题卡片恢复普通 Pro 锁定状态。
4. B 的主题卡片显示倒计时。

界面上不能同时出现两个主题卡片倒计时。

### 6.6 体验中选择免费主题

免费用户体验 Pro 主题时选择免费主题：

1. 体验立即结束。
2. 被选择的免费主题成为真实保存主题。
3. 倒计时消失。
4. 主题页恢复普通免费状态。

不需要警告弹窗。

### 6.7 体验到期

倒计时结束时：

1. Pro 主题体验自动结束。
2. App Grid 恢复到用户真实可用主题。
3. 倒计时消失。
4. 主题页恢复普通免费状态。

推荐轻量反馈：

```text
主题体验已结束
```

如果产品内已有轻量 inline 或 toast 反馈模式，可以复用。不要为到期新增阻塞弹窗。

### 6.8 体验中购买或恢复 Pro

用户在体验 Pro 主题时购买或恢复 Pro 成功：

1. 当前体验主题成为真实保存主题。
2. 倒计时消失。
3. 主题页进入已解锁状态。
4. Pro 主题卡片显示选中状态，而不是计时器。

用户不应在成功解锁后丢失正在体验的主题。

### 6.9 关闭与重新打开界面

倒计时应表示真实剩余时间，而不是界面可见时间。

用户可感知行为要求：

- 设置窗口关闭时，如果体验仍在进行，体验计时继续按现有规则运行。
- 用户在到期前重新打开设置页，倒计时显示当前真实剩余时间。
- 如果体验在设置页关闭期间到期，重新打开设置页后显示普通免费状态。
- 如果 App 退出并重启，除非现有体验系统已经支持恢复，否则本需求不要求恢复上次体验。

## 7. 信息架构

本功能归属：

```text
设置
└── 主题
    ├── Pro 状态行
    │   └── 体验倒计时
    └── 主题网格
        └── 当前 Pro 体验主题卡片倒计时
```

这是 Pro 主题体验的子行为，不是新的设置分区，也不是新的 Pro 管理页。

## 8. 用户旅程

### 8.1 首次体验

1. 免费用户打开“设置 > 主题”。
2. 用户点击一个 Pro 主题。
3. App Grid 切换到该主题。
4. 主题页显示 `体验中 · 剩余 05:00`。
5. 当前 Pro 主题卡片显示 `05:00`。
6. 用户知道这是临时体验。

### 8.2 体验结束

1. 用户正在体验 Pro 主题。
2. 倒计时到期。
3. App Grid 恢复到用户真实可用主题。
4. 主题页恢复免费状态文案。
5. 用户可看到轻量提示：主题体验已结束。

### 8.3 体验中解锁 Pro

1. 免费用户正在体验 Pro 主题。
2. 用户点击解锁 Pro。
3. 购买或恢复成功。
4. 当前体验主题成为真实保存主题。
5. 倒计时消失，界面显示已解锁状态。

### 8.4 体验中切换主题

1. 免费用户正在体验 Pro 主题 A。
2. A 上显示倒计时。
3. 用户点击 Pro 主题 B。
4. App Grid 切换到 B。
5. 倒计时在 B 上重新开始。
6. A 恢复普通 Pro 锁定状态。

## 9. 用户故事

- 作为免费用户，我想看到 Pro 主题体验还剩多久，以便理解为什么主题之后会消失。
- 作为免费用户，我想清楚知道当前正在体验哪一个主题，以便比较不同 Pro 主题。
- 作为免费用户，我想在切换另一个 Pro 主题时看到新的倒计时，以便知道体验已经重新开始。
- 作为潜在购买用户，我希望解锁 Pro 后继续保留正在体验的主题，以便购买前后的体验是连续的。
- 作为 QA，我希望能用缩短体验时长的方式验证倒计时，以便不用每次等待完整 5 分钟。

## 10. 文案需求

需要覆盖以下含义：

| 含义 | 中文草案 | 英文草案 |
|:---|:---|:---|
| 带剩余时间的体验状态 | `体验中 · 剩余 %@` | `Previewing · %@ left` |
| 卡片紧凑计时 | `%@` | `%@` |
| 体验结束反馈 | `主题体验已结束` | `Theme preview ended` |
| 解锁后保留提示 | `解锁 Pro 后可永久保留` | `Unlock Pro to keep it` |

说明：

- `%@` 表示格式化后的剩余时间，例如 `04:59`。
- 现有 Pro 主题体验文案可以复用，前提是状态足够清楚。
- 所有支持语言必须补齐本功能文案。
- 非中文、非英文语言不能混入中文或英文兜底文案。

## 11. 验收标准

PTC-01：免费用户点击任一 Pro 专属主题后，开始体验，并在主题页状态行看到倒计时。

PTC-02：免费用户正在体验的 Pro 主题卡片，在 accessory 区域显示紧凑倒计时。

PTC-03：倒计时以 `MM:SS` 显示真实剩余时间，且不会显示负数。

PTC-04：倒计时必须读取真实配置体验时长，不允许把界面文案写死为“5 分钟”或任何固定时长。

PTC-05：体验中从一个 Pro 主题切换到另一个 Pro 主题时，新主题重新开始倒计时，旧主题移除倒计时。

PTC-06：体验中选择免费主题时，立即结束体验、隐藏倒计时，并保存该免费主题。

PTC-07：体验时间到期后，界面退出体验状态、隐藏倒计时，并恢复用户真实可用主题；不得弹出阻塞弹窗。

PTC-08：体验中解锁 Pro 成功后，当前体验主题成为真实保存主题，倒计时消失。

PTC-09：体验中关闭并重新打开设置页，如果体验尚未到期，应显示真实剩余时间。

PTC-10：体验在设置页关闭期间到期后，重新打开设置页不得显示过期倒计时。

PTC-11：Pro 用户和 legacy Pro 用户不显示 Pro 主题倒计时，按普通已解锁主题行为展示。

PTC-12：所有支持语言都必须补齐倒计时和体验结束文案，不得出现占位符泄漏或混合语言兜底。

PTC-13：倒计时每秒变化时，不得造成主题卡片宽高跳动或主题网格布局抖动。

PTC-14：倒计时在浅色和深色系统外观下都必须清晰可读。

PTC-15：QA 可以通过现有缩短体验时长的 QA 路径验证倒计时到期行为。

## 12. QA 范围

必须覆盖以下场景：

1. 免费用户分别体验每个 Pro 主题。
2. 免费用户在两个 Pro 主题之间切换。
3. 免费用户从 Pro 主题体验切换到免费主题。
4. 免费用户等待体验到期。
5. 免费用户体验中关闭并重新打开设置页。
6. 免费用户关闭设置页后等待体验到期，再重新打开设置页。
7. 免费用户体验中购买或恢复 Pro。
8. Pro 用户选择 Pro 主题。
9. legacy Pro 用户选择 Pro 主题。
10. 29 种语言文案完整性。
11. 浅色和深色系统外观。
12. macOS 14 兼容性。

推荐 QA 加速方式：

- 使用现有缩短体验时长的 QA override 验证到期链路，不必每次等待完整生产时长。
- 至少包含一条测试：倒计时从缩短时长开始，进入最后几秒，到期后退出体验，并且界面不残留过期计时。

## 13. 发布说明草案

中文：

```text
Pro 主题体验现在会显示剩余时间，体验结束前后状态更清楚。
```

英文：

```text
Pro theme previews now show remaining time, making temporary previews easier to understand.
```

## 14. 待确认决策

OD-01：生产体验时长保持当前 5 分钟，还是作为独立产品决策改为其它时长。

OD-02：体验结束时只通过状态行恢复表达，还是额外复用现有轻量 toast。

OD-03：主题卡片 accessory 最终采用纯时间 `04:59`，还是在空间允许时采用 `体验中 04:59`。