大屏进销存对接
与后期维护手册

版本：1.1 · 核对日期：2026-10-22 · 时区：Asia/Shanghai

适用对象：智慧食堂后端、前端、Android APK、部署实施、运维人员及进销存供应商。本文基于当前代码说明现状，不代表已在安徽现场部署或完成现场验收。

核心结论：打开大屏、恢复可见及点击进销存会请求本方后端检查 token；未满 12 小时且有效直接复用，达到 12 小时或失效后加锁刷新。失败保留有效旧值，提示并在 60 秒后重试。网页地址可配置；登录 API 目前固定；项目切换不能只换 IP。

01 对接范围与系统边界

{
  "sso_base_url": "https://NEW_PROJECT_HOST_PLACEHOLDER",
  "username": "NEW_PROJECT_ACCOUNT_PLACEHOLDER",
  "password_md5": "NEW_PROJECT_PASSWORD_32_HEX_MD5_PLACEHOLDER"
}

系统职责

当前 SSO 为一套后端配置、一份共享 token 缓存。它不会根据大屏的 type 自动选择不同进销存项目。type 用于智慧食堂档口选择，不等于进销存租户/项目标识。未来如需多项目映射，必须同时设计账号映射、项目级 token 存储隔离和授权，不能复用当前单文件方案直接拼接。

02 三种地址不要混淆

本机电视使用的 127.0.0.1:8081 和 ADB reverse 仅供联调，不是安徽现场部署地址，也不是进销存地址。

03 完整调用链路

打开大屏/恢复可见/到达维护时间，或用户点击“进销存”
  → 大屏 POST /api/screen/wmsLogin，发送 refresh_if_needed=1
  → 可信代理注入 X-Wms-Proxy-Key
  → 后端校验 Origin、真实连接源 IP、代理密钥
  → 校验私有 token 文件、账号指纹、剩余有效期及 saved_at
  → 未满 12 小时且有效：直接复用
  → 达到 12 小时/失效：加锁后再次检查，再按需登录并原子保存
  → 失败：60 秒共享退避；有效旧值可继续用，无有效值返回错误
  → 返回 token、剩余有效秒数、base_url、refreshAfter、refreshFailed
  → 后台准备只安排下一次检查，不跳转；只有用户点击时才携带 token 跳转

独立的定时链路：
调度器每 12 小时 → php think WmsSsoRefresh --if-needed
       → 未满 12 小时且有效时跳过，其他情况调用进销存登录 API
       → 校验响应及 expireTime
       → 加锁、私有文件原子替换
       → 后续点击读取新的缓存 token

首次打开检查与按钮点击会复用同一条进行中请求。维护返回 refreshAfter 后，页面按该秒数安排下一次检查，因此旧 token 已保存 9 小时，就约 3 小时后再检查，不会额外等待完整 12 小时。失败 60 秒后重试；离开/销毁页面清理计时器，恢复可见时重新检查。电视关机或进入其他页面后，网页计时器不保证继续运行，因此保留服务器兜底任务。普通人数/菜谱轮询独立，不触发 token 检查。

按钮有进行中状态，防止同一页面连续点击发起重复请求。页面销毁后不继续跳转。非 Android 浏览器优先预开新窗口，Android 电视走当前页跳转；具体行为还取决于实际 User-Agent 和窗口是否可创建。

前端跳转约定

{base_url}/tv/#/login/production?code={encodeURIComponent(token)}&path=monitor

当前目标为 path=monitor。早期资料出现过 path=operate，不能照旧资料回填。更换供应商页面版本时，应重新确认登录路由与监控路由。

04 本方读取 token 接口

接口：POST /api/screen/wmsLogin。新版大屏发送表单 refresh_if_needed=1 启用有条件维护；省略该字段仍兼容旧客户端，仅读取有效缓存。不接收浏览器提供的进销存账号、密码、目标项目、任意跳转地址或强制刷新请求。

由可信服务端代理设置 X-Wms-Proxy-Key；页面正常请求需要带有匹配配置的 Origin。不要在前端 JavaScript 中自行写这个密钥。

成功响应示例，所有敏感值均为占位符：

{
  "code": 0,
  "message": "",
  "data": {
    "token": "TOKEN_PLACEHOLDER",
    "expireTime": 259200,
    "base_url": "https://wms.houchuguanjia.com",
    "refreshAfter": 43200,
    "refreshFailed": false
  }
}

这里的 expireTime 是读取时的剩余秒数，并非每次都返回 259200。维护模式额外返回 refreshAfter（下一次检查间隔，1 至 43200 秒）和 refreshFailed（是否因异常回退到有效旧值）；默认只读模式不增加这两个字段。响应配置 Cache-Control: no-store, private、Pragma: no-cache 和 Referrer-Policy: no-referrer。本方响应日志对 token 脱敏。

默认无参数模式仍然只读缓存。refresh_if_needed=1 模式会按需调用第三方，先通过所有来源校验，再检查新鲜度；浏览器无法要求每次强制登录。旧值仍有效时，刷新异常可以回退为 200 并返回 refreshFailed=true；没有有效值则不返回 token。

05 进销存登录接口

由 store 后端刷新命令调用，浏览器不直接携带登录凭据访问。

POST https://api.houchuguanjia.com/hcgj-portal/api/sso/login
Content-Type: application/json
Accept: application/json

请求体示例：

{
  "userName": "PROJECT_ACCOUNT_PLACEHOLDER",
  "password": "32_HEX_MD5_PLACEHOLDER",
  "userIdentity": "1"
}

密码字段使用接口要求的 MD5 值，并转换为小写。MD5 值仍然属于凭据，不等于可以公开的“安全密文”。如果配置了 initial_access_token，请求额外携带 Access-Token；它的签发、必要性和维护规则需向供应商确认，不要和响应中的登录 token 混为一谈。

当前代码要求的响应结构：

{
  "success": true,
  "errorCode": 0,
  "data": {
    "token": "TOKEN_PLACEHOLDER",
    "expireTime": 259200
  }
}

要求 HTTP 2xx、success 为布尔 true、errorCode 为整数 0，token 非空且不含空白控制字符。expireTime 按 TTL 秒数处理，不是毫秒或绝对时间戳。当前存储接受大于 60 秒、不超过 365 天的 TTL。三天为供应商当前返回的有效期，不是本方写死的常量。

登录请求连接超时 3 秒、整体超时 8 秒；仅允许 HTTPS，校验服务端证书、不自动跟随重定向，响应大小有限制。不能为了改成 IP 而直接关闭证书校验。

06 配置位置与优先级

配置读取顺序：先读 HCGJ_CONFIG_FILE 指定的 JSON；未指定时读项目 runtime/private/wms-sso/config.json；随后已设置的环境变量覆盖同名文件字段。旧环境变量未移除时，只修改 JSON 可能不会生效。

配置模板仅说明字段，不能原样运行：

{
  "username": "PROJECT_ACCOUNT_PLACEHOLDER",
  "password_md5": "32_HEX_MD5_PLACEHOLDER",
  "allowed_ips": ["TRUSTED_PROXY_SOURCE_IP_PLACEHOLDER"],
  "allowed_origins": ["https://screen.example.test"],
  "sso_base_url": "https://wms.houchuguanjia.com",
  "proxy_key_sha256": "64_HEX_SHA256_PLACEHOLDER"
}

sso_base_url 只允许 HTTP/HTTPS 的协议、主机及可选端口，不允许用户名密码、查询参数、hash 或额外路径。/tv/ 不能写进该配置，当前由前端统一拼接。

配置必须同时供 Web PHP 进程和 CLI 刷新任务使用。私有文件内容每次读取；改变进程环境变量则需要按部署方式重新加载对应进程，由授权运维执行。

文件与权限

• token 缓存位于项目 runtime/private/wms-sso/token.json，与配置文件分开，不在 public 目录。
• 私有目录按 0700、文件按 0600 管理，不进 Git，不放入网页包、APK 或交付附件。
• token 文件包含 account_fingerprint、saved_at、expires_at 和 token，维护报告只读时间元数据。
• 新增私有 token.json.retry 保存与账号指纹绑定的 60 秒退避时间，不保存 token。Web PHP 进程现在也必须能创建锁、退避文件及原子替换缓存，不能只赋予读权限。
• 指纹当前根据账号和密码 MD5 计算；账号/密码变化时旧缓存会被拒绝。网页地址和登录端点没有纳入指纹，换项目时不能依靠指纹自动隔离环境。

07 访问保护与代理部署

当前校验三项：配置中的页面 Origin、REMOTE_ADDR 真实连接源 IP、代理头密钥 SHA-256。后端不信任浏览器伪造的 X-Forwarded-For。

注意：Origin 不是用户身份凭证，非浏览器客户端可以伪造。此方案依赖可信代理和受控内网访问，不等于完整的用户/角色鉴权，不应将共享 token 读取入口无保护地暴露到公网。

本机开发代理从服务端环境 SCREEN_WMS_PROXY_KEY 或私有文件 application/config/local/wms-proxy-key 读取密钥，仅给该接口注入请求头。现场 Nginx/网关需要独立配置相同能力，前端生产构建不会携带本机开发代理。

部署核对：

1. 只对精确路径 /api/screen/wmsLogin 注入密钥，不向任意第三方或其他接口转发。
2. 覆盖客户端传入的同名头，使用服务端持有的值；后端配置其 SHA-256 摘要。
3. 保留正确 Origin，明确代理转发后 PHP 看到的源 IP，不把整段不必要的网络加入白名单。
4. 根据现场网络限制可调用者；共享 token 不应返回给不可信用户。
5. 避免记录响应正文、完整 SSO 地址或包含 token 的调试信息。

08 token 生命周期与现有局限

已实现 12 小时有条件维护、页面失败提示与 60 秒重试，以及后端共享退避。仍未实现供应商 token 验真、第三方页面拒绝后的自动重新登录，也没有已验证的集中失败告警闭环。不能向用户承诺“每次点击一定登录成功”。

SSO 协议要求将 token 放入登录路由参数。即使本方日志脱敏，也不能保证第三方日志、浏览器历史或截图完全没有该值；排障时必须遮蔽完整登录地址。

09 定时刷新与日常巡检

已核实的本机任务

本次已将本机 macOS LaunchAgent com.zhct.store.wms-token-refresh 从每天 06:00 改为 StartInterval=43200（每 12 小时检查），并在注册/加载时检查一次。包装脚本调用本机 Docker 内的 WmsSsoRefresh --if-needed；未满 12 小时则不实际登录，避免与页面维护重复。本机用户会话、电脑、Docker 和网络必须处于可运行状态；不能将休眠/关机期间的计划时间当成成功执行证据。

这不是现场服务器调度。不要把 Mac 上的 .plist 直接当作 Linux 服务器的部署配置。

本机任务文件为 $HOME/Library/LaunchAgents/com.zhct.store.wms-token-refresh.plist，包装脚本为 $HOME/Library/Application Support/zhct-store/wms-token-refresh.sh，日志位于 $HOME/Library/Logs/zhct-store-wms/refresh.log 和 refresh-error.log。通过 launchctl list 查看对应任务存在与退出状态；不要在公开场合打印可能含环境变量的完整调度配置。

现场服务器建议模板

在现场授权配置完成后，使用服务器调度器每 12 小时做一次有条件检查。原每天 06:00 的强制任务应替换或改成同样的条件检查，不要继续重复强制登录。以下路径全部需要替换，且先确认供应商是否限制登录频率或使旧 token 失效：

0 */12 * * * HCGJ_CONFIG_FILE=/etc/zhct/wms-sso.json WMS_PHP_BIN=/usr/local/php7.3/bin/php /path/to/store/application/cron/shell/prod/wms_sso_refresh.sh >> /var/log/zhct/wms-sso-refresh.log 2>&1

要求任务用户能够创建锁文件、临时文件并替换缓存，同时 PHP Web 用户能够读取最终文件。优先使用同一受控服务账号；不要用 root 写出 0600 文件后再让 www 用户读取，造成按钮 503。调度时区、PHP 版本、项目路径、商户环境必须与站点一致，不能从空白环境直接照抄命令。

手动刷新：会产生真实第三方登录

只有在授权维护窗口执行，不作为无副作用的健康检查。共享账号再次登录可能影响其他设备，具体取决于供应商策略。

cd /path/to/store
/usr/local/php7.3/bin/php think WmsSsoRefresh

本机已知容器的等价维护命令：

docker exec -u www -w /workspace/zhct/store zhctapp_v2_0_menu_nutrition /usr/local/php7.3/bin/php think WmsSsoRefresh

日常调度使用 php think WmsSsoRefresh --if-needed 或已更新的服务器 shell，命令输出 token ready 可能只是复用，并非一定登录了第三方。不带 --if-needed 的上述手动命令仍是强制刷新，只在授权维护窗口使用。

命令成功应退出 0，输出到期时间与存储位置；失败应非零。不能把“有计划任务”或“文件存在”当作刷新成功。

推荐巡检表

安全查看元数据示例（需已安装 jq；不要直接输出整个 token 文件）：

jq '{saved_at, expires_at}' /path/to/store/runtime/private/wms-sso/token.json

10 更换 IP、项目或账号的标准流程

场景 A：只换同一项目网页地址

1. 供应商确认只是同一系统换访问入口，原 token 仍适用，且 /tv/ 登录和监控路由不变。
2. 修改 sso_base_url 或 HCGJ_SSO_BASE_URL，确保没有旧环境变量覆盖。
3. 检查 TLS 证书与电视网络可达性；网页可以配置 HTTP，但这不意味着认证 API 也支持 HTTP。
4. 核对 APK 专门适配：当前原生 MainActivity、wms-compat.js、wms-ready.js 匹配后厨管家域名，新的 IP/端口/协议可能需要调整匹配范围并重新构建 APK。
5. 验证单点登录、目标项目名称、运营监控适配及返回大屏，不只验证页面能打开。

场景 B：切换进销存项目或私有化部署

1. 供应商提供目标网页地址、登录 API、账号权限、响应格式和 token 失效规则。
2. 确认新账号的项目授权；IP 地址本身不能证明进入了正确项目。
3. 更新账号/凭据及网页地址。若认证域名也变更，需修改后端当前固定登录 URL，按 HTTPS 要求回归，不能只改 sso_base_url。
4. 核对可选 initial_access_token 是否仍适用，防止混用旧环境引导凭据。
5. 在维护窗口按新配置获取 token，再读取并验证目标项目。旧 token 不应直接发往另一个部署环境。
6. 检查前端登录路由和 APK 域名适配后发布；记录版本、配置位置、授权范围、执行人和回退方案，不记录密钥本身。

场景 C：大屏自身 IP 或域名变化

此时改变的是页面 Origin，需要同步核对 allowed_origins、代理入口、实际连接源 IP，以及 APK 的大屏入口配置。不要因为换了进销存目标 IP，就不加区分地扩大大屏 Origin 白名单。

11 故障排查手册

正确排查顺序：确认用户所处环境 → 记录无敏感参数的错误与时间 → 检查本方 HTTP 状态 → 检查来源/缓存/刷新任务 → 最后核对供应商登录和项目授权。不要未经授权部署、重启生产服务或反复刷新共享账号。

12 交接验收与回退

发布前验收

1. 三种地址分别确认，大屏入口不包含本机联调地址，网页目标和认证 API 属于同一授权环境。
2. 凭据和代理密钥经安全渠道下发，不在 Git、APK、构建资源、日志或说明文档中。
3. 来源校验正常，可信来源可调用，非授权来源不能取得 token。
4. 首次真实刷新成功，Web 用户可读；接口返回成功，但日志不包含 token。
5. 授权电视完成“点击进销存 → 正确项目运营监控 → 返回大屏”，IP/域名变化时完成缩放与过渡验证。
6. 计划任务不仅注册成功，还要有真实执行成功记录；模拟刷新失败后确认旧 token 仍有效可读，过期/指纹变化会拒绝返回。
7. 多设备场景向供应商确认新登录是否使旧 token 或已登录会话失效，避免共享账号互踢。
8. 记录代码/APK 版本、配置路径、调度器、执行用户、日志位置和责任人；现场尚未执行的项目必须标待验收。

回退原则

保留旧版本及受控配置备份，配置备份同样属于秘密资产，不放进交付附件。先恢复匹配的网页/认证环境与账号配置，再经授权重新获取该环境 token；旧 token 可能已被供应商撤销，不能保证直接恢复旧文件就能回退。

APK 改了域名适配时也要有对应版本回退计划。Android 一般不允许直接覆盖降级，不应先卸载清数据强行回退。用户数据保留策略需现场确认。

13 责任划分与供应商待确认项

待供应商确认：三天 TTL 是否固定；新登录是否作废旧 token；是否支持多个电视共享会话；是否有 token 验真/刷新接口；切换部署是否共用签名与 token；监控路由与页面 DOM 是否稳定。

建议改进但当前未实现：集中失败告警、供应商验真、第三方明确失效后的受控重登、多项目独立缓存。实施前需评估并发锁、重试次数和对其他设备会话的影响，不能直接改成“每次点击都登录”。

14 代码定位与当前交付状态

以下路径相对于各仓库根目录，方便不同服务器使用，不绑定个人电脑路径。

核对基础提交：store bd5d68fc0，以及本次尚未提交的 12 小时有条件维护变更；跳转参数仍为 monitor。本机 12 小时条件检查任务已调整并核验，首次任务复用现有有效 token。安徽现场服务器仍需独立部署；本次未安装 APK 或部署现场服务。