94 lines
4.4 KiB
Markdown
Executable File
94 lines
4.4 KiB
Markdown
Executable File
# TTSHOP 销售看板
|
||
|
||
TTSHOP 从公开的 Google Sheets 工作簿读取销售数据，生成合并后的原始数据页面，并提供 Commission 与 GMV 趋势看板。
|
||
|
||
- **项目仓库**：<https://git.ops.roasbloom.site/liuji/ttshop>
|
||
- **销售看板**：<https://ops.roasbloom.site/ttshop/>
|
||
- **原始数据**：<https://ops.roasbloom.site/ttshop/data/merged.html>
|
||
|
||
## 数据同步
|
||
|
||
数据源是公开的 Google Sheets 工作簿。`sync.py` 默认使用以下工作簿 ID：
|
||
|
||
```text
|
||
1DPbdVsX3SG_kgDXs2j34mDAgplRSfcAWKKG9yqalFmw
|
||
```
|
||
|
||
运行时可通过 `WORKBOOK_ID` 环境变量覆盖默认值，例如：
|
||
|
||
```sh
|
||
WORKBOOK_ID=your-workbook-id ./update.sh
|
||
```
|
||
|
||
未设置 `WORKBOOK_ID` 时，脚本继续使用上述默认值。`sync.py` 的处理流程如下：
|
||
|
||
1. 读取 XLSX 导出文件，获取工作表顺序。
|
||
2. 使用 Google Visualization API（gviz）读取各工作表中的显示值。
|
||
3. 合并所有工作表，并生成 UTF-8 的 `data/merged.html`，供数据读取和 `IMPORTHTML` 使用。
|
||
|
||
### 字段与合并规则
|
||
|
||
- 每张工作表的第一行作为标题行。
|
||
- 输出列按各工作表标题的首次出现顺序取并集。
|
||
- 源数据中的 `LinkName` 会重命名为 `LinkName_Source`、`LinkName_Source_2` 等，并保留原值。
|
||
- 合并结果末尾增加生成的 `LinkName` 列。
|
||
- 看板对仅包含 `Date`、且 `Commission` 与 `GMV` 均为空的日期行进行过滤；该过滤由 `index.html` 完成。
|
||
|
||
### 同步运行日志
|
||
|
||
`data/sync-log.json` 保存最后一次成功同步的摘要，字段包括：
|
||
|
||
- `last_success_at`：UTC ISO-8601 时间，使用 `Z` 表示 UTC。
|
||
- `last_success_at_shanghai`：`Asia/Shanghai` 时区的 ISO 时间。
|
||
- `worksheet_count`：本次读取的工作表数量。
|
||
- `record_count`：合并结果中的数据记录数量，不含标题行。
|
||
- `artifact_bytes`：本次生成的 `data/merged.html` 字节数。
|
||
|
||
只有 Google Sheets 读取、合并和 HTML 生成全部成功后才会生成并发布新的运行日志。同步失败或 Git 推送失败不会用失败时间覆盖已发布的最后成功时间。AgentStage 每次成功运行都会提交 `data/merged.html` 或 `data/sync-log.json` 中发生变化的文件；即使数据内容没有变化，运行日志的成功时间也会变化，因此仍可通过 Git 提交和日志确认运行记录。
|
||
|
||
## 看板功能
|
||
|
||
看板页面采用上下布局，包含以下内容：
|
||
|
||
- **总体趋势**：Commission 柱状图与 GMV 折线图。
|
||
- **LinkName Commission 趋势**：按日期和 LinkName 堆积的 Commission 柱状图。
|
||
- **LinkName GMV 趋势**：按日期和 LinkName 堆积的 GMV 柱状图。
|
||
- **币种切换**：支持 IDR 与 USD；检测到多个源币种时统一换算为 USD。
|
||
- **日期范围筛选**：支持当月、最近 30 天和全部日期；默认选择数据最新月份。
|
||
- **KPI**：显示 Total Commission 和 Total GMV，并提供记录数、LinkName 数等概览信息。
|
||
- **原始数据入口**：可从看板打开 `data/merged.html`。
|
||
|
||
### 汇率
|
||
|
||
需要换算时，看板请求公开汇率接口：
|
||
|
||
<https://open.er-api.com/v6/latest/USD>
|
||
|
||
页面注明该公开接口通常每日更新，不承诺分钟级实时，并提供汇率来源说明：<https://www.exchangerate-api.com>。
|
||
|
||
## 自动运行
|
||
|
||
AgentStage 自动执行仓库根目录的 `update.sh`，不使用 Gitea Actions workflow。
|
||
|
||
`schedule.conf` 为单独一行 `3`，表示每 3 小时自动运行一次。`update.sh` 会执行 `sync.py`。
|
||
|
||
当前没有独立持久化的更新日志；AgentStage 任务日志以及脚本的 stdout/stderr 是运行日志。同步失败时脚本返回非零退出状态。只有在 AgentStage 运行环境中配置并注入 `SYNC_FAILURE_WEBHOOK_URL` 时，脚本才会发送一次失败 Webhook；未配置时不会发送主动通知。Webhook URL 必须由 AgentStage 运行环境注入，不会因为仓库中的模板文件而自动生效。
|
||
|
||
## 本地手动运行
|
||
|
||
在仓库根目录执行：
|
||
|
||
```sh
|
||
python3 -m pip install -r requirements.txt
|
||
./update.sh
|
||
```
|
||
|
||
Git 推送凭据由环境变量或 AgentStage 运行环境提供。凭据不得写入 remote URL、脚本、提交文件或日志。
|
||
|
||
## 安全提醒
|
||
|
||
- 不要提交 token、密码或 `credentials` 文件。
|
||
- 不要把敏感凭据写入 Git URL、代码、数据文件或日志。
|
||
- 本地密钥和临时文件应通过 `.gitignore` 等规则排除在提交之外。
|
||
- `update.sh` 失败时会返回非零状态，调用方应据此判断同步失败。
|