活动需求分析与技术设计（导航）

本文件是导航入口，每步详细内容在 steps/ 子目录中按需加载。

强制要求：所有新活动代码必须严格遵循以下规范，不可跳过：

coding-style — 活动模块编码规范（分层职责、接口变更同步等）

go-style 及 go-style-*.md — 通用 Go 编码规范

testing-style — 测试规范

端到端流程 + 数据契约图

flowchart LR
    S0["Step 0<br/>prd.md"] --> S1
    S1["Step 1 摘要<br/>§A-§H"]
    S1 -.§A/§B/§D 有新资源.-> S2["Step 2<br/>资源占位"]
    S1 --> S3
    S2 --> S3
    S3["Step 3<br/>technical_design.md<br/>§3时序 §4外部 §6存储 §9配置"]
    S3 --> S4["Step 4<br/>wiki 上传"]
    S3 --> S5["Step 5<br/>activity_info.json"]
    S1 -.§E actcfg 清单.-> S5
    S1 -.§D SpecialInfo.-> S5
    S5 --> S6["Step 6<br/>脚手架 9 文件"]
    S6 --> S7["Step 7<br/>编码 service/hook"]
    S3 -.§3/§4/§6.-> S7
    S7 --> S8["Step 8<br/>openapi.yaml"]
    S7 --> S9["Step 9<br/>CLAUDE.md"]
    S8 --> S9
    S9 --> S10["Step 10<br/>埋点"]
    S9 --> S11["Step 11<br/>单测"]

    style S1 fill:#fef3c7
    style S3 fill:#fef3c7
    style S5 fill:#dbeafe
    style S7 fill:#dbeafe

读法：实线 = 顺序依赖，虚线 = 跨步数据契约引用。黄色 = 设计类产出，蓝色 = 落地类产出。任一步进入前先看虚线标签确认上游契约是否就绪。

⚠️ 逐步确认原则（CRITICAL）：每一步完成后必须停下来，输出结果摘要，明确等待用户确认后才能进入下一步。 禁止在任何步骤间自动推进，无论上下文中是否有计划或已知的下一步。

❌ 反例（禁止）：用户说"一次性把 prd.md 和 technical_design.md 都做完"，AI 连续生成两份文档后直接开始生成 activity_info.json——这违反本原则。即使用户指示"一次性做完"，仍必须在每步完成后停顿，输出本步摘要并等待用户回复确认。

Step 导航表

每步进入时 Read 对应的 steps 文件。若子文件缺失，参考 git 历史恢复。

Step	产物 / 用途	详细说明
0	飞书文档 → `prd.md`（唯一需求真相源）	steps/step0-fetch-prd.md
1	模块 / 接口 / SpecialInfo / actcfg 清单 + 完整性检查 + 歧义澄清	steps/step1-analyze.md
2	新资源占位（可选）	steps/step2-placeholder.md
3	`technical_design.md`（完整技术方案，含章节裁剪）	steps/step3-tech-design.md
4	上传技术文档到飞书 wiki	steps/step4-upload-wiki.md
5	`activity_info.json`（运营配置）	steps/step5-activity-info.md
6	脚手架（9 个标准文件）	steps/step6-scaffold.md
7	按模块实现编码	steps/step7-coding.md
8	`openapi.yaml`（OpenAPI 3.1，可选）	steps/step8-openapi.md
9	`CLAUDE.md`（AI 快速查阅手册，编码后生成）	steps/step9-claude-md.md
10	埋点实现	steps/step10-sensor.md
11	单元测试（覆盖率 ≥ 90%）	steps/step11-test.md

Step 跳过判定

下列 Step 在特定条件下可跳过；每步入口需先核对本表。未列出的 Step 均为必执行。

Step	可跳过条件	跳过后果
Step 2（新资源占位）	prd.md 中所有礼物 / 道具 / 称号均有现成 ID，无 "待定" 或新资源	直接进入 Step 3；technical_design.md 不留 TBD
Step 4（上传 wiki）	文档仅本地使用（如调试用临时方案）	跳过；团队不可检索
Step 8（openapi.yaml）	联调文档 §9.4 已含完整 req/rsp JSON 且无需导入 API 平台	跳过；前端仅依赖 technical_design.md
Step 10（埋点）	prd.md 无"数据需求"章节 / 运营明确不需要埋点	跳过；数据看板缺失

质量门禁

G1-G4 四个强制门禁（需求完整性 / 配置校验 / 编码自查 / 覆盖率）详见 references/quality-gates.md。门禁不可跳过，失败项必须修复后再进入下一步。

关键决策原则

以下原则跨步生效，不在单个 step 文件中重复：

prd.md 是唯一真相源：所有数值、规则、道具 ID 均从 prd.md 提取，不凭记忆或猜测。
actcfg 技能优先：生成任何 widget 配置前，必须先读取对应的 /actcfg:* 子技能模板；不得凭记忆拼写 JSON key。
接口变更同步四文件：router.go / service.go / store/{req,resp}.go / openapi.yaml 必须同时维护。
big_pack_list 的 chip 同时注册到 collect_chip：以 reward_type="collect_chip" 发放的 chip（含大礼包）必须在 collect_chip 有对应条目。
技术文档目标位置固定：/lark-doc 创建至「业务支持-服务器 → 项目与交付 → 方案设计 → 运营活动 → 年份 → 季度」，不创建到需求文档节点下。
飞书文档 Mermaid 必须单独补充：lark-cli docs +create 会静默丢弃 mermaid 代码块，需用 whiteboard 机制补充（见 Step 4）。
常驻活动走独立分支流程：is_resident_act: true 的活动按月增量更新，参考 app/activity/resident/monthly_flower/ 标杆。

actcfg 速查

完整「需求特征 → 配置区域 → 子技能」映射以及使用规则见 references/actcfg-map.md（权威清单，Step 1 §1.5 / Step 5 配置生成均 Read 此文件）。

参考实现

新活动标杆：app/activity/2026/spring_outing_play/ / app/activity/2026/brain_teasers/
常驻活动标杆：app/activity/resident/monthly_flower/
示例与校验脚本：examples/prd_sheet_to_markdown.py / examples/validate_activity_info.py

使用方式：用户提供飞书需求文档链接或内容，按 Step 导航表逐步推进——每步完成后等待用户确认，收到确认后再进入下一步。

activity-design