======================================
  广告机系统使用说明
  版本：v4.9（最新）
  更新日期：2026年6月16日
======================================

一、系统概述
-----------

广告机系统是一套B/S架构的图片轮播展示解决方案，由两部分组成：

  管理后台 - Node.js 服务端，运行在电脑上，提供网页管理界面
  展示端 App - Android 平板/手机 App，全屏轮播展示广告图片

工作流程：在电脑上启动管理后台 → 上传图片/配置轮播 → 在Android设备
上安装App并连接后台 → 设备自动同步并开始轮播。


二、管理后台（服务端）
---------------------

2.1 启动后台

管理后台已打包为独立可执行文件（Windows EXE）。双击运行 server.exe
（或通过命令行 node server.js 启动），默认监听 3456 端口。

启动成功后，命令行窗口会显示类似以下信息：

  广告机管理后台运行中
  管理页面: http://localhost:3456/
  设备页面: http://localhost:3456/board
  局域网访问: http://192.168.x.x:3456/

※ 请务必记录局域网访问地址，后续在Android设备上需要填写此地址。


2.2 管理页面功能

在电脑浏览器中打开 http://localhost:3456/ ，进入管理后台：

-- 上传图片 --
  · 点击上传区或拖拽图片到上传区域即可添加
  · 支持格式：JPG / PNG / GIF / WebP
  · 单文件最大50MB，一次可多选
  · 上传时会自动压缩优化：宽度超过1920px的图片会缩放，
    JPEG质量调整为70%，减少存储和带宽占用

-- 图片管理 --
  · 拖拽排序：在图片列表中直接拖拽调整轮播顺序
  · 单张时长：每张图片可单独设置显示时长（秒）
    - 留空 = 跟随全局设置
    - 输入 -1 = 永久停留（不切换）
  · 删除单张：点击图片下方的"删除"按钮
  · 清空全部：工具栏"清空全部"按钮（不可恢复，请谨慎操作）
  · 保存时长：修改时长后需点击"保存所有时长"

-- 轮播设置 --
  切换动画：左右滑动 / 淡入淡出 / 缩放 / 无效果
  默认间隔：秒数（0=永久），全局默认的每张图片显示时长

  ※ 修改设置后所有已连接的设备端会自动同步，无需手动刷新。


2.3 数据存储

  · 上传的图片存储在 uploads/ 目录
  · 配置和图片元数据存储在 data.db（SQLite数据库）
  · 数据目录位于可执行文件同级目录，备份时复制整个文件夹即可


三、展示端 App（Android设备）
----------------------------

3.1 安装 App

将APK安装文件复制到Android设备并安装：

  广告机-v4.9.apk      v4.9（最新）  ★推荐，纯原生WebView，性能最佳
  广告机-v4.8及更早    v4.0~4.8     历史版本
  ad-board-pad.apk     Pad版        大屏设备优化版
  广告机-诊断-v4.1.apk 诊断版       故障排查用，含调试信息

  安装时如提示"未知来源"，请在系统设置中允许安装未知应用。


3.2 首次配置

  1. 确保Android设备与电脑处于同一局域网
  2. 打开"广告机"App
  3. 在设置界面输入管理后台的局域网地址，例如：
     http://192.168.1.100:3456
     （请替换为实际的管理后台IP地址）
  4. 点击"连接并开始"
  5. 连接成功后自动进入全屏轮播模式，地址会自动保存，
     下次打开无需重新输入

  ※ 如需更换后台地址，在Android系统设置中清除"广告机"App数据
    即可重新进入设置界面。


3.3 展示端功能

  · 全屏轮播：横屏全屏显示，无状态栏、无导航栏
  · 自动同步：每10秒自动检查后台更新，变更实时生效
  · 防误触：屏蔽返回键，防止意外退出
  · 屏幕常亮：轮播期间屏幕不会自动关闭
  · 断网重连：后台断开时显示"离线"标识，网络恢复后自动重连
  · 图片加载失败重试：自动重试最多5次
  · 页面恢复：切到后台再回来自动恢复轮播


3.4 页面元素说明

  底部 · 进度指示器   白色圆点=当前图片，灰点=其他图片
  左上角 · 计数器     显示"当前/总数"及倒计时
  右上角 · 离线标识   网络断开时显示"离线"


四、常见问题
-----------

Q1：Android设备连接不上后台？

  · 确认电脑和Android设备连接同一个Wi-Fi/路由器
  · 检查电脑防火墙是否放行了3456端口
  · 在Android设备浏览器中输入管理后台地址测试是否能打开
  · Windows防火墙设置：控制面板 → Windows Defender防火墙
    → 允许应用通过防火墙 → 允许Node.js

Q2：上传图片后设备不显示？

  · 等待10秒让设备自动同步，或重启App
  · 检查App是否正确输入了后台地址
  · 确认管理后台正在运行且未被关闭

Q3：如何批量替换所有图片？

  · 使用"清空全部" → 重新上传新图片

Q4：如何让某张图片一直显示不切换？

  · 在该图片的时长输入框中输入 -1，然后点击"保存所有时长"

Q5：如何把管理后台放到服务器上长期运行？

  · 直接复制整个dist文件夹到服务器
  · Windows服务器：双击 node-runtime/node.exe server.js
    或使用NSSM注册为Windows服务
  · 也可以直接运行server.exe（pkg打包的独立可执行文件）


五、技术架构
-----------

  后端框架      Node.js + Express
  数据库        SQLite（sql.js，纯JS实现，零编译依赖）
  文件上传      Multer
  前端管理页    原生 HTML/CSS/JS（无框架依赖）
  前端展示页    原生 HTML/CSS/JS（ES5兼容，适配低版本Android WebView）
  Android App   原生 WebView 壳（Java），沉浸式全屏
  打包部署      pkg（Node.js → 独立EXE）

  端口：3456
  API接口：RESTful风格，CORS全开放
  同步机制：增量版本号比对，10秒轮询


六、版本历史
-----------

  v1.0 · 2025 · Cordova壳版本，基础轮播功能
  v2.0 · 2025 · 增加设置界面（URL输入）
  v3.0 · 2025 · ES5兼容优化，低版本Android适配
  v3.1 · 2025 · 诊断版，故障排查增强
  v4.0 · 2026 · 纯原生Android WebView，去除Cordova依赖
  v4.5 · 2026 · 前端压缩、上传优化
  v4.9 · 2026-06 · ★最新版：交互优化，稳定性增强