巨量本地推盯盘系统 - 维护说明
========================================

一、系统组成
----------------------------------------
本系统分两部分：
1. 整点自动推送（每小时自动跑一次，推送到企业微信群）
2. 实时查询（群里@机器人发"数据"，手动触发查询）

二、文件清单（本地项目目录：D:\Doubao\巨量引擎\）
----------------------------------------
1. config.json
   - 推送配置文件
   - 包含：企业微信群机器人webhook、巨量API token、预警阈值、7个账户列表

2. monitor.py
   - 整点推送主程序（Python源码）
   - 功能：拉取巨量数据 → 生成预警文字 → 生成表格图片 → 推送到企业微信群

3. wechat_callback.php
   - 企业微信回调接口（部署在服务器上）
   - 功能：接收@机器人消息 → 调用exe拉数据 → 发文字+图片到群里

4. dist\juliang_monitor.exe
   - 打包好的exe程序（部署在服务器上）
   - 两种运行模式：
     · 不带参数：整点推送模式，自动发消息到群里
     · --query：查询模式，生成文字输出和query_table.png图片，不推送

三、服务器部署位置（39.108.208.79）
----------------------------------------
目录：D:\txshiping\juliang\
文件：
- juliang_monitor.exe    ← 整点推送exe
- wechat_callback.php    ← 企业微信回调接口
- config.json            ← 配置文件（和exe同目录）
- query_table.png        ← 实时查询生成的临时图片（自动生成）
- debug.log              ← 回调调试日志
- .query_lock            ← 防重复锁文件（自动生成）

Windows任务计划：
- 名称：巨量本地推整点盯盘
- 频率：每整点执行一次
- 时间范围：8:00-22:00（脚本内置判断，其他时间自动退出）

四、常见维护操作
========================================

【1】增加/删除/修改账户
----------------------------------------
步骤：
1. 打开本地 config.json
2. 在 accounts 数组里增删改账户：
   {
     "id": "账户ID",
     "name": "显示名称"
   }
3. 同时修改 wechat_callback.php 里的 $ACCOUNTS 数组（保持一致）
4. 重新打包exe（见下面"重新打包exe"）
5. 上传新的 exe 和 php 到服务器覆盖

注意：账户ID是巨量后台的广告主ID，在巨量引擎后台"账户管理"里能看到。

【2】修改预警阈值
----------------------------------------
打开 config.json，修改：
- "intention_cost_threshold": 300  ← 意向成本预警线（元）

其他两个阈值在 monitor.py 里：
- 消耗>200无转化预警（搜索 "cost > 200"）
- 消耗>300无意向预警（搜索 "cost > 300"）

改完后重新打包exe，上传覆盖。

【3】修改推送群（换企业微信群机器人）
----------------------------------------
打开 config.json，修改 wechat_webhook 字段：
- 新的webhook地址（在企业微信群里添加机器人，复制webhook地址）

同时修改 wechat_callback.php 里的 $webhookUrl（搜索 webhookUrl）。

改完后：
- config.json 直接上传到服务器覆盖
- php 上传到服务器覆盖
- exe 不需要重新打包（因为webhook在config.json里）

【4】修改推送时间
----------------------------------------
整点推送时间由 Windows任务计划 控制：
- 打开"任务计划程序" → 找到"巨量本地推整点盯盘"
- 修改触发器，改成你想要的频率（比如每半小时一次）

脚本内置了8:00-22:00的时间判断，其他时间运行会自动退出。
如果要改这个时间范围，打开 monitor.py，搜索 "hour < 8" 或 "hour > 22"，修改数字。

【5】重新打包exe
----------------------------------------
每次修改 monitor.py 后，都要重新打包：

1. 打开PowerShell，进入项目目录：
   cd D:\Doubao\巨量引擎

2. 执行打包命令：
   C:\Users\Administrator\AppData\Local\Programs\Python\Python311\python.exe -m PyInstaller --onefile --name "juliang_monitor" monitor.py --noconfirm

3. 打包完成后，exe在 dist\juliang_monitor.exe

4. 把 exe 上传到服务器 D:\txshiping\juliang\ 覆盖

【6】测试推送效果
----------------------------------------
本地测试（不需要服务器）：
cd D:\Doubao\巨量引擎\dist
.\juliang_monitor.exe

会直接推送到群里，看看效果对不对。

实时查询测试：
.\juliang_monitor.exe --query
会在当前目录生成 query_table.png，控制台输出预警文字。

五、关键参数说明
========================================

巨量引擎API Token：
- 在 config.json 的 oceanengine_access_token 字段
- 有效期90天，到期需要去巨量开放平台重新生成
- 到期后同时修改 config.json 和 wechat_callback.php 里的 token

企业微信配置（wechat_callback.php顶部）：
- $CORP_ID：企业ID
- $AGENT_ID：自建应用AgentId
- $SECRET：自建应用Secret
- $TOKEN：回调Token
- $ENCODING_AES_KEY：回调EncodingAESKey
- $OCEANENGINE_TOKEN：巨量API Token

六、常见问题排查
========================================

【问题1】整点没推送
- 检查服务器上exe能不能手动运行（远程桌面进去双击试试）
- 检查 Windows任务计划 是否正常运行
- 检查是不是在8:00-22:00之外的时间（脚本会自动退出）

【问题2】@机器人没反应
- 打开 debug.log 看看最新的日志
- 检查 wechat_callback.php 是不是最新版本
- 检查服务器上PHP能不能正常访问（浏览器打开 https://sp.jjbbcc.com/juliang/wechat_callback.php）

【问题3】预算显示不对/都显示预算不限
- 检查 fetch_budgets 函数，确认账户ID转成了整数数组传给API
- 手动调用预算API测试：
  python -c "import requests,json; r=requests.get('https://api.oceanengine.com/open_api/v3.0/local/advertiser/budget/get/', params={'local_account_id':'[1864972662313024]'}, headers={'Access-Token':'你的token'}); print(r.json())"

【问题4】重复推送多条
- 已经加了10秒防重复锁（.query_lock文件）
- 如果还重复，把锁时间从10秒改大一点（搜索 $now - $lastTime < 10）

【问题5】图片生成失败
- 检查服务器上有没有微软雅黑字体（C:/Windows/Fonts/msyh.ttc）
- 一般Windows服务器都自带，不用管

七、指标说明
========================================
- stat_cost：消耗（元）
- attribution_convert_cnt：转化数
- attribution_convert_cost：转化成本（元）
- attribution_message_action_cnt：私信咨询数
- attribution_clue_confirm：确认意向数
- attribution_clue_confirm_cost：确认意向成本（元）

预警规则：
1. 意向成本 > 300元 → 红色预警
2. 消耗 > 200元 且 转化=0 → 橙色预警
3. 消耗 > 300元 且 意向=0 → 橙色预警
4. 意向成本 < 300元 → 绿色提示（效果好，可加预算）
5. 预算-消耗 < 1000元 → 黄色提示（预算快花完了）
