---
project: 良渚电商数据看板（前后端分离）
created_at: 2026-06-02 02:57
owner_profile: bot1/it
related_org_or_ip: 良渚
use_case: 电商经营数据看板
status: formal-flow-integrated
public_url: https://wwyl.yipeng.online/liangzhu-dashboard/
---

# 项目上下文

本项目从 bot1 每日正式流程 `liangzhu_daily_flow_bot1.py` 中内嵌的 `generate_html()` 静态页面拆出，做成可复用的前后端分离看板。

## 原始来源

- 原流程脚本：`/Users/bot1/.hermes/profiles/it/scripts/liangzhu_daily_flow_bot1.py`
- 原 HTML 输出：`/Users/bot1/Volumes/root_for_ai/AI工作区/千牛_数据导出_取数模板CLI_20260531_1331/deliverables/daily_cli_<YYYYMMDD>/html/index.html`
- 数据库：云端 PostgreSQL `liangzhu_qianniu`
- 数据生产链路：千牛 CLI 导出 + 京东 CLI 导出 + JSONL staging + PostgreSQL 入库

## 当前正式接入方式

正式外链：

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

云端部署位置：

```text
/srv/liangzhu-dashboard-app
```

云端服务：

```text
systemd: liangzhu-dashboard.service
listen: 127.0.0.1:8768
nginx route: /liangzhu-dashboard/
```

bot1 每日流程脚本已接入 `verify_split_dashboard()`：导出和入库后会验证该前后端看板，并把结果写入每日 `liangzhu_daily_flow_summary.json` 的 `split_dashboard` 字段。

正式流程已用本前后端分离看板替代原先“数据刷新后重新生成 / 部署 HTML”的部分；旧静态 HTML 仅作为应急兼容地址保留。

正式通知目标：飞书 `万事知答疑群`，chat_id `oc_d752acb35375df20a3557988f1755c8d`。每日任务完成后发送正式看板链接并 @ 沐雨（朱潇潇，open_id `ou_66def5be461d37087997a8b74347a665`）；周一额外发送周报附件；每月 1 日额外发送上个月月报附件。

## 项目目标

1. 后端 API：按日 / 周 / 月维度查询数据库；
2. 前端页面：日期选择器 + 维度选择 + 指标卡 + 趋势 + 表格；
3. 正式外链长期可访问，作为后续迭代主入口；
4. 保持看板服务只读查询，不在看板项目内做凭证落盘；
5. 旧静态 HTML 只作为应急兼容产物，正式查看和后续迭代以本前后端看板为准。

## 2026-06 推广效果模块

- 看板已升级为“经营结果 + 推广投入 + 推广产出 + 推广效率”：KPI 增加推广花费、推广成交、ROI、推广费率、推广成交占比、点击/展现/CPC/CTR。
- API 返回 `promotion_summary`、`promotion_trend`、`promotion_by_store`、`promotion_scenes`、`promotion_plans`，前端对应展示趋势、店铺推广效果、场景效果和计划 TOP。
- 推广数据来自阿里妈妈 / 万相台 CLI，入库脚本在 operations profile：`/Users/bot1/.hermes/profiles/operations/scripts/liangzhu_alimama_promotion_flow.py`。
- 数据库新增/使用独立推广链路：`raw.promotion_report_row`、`fact.promotion_daily_core`、`mart.promotion_daily_effect_summary`，不与销售事实表混写。
- 总推广花费默认以“营销场景报表 / scene”汇总，计划和关键词报表用于明细分析，避免重复加总；ROI 采用阿里妈妈后台归因口径。
- 每日 11:00 operations cron 已加载 `alimama-exporter` skill，并由 `liangzhu_daily_flow_bot1.py` 在销售/JD 入库后调用推广导出/入库。

## 后续迭代入口

- 前端布局与交互：`static/index.html`、`static/app.js`、`static/styles.css`
- API 路由：`app/main.py`
- 指标聚合与日/周/月逻辑：`app/service.py`
- 数据库查询：`app/repository.py`
- 部署与回滚：`docs/DEPLOYMENT.md`