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

这是良渚电商每日数据流程的正式前后端分离看板项目。它把原来 `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
```

## 正式流程接入

正式每日流程脚本：

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

当前接入方式：

- 原脚本仍负责千牛 / 京东导出；
- 原脚本仍负责 staging 与云 PostgreSQL 入库；
- 原先“每次数据刷新后重新生成 HTML 并部署”的部分已被本前后端分离看板替代；
- 新前后端分离看板作为正式看板入口；
- 每日流程结束时会验证新看板接口，并把验证结果写入 `liangzhu_daily_flow_summary.json` 的 `split_dashboard` 字段；
- 11:00 定时任务跑完后，会把看板链接发送到飞书 `万事知答疑群`，并 @ 沐雨（朱潇潇，open_id `ou_66def5be461d37087997a8b74347a665`）；
- 周一额外发送周报附件；每月 1 日额外发送上月月报附件；
- 京东日报与分天报表若覆盖同一店铺/日期，入库事实表只保留一条日事实，优先采用 `京东日报`，避免周/月视图重复计算。

## 数据源

云端 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-1100
schedule: 0 11 * * *
script: /Users/bot1/.hermes/profiles/it/scripts/liangzhu_daily_flow_bot1.py --skip-backup
```

正式流程导出、入库完成后会调用 `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、更新和回滚方式。