liuji/af-click-gap
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: simplify project README

Browse Source
This commit is contained in:
SHAREit
2026-10-16 17:58:39 +08:00
parent dd44e59a54
commit f45b51e9ff
1 changed files with 36 additions and 59 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+36 -59
View File
@@ -1,78 +1,55 @@
# Click Gap 数据看板
https://ops.roasbloom.site/af-click-gap/
运行目标是 **mac2**。另一个独立的外部 AppsFlyer 任务每天把汇总结果写入 SQLite；本项目不调用该任务、不访问 AppsFlyer、Superset 或其它提取 API，只从固定数据库只读查询并发布静态 JSON。
# af-click-gap
固定数据库：`/Users/ads-center/Documents/database/af_click_gap.db`。数据库必须预先存在 `click_gap` 表，脚本不建表、不迁移、不写入数据库。表要求包含：
生成 AppsFlyer 点击差异看板的数据。上游 AppsFlyer 脚本负责采集并写入 SQLite；本项目流水线只读数据库，生成 JSON 并发布到 Gitea。
```text
pid TEXT NOT NULL, dt TEXT NOT NULL, attr_platform TEXT NOT NULL,
pkg_name TEXT NOT NULL, shareit_clicks REAL NOT NULL, af_clicks REAL NOT NULL,
installs_ua REAL NOT NULL, clicks_diff REAL NOT NULL,
clicks_diff_rate REAL, updated_at TEXT NOT NULL
```
## 数据与输出
主键必须为 `(pid, dt, pkg_name)`。脚本只读取 `pid='shareit'`，并校验字段、日期、数值、重复业务键和有限数值。
## 输出协议
- `data/YYYYMMDD.json`：直接 JSON 数组；默认最近 7 天每天生成一个文件，即使当天无数据也生成 `[]`。使用 `--all` 时只为数据库中实际有数据的日期生成文件。
- `data/index.json`：包含 `schema_version`、`generated_at` 和本次实际生成的 `data/YYYYMMDD.json` 清单。
- 每行字段为 `dt`（`YYYYMMDD`）、`attr_platform`、`pkg_name`、`shareit_clicks`、`af_clicks`、`installs_ua`、`clicks_diff`、`clicks_diff_rate`；最后一项可以为 `null`。
默认日期边界为运行日往前 6 天至运行日，首尾包含，共 7 天。手工补数使用 `--start-date` 和 `--end-date`，两者必须同时提供且最多 7 天。
## 手工运行
mac2 推荐始终通过包装脚本运行：
```sh
cd /Users/shareit./Library/CloudStorage/OneDrive-个人/ubuntu/Gitea/af-click-gap
scripts/run_pipeline.sh
scripts/run_pipeline.sh --start-date 2026-10-10 --end-date 2026-10-16
# 全量重建数据库中所有实际有数据的日期并 push
scripts/run_pipeline.sh --all
```
包装脚本默认定位项目根目录，并读取 sibling 项目 `../direct-report-dashboard/.env`（mac2 默认路径为 `~/ubuntu/Gitea/af-click-gap` 与 `~/ubuntu/Gitea/direct-report-dashboard`）。也可以用 `PROJECT_ROOT` 和 `ENV_FILE` 覆盖路径。它只解析 `AGENTSTAGE_USER`、`AGENTSTAGE_TOKEN`，不执行整个 `.env`；凭据只进入子进程环境，不写入文件、remote URL、命令行参数或日志。脚本使用临时 `GIT_ASKPASS` 响应 Git 的用户名和密码提示，临时文件权限为仅当前用户可读写，并在退出时清理。
不要直接运行 `python3 scripts/af_click_gap_pipeline.py --push`：该命令可能使用 mac2 Keychain 中没有仓库写权限的旧凭据。包装脚本会执行相同的 SQLite 最近 7 天提取和 `--push`，额外参数会继续传给流水线；因此 `scripts/run_pipeline.sh --all` 最终执行全量 `--all --push`。需要只检查数据时可直接使用 `python3 scripts/af_click_gap_pipeline.py --dry-run` 或 `python3 scripts/af_click_gap_pipeline.py --all --dry-run`。
`--all` 会读取数据库中 `pid='shareit'` 的全部记录并按实际出现的日期生成 JSON；它不能与日期范围参数同时使用。全量运行可能改动并提交大量历史数据，执行前应确认数据库内容和工作区，且仍会经过字段、日期、数值、JSON 和 Git 数据白名单校验。脚本对数据库使用 SQLite 只读连接，不建表、不迁移、不写入数据库。
`--dry-run` 只读取数据库并在仓库外临时目录生成、校验 JSON，不写 `data` 或 Git。正式运行先原子替换 `data/` 输出目录中的数据文件，再执行 Git；数据库查询或校验失败不会发布文件。Git 安全检查只允许本次生成的 `data/*.json`（含 `data/index.json`），工作区存在其它未提交改动时拒绝继续。push 失败会保留本地 commit，不会 force push。
- 数据库：`/Users/ads-center/Documents/database/af_click_gap.db`。
- 默认生成最近 7 天（含当天）的 `data/YYYYMMDD.json`；使用 `--all` 时生成数据库中所有实际有数据日期的文件。
- `data/index.json` 保存生成时间、版本和 JSON 文件清单。
- 每个日期文件是 JSON 数组，记录包含 `dt`、`attr_platform`、`pkg_name`、`shareit_clicks`、`af_clicks`、`installs_ua`、`clicks_diff`、`clicks_diff_rate`。
- SQLite 以只读方式打开；不会建表、迁移或写入数据库。
## 看板
`index.html` 是无构建依赖的静态页面，读取并校验 `data/index.json` 及其清单，支持日期范围、包名筛选和表头排序。直接打开文件或执行 `python3 -m http.server` 后访问即可。
`index.html` 是无构建依赖的静态页面，读取 `data/index.json` 和日期 JSON。开始日期、结束日期默认都为昨天，支持日期筛选、`pkg_name` 多选、表头排序、每页 200 行和下载原始数据。
## mac2 crontab
## mac2 任务
mac2 使用 crontab 定时调用 `scripts/run_pipeline.sh`。包装脚本会读取 sibling 项目 `.env` 中的凭据，因此 cron 环境不需要配置密钥。先确认手工执行成功，再编辑当前用户的 crontab：
两个任务按以下顺序执行：先由上游 AppsFlyer 脚本写数据库，再运行本项目流水线读取数据库并生成、推送 JSON：
```sh
cd /Users/shareit./Library/CloudStorage/OneDrive-个人/ubuntu/Gitea/af-click-gap
scripts/run_pipeline.sh
crontab -e
/Users/ads-center/py314env/bin/python /Users/ads-center/ubuntu/appsflyer/af_click_gap.py
/Users/ads-center/ubuntu/Gitea/af-click-gap/scripts/run_pipeline.sh
```
加入以下示例（每天 mac2 本地时间 06:10 运行；请按实际 Python 路径和日志位置调整）：
流水线脚本必须从 `direct-report-dashboard/.env` 读取 `AGENTSTAGE_USER` 和 `AGENTSTAGE_TOKEN`。默认读取项目 sibling 目录的 `.env`，也可通过 `ENV_FILE` 指定路径；只解析这两个变量，不执行整个 `.env`。凭据只通过临时 `GIT_ASKPASS` 提供给 Git，不写入 remote URL、命令行、日志或仓库。
## 手动运行
```sh
cd /Users/ads-center/ubuntu/Gitea/af-click-gap
./scripts/run_pipeline.sh # 最近 7 天并推送
./scripts/run_pipeline.sh --start-date 2026-10-10 --end-date 2026-10-16
./scripts/run_pipeline.sh --all # 全量日期并推送
python3 scripts/af_click_gap_pipeline.py --dry-run
python3 scripts/af_click_gap_pipeline.py --all --dry-run
```
`--all` 不能与日期范围同时使用；全量运行可能提交大量历史 JSON。`--dry-run` 只检查数据并在临时目录生成 JSON，不修改 `data/` 或 Git。
## crontab
先确认两个命令手动执行成功，再使用当前 mac2 用户的 `crontab -e`。示例（每天本地 06:10 执行，按实际路径调整）：
```cron
10 6 * * * cd /Users/shareit./Library/CloudStorage/OneDrive-个人/ubuntu/Gitea/af-click-gap && /usr/bin/env PYTHON_BIN=/usr/bin/python3 ./scripts/run_pipeline.sh >> "$HOME/Library/Logs/af-click-gap/cron.log" 2>&1
10 6 * * * /Users/ads-center/py314env/bin/python /Users/ads-center/ubuntu/appsflyer/af_click_gap.py && /Users/ads-center/ubuntu/Gitea/af-click-gap/scripts/run_pipeline.sh >> "$HOME/Library/Logs/af-click-gap/cron.log" 2>&1
```
创建日志目录：`mkdir -p "$HOME/Library/Logs/af-click-gap"`。数据库、`.env`、密钥、日志和缓存均不会提交；不再使用或保留系统级 plist 配置。
日志目录不存在时先创建：`mkdir -p "$HOME/Library/Logs/af-click-gap"`。
## Git 创建和推送
## 安全
远程仓库约定为 Gitea `https://git.ops.roasbloom.site/liuji/af-click-gap.git`。仓库创建和首次配置可使用已有流程；日常 mac2 发布必须使用 `scripts/run_pipeline.sh`，它从 `/Users/shareit./Library/CloudStorage/OneDrive-个人/ubuntu/Gitea/direct-report-dashboard/.env`（或 `ENV_FILE` 指定路径）读取 `AGENTSTAGE_USER` 和 `AGENTSTAGE_TOKEN`。凭据不进入 Git、remote URL、命令行、临时 askpass 文件或日志，且 `.env` 绝不提交。
## 验证和安全
```sh
python3 -m py_compile scripts/af_click_gap_pipeline.py
python3 scripts/af_click_gap_pipeline.py --help
python3 -m json.tool data/index.json
```
禁止提交数据库文件、`.env*`、密钥、日志、浏览器状态、缓存或临时文件；`.gitignore` 已覆盖这些类型。
不要提交 `af_click_gap.db`、数据库、`.env`、token、密钥、日志、浏览器状态或缓存。发布前确认工作区没有无关改动；不再使用 launchd 目录或 plist 配置。