docs: 对齐现状,清 v1 残留(bitmap/15天/AntD/四态)

docs/02 §3/4/7/8、docs/05 §5/6/7、docs/03 §7 更新到拼团两表 + shadcn +
ready/missing;平台更名 数据服务平台→数据平台 的剩余文档引用一并落实。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

CHANGELOG.md

@@ -5,6 +5,11 @@
 ## 2026-06-25
 
 ### 变更
+- **文档对齐现状(清 v1 残留)**:几次 pivot(bitmap→拼团两表、AntD→shadcn、四态→两态)后,周边文档段没回头清。本次对齐:
+  - `docs/02` §3/§4(前端/后端职责)、§7(性能)、§8(测试):由 bitmap / 15 天自定义范围 / Ant Design / 步骤参数 → **拼团两表 + shadcn + ready/missing + period 取列**。
+  - `docs/05` §5/§6(前后端 agent)、§7(数据状态):同步到两表 + shadcn + 两态。
+  - `docs/03` §7:标注当前两表源**只用 `ready`/`missing`**,`partial`/`invalid` 属后续 bitmap 方案(暂不落地)。
+  - 保留有意内容:历史修订注、"不读 bitmap"、后续泛用漏斗段、"数据服务**层**"(PG 存储术语)。
 - **平台更名「数据服务平台」→「数据平台」**:把"数据服务"一词留给将来的**对外供数 / API 层**(业界 OneService = 统一数据服务,该词语义本属 API 层,不该占在看数平台上)。改顶栏品牌、`index.html` / `document.title`、`package.json`、`docs/01-05` 的平台名引用;**保留"数据服务层"**(PG 存储层术语,不动)。`docs/01` §1 加命名约定。
 - **时间边界条收尾**:去掉"· 不含今日";**单日不显示任何时间文案**(日期已在按钮上),仅近 7/30 天显示日期范围。
 

docs/02-技术架构.md

@@ -47,28 +47,25 @@ MVP 阶段不拆分多个 Git 仓库。前后端、文档和本地基础设施
 
 ## 3. 前端职责
 
-前端负责产品交互和展示：
+前端负责产品交互和展示(拼团固定漏斗,v3):
 
-- 漏斗步骤选择。
-- 时间范围选择。
-- 自定义时间最大 15 天限制。
-- 今天不可选或不可提交。
+- 周期选择:单日(可回溯历史日,上限昨日)/ 近 7 天 / 近 30 天。
+- 单日的历史日期不可选今天及未来(T+1)。
 - 请求后端漏斗查询接口。
-- 使用 ECharts 展示漏斗图。
-- 使用 Ant Design 展示表格、表单、空状态和错误提示。
+- 使用 **ECharts** 展示漏斗图。
+- 使用 **shadcn/ui + Tailwind** 展示表格、控件、空状态和错误提示。
+- 按 `data_status`(`ready` / `missing`)显式渲染,缺失不补零。
 
-前端不负责 bitmap 解析或计算。
+前端不解析底层存储,只消费接口返回的 UV / 转化率 / 流失率。
 
 ## 4. 后端职责
 
-后端负责数据服务 API 和 bitmap 计算：
+后端负责漏斗查询 API:
 
-- 提供漏斗查询接口。
-- 校验时间范围和漏斗步骤参数。
-- 从 PostgreSQL 读取 `bytea` bitmap。
-- 对自定义时间范围内的 daily bitmap 做 OR 计算。
-- 对标准周期优先读取预计算 period bitmap 或结果。
-- 返回每层 UV、转化率和数据状态。
+- 提供 `POST /api/funnels/query`(契约见 §5)。
+- 校验 `period`(枚举)与 `snapshot_dt`(仅单日有效、上限昨日)。
+- 从 PostgreSQL 读取**预聚合宽表**(`ads_trd_group_funnel_daily` / `_rolling`,见 `docs/03` §11),按 `period` 选对应列,**不读 bitmap、不做 OR、不跨天聚合**。
+- 返回每层 UV、相邻转化率/流失率、`data_status`(`ready` / `missing`)。
 
 后端不存储埋点明细，不负责数仓产出逻辑。
 
@@ -139,40 +136,33 @@ UV 直接取列值;相邻转化率由 UV 计算。**不读 bitmap、不做 OR、
 
 系统是内部低并发数据平台，MVP 不引入额外缓存层。
 
-后端性能策略：
+后端性能策略(拼团两表,v3):
 
-- FastAPI 使用多 worker 部署。
-- 大 bitmap 的 CPU 计算不直接阻塞 async event loop。
-- 典型查询按 `漏斗层数 x 日期天数` 读取 bitmap。
-- 自定义范围最大 15 天，用产品规则控制计算上限。
+- FastAPI 多 worker 部署。
+- 查询是**单行宽表读取 + 取列值**(取最新 `dt` 行或指定单日 `dt`),无 bitmap 计算、无跨天聚合,极轻。
 
 MVP 不引入：
 
 - Redis。
 - Celery。
 - ClickHouse。
-- PostgreSQL bitmap 扩展。
 
 ## 8. 测试策略
 
-后端测试：
+后端测试(对照实现):
 
-- 单日查询。
-- 多日查询。
-- 标准周期查询。
-- 空 bitmap 查询。
-- 缺失数据查询。
-- 重复用户在 bitmap 中只计一次。
-- 多步骤 UV 和转化率计算。
+- `period` 校验:`day` / `last_7d` / `last_30d` 接受,非法值 422。
+- 单日:无 `snapshot_dt` 取最新行;给 `snapshot_dt` 取该日;不存在的日 → `missing`;`snapshot_dt` > 昨日(今天/未来)→ 422。
+- 近 7/30 天:从 rolling 唯一行取 `*_7d` / `*_30d`。
+- 转化率:第 1 层 `null`;`uv[i]/uv[i-1]`;`uv[i-1]==0` → `null`。
+- `data_status`:`ready` / `missing`;`snapshot_dt` 回显正确。
 
 前端测试：
 
-- 快捷时间选择。
-- 自定义时间最大 15 天限制。
-- 今天不可选或不可提交。
-- 图表渲染。
-- 表格渲染。
-- 空状态和错误状态展示。
+- 周期选择(单日 / 近 7 天 / 近 30 天),默认单日。
+- 单日日历:今天/未来不可选;选历史日重查。
+- 图表渲染、表格渲染。
+- `missing` 数据缺失空态、错误态。
 
 ## 9. 前端模块结构与路由
 

docs/03-数据契约.md

@@ -131,20 +131,20 @@ period_type + period_start + period_end + event_name
 
 数据缺失时，接口必须返回明确状态，不静默补零。
 
-缺失场景包括：
+> **当前 MVP(拼团两表,§11)只用两态:**
+> ```text
+> ready       # 目标行存在且对应列非空
+> missing     # 目标行不存在或对应列为空(不补零)
+> ```
+> 下方 `partial` / `invalid` 是为**后续 bitmap 方案**(§3–§9,暂不落地)准备的格式/部分缺失态,本期不用。
 
-- 某日期没有对应事件 bitmap。
-- 某标准周期没有对应事件 bitmap。
-- bitmap 格式不被服务端支持。
-- bitmap payload 无法解析。
-
-建议状态：
+后续 bitmap 方案的缺失场景与状态(暂不落地):
 
 ```text
 ready       # 数据完整
 partial     # 部分数据缺失
 missing     # 查询范围数据缺失
-invalid     # 数据格式错误
+invalid     # 数据格式错误(格式不支持 / payload 无法解析)
 ```
 
 ## 8. 查询使用规则

docs/05-agent协作准则.md

@@ -45,28 +45,29 @@
 ## 5. 前端 agent
 
 - **目录**：只在 `apps/web/`。
+- **技术**：React 19 + Vite + TypeScript + **shadcn/ui + Tailwind v4** + ECharts(漏斗图)+ TanStack Query。
 - **职责**：
-  - 平台导航/布局壳，五大能力域全部进入导航。
-  - 漏斗模块：时间选择区、漏斗配置区、结果图表区（ECharts 漏斗图）、结果表格区、空/错误状态。
-  - 其余四域："待开发"占位页。
-  - 前端校验：自定义范围最大 15 天、今天不可选/不可提交。
-  - 调用后端 `POST /api/funnels/query`，消费 UV/转化率/流失率/数据状态。
-- **不碰**：bitmap 字节解析与计算、后端代码、数据契约的服务端实现。
+  - 平台导航/布局壳,五个 L1 能力域进导航(见 `docs/01` §2)。
+  - 拼团漏斗模块:时间控件(单日 / 近 7 天 / 近 30 天,单日带历史日历)、ECharts 漏斗图、结果表格、空/错误状态。
+  - 其余域:"待开发"占位页(复用同一占位组件)。
+  - 前端校验:单日上限昨日、今天/未来不可选(T+1)。
+  - 调用后端 `POST /api/funnels/query`,消费 UV/转化率/流失率/`data_status`。
+- **不碰**：后端代码、数据契约的服务端实现。
 - **产出**：可运行前端 + 组件；契约未就绪时用 **mock 响应** 对齐字段并行开发。
-- **测试**：快捷时间选择、15 天限制、今天不可提交、图表渲染、表格渲染、空/错误状态。
+- **测试**：周期选择、单日历史/今天不可选、图表渲染、表格渲染、`missing`/错误状态。
 
 ## 6. 后端 agent
 
 - **目录**：只在 `apps/api/`。
+- **技术**：FastAPI + Pydantic v2 + SQLAlchemy(async)。
 - **职责**：
   - 提供 `POST /api/funnels/query`。
-  - 校验时间范围与漏斗步骤参数（15 天上限、今天不可查）。
-  - 从 PostgreSQL 读取 `bytea` bitmap；自定义范围对 daily bitmap 做 OR 后取 cardinality；标准周期优先读 period 表。
-  - 返回每层 UV、转化率、流失率、数据状态。
-  - bitmap 的 CPU 计算不阻塞 async event loop（放线程/进程池）。
+  - 校验 `period`(枚举)与 `snapshot_dt`(仅单日有效、上限昨日、今天/未来拒绝)。
+  - 从 PostgreSQL 读**预聚合两表**(`ads_trd_group_funnel_daily` / `_rolling`,见 `docs/03` §11):单日取 daily 行、近 7/30 天取 rolling 行的对应列;**不读 bitmap、不做 OR、不跨天聚合**。
+  - 返回每层 UV、相邻转化率/流失率、`data_status`(`ready`/`missing`)。
 - **不碰**：前端代码、埋点明细存储、数仓侧产出逻辑（只消费 `docs/03` 约定的表）。
-- **产出**：可运行 API + 单测；真数据未就绪时基于 **seed 假数据** 开发。
-- **测试**：单日/多日/标准周期/空 bitmap/缺失数据查询、重复用户只计一次、多步骤 UV 与转化率计算。
+- **产出**：可运行 API + 单测；真数据未就绪时基于 **seed 假数据** 开发(`USE_FAKE_DATA` 兜底)。
+- **测试**：`period` 校验、单日(最新/指定/不存在/今天拒绝)、近 7/30 天取列、转化率(第 1 层 null)、`data_status` 两态。
 
 ## 7. 契约交接点
 
@@ -75,7 +76,7 @@
 - **唯一来源**：`docs/02-技术架构` §5 的请求/响应字段。
 - **并行机制**：前端按契约 mock、后端按契约 + seed 实现，各自先跑通，再联调。
 - **改契约协议**：任一侧需要改字段，先改 `docs/02` 并同步对端，不在代码里单方面偏离。
-- **数据状态**：`ready`/`partial`/`missing`/`invalid` 由后端判定并返回，前端按状态渲染，**两侧都不静默补零**。
+- **数据状态**：`ready` / `missing` 由后端判定并返回，前端按状态渲染，**两侧都不静默补零**。
 
 ## 8. 主会话职责（不下放给 agent）