From a73a5ca6316927d145995ffdf0ff8ffa80bd3a85 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=B8=A1=E5=8F=A3=E6=B5=AA=E4=BA=BA?= Date: Sun, 18 Oct 2026 17:53:43 +0800 Subject: [PATCH] docs: align repository names and bilingual entry points; remove obsolete reports --- DEPLOYMENT.md | 35 ----------------------------------- README.md | 43 ++++++++++++++++++++++--------------------- README.zh-CN.md | 36 ++++++++++++++++++++++++++++++++++++ 3 files changed, 58 insertions(+), 56 deletions(-) delete mode 100644 DEPLOYMENT.md create mode 100644 README.zh-CN.md diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md deleted file mode 100644 index 1b107a1..0000000 --- a/DEPLOYMENT.md +++ /dev/null @@ -1,35 +0,0 @@ -# 生产部署 - -2026-10-17（Asia/Shanghai），插件 v1.0.0 已通过 Console 在线安装接口安装、启用并登记。 - -- Console：`http://192.168.89.19/`；Frame Flow：`http://192.168.89.19:81`。 -- 插件 ID 与登记 ID：`pigway-frame-flow`；采集周期 60 秒。 -- 安装包 SHA-256：`88797d8836e5c8b5f4fe3b54f809886a18b19732fb6d2e55a2a4fe5d2cd2522e`。 -- 安装前 SQLite 在线备份：`/srv/pigway/apps/pigway-device-console/backups/frame-adapter-20261017-150107/console.db`（目录时间使用服务器时区）。 -- 首轮生产采集：服务就绪，1 台画框在线，电量 28%；1 个任务启用，最近结果成功；无活动告警。原树莓派、Ubuntu、NAS 三台设备均在线。 -- 后续后台自动采样时间已推进，设备保持在线；历史 API 已有 7 条指标序列。 -- 未重启容器，未修改 Frame Flow 配置或执行画框写入。API 令牌仅在服务器内读取并保存至 Console 敏感字段，未进入源码或报告。 - -停用插件可暂停新采集并保留设备与历史；不需要回滚 Console 核心。 - -## v1.0.1 中文显示修复 - -2026-10-17（Asia/Shanghai）：为插件增加 console-ui-v1 卡片及中英文指标/告警标签，随 Console 语言切换。`living-room` 仅是内部资源标识，显示名称直接使用 API 上报的“渡口浪人的相框”；已清除临时显示别名，未修改 Frame Flow 或厂商名称、资源 ID 和历史归属。 - -历史页补充 7 个指标的中英文译名；基于生产原镜像仅加入这一文件改动，运行镜像为 `pigway-device-console-manager:v2.8.2-frame-flow-i18n1`，原镜像保留。Console 容器已重建，其他服务未重启。数据库、旧插件、原 Compose 和 history.js 备份于 `/srv/pigway/apps/pigway-device-console/backups/frame-i18n-20261017-150652`。 - -新包 SHA-256：`455b1ec5fb5d43aeb042528da0d13ebf1b5b214a2f56234038c4639cb0cac83c`。6 项 Python 测试通过；生产中英文与桌面/平板/手机共 6 次页面检查通过，无横向溢出及页面脚本错误；四台登记设备在线。 - -## v1.0.2 平铺卡片 - -2026-10-17（Asia/Shanghai）：删除中间资源分组框，指标直接平铺；相框名称使用 Console 现有 `host-title` / `device-details` 结构显示在 Frame Flow 下方，与 Docker 的 Server 副标题一致。轮播任务合并为“轮播任务 / 启用”，最近运行成功时右上角显示蓝色“正常”，失败和未确认保留对应状态。 - -生产旧插件备份：`/srv/pigway/apps/pigway-device-console/backups/frame-flat-20261017-153104`；仅重启 Console 容器以加载插件版本。中英文与三尺寸生产浏览器检查共 6 次通过，确认无嵌套指标卡、任务状态颜色使用 Console 的 `--status-normal`、无横向溢出及脚本错误。四台设备在线。 - -## 告警空态统一 - -2026-10-17：Frame Flow 沿用 NAS 的常驻折叠“已读取范围内的告警”区域及共享 summaryStatus/scopeAlertHealth；仅完整且当前的快照确认“正常 / 无告警”，采集过期或范围不完整则显示未确认。生产中英文三尺寸共 6 次检查通过。 - -## 隐藏正常告警空态 - -2026-10-17 按用户最终偏好统一树莓派、Ubuntu、NAS 与 Frame Flow：新鲜完整快照没有告警时隐藏告警区域；有告警显示，数据过期或采集范围不完整仍显示未确认提示。Docker 沿用现有容器异常与采集错误显示。仅更新四个插件 UI，无服务重启。旧 UI 备份于 `/srv/pigway/apps/pigway-device-console/backups/hide-empty-alerts-20261017-155017`。中英文三尺寸覆盖 4 插件×3状态共 72 项生产渲染检查通过，无脚本错误和横向溢出。 diff --git a/README.md b/README.md index 0bd3356..b5399d1 100644 --- a/README.md +++ b/README.md @@ -1,34 +1,35 @@ # PIGWay Console Adapter — Frame Flow -独立 ZIP 插件 `pigway-frame-flow` v1.0.2，采用现有 Console adapter protocol v1，仅依赖 Python 标准库。源码在独立仓库 `pigway-console-adapter-frame-flow` 维护，无需修改 Console 核心或部署额外服务。 +[简体中文](README.zh-CN.md) | English -## 安装 +An independent, read-only ZIP adapter for PIGWay Device Console, using adapter protocol v1 and the Python standard library. It connects to Frame Flow over HTTP; no Frame Flow package or extra service is required at runtime. -1. 在 Console「机器管理」上传 `dist/pigway-frame-flow-1.0.2.zip`，启用插件。 -2. 添加设备，选择 PIGWay Frame Flow，填写 Console 能访问的 Frame Flow HTTP(S) 根地址（不含 `/api/v1`）和 **Frame Flow API 令牌**，不是 KoKonna Key 或网页登录密码。 -3. 若使用受限 API 客户端，授予 `devices:read`、`jobs:read`；默认 `FRAME_FLOW_TOKEN` 也可使用。令牌保存于 Console 敏感字段。跨不可信网络使用 HTTPS。 -4. 查看通用资源看板、告警与历史；默认每 60 秒采集一次。卡片和告警随 Console 中英文切换，资源显示 API 上报名称或 Console 中设置的显示名称。 +## Installation -采集 `/health`、`/ready`、`/api/v1/devices`、`/api/v1/jobs`，不发送写请求、不刷新画框、不执行任务。设备接口可能按 Frame Flow 现有缓存规则查询厂商只读状态。 +1. Build the ZIP below, upload it under Console Machine management, and enable it. +2. Add a PIGWay Frame Flow device with the HTTP(S) origin (without `/api/v1`) and a **Frame Flow API token**, not a KoKonna key or browser password. +3. Restricted API clients need `devices:read` and `jobs:read`. The default `FRAME_FLOW_TOKEN` is also supported. Use HTTPS across untrusted networks. +4. View cards, alerts and history. Collection defaults to 60 seconds; labels follow the Console language and resource names come from the API or Console display settings. -服务：就绪状态、设备数、任务数。画框：在线状态、可用时的电量。任务：启用状态和最近终态结果。`FAILED` 与 `UNKNOWN` 分别告警；未运行或执行中不当作成功。停用任务仍显示其最近失败，成功后恢复。设备离线、服务未就绪分别告警。 +The adapter reads `/health`, `/ready`, `/api/v1/devices` and `/api/v1/jobs`. It never refreshes a frame or runs a job. Device reads may use Frame Flow's existing vendor read-only status cache. -`/ready` 的 HTTP 503 作为未就绪状态采集；认证、超时、格式错误或其他采集失败交给 Console 保留旧快照并标记未更新，不伪造离线和零值。完整成功快照才确认告警恢复。历史从安装后的采样开始；设备指标是读取时观察到的 API 状态，不证明物理屏幕已刷新。Mock 服务返回的也是 Mock 设备状态。 +## Status semantics -## 本地验证与打包 +Reports readiness, device/job counts, frame connectivity and available battery levels, and job enablement/latest terminal result. `FAILED` and `UNKNOWN` produce distinct alerts; pending or running jobs are not reported as successful. A disabled job retains its last failure until a successful result replaces it. -在本仓库根目录执行（运行插件无需安装第三方依赖）： +HTTP 503 from `/ready` means not ready. Authentication, timeout and malformed-response failures preserve the previous Console snapshot and mark collection as unsuccessful. Only a complete successful snapshot confirms recovery. History starts with collection; an API status is not proof that a physical display refreshed. Mock status remains mock status. + +## Development + +Install `pytest` and `ruff` in a virtual environment, then run `python -m pytest -q`. Optional Frame Flow API contract tests require Frame Flow and its dependencies; otherwise they are skipped. With a sibling Frame Flow environment, use `PYTHONPATH=../pigway-frame-flow ../pigway-frame-flow/.venv/bin/python -m pytest -q`. Optional browser checks use Playwright and `node tests/ui.cjs`. + +For development, set `PIGWAY_ADAPTER_PATH` to this repository's absolute `plugin` path. Newly installed ZIPs are disabled by default. Additional history label translations require matching Console support. + +## Build + +Current adapter version: **1.0.2**. ```sh -python3 -m venv .venv -.venv/bin/python -m pip install pytest ruff -.venv/bin/python -m pytest -q mkdir -p dist -.venv/bin/python package.py plugin dist/pigway-frame-flow-1.0.2.zip +python3 package.py plugin dist/pigway-frame-flow-1.0.2.zip ``` - -开发时可将 `PIGWAY_ADAPTER_PATH` 指向本目录 `plugin` 的绝对路径。ZIP 安装默认停用；生产安装与设备登记需在 Console 中执行。本地验证覆盖模拟接口、RPC 和隔离安装；生产部署记录见 [DEPLOYMENT.md](DEPLOYMENT.md)。 - -Frame Flow API 契约测试为可选集成验证，需要另行安装 Frame Flow 及其依赖。例如相邻项目保留现有虚拟环境时，执行 `PYTHONPATH=../pigway-frame-flow ../pigway-frame-flow/.venv/bin/python -m pytest -q`。独立环境未安装 Frame Flow 时跳过该项，其余测试正常运行。 - -历史页的新增指标译名需 Console 配套支持（生产已安装）。仅安装插件也可正常采集并显示双语概览卡片。浏览器测试：安装 Playwright 后执行 `node tests/ui.cjs`。 diff --git a/README.zh-CN.md b/README.zh-CN.md new file mode 100644 index 0000000..17bb82d --- /dev/null +++ b/README.zh-CN.md @@ -0,0 +1,36 @@ +# PIGWay Console Adapter — Frame Flow + +简体中文 | [English](README.md) + +独立 ZIP 插件 `pigway-frame-flow` v1.0.2，采用现有 Console adapter protocol v1，仅依赖 Python 标准库。源码在独立仓库 `pigway-console-adapter-frame-flow` 维护，无需修改 Console 核心或部署额外服务。 + +## 安装 + +1. 在 Console「机器管理」上传 `dist/pigway-frame-flow-1.0.2.zip`，启用插件。 +2. 添加设备，选择 PIGWay Frame Flow，填写 Console 能访问的 Frame Flow HTTP(S) 根地址（不含 `/api/v1`）和 **Frame Flow API 令牌**，不是 KoKonna Key 或网页登录密码。 +3. 若使用受限 API 客户端，授予 `devices:read`、`jobs:read`；默认 `FRAME_FLOW_TOKEN` 也可使用。令牌保存于 Console 敏感字段。跨不可信网络使用 HTTPS。 +4. 查看通用资源看板、告警与历史；默认每 60 秒采集一次。卡片和告警随 Console 中英文切换，资源显示 API 上报名称或 Console 中设置的显示名称。 + +采集 `/health`、`/ready`、`/api/v1/devices`、`/api/v1/jobs`，不发送写请求、不刷新画框、不执行任务。设备接口可能按 Frame Flow 现有缓存规则查询厂商只读状态。 + +服务：就绪状态、设备数、任务数。画框：在线状态、可用时的电量。任务：启用状态和最近终态结果。`FAILED` 与 `UNKNOWN` 分别告警；未运行或执行中不当作成功。停用任务仍显示其最近失败，成功后恢复。设备离线、服务未就绪分别告警。 + +`/ready` 的 HTTP 503 作为未就绪状态采集；认证、超时、格式错误或其他采集失败交给 Console 保留旧快照并标记未更新，不伪造离线和零值。完整成功快照才确认告警恢复。历史从安装后的采样开始；设备指标是读取时观察到的 API 状态，不证明物理屏幕已刷新。Mock 服务返回的也是 Mock 设备状态。 + +## 本地验证与打包 + +在本仓库根目录执行（运行插件无需安装第三方依赖）： + +```sh +python3 -m venv .venv +.venv/bin/python -m pip install pytest ruff +.venv/bin/python -m pytest -q +mkdir -p dist +.venv/bin/python package.py plugin dist/pigway-frame-flow-1.0.2.zip +``` + +开发时可将 `PIGWAY_ADAPTER_PATH` 指向本目录 `plugin` 的绝对路径。ZIP 安装默认停用；生产安装与设备登记需在 Console 中执行。本地验证覆盖模拟接口、RPC 和隔离安装。 + +Frame Flow API 契约测试为可选集成验证，需要另行安装 Frame Flow 及其依赖。例如相邻项目保留现有虚拟环境时，执行 `PYTHONPATH=../pigway-frame-flow ../pigway-frame-flow/.venv/bin/python -m pytest -q`。独立环境未安装 Frame Flow 时跳过该项，其余测试正常运行。 + +历史页的新增指标译名需 Console 配套支持（生产已安装）。仅安装插件也可正常采集并显示双语概览卡片。浏览器测试：安装 Playwright 后执行 `node tests/ui.cjs`。