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：

1DPbdVsX3SG_kgDXs2j34mDAgplRSfcAWKKG9yqalFmw

运行时可通过 WORKBOOK_ID 环境变量覆盖默认值，例如：

WORKBOOK_ID=your-workbook-id ./update.sh

未设置 WORKBOOK_ID 时，脚本继续使用上述默认值。sync.py 的处理流程如下：

读取 XLSX 导出文件，获取工作表顺序。
使用 Google Visualization API（gviz）读取各工作表中的显示值。
合并所有工作表，并生成 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 时间。
last_data_update_at：最近一次检测到 data/merged.html 内容变化的 UTC ISO-8601 时间，使用 Z 表示 UTC；数据内容未变化时保留上次成功记录，首次没有旧值时为 null。
last_data_update_at_shanghai：last_data_update_at 对应的 Asia/Shanghai 时区 ISO 时间；没有数据更新时间时为 null。
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。
同步状态提示：顶部逐行显示最后成功运行时间和数据最后更新时间，均按 Asia/Shanghai 格式化到秒；缺少记录时显示“暂无记录”。最后成功运行超过 24 小时会提示检查自动任务。
数据过期提示：last_data_update_at 超过 48 小时未更新时，顶部 warning 使用红色高亮并提示检查数据同步；没有数据更新时间记录时只提示“暂无记录”和缺少更新时间，不会按 48 小时误判。

汇率

需要换算时，看板请求公开汇率接口：

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 运行环境注入，不会因为仓库中的模板文件而自动生效。

本地手动运行

在仓库根目录执行：

python3 -m pip install -r requirements.txt
./update.sh

Git 推送凭据由环境变量或 AgentStage 运行环境提供。凭据不得写入 remote URL、脚本、提交文件或日志。

安全提醒

不要提交 token、密码或 credentials 文件。
不要把敏感凭据写入 Git URL、代码、数据文件或日志。
本地密钥和临时文件应通过 .gitignore 等规则排除在提交之外。
update.sh 失败时会返回非零状态，调用方应据此判断同步失败。

5.2 KiB Executable File Raw Permalink Blame History Unescape Escape