推进活动列表第一刀与联调回归

2026-04-03 19:33:16 +08:00
parent b09c21c814
commit 527b4c78a9
34 changed files with 3094 additions and 224 deletions
--- a/doc/gameplay/活动卡片列表最小产品方案.md
+++ b/doc/gameplay/活动卡片列表最小产品方案.md
@@ -0,0 +1,304 @@
+# 活动卡片列表最小产品方案
+> 文档版本：v1.2
+> 最后更新：2026-04-03 19:26:23
+
+## 1. 当前定位
+
+当前阶段“活动卡片列表页”第一刀已落地，当前文档转为：
+
+1. 第一刀范围说明
+2. 当前最小字段口径
+3. 当前联调回归重点
+
+也就是说，这份文档当前是：
+
+**第一刀已完成后的最小产品方案文档**
+
+---
+
+## 2. 当前阶段边界
+
+### 2.1 当前已完成
+
+- 独立活动列表页：`/pages/events/events`
+- 最小筛选：`全部 / 体验`
+- 最小卡片展示
+- 列表跳转活动详情页
+- 首页补“活动列表”独立入口
+
+### 2.2 当前不做
+
+- 不重构首页现有卡片入口
+- 不设计复杂运营样式
+- 不展开 `presentation schema`
+- 不展开 `content bundle` 明细
+- 不直接下发报名、签到、排行榜等复杂前台流程
+
+---
+
+## 3. 最小字段表
+
+以下字段按“当前第一刀已使用的最小口径”划分。
+
+### 3.1 必需字段
+
+- `eventId`
+  - 活动唯一标识
+- `title`
+  - 活动主标题
+- `subtitle`
+  - 副标题或活动短说明
+- `summary`
+  - 卡片摘要
+- `status`
+  - 活动状态
+- `timeWindow`
+  - 活动时间窗口摘要
+- `ctaText`
+  - 主动作文案
+
+### 3.2 推荐字段
+
+- `coverUrl`
+  - 封面图
+- `isDefaultExperience`
+  - 是否默认体验活动
+- `eventType`
+  - 活动类型摘要
+- `currentPresentation`
+  - 当前展示版本摘要
+- `currentContentBundle`
+  - 当前内容包摘要
+
+### 3.3 可选字段
+
+- `locationName`
+  - 地点摘要
+- `tagText`
+  - 轻标签
+- `participantHint`
+  - 人群或参与提示
+- `ruleHint`
+  - 规则提示
+
+当前阶段不建议为了列表页再额外增加复杂字段。
+
+---
+
+## 4. 字段展示建议
+
+### 4.1 卡片主信息
+
+- 主标题：`title`
+- 副标题：`subtitle`
+- 摘要：`summary`
+
+### 4.2 卡片状态信息
+
+- 状态：`status`
+- 时间：`timeWindow`
+- 主动作：`ctaText`
+
+### 4.3 卡片轻运营信息
+
+- 封面：`coverUrl`
+- 体验标识：`isDefaultExperience`
+- 展示版本摘要：`currentPresentation`
+- 内容包摘要：`currentContentBundle`
+
+当前阶段只建议做“摘要显示”，不要做复杂 schema 级解释。
+
+---
+
+## 5. 缺字段降级策略
+
+活动卡片列表属于前台浏览层，必须允许后端阶段性缺字段时仍可工作。
+
+### 5.1 标题缺失
+
+- `title` 缺失时：显示 `未命名活动`
+
+### 5.2 副标题缺失
+
+- `subtitle` 缺失时：整行不显示
+
+### 5.3 摘要缺失
+
+- `summary` 缺失时：显示 `当前暂无活动摘要`
+
+### 5.4 状态缺失
+
+- `status` 缺失时：显示 `状态待确认`
+- 不影响点击进入详情页
+
+### 5.5 时间窗口缺失
+
+- `timeWindow` 缺失时：显示 `时间待公布`
+
+### 5.6 CTA 缺失
+
+- `ctaText` 缺失时：统一回退成 `查看详情`
+
+### 5.7 封面缺失
+
+- `coverUrl` 缺失时：使用默认卡片背景，不阻断渲染
+
+### 5.8 `currentPresentation` 缺失
+
+- 显示：`当前未声明展示版本`
+
+### 5.9 `currentContentBundle` 缺失
+
+- 显示：`当前未声明内容包版本`
+
+### 5.10 体验标识缺失
+
+- `isDefaultExperience` 缺失时：按普通活动处理
+
+---
+
+## 6. 最小页面结构建议
+
+当前结构已按第一刀最小版本落地。
+
+建议的最小结构如下：
+
+```text
+活动列表页
+├─ 顶部说明区
+│  ├─ 标题
+│  ├─ 频道/地区摘要
+│  └─ 当前状态说明
+├─ 筛选区
+│  ├─ 全部
+│  ├─ 体验活动
+│  ├─ 进行中
+│  ├─ 即将开始
+│  └─ 已结束
+├─ 卡片列表区
+│  ├─ 活动卡片
+│  ├─ 活动卡片
+│  └─ 活动卡片
+└─ 空状态 / 错误状态
+```
+
+当前第一刀阶段保留这套最小结构，不扩复杂分组和复杂运营区。
+
+---
+
+## 7. 最小卡片状态建议
+
+### 7.1 默认体验活动
+
+- 标识：`体验`
+- 主动作：`进入体验`
+
+### 7.2 进行中
+
+- 标识：`进行中`
+- 主动作：`进入活动`
+
+### 7.3 即将开始
+
+- 标识：`即将开始`
+- 主动作：`查看详情`
+
+### 7.4 已结束
+
+- 标识：`已结束`
+- 主动作：`查看详情`
+  或
+- `查看回顾`
+
+---
+
+## 8. 与当前架构的关系
+
+活动卡片列表层只消费轻摘要，不直接消费后台复杂生产对象。
+
+建议关系保持为：
+
+```text
+Event
+-> EventRelease
+-> currentPresentation / currentContentBundle / runtime 摘要
+-> 活动卡片列表层
+```
+
+前端列表层当前只认：
+
+- 活动摘要
+- 当前状态
+- 轻运营摘要
+- 主动作文案
+
+不要把：
+
+- 原始 `EventPresentation schema`
+- 原始 `ContentBundle` 明细
+- backend 内部生产对象
+
+直接推到卡片列表层。
+
+---
+
+## 9. 与活动详情页的分工
+
+### 9.1 活动卡片列表层
+
+负责：
+
+- 浏览
+- 粗筛
+- 判断要不要进入活动详情页
+
+### 9.2 活动详情页
+
+负责：
+
+- 活动介绍
+- 展示版本摘要
+- 内容包摘要
+- 准备页入口
+- 后续更深的运营信息
+
+这样列表层可以一直保持轻。
+
+---
+
+## 10. 当前阶段输出物
+
+当前第一刀的输出物已经包括：
+
+1. 最小字段表
+2. 缺字段降级规则
+3. 最小页面结构落地
+4. 列表页到详情页的最小跳转链
+
+当前阶段不应继续包括：
+
+- 列表页重构
+- 卡片系统深度样式扩张
+- 复杂运营专区方案
+- 更多玩家侧新入口
+
+---
+
+## 11. 下一步建议
+
+当前第一刀之后，下一步建议按下面顺序推进：
+
+1. 先做联调回归与小范围修复
+2. 后端继续收口字段稳定性和默认值
+3. 前端确认分组和卡片信息层级是否顺手
+4. 再决定是否进入第二刀产品扩展
+
+---
+
+## 12. 一句话结论
+
+当前“活动卡片列表最小产品方案”已从准备阶段进入第一刀落地阶段：
+
+**独立列表页 + 最小筛选 + 最小卡片字段 + 跳详情页链路**
+
+接下来先做联调回归和小范围修复，不直接扩第二刀。