af-click-gap/README.md

https://ops.roasbloom.site/af-click-gap/

af-click-gap

生成 AppsFlyer 点击差异看板的数据。上游 AppsFlyer 脚本负责采集并写入 SQLite；本项目流水线只读数据库，生成 JSON 并发布到 Gitea。

数据与输出

• 数据库：/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 和日期 JSON。开始日期、结束日期默认都为昨天，支持日期筛选、pkg_name 多选、表头排序、每页 200 行和下载原始数据。

mac2 任务

两个任务按以下顺序执行：先由上游 AppsFlyer 脚本写数据库，再运行本项目流水线读取数据库并生成、推送 JSON：

/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

流水线脚本必须从 direct-report-dashboard/.env 读取 AGENTSTAGE_USER 和 AGENTSTAGE_TOKEN。默认读取项目 sibling 目录的 .env，也可通过 ENV_FILE 指定路径；只解析这两个变量，不执行整个 .env。凭据只通过临时 GIT_ASKPASS 提供给 Git，不写入 remote URL、命令行、日志或仓库。

手动运行

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 执行，按实际路径调整）：

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"。

安全

不要提交 af_click_gap.db、数据库、.env、token、密钥、日志、浏览器状态或缓存。发布前确认工作区没有无关改动；不再使用 launchd 目录或 plist 配置。