docs: align repository names and bilingual entry points; remove obsolete reports
This commit is contained in:
@@ -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`。
|
||||
|
||||
Reference in New Issue
Block a user