集成与 API - FoxKiosk 文档

把 IFU 接进现有系统

1. 基本信息

项	值
Base URL	`http://<终端IP>:19500`（默认端口，被占用自动顺延）
协议	HTTP / JSON（UTF-8）
鉴权	无（仅限可信局域网；禁止暴露公网）
接口权威	仓库 `docs/PROTOCOL.md`（本文为摘要）

2. 接口总表

2.1 控制（Control）

方法	路径	Body	说明
POST	`/api/control/navigate`	`{"url":"https://www.example.com"}`	前台跳转；无协议头自动补 `http://`
POST	`/api/control/reload`	—	刷新当前页面
POST	`/api/control/exit`	—	退出应用
POST	`/api/control/config`	—	前台加载配置页

2.2 配置（Config）

方法	路径	Body	说明
GET	`/api/config`	—	返回完整配置 JSON（附 `platform` 字段）
POST	`/api/config`	部分 / 完整配置对象	增量更新，持久化并热生效

# 示例：远程改主页并立即生效
curl -X POST http://192.168.1.100:19500/api/config \
  -H "Content-Type: application/json" \
  -d '{"defaultUrl": "https://kiosk.example.com/"}'

2.3 窗口（Window）

方法	路径	Body	说明
POST	`/api/window/minimize`	—	最小化
POST	`/api/window/maximize`	—	最大化
POST	`/api/window/restore`	—	还原
POST	`/api/window/notification`	`{"title":"标题","body":"内容"}`	系统通知

2.4 日志（Logs）

方法	路径	参数	说明
GET	`/api/logs`	`level` / `limit`（默认 100）/ `search`	查询日志
DELETE	`/api/logs`	—	清空
GET	`/api/logs/export`	—	下载 JSON 日志文件

2.5 文件（Files，根目录 `FoxKiosk/static/`）

方法	路径	参数 / Body	说明
GET	`/api/files/list`	`path`（默认 `/`）	列目录
POST	`/api/files/upload`	multipart，`path` 为目标目录	上传
POST	`/api/files/mkdir`	`{"path":"new_folder"}`	建目录
PUT	`/api/files/rename`	`{"oldPath":"a","newPath":"b"}`	重命名
DELETE	`/api/files`	`path`	删除
POST	`/api/files/unzip`	`{"path":"pkg.zip"}`	解压到同级目录（拒绝 `..`）

2.6 缓存与网络

方法	路径	说明
GET	`/api/cache/size`	缓存容量
DELETE	`/api/cache`	清理 WebView 缓存
GET	`/api/network`	本机 IP 列表、服务端口、访问示例

{ "ipAddresses": ["192.168.1.100"], "serverPort": 19500, "examples": ["http://192.168.1.100:19500/"] }

2.7 静态资源

路径	内容
`/`	管理页 SPA（内置）
`/static/*`	上传文件目录

3. JS 桥（业务页 → 宿主）

业务页面通过平台 JS 消息通道发送单行 JSON：

{"action": "restart"}
{"action": "exit"}
{"action": "log", "message": "办理完成"}

action	行为
restart	重启应用
exit	请求退出；`preventExit` 开启时弹出退出密码验证
log	写入应用日志（可在管理页查看）

4. 对接示例：办理完成自动换页

业务系统在办理完成后，把页面跳回登记地址即可；若需要终端层面控制（如夜间自动切到待机页），用定时任务调 REST API：

# 每天 21:00 把终端切到待机页（cron 中执行）
curl -X POST http://192.168.1.100:19500/api/control/navigate \
  -H "Content-Type: application/json" \
  -d '{"url":"https://kiosk.example.com/night.html"}'

5. 注意事项

全部接口无鉴权：仅限可信局域网，禁止端口映射公网；
POST /api/config 是增量更新，只传要改的字段即可；
端口顺延后，旧端口连接会失败——集成方建议先调 GET /api/network 取实际端口。

把 IFU 接进现有系统

1. 基本信息

2. 接口总表

2.1 控制（Control）

2.2 配置（Config）

2.3 窗口（Window）

2.4 日志（Logs）

2.5 文件（Files，根目录 FoxKiosk/static/）

2.6 缓存与网络

2.7 静态资源

3. JS 桥（业务页 → 宿主）

4. 对接示例：办理完成自动换页

5. 注意事项

文档解决不了的，直接问我们

2.5 文件（Files，根目录 `FoxKiosk/static/`）