巨量引擎「本地推」· 素材优化分析工具 · 部署说明
============================================

一、这是什么
-----------
贝成口腔素材日常优化工具：扫描巨量本地推账户 → 按《素材优化操作SOP》自动标记
(暂停候选 / 观察 / 保留) → 输出优化清单 → 人工在后台执行暂停/删除后，在工具里"登记"。
工具本身【不调用】暂停/删除接口（本地推无单素材级暂停 API），只负责"扫描 + 标记 + 记录"。

数据模型：账户(local_account) → 项目(project) → 素材(material)
实体映射：巨量账户 = 本地推广告主；巨量项目 = project；巨量素材 = material（对应腾讯"创意"）

二、文件清单（同目录一起上传，隐藏文件别漏）
-----------
  index.php            主程序（本地推版，已实测可用）
  config.php           配置（access_token / 账户表 / SOP 阈值 / 密码）
  账户简称.xlsx         账户清单（15 个本地推广告主；列：账户名称 | 账户ID | 简称）
  accounts.csv         兜底账户表（xlsx 拿不到时用）
  data/                缓存 / 操作记录目录（含 .htaccess，隐藏文件别漏）
  data/index.html      占位
  素材优化操作SOP.txt   判定规则来源（参考）
  巨量引擎适配清单.txt   改造指南（参考）

三、打开方式
-----------
1) 把整个目录放到支持 PHP 的服务器（或本地 PHP 内置服务器均可）。
2) 浏览器访问目录首页 → 输入密码进入。
   登录密码见 config.php 的 `password`（当前为：beicheng2026，部署后请改成自己的）。
3) 首次进入点「利是本地推A深」等账户按钮逐个扫描（避免触发接口限频）。
   也可点「扫描全部账户」一次拉全（15 个账户，可能耗时较久）。
4) 扫描完出现素材表：含消耗 / 私信 / 留资 / 确认意向 / 意向成本 / 判定 / 建议 / 操作登记。

四、环境要求
-----------
1) PHP 7.4 以上（实测 8.3.36 通过；建议 8.x）
2) curl 扩展（必须有，接口走 curl；无 curl 不自动兜底，请装好）
3) data 目录必须可写（755，不行 777）

五、配置（config.php，改完刷新网页即生效）
-----------
  access_token    : 本地推 OpenAPI 的 access_token（会过期，过期需重填，见第七.1）
  password        : 网页登录锁（建议改成自己的）
  accounts_local  : 账户清单文件名，默认 '账户简称.xlsx'（同目录）
                   账户ID = 本地推 local_account_id（19 位）；表里写成 "ID：xxxx" 也会自动清洗
  accounts_url    : 在线 xlsx 地址（留空则只用本地 xlsx）
  accounts_file   : xlsx 都拿不到时的 CSV 兜底
  data_dir        : 缓存/操作记录目录（需可写）
  scan_days       : 扫描窗口天数，默认 7（消耗/私信/留资/确认意向均按此窗口）
  ── SOP 判定阈值（与《素材优化操作SOP.txt》对齐）──
  low_cost        : 近 N 天消耗 < 100 且 确认意向=0 → 暂停候选·低效（默认 100）
  cost_band1      : 意向成本 ≤ 250 → 保留·达标优（默认 250）
  cost_band2      : 250 < 意向成本 ≤ 300 → 保留·临界达标（默认 300）
  cost_band3      : 300 < 意向成本 ≤ 400 → 观察·成本偏高；> 400 → 暂停候选·成本过高（默认 400）
  high_cost_no_conv: 消耗 ≥ 此值且 0 确认意向但私信>0 → 重点查落地页提醒（默认 500）
  metrics         : 报表指标字段（见下表）
  cache_ttl       : 扫描缓存秒数（默认 600，期间刷新不调接口）
  throttle_sec    : 接口调用间隔秒（默认 1.0，本地推有限频，实测命中"请求频率超限"）
  max_materials   : 单次扫描最大素材条数保护（默认 5000）
  verify_ssl      : SSL 证书校验（默认 true；自签/TLS 拦截环境会自动降级重试）

六、指标口径与接口（本地推，与腾讯版完全不同）
-----------
接口基址 ：https://api.oceanengine.com/open_api/v3.0/local/...
鉴权方式 ：请求头 Access-Token: <access_token>（不是 Authorization: Bearer，
           也不是标准巨量的 ad.oceanengine.com 域名）
注意     ：全部 15 个账户都是「本地推虚拟广告主」，统一走 /v3.0/local/ 接口。

报表指标字段（已在 config.php 固化）：
  stat_cost                  → 消耗(元)
  message_action_cnt         → 私信咨询数
  attribution_form_cnt       → 线索留资数(计费时间)
  attribution_clue_confirm   → 确认意向数(计费时间)  ← 核心转化指标
★ 意向成本 = 消耗 ÷ 确认意向数（本地推报表不返回成本字段，由工具推算，与后台口径一致）

关键接口：
  GET /local/report/project/get/   项目级报表（筛出有消耗的项目）
  GET /local/report/material/get/  素材级报表（被优化/标记的最小单元）
  GET /local/project/list/         诊断接口 token 连通性用（仅取 1 条）

七、动作与页面功能
-----------
  ?act=scan&aid=xxx    扫描单个账户（点账户按钮触发）
  ?act=scanall         顺序扫描全部账户
  ?act=oprecord        POST 登记操作 → 写入 data/operation_log.csv
                       （字段：time/operator/account_*/project_*/material_*/action/note）
  ?act=export          导出 CSV（带 UTF-8 BOM，Excel 中文不乱码）
  ?act=diag            返回 JSON 诊断：token_len / account_count / account_source / token_ok

页面功能：
  - 统计卡片：暂停候选 / 观察 / 保留 数量
  - 判定筛选下拉 + 账户筛选 + 关键词搜索
  - 素材表：账户/项目/素材/类型/消耗/私信/留资/确认意向/意向成本/判定/建议/备注/登记状态/操作
  - 每行「登记」：选 已暂停/已删除/已观察/保留/备注 + 填备注 → 仅记录，不调接口
  - 「扫描全部账户」「导出CSV」「接口诊断」按钮

八、关键提醒（务必注意）
-----------
1) access_token 过期：本地推 token 有效期短，过期后扫描/诊断会报接口错误。
   本版未内置自动刷新，需手动更新 config.php 里的 access_token。
2) 指标字段已与业务确认：核心转化 = 确认意向数(attribution_clue_confirm)；
   意向成本 = 消耗÷确认意向 推算。如后期巨量改字段名，改 config.php 的 metrics 即可。
3) 本地推【无单素材暂停 API】：标准 /v3.0/material/status/update/ 不接受 local_account_id，
   本地推变体返回 404。因此暂停/删除只能人工在巨量投放后台执行，工具仅"标记+记录"。
4) 接口限频：本地推报表接口有频率限制，已设 throttle_sec=1.0 间隔；若仍报错，调大该值。
5) 扫描只取"有消耗项目"的素材（无消耗项目素材无意义），如需全量，删掉 scanAccount 里的 active 过滤。
6) 数据目录保护：data/.htaccess 已拦下载；Nginx 请加 location ^~ /data/ { deny all; }

九、环境自检
-----------
打开 首页 → 右上「接口诊断」→ 看 token_ok 是否为 true、account_count 是否为 15。
或访问 ?act=diag 直接看 JSON。

十、常见问题
-----------
  Q: 打开空白/500 → PHP 版本太低，切到 8.0 以上。
  Q: 扫描很久没数据 → max_execution_time 太短，调到 120 秒以上（逐账户拉更慢）。
  Q: 诊断 token_ok=false → access_token 过期或填错，重填 config.php。
  Q: 某账户素材为 0 → 该账户近 7 天无消耗，或项目/素材接口权限未开。
  Q: data 目录会不会被下载 → Apache 靠 data/.htaccess；Nginx 见第八.6。
