소스 검색

docs: PRD 两层结构落地(抽 docs/prd/拼团漏斗.md)+ CLAUDE 规则7 PRD先行

docs/01 §4 收敛为模块索引、§8 拆平台级验收;模块详规/验收入模块 PRD;
docs/07 树补 prd/。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
tianyu.chu 1 개월 전
부모
커밋
b787de28b7
6개의 변경된 파일75개의 추가작업 그리고 50개의 파일을 삭제
  1. 3 0
      CHANGELOG.md
  2. 2 0
      CLAUDE.md
  3. 13 48
      docs/01-产品需求-MVP.md
  4. 2 1
      docs/07-项目结构与模块.md
  5. 1 1
      docs/08-迭代与发布.md
  6. 54 0
      docs/prd/拼团漏斗.md

+ 3 - 0
CHANGELOG.md

@@ -8,6 +8,9 @@
 - **PRD(`docs/01`)对齐现状 + 补完整性**:
   - 对齐:阶段改「已内网上线」、补 06-26/06-29 修订记录;§3 范围与 §8 验收补入**趋势视图**;§7 去掉与趋势矛盾的"不做自定义日期范围"(趋势已支持自定义起止);空态文案「数据缺失」→「暂无数据」。
   - 补充:§1.2 业务目标与成功指标、§1.3 目标用户与典型场景、§1.4 访问与权限(现状内网无鉴权、对外前须补)。
+- **PRD 两层结构落地 + PRD 先行入铁律**:
+  - 抽出模块级 PRD **`docs/prd/拼团漏斗.md`**(漏斗定义/时间能力/漏斗视图/趋势视图/模块验收);`docs/01` §4 收敛为**模块索引表**、§8 验收拆为"平台级"(导航/IA/不补零),模块功能级验收移入模块 PRD。
+  - `CLAUDE.md` 加**规则 7「新模块 PRD 先行」**:开新模块前先登记 + 写模块 PRD 对齐再写码;docs/08 §3 同步"已落地"。
 - **`docs/08-迭代与发布` 新增**:沉淀迭代方式(端到端垂直切片 + 闭环流程 + PRD 先行)、PRD 两层结构与拆分时机、**版本方案**(里程碑版 v1.0 起、每模块 minor+1,API 对外供数时另走 SemVer)、三层记录区分、发布收尾 7 步清单。PRD 顶部加"版本"栏 + 修订记录加"版本"列(MVP 期留空);README/docs07 索引补 docs/08。
 - **`/docs-check` 全套复扫**(只读、未派子代理):修掉 3 处残留漂移——`docs/06` 鉴权交叉引用 §7→§1.4、`docs/02` 空态措辞对齐「暂无数据」、`docs/02` §5 标注 `/query` 不含自定义范围(趋势见 §5.1);其余(接口/口径/表结构/IA/结构/部署)均一致。
 

+ 2 - 0
CLAUDE.md

@@ -21,3 +21,5 @@
    | 目录/模块/运行/部署架构 | `docs/07`、`docs/02 §10`、`README`、`infra` |
 
    纯内部实现细节(不改契约/口径/IA/视觉/结构)无需动文档。定期或发版前可跑 `/docs-check` 审计漂移。
+
+7. 新模块 PRD 先行——开一个新的分析模块 / L3 报表(垂直切片)前,**先**在 `docs/01` §4 状态表登记 + 写模块级 PRD(`docs/prd/<模块>.md`:定义/口径/时间能力/页面/验收)并对齐,**再**写代码;不"边做边补"。小改/修复不受此限(照规则 6 收尾即可)。迭代与发布流程见 `docs/08`。

+ 13 - 48
docs/01-产品需求-MVP.md

@@ -97,7 +97,7 @@ hs-data 是一个**面向内部的一站式数据平台门户**:把数仓产出
 
 **L1-1 行为分析**(本期唯一有可用模块的域)
 - L2 漏斗分析 **[可用]**
-  - L3 **拼团漏斗(固定)[可用,MVP]** — 见 §4 详规
+  - L3 **拼团漏斗(固定)[可用,MVP]** — 详规见 [`docs/prd/拼团漏斗.md`](prd/拼团漏斗.md)
   - L3 其他固定漏斗(下单漏斗…)[待开发]
   - L3 自助漏斗(用户选事件)[远期,需事件级数据]
 - L2 留存分析 / 路径分析 / 事件分析 / 分布分析 / 归因分析(均 [待开发])
@@ -127,51 +127,18 @@ hs-data 是一个**面向内部的一站式数据平台门户**:把数仓产出
 
 **B. 拼团漏斗(端到端可用)** — 落点 `行为分析 > 漏斗分析 > 拼团漏斗`,页内含 **`漏斗 / 趋势` 两视图**
 - **漏斗视图**:固定 5 步拼团转化漏斗,展示每层 UV、相邻层转化率/流失率;时间 单日(可回溯历史)/ 近 7 天 / 近 30 天。
-- **趋势视图**:同 5 个事件的**按日折线**(UV + 相邻转换率),范围 近 30 天 / 自定义起止(见 §4.4)。
+- **趋势视图**:同 5 个事件的**按日折线**(UV + 相邻转换率),范围 近 30 天 / 自定义起止(详见 `docs/prd/拼团漏斗.md`)。
 - 数据来自数据服务层 PostgreSQL 的预聚合宽表(见 `docs/03` §11)。
 
-## 4. 拼团漏斗模块详规
+## 4. 模块详规(模块级 PRD)
 
-### 4.1 漏斗定义
+平台采用**两层 PRD**:本文(平台级)保留定位/IA/路线/状态;**每个端到端模块的详规独立成册**,放 `docs/prd/<模块>.md`(结构与拆分约定见 `docs/08` §3)。
 
-固定的**拼团转化漏斗**,5 步固定顺序:
-
-**启动 → 曝光 → 拼团详情 → 下单 → 成功**(`start / show / detail / order / paid`)。
-
-- 每层 UV = 该步骤事件在所选周期内的独立用户数。
-- 非递进、不要求按序完成;步骤顺序只影响展示与相邻转化率口径。
-- 相邻层转化率 = 当前层 UV / 上一层 UV;相邻层流失率 = 1 − 转化率。
-- 第 1 层转化率/流失率为空(展示"—",不为 100%/0)。
-
-### 4.2 时间能力
-
-三种周期(数据 **T+1**,最大可查日**始终为昨日**;今天不可查):
-
-- **单日**:看某一天的当日漏斗。配**常驻日历**,默认昨日,可回溯任意历史日;上限昨日(今天/未来禁选)。
-- **近 7 天 / 近 30 天**:滚动窗口,取最新 as-of 快照(截至昨日);**无历史**(数据源只保留最新一行)。
-
-取数路由与字段见 `docs/02` §5(v3)与 `docs/03` §11。
-
-### 4.3 页面说明(视觉/交互定稿见 `docs/04`)
-
-L3 页含 **`漏斗 / 趋势` 两视图 Tab**。
-
-**漏斗视图**:
-
-- **时间控件**(标题行右):单日(默认昨日,按钮只显日期)+ 近 7 天 / 近 30 天 segmented。
-- **结果图表区**:ECharts 漏斗图,每层 UV + 块比例。
-- **结果表格区**:步骤名 / UV / 转化率 / 流失率。
-- **范围文案**:单日不显;近 7/30 天显示 `起 ~ 止` 日期范围。
-- **状态**:`ready` 出图表+表格;`missing` 出"暂无数据"空态(**不补零**);传输错误出错误态。
-
-### 4.4 趋势视图(按日折线)
-
-同一批 5 个事件的**按日**时间序列,数据源即 `ads_trd_group_funnel_daily`(天然时序)。
+| 模块 | 详规 | 状态 |
+|---|---|---|
+| 拼团漏斗(漏斗 + 趋势两视图) | [`docs/prd/拼团漏斗.md`](prd/拼团漏斗.md) | 可用(MVP) |
 
-- **两张折线**:事件 UV(5 步)+ 相邻转换率(4 段),图例可点开关。
-- **范围**:近 30 天(默认,相对最新可用日)/ 自定义起止(上限昨日)。
-- 前导全 0 天(上线前)裁掉;范围内缺口日断线、**不补零**。
-- 接口见 `docs/02` §5.1 / `docs/06` §3。
+> 新模块动工前先在此表登记 + 建对应 `docs/prd/<模块>.md`(**PRD 先行**,见 `docs/08` §2)。
 
 ## 5. 演进路线图
 
@@ -200,19 +167,17 @@ L3 页含 **`漏斗 / 趋势` 两视图 Tab**。
 
 - **自助分析**:任意步骤漏斗、自定义事件/维度组合(需事件级数据,远期)。
 - 严格顺序漏斗、转化窗口、用户/事件属性筛选、复杂人群圈选。
-- 漏斗视图的自定义日期范围(漏斗周期固定 单日/近7天/近30天;**趋势视图已支持自定义起止**,见 §4.4)。
+- 漏斗视图的自定义日期范围(漏斗周期固定 单日/近7天/近30天;**趋势视图已支持自定义起止**,见 `docs/prd/拼团漏斗.md`)。
 - 实时今天数据(T+1)。
 - 指标体系、画像体系、数据看板、营销触达的**任何实际功能**(仅占位)。
 - 指标口径定义后台 / 数据治理 / 工作台等中台门面(内部工具不做主导航域)。
 - 报表保存/分享/订阅;多数据源接入;Redis 等额外加速层。
 
-## 8. 验收标准
+## 8. 验收标准(平台级)
 
 - 平台导航包含 5 个 L1 能力域(行为分析/指标体系/画像体系/数据看板/营销触达);拼团漏斗可用,其余进入后展示"待开发"占位。
 - 导航分组可手动展开/折叠、多个同时展开;进入某页自动展开其所在分支。
-- 拼团漏斗展示固定 5 步(启动→曝光→拼团详情→下单→成功)的每层 UV、相邻层转化率/流失率;第 1 层转化率展示"—"。
-- 时间可选 单日(含历史回溯)/ 近 7 天 / 近 30 天;**最大可选日为昨日**,今天及未来不可选/不可查(前端禁选,后端拒绝)。
-- 单日可选历史日;近 7/30 天展示 as-of 截至日。
-- **趋势视图**:漏斗/趋势 两视图可切换;趋势出 UV 与相邻转换率两张按日折线,范围 近 30 天 / 自定义起止;前导全 0 天裁掉,范围内缺口日断线(不补零)。
-- 数据缺失时**不静默补零**,展示明确的「**暂无数据**」空态。
+- 数据缺失时**不静默补零**,展示明确的「**暂无数据**」空态(全平台一致)。
 - 信息架构可承载未来扩展:新分析模型落 L2、新报表落 L3,不破坏顶层 L1。
+
+> 各模块的功能级验收在其模块 PRD 内(如拼团漏斗见 [`docs/prd/拼团漏斗.md`](prd/拼团漏斗.md) §5)。

+ 2 - 1
docs/07-项目结构与模块.md

@@ -16,7 +16,8 @@ hs-data/
 │   └── api/            # 后端只读查询服务(FastAPI + SQLAlchemy async + asyncpg)
 ├── packages/
 │   └── api-types/      # 由后端 OpenAPI 生成的 TS 类型(契约同步用)
-├── docs/               # 产品 / 技术 / 数据契约 / 设计 / 协作 / 接口 / 本文
+├── docs/               # 平台级 PRD / 技术 / 数据契约 / 设计 / 协作 / 接口 / 结构 / 发布
+│   └── prd/            # 模块级 PRD(每个端到端模块一份详规,如 拼团漏斗.md)
 ├── infra/              # 部署与本地基础设施脚本(look.sh / serve*.sh / serve.py / docker-compose)
 ├── CLAUDE.md           # 开发硬约束(给 AI 与人)
 └── CHANGELOG.md        # 改动留痕(按日期,顶部最新)

+ 1 - 1
docs/08-迭代与发布.md

@@ -23,7 +23,7 @@
 - **平台级 PRD**(`docs/01`,保留):定位、IA(5 能力域)、路线图、全局约束(数据现实/访问权限)、**各模块"可用/待开发"状态总表**。精简、稳定、少改。
 - **模块级 PRD**(`docs/prd/<模块>.md`,按需新增):每个端到端模块一份详规(定义/口径/时间能力/页面/验收,即现在 `docs/01` §4 的形态)。`docs/01` 只留一句定位 + 链接。
 
-**拆分时机**:等**第二个模块动工**时,把现 `docs/01` §4 拼团漏斗详规抽成 `docs/prd/拼团漏斗.md`,§4 收敛为索引。**当前单模块不拆**(拆了是空架子)。
+**现状(已落地)**:`docs/01` §4 已收敛为**模块索引表**;拼团漏斗详规独立成册 [`docs/prd/拼团漏斗.md`](prd/拼团漏斗.md)。新模块动工前,先在 §4 表登记 + 建对应 `docs/prd/<模块>.md`(**PRD 先行**,见 §2 与 CLAUDE.md 规则 7)。
 
 ## 4. 版本方案
 

+ 54 - 0
docs/prd/拼团漏斗.md

@@ -0,0 +1,54 @@
+# 模块 PRD:拼团漏斗
+
+> 模块级详规。平台定位/IA/路线见 [docs/01](../01-产品需求-MVP.md);取数契约见 [docs/02](../02-技术架构.md) §5,数据表见 [docs/03](../03-数据契约.md) §11,视觉/交互见 [docs/04](../04-设计规范.md),接口见 [docs/06](../06-接口文档.md)。
+
+| 项 | 内容 |
+|----|----|
+| 落点 | `行为分析 > 漏斗分析 > 拼团漏斗`(L3) |
+| 状态 | **可用(MVP,已内网上线)** |
+| 视图 | `漏斗`(固定 5 步快照)+ `趋势`(按日折线)两 Tab |
+
+## 1. 漏斗定义
+
+固定的**拼团转化漏斗**,5 步固定顺序:
+
+**启动 → 曝光 → 拼团详情 → 下单 → 成功**(`start / show / detail / order / paid`)。
+
+- 每层 UV = 该步骤事件在所选周期内的独立用户数。
+- 非递进、不要求按序完成;步骤顺序只影响展示与相邻转化率口径。
+- 相邻层转化率 = 当前层 UV / 上一层 UV;相邻层流失率 = 1 − 转化率。
+- 第 1 层转化率/流失率为空(展示"—",不为 100%/0)。
+
+## 2. 时间能力
+
+三种周期(数据 **T+1**,最大可查日**始终为昨日**;今天不可查):
+
+- **单日**:看某一天的当日漏斗。配**常驻日历**,默认昨日,可回溯任意历史日;上限昨日(今天/未来禁选)。
+- **近 7 天 / 近 30 天**:滚动窗口,取最新 as-of 快照(截至昨日);**无历史**(数据源只保留最新一行)。
+
+取数路由与字段见 `docs/02` §5(v3)与 `docs/03` §11。
+
+## 3. 漏斗视图(视觉/交互定稿见 `docs/04`)
+
+- **时间控件**(标题行右):单日(默认昨日,按钮只显日期)+ 近 7 天 / 近 30 天 segmented。
+- **结果图表区**:ECharts 漏斗图,每层 UV + 块比例。
+- **结果表格区**:步骤名 / UV / 转化率 / 流失率。
+- **范围文案**:单日不显;近 7/30 天显示 `起 ~ 止` 日期范围。
+- **状态**:`ready` 出图表+表格;`missing` 出「暂无数据」空态(**不补零**);传输错误出错误态。
+
+## 4. 趋势视图(按日折线)
+
+同一批 5 个事件的**按日**时间序列,数据源即 `ads_trd_group_funnel_daily`(天然时序)。
+
+- **两张折线**:事件 UV(5 步)+ 相邻转换率(4 段),图例可点开关。
+- **范围**:近 30 天(默认,相对最新可用日)/ 自定义起止(上限昨日)。
+- 前导全 0 天(上线前)裁掉;范围内缺口日断线、**不补零**。
+- 接口见 `docs/02` §5.1 / `docs/06` §3。
+
+## 5. 验收(本模块)
+
+- 漏斗展示固定 5 步(启动→曝光→拼团详情→下单→成功)每层 UV、相邻层转化率/流失率;第 1 层转化率展示"—"。
+- 时间可选 单日(含历史回溯)/ 近 7 天 / 近 30 天;**最大可选日为昨日**,今天及未来不可选/不可查(前端禁选、后端拒绝)。
+- 单日可选历史日;近 7/30 天展示 as-of 截至日。
+- `漏斗 / 趋势` 两视图可切换;趋势出 UV 与相邻转换率两张按日折线,范围 近 30 天 / 自定义起止;前导全 0 天裁掉,范围内缺口日断线(**不补零**)。
+- 数据缺失时**不静默补零**,展示明确的「暂无数据」空态。