Document dashboard and sync workflow

REAMME.md

@@ -1,30 +1,73 @@
-# TTSHOP 同步脚本
+# TTSHOP 销售看板
 
-TTSHOP 的代码仓库地址为 `git.ops.roasbloom.site`，报告目录地址为 `ops.roasbloom.site/<仓库名>/`；本仓库对应的报告目录为 `ops.roasbloom.site/ttshop/`。
+TTSHOP 从公开的 Google Sheets 工作簿读取销售数据，生成合并后的原始数据页面，并提供 Commission 与 GMV 趋势看板。
 
-`sync.py` 使用 Python 标准库和 `requests` 读取公开 Google Sheets 工作簿，并把所有工作表合并成一个 UTF-8 HTML 表格，固定写入 `data/merged.html`。生成的 `data/merged.html` 供 Google Sheets 的 `IMPORTHTML` 使用，不改成 `index.html` 或 `data.json`。工作表名称和顺序来自 XLSX 导出，单元格使用公开 gviz 接口返回的显示值。
+- **项目仓库**：<https://git.ops.roasbloom.site/liuji/ttshop>
+- **销售看板**：<https://ops.roasbloom.site/ttshop/>
+- **原始数据**：<https://ops.roasbloom.site/ttshop/data/merged.html>
 
-合并规则：每张表第一行是标题；列按首次出现顺序取并集；源表已有的 `LinkName` 会改名为 `LinkName_Source`、`LinkName_Source_2` 等并保留；脚本最后追加生成的 `LinkName` 列。HTML 文本会进行转义。内容没有变化时不产生 Git 提交，变化时只提交 `data/merged.html` 并推送到 `main`。
+## 数据同步
 
-## AgentStage 自动更新
+数据源是公开的 Google Sheets 工作簿，固定 ID 为：
 
-AgentStage 服务器会自动执行仓库根目录的 `update.sh`，不使用 Gitea Actions workflow。`update.sh` 会进入脚本所在目录并使用 `python3` 执行 `sync.py`；脚本失败时会以非零状态退出。
+```text
+1DPbdVsX3SG_kgDXs2j34mDAgplRSfcAWKKG9yqalFmw
+```
 
-`schedule.conf` 是一个表示间隔小时数的数字：默认值为 `1`（每小时一次），本仓库设置为 `8`，表示每 8 小时刷新一次。服务器执行更新后，报告可从 `ops.roasbloom.site/<仓库名>/` 访问。
+`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`。
+
+### 汇率
+
+需要换算时，看板请求公开汇率接口：
+
+<https://open.er-api.com/v6/latest/USD>
+
+页面注明该公开接口通常每日更新，不承诺分钟级实时，并提供汇率来源说明：<https://www.exchangerate-api.com>。
+
+## 自动运行
+
+AgentStage 自动执行仓库根目录的 `update.sh`，不使用 Gitea Actions workflow。
+
+`schedule.conf` 当前值为 `8`，表示每 8 小时自动运行一次。`update.sh` 会执行 `sync.py`；同步失败时返回非零状态。
+
+## 本地手动运行
+
+在仓库根目录执行：
 
 ```sh
 python3 -m pip install -r requirements.txt
 ./update.sh
 ```
 
-脚本默认使用固定工作簿 ID `1DPbdVsX3SG_kgDXs2j34mDAgplRSfcAWKKG9yqalFmw`、仓库 `ttshop`、分支 `main` 和输出路径 `data/merged.html`。本地运行需要当前目录是该仓库，并且 Git 已配置可推送的 `origin`；不要把凭据写入 remote URL。
+Git 推送凭据由环境变量或 AgentStage 运行环境提供。凭据不得写入 remote URL、脚本、提交文件或日志。
 
-## 环境变量
+## 安全提醒
 
-- `GIT_CREDENTIAL_SECRET`：可选的 Git 密码/token。脚本通过临时 `GIT_ASKPASS` 使用，不写入 URL、日志或提交文件。
-- `GITEA_OWNER`：Git askpass 的用户名提示值。
-- `SYNC_FAILURE_WEBHOOK_URL`：可选的失败通知 URL。失败时最多发送一次简短通知，通知失败不会覆盖原始异常。
-
-AgentStage 运行不需要 Gitea Actions、Google OAuth 或 Google 服务账号。请勿把 token、密码或其他密钥写入脚本、仓库 URL、提交文件或日志；本地密钥和临时文件应被 `.gitignore` 规则忽略，避免进入提交。
+- 不要提交 token、密码或 `credentials` 文件。
+- 不要把敏感凭据写入 Git URL、代码、数据文件或日志。
+- 本地密钥和临时文件应通过 `.gitignore` 等规则排除在提交之外。
+- `update.sh` 失败时会返回非零状态，调用方应据此判断同步失败。