# 良渚电商数据看板（前后端分离）

这是良渚电商每日数据流程的正式前后端分离看板项目。它把原来 `liangzhu_daily_flow_bot1.py` 里每天生成的单文件静态 HTML，升级为：

- FastAPI 后端只读接口；
- 前端日期选择器；
- 日 / 周 / 月三种查询维度；
- KPI、趋势图、店铺结构、商品 TOP、流量来源 TOP、店铺明细；
- 云端长期服务外链。

正式外链：

```text
https://wwyl.yipeng.online/liangzhu-dashboard/
```

## 本地项目记录

本地项目目录：

```text
/Users/bot1/Volumes/root_for_ai/AI工作区/良渚_电商数据看板_前后端分离_20260602_0257
```

AI 工作区索引记录：

```text
/Users/bot1/Volumes/root_for_ai/AI工作区/00_AI工作区项目索引/projects/良渚_电商数据看板_前后端分离_20260602_0257.md
```

## 来源

原始静态 HTML 来源于 bot1 每日正式流程脚本：

```text
/Users/bot1/.hermes/profiles/it/scripts/liangzhu_daily_flow_bot1.py
```

原静态 HTML 输出路径：

```text
/Users/bot1/Volumes/root_for_ai/AI工作区/千牛_数据导出_取数模板CLI_20260531_1331/deliverables/daily_cli_<YYYYMMDD>/html/index.html
```

当前正式流程仍会保留这份静态 HTML 作为兼容产物，但用户查看和后续迭代以本前后端看板为主。

## 数据源

云端 PostgreSQL：

```text
host: wwyl-cloud
database: liangzhu_qianniu
schemas: mart, fact, raw, dim, ops
```

本项目不保存数据库密码、Cookie、Token 或其他敏感凭证。

本地开发默认通过 SSH 调用云端 psql：

```text
ssh wwyl-cloud sudo -u postgres psql -d liangzhu_qianniu
```

云端部署时，服务在同一台云主机上以 `postgres` 用户运行，使用本地 `psql -d liangzhu_qianniu` 只读查询。

## 目录

```text
app/        FastAPI 后端
static/     前端页面、CSS、JS
tests/      API、前端结构、正式流程接入测试
docs/       设计与部署说明
scripts/    本地启动脚本
```

## 本地运行

```bash
cd /Users/bot1/Volumes/root_for_ai/AI工作区/良渚_电商数据看板_前后端分离_20260602_0257
python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --host 127.0.0.1 --port 8765
```

打开：

```text
http://127.0.0.1:8765/
```

## API

```text
GET /api/health
GET /api/meta
GET /api/dashboard?grain=day&date=2026-05-31
GET /api/dashboard?grain=week&date=2026-05-31
GET /api/dashboard?grain=month&date=2026-05-31
```

## 正式流程接入

bot1 每日正式流程：

```text
cron: liangzhu-daily-cli-export-import-report-bot1-0730
schedule: 30 7 * * *
script: /Users/bot1/.hermes/profiles/it/scripts/liangzhu_daily_flow_bot1.py --skip-backup --skip-notify
```

正式流程导出、入库完成后会调用 `verify_split_dashboard()` 验证云端前后端看板，并在每日 summary 中记录：

```json
"split_dashboard": {
  "url": "https://wwyl.yipeng.online/liangzhu-dashboard/",
  "latest_date": "...",
  "day_kpis": {}
}
```

## 文档

- `PROJECT_CONTEXT.md`：项目来源、边界、当前状态；
- `docs/DESIGN.md`：日 / 周 / 月视图设计；
- `docs/DEPLOYMENT.md`：云端部署位置、systemd、Nginx、更新和回滚方式。