juzi/docs/TAOBAO-ADMIN-CHANNELS.md

H5 / 淘宝统一后台：数据源与部署

统一后台增加“全部渠道 / H5 / 淘宝小程序”筛选，覆盖记录、统计、失败记录及 CSV 导出。用户账号、照片、报告仍由各自业务服务保存，不做账号合并，也不改变 H5 用户历史。

默认行为

未配置额外数据源时，后台继续读取当前服务的 JUZI_DATA_ROOT，现有 CSV 列顺序和末尾“渠道”保持不变。新接口返回数据来源标识，不公开服务器目录。

接入淘宝只读数据源

在承载管理后台的 H5 服务环境中配置绝对路径，例如：

JUZI_ADMIN_TAOBAO_DATA_ROOT=/home/ubuntu/juzi-tb-data

需要部署本次修改的 h5/server.js、h5/lib/admin-sources.js、h5/admin.html 和 h5/js/admin.js，然后按原部署流程重启该 H5 服务。淘宝业务服务继续使用原数据目录。管理后台进程需要拥有该目录的只读权限；两个服务不得共用同一可写 JSON 目录。

该配置只增加管理读取，不修改淘宝账号库或检测文件，不迁移、不删除历史数据。配置的额外目录必须存在，与当前数据目录独立，并位于 H5 静态应用目录之外；配置错误时服务启动会明确失败。

后台仍经原有 nginx 管理员认证入口访问，保持业务服务监听回环地址；不要为汇总功能放开 /tb/ 网关白名单或取消后台认证。小红书隔离实例不接入此额外数据源。

路由与数据口径

• 每条汇总记录包含 source、admin_key 和只读状态。两个数据源即使有相同记录 ID，也能分别打开正确详情、照片和原始 JSON。
• 详情和媒体请求通过后台已有路径的 source=local 或 source=taobao 选取已配置的数据源；HTTP 请求不能指定任意文件目录。
• 全局列表先合并再筛选、稳定排序和分页。CSV 沿用所有记录筛选条件，导出日期可另选；接入额外数据源后，仅在原有列末尾追加“数据来源、记录唯一键”。
• 按渠道统计检测记录及拍照流程；游客不留存的检测不会伪装成已保存报告。拍照漏斗是匿名客户端事件，不能视为人数或计费次数。淘宝尚未上报漏斗事件时显示零事件，不据此推断淘宝无检测。
• 外部数据源为只读：详情和失败页关闭重试按钮，服务端也拒绝外源重试。重试必须在原服务后台进行，避免写入错误渠道。
• “用户最近 5 份报告”是用户历史展示范围，不是后台磁盘保留期限。本次不会删除旧照片、原始结果、报告快照或检测记录；清理与备份周期需另行约定。

验证

node --test taobao/test/admin-channels.test.cjs
$env:JUZI_ADMIN_BROWSER_QA = '1'
node --test taobao/test/admin-channels.test.cjs

测试使用独立临时数据目录和伪造图片，不请求 Face++，也不访问或修改线上数据。浏览器验证截图位于 temp/taobao-adaptation/admin-channels.png。