# TTSHOP 销售看板 TTSHOP 从公开的 Google Sheets 工作簿读取销售数据，生成合并后的原始数据页面，并提供 Commission 与 GMV 趋势看板。 - **项目仓库**： - **销售看板**： - **原始数据**： ## 数据同步 数据源是公开的 Google Sheets 工作簿，固定 ID 为： ```text 1DPbdVsX3SG_kgDXs2j34mDAgplRSfcAWKKG9yqalFmw ``` `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` 完成。 ## 看板功能 看板页面采用上下布局，包含以下内容： - **总体趋势**：Commission 柱状图与 GMV 折线图。 - **LinkName Commission 趋势**：按日期和 LinkName 堆积的 Commission 柱状图。 - **LinkName GMV 趋势**：按日期和 LinkName 堆积的 GMV 柱状图。 - **币种切换**：支持 IDR 与 USD；检测到多个源币种时统一换算为 USD。 - **日期范围筛选**：支持当月、最近 30 天和全部日期；默认选择数据最新月份。 - **KPI**：显示 Total Commission 和 Total GMV，并提供记录数、LinkName 数等概览信息。 - **原始数据入口**：可从看板打开 `data/merged.html`。 ### 汇率 需要换算时，看板请求公开汇率接口： 页面注明该公开接口通常每日更新，不承诺分钟级实时，并提供汇率来源说明：。 ## 自动运行 AgentStage 自动执行仓库根目录的 `update.sh`，不使用 Gitea Actions workflow。 `schedule.conf` 当前值为 `8`，表示每 8 小时自动运行一次。`update.sh` 会执行 `sync.py`；同步失败时返回非零状态。 ## 本地手动运行 在仓库根目录执行： ```sh python3 -m pip install -r requirements.txt ./update.sh ``` Git 推送凭据由环境变量或 AgentStage 运行环境提供。凭据不得写入 remote URL、脚本、提交文件或日志。 ## 安全提醒 - 不要提交 token、密码或 `credentials` 文件。 - 不要把敏感凭据写入 Git URL、代码、数据文件或日志。 - 本地密钥和临时文件应通过 `.gitignore` 等规则排除在提交之外。 - `update.sh` 失败时会返回非零状态，调用方应据此判断同步失败。