# hs-data 内部数据服务平台 (hs-data)

数仓行为数据的可视化自助分析平台 · 五大能力域 · MVP 先交付泛用 UV 漏斗。

> 完整需求见 [docs/01-产品需求.md](docs/01-产品需求-MVP.md)；
> 开发约定（技术栈、工程铁律、留痕规范）见 [docs/05-agent协作准则.md](docs/05-agent协作准则.md)（新项目根 `CLAUDE.md` 蓝本）。

## Monorepo 结构

```
.
├── apps/
│   ├── web/               # 前端 (React + Vite · 平台框架 + 漏斗模块)
│   └── api/               # 后端 (Python + FastAPI · 只读查询服务)
│       └── modules/       # 按能力域分模块：funnel /（后续 retention / path / profile / realtime / touch）
├── packages/
│   └── api-types/         # 由后端 OpenAPI 生成的 TS 类型（前端共享，勿手改）
├── docs/                  # 产品 / 技术 / 数据契约 / 设计 / 协作 / ADR
├── infra/                 # 本地开发与部署配置
└── CLAUDE.md              # 给 AI 与人的开发硬约束
```

## 技术栈

| 层 | 选型 |
|----|------|
| 前端 | React 19 + Vite + TypeScript + Ant Design 5 + ECharts + TanStack Query |
| 后端 | Python 3.11+ + FastAPI + Pydantic v2 |
| 数据 | PostgreSQL 16 · roaring bitmap (`bytea` · pyroaring) |
| 契约 | 后端 OpenAPI → 前端生成 TS 类型；DB 迁移走 Alembic |
| 部署 | Docker |

详见 [docs/02-技术架构.md](docs/02-技术架构.md)。

## 快速开始

前置：Node ≥ 20、pnpm 10、Python ≥ 3.11、PostgreSQL 16。

```bash
# TODO: 待 Monorepo 脚手架建立后填入
pnpm install                 # 安装前端依赖
pnpm dev:web                 # 启动前端
pnpm gen:api-types           # 由后端 OpenAPI 生成 TS 类型
# 后端
cd apps/api && uvicorn app.main:app --reload
alembic upgrade head         # DB 迁移
pytest                       # 后端测试
```

## 平台能力（五大能力域）

| 能力域 | MVP 状态 |
|--------|----------|
| 漏斗 | **可用（MVP）** |
| 埋点完整（留存 / 路径） | 待开发 |
| 用户画像（标签 / 人群包） | 待开发 |
| 实时（实时大盘） | 待开发 |
| 营销触达 | 待开发 |

MVP 只开漏斗模块端到端可用，其余进导航、占位"待开发"。能力域定位与演进路线见 CLAUDE.md §1 与 docs/01。