06 · GSheet 与表格核对指南¶

用途：理解 P222 投流数据在 Google Sheet / xlsx / iConsole 之间如何流转，便于日常对账。
技术细节源：/Users/bob/Coding/iconsole 项目（Bob · Phase 9）
最后更新：2026-06-20 · Bob

1. 总览：数据从哪来到哪去¶

flowchart LR
    A["渠道填「渠道自有 GSheet」"] -- 人工对账 --> C
    B["投流填澎湃后台数 →「主 GSheet」各 Tab"] -- 人工对账 --> C
    C["统一日报 xlsx（出预算/请款）"] --> D["iConsole cron 22:00 Jakarta 自动拉主 GSheet"]
    D --> E["PostgreSQL fact_ad_daily"]
    E --> F["iConsole Board（报表/告警/对账）"]

结算标准永远是澎湃后台，GSheet 是协作与汇总层。

2. P222 主 GSheet¶

属性	值
环境变量	`P222_GSHEET_ID`（Spreadsheet ID）
结构	一个 Spreadsheet，~340 个 Tab
Tab 命名	`P222-{FB\\|TT}-{PWA\\|W2A}-P{群号}-{线号}`
示例	`P222-FB-PWA-P34-3`（投流组称「较好渠道」范例）
认证	Service Account JSON → `GSHEET_SA_KEY_PATH`（默认 `/secrets/gsheet-sa.json`）
同步	`gsheet_ad_account_sync` · 每日 cron + 管理 API 手动触发

2.1 单 Tab 列（摘要）¶

与 09-日常对账SOP §2.2 相同：

B/C = 消耗 + 回流（渠道/面板侧）
G/H = 前台注册/首充
I/J = 后台注册/首充（投流填，结算用 J）
V = 后台首充成本 = (B+C)/J
Q = 2 日留存率（填 46.67% 或 0.4667，parser 会归一）

完整 26 列映射 → iconsole scripts/lib/gsheet_ad_account_mapping.py

2.2 另有 `fact_ad_daily` Tab（早期格式）¶

iconsole 还支持单页 fact_ad_daily 表（A–R 列，一行一账号一日）。
当前主流程以 每渠道独立 Tab 为主；两种格式 parser 不同，勿混。

3. 渠道自有 GSheet¶

各渠道按 统一日报-菲律宾-模板.xlsx 自行复制一份 GSheet
渠道维护前台数据 + 与广告面板截图对齐
投流每日打开渠道表与主 GSheet 同 ID Tab + 澎湃后台三方核对

4. 如何用 iConsole 访问（运维/开发）¶

新人日常对账不必须登录 iConsole；填 GSheet + 澎湃即可。Board 适合看趋势、告警。

4.1 凭证（在 dhv6 服务器）¶

SA key：/opt/iconsole/secrets/gsheet-sa.json
.env.m2：P222_GSHEET_ID=<spreadsheet_id>
Sheet 须 Share 给 SA email（只读 Viewer）

完整 10 步 → iconsole docs/ops/gsheet-sa-rollout-sop.md

4.2 本地调试读某个 Tab（有 SA key 时）¶

cd /path/to/iconsole
export GSHEET_SA_KEY_PATH=/path/to/gsheet-sa.json
export P222_GSHEET_ID=<spreadsheet_id>
python3 -c "
from scripts.lib.gsheet_parser import read_sheet
rows = read_sheet('$P222_GSHEET_ID', 'P222-FB-PWA-P34-3!A1:V30')
for r in rows[:5]: print(r[:6])
"

4.3 API 手动 sync 单渠道¶

POST /admin/gsheet/sync-ad-account?ad_account_id=P222-FB-PWA-P34-3
（需 iConsole 管理员 JWT；见 apps/api/app/routes/admin/gsheet.py）

4.4 Board 可看¶

Platform Report：gsheet 风格全量报表
Channel Loss / ROI：渠道损耗、回收
告警：CPFD 超 KPI、新线异常消耗等（见 docs/business/p222-alert-catalog-2026-05-28.md）

❓ 新人只读 Board 账号申请流程 → 待确认

5. 对账差异类型（iConsole reconcile 逻辑摘要）¶

严重度	含义	典型处理
critical	GSheet 与 DB/后台差异大	当天必须改 GSheet 或说明
gsheet_missing	DB 有数，GSheet 漏填	补填
db_missing	GSheet 有，后台还没 sync	等 API/cron 或手补

Cashflow 子表另有一套对账（打款 vs 渠道名 normalize）。

6. 好渠道 Tab 长什么样（P34-3 类）¶

无法在此贴 live 数据（需 SA 凭证）。判断标准见 09-日常对账SOP §4.1：

近 7 日 B 列消耗阶梯上升
V 列 CPFD 稳定在 6～7U 或测试期后进入该区间
J 列后台首充与澎湃一致
Q 列留存不低于全站太多

拿到权限后：打开 Tab → 看总计行 + 最近 7 行日明细 → 与澎湃同渠道截图对比。

7. 相关文件索引（iconsole 仓库）¶

路径	内容
`docs/ops/gsheet-sa-rollout-sop.md`	SA 接入 10 步
`docs/ops/gsheet-template-spec.md`	fact_ad_daily 单页规范
`scripts/lib/gsheet_ad_account_mapping.py`	每渠道 Tab 列映射
`apps/api/app/services/gsheet_ad_account_sync.py`	单 Tab sync
`apps/api/app/services/gsheet_reconcile.py`	字段级对账