# 云端部署说明：良渚电商前后端分离看板

## 正式外链

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

该外链是当前前后端分离看板的正式入口。旧静态 HTML 仍作为兼容入口保留：

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

## 来源关系

本项目来源于 bot1 每日正式流程中原本的静态 HTML 生成函数：

```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
```

当前前后端项目本地源目录：

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

## 云端部署位置

云端主机：

```text
wwyl-cloud
```

应用目录：

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

应用服务：

```text
systemd unit: /etc/systemd/system/liangzhu-dashboard.service
service name: liangzhu-dashboard.service
listen: 127.0.0.1:8768
```

Nginx 配置：

```text
file: /etc/nginx/sites-available/wwyl.yipeng.online-ssl
route: /liangzhu-dashboard/
proxy_pass: http://127.0.0.1:8768/
```

Nginx 配置修改前会生成备份，最近一次备份命名模式：

```text
/etc/nginx/sites-available/wwyl.yipeng.online-ssl.bak-liangzhu-dashboard-<YYYYMMDDHHMMSS>
```

## 数据源和凭证边界

数据库：

```text
PostgreSQL database: liangzhu_qianniu
schemas: mart, fact, raw, dim, ops
```

云端服务以 `postgres` 用户运行，通过本地 `psql -d liangzhu_qianniu` 查询，不在项目目录保存数据库密码。

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

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

禁止写入或提交：数据库密码、Cookie、Token、SSH key、Feishu 凭证、原始导出凭证。

## 更新部署步骤

从 bot1 本地项目同步到云端：

```bash
cd '/Users/bot1/Volumes/root_for_ai/AI工作区/良渚_电商数据看板_前后端分离_20260602_0257'
. .venv/bin/activate
pytest tests/ -q
rsync -az --delete --exclude '.venv' --exclude '__pycache__' --exclude '.pytest_cache' ./ wwyl-cloud:/tmp/liangzhu-dashboard-app/
ssh wwyl-cloud "sudo rsync -a --delete --exclude '.venv' /tmp/liangzhu-dashboard-app/ /srv/liangzhu-dashboard-app/ && sudo chmod -R a+rX /srv/liangzhu-dashboard-app && sudo systemctl restart liangzhu-dashboard.service"
```

注意：第二段同步到 `/srv/liangzhu-dashboard-app/` 时也必须排除 `.venv`，否则会删除云端虚拟环境，导致 systemd `203/EXEC`。若已误删，按下方依赖变更命令重建 `.venv`。

如依赖变更，在云端执行：

```bash
ssh wwyl-cloud "cd /srv/liangzhu-dashboard-app && sudo -u www-data python3 -m venv .venv && sudo -u www-data .venv/bin/pip install -r requirements.txt"
```

当前 systemd 以 `postgres` 用户运行，但 `.venv` 目录可读可执行即可。

## 验证命令

云端服务状态：

```bash
ssh wwyl-cloud "systemctl is-active liangzhu-dashboard.service && systemctl is-enabled liangzhu-dashboard.service"
```

外链验证：

```bash
curl -fsS -o /dev/null -w 'page=%{http_code}\n' https://wwyl.yipeng.online/liangzhu-dashboard/
curl -fsS https://wwyl.yipeng.online/liangzhu-dashboard/api/meta
curl -fsS 'https://wwyl.yipeng.online/liangzhu-dashboard/api/dashboard?grain=day&date=2026-05-31'
curl -fsS 'https://wwyl.yipeng.online/liangzhu-dashboard/api/dashboard?grain=week&date=2026-05-31'
curl -fsS 'https://wwyl.yipeng.online/liangzhu-dashboard/api/dashboard?grain=month&date=2026-05-31'
```

正式每日流程验证字段：

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

字段：html.reason / deploy.reason / split_dashboard.url / split_dashboard.latest_date / split_dashboard.day_kpis / notify
```

## 正式通知流程

每日 11:00 cron 完成后，`liangzhu_daily_flow_bot1.py` 会向飞书 `万事知答疑群` 发送看板链接，并 @ 沐雨（朱潇潇）：

```text
chat_id: oc_d752acb35375df20a3557988f1755c8d
at_open_id: ou_66def5be461d37087997a8b74347a665
正式看板: https://wwyl.yipeng.online/liangzhu-dashboard/
```

发送规则：

- 每天：发送看板链接和当天流程摘要；
- 周一：额外生成并发送周报附件；
- 每月 1 日：额外生成并发送上个月月报附件；
- 京东日事实去重：如果 `京东日报` 与 `京东分天店铺交易流量报表` 覆盖同一店铺/日期，正式入库只保留一条日事实，优先采用 `京东日报`。

## 回滚方式

1. 若前后端看板代码有问题，但旧静态看板正常：继续使用旧地址 `https://wwyl.yipeng.online/detail-pages/liangzhu-store-dashboard/`。
2. 停止新服务：

```bash
ssh wwyl-cloud "sudo systemctl stop liangzhu-dashboard.service"
```

3. 回滚 Nginx：从 `/etc/nginx/sites-available/wwyl.yipeng.online-ssl.bak-liangzhu-dashboard-*` 选择最近可用备份恢复，然后：

```bash
ssh wwyl-cloud "sudo nginx -t && sudo systemctl reload nginx"
```

4. 恢复后重新验证旧静态看板 HTTP 200。

## 后续迭代注意

- 修改前端：`static/index.html`、`static/app.js`、`static/styles.css`；
- 修改 API：`app/main.py`；
- 修改指标或日/周/月口径：`app/service.py`；
- 修改数据库 SQL：`app/repository.py`；
- 每次上线前必须跑本地 `pytest tests/ -q`，上线后验证页面、静态资源、`/api/meta` 和 day/week/month 三个 dashboard API。