# zizu

**Repository Path**: taidai/zizu

## Basic Information

- **Project Name**: zizu
- **Description**: 自足物联网平台，开源物联网低代码平台，简单配置即可交付工业控制系统。
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-09-05
- **Last Updated**: 2026-09-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ZiZu

用于开发和交付 EMS 的配置型工业 IoT 平台。

实施工程师不修改平台源码、不直接编写 SQL，只需建立真实节点、接入设备点位、把原始数据加工成稳定
实体，再配置告警、调度策略、控制和固定 EMS 工作台，即可交付单站工业控制系统。光储充 EMS 是首个参考
交付场景。

**当前代码版本：`v1.1.0`** · [English](README_EN.md) · [完整中英文架构说明](docs/ZIZU-TECHNICAL-ARCHITECTURE.md)

v1.1.0 以 **10.1寸横屏平板**为主尺寸，主验收1280×800、兼顾1024×768；能流三行网格避免文字重叠，底部说明不被导航遮挡。见[平板显示规范](docs/tablet-primary-display.md)。本次现场连接不可用，v1.1.0尚未部署；以下为上一版发布记录。

v1.0.9 已部署到1号机，Schema 065、应用健康，现场无头只读主干10项通过。运行总览按已确认 Demo 复刻：四张指标卡、五个能流节点、拟物 SVG 与红金亮银布局，新增独立站内负荷绑定；页面仍消费正式 API 与 committed L2。近期版本还提供调度策略合栏管理、安全硬删除和默认折叠的控制回读。详见[本版发布记录](docs/deploy-1号机-v1.0.9-http.md)及[首页功能说明](docs/workbench-demo-overview.md)。

[v1.0.4 集成、发布与现场复验记录](docs/reviews/2026-09-07-tablet-production-acceptance.md) · [v0.9.9 历史现场记录](docs/deploy-1号机-v0.9.9-http.md)

本版没有修改现场指标绑定或下发设备控制。部分指标仍显示最后值，充电与负荷尚未绑定；可见 Browser 插件抽查未完成。这些边界与代码、制品发布、只读验收分别记录，不将页面可用等同于完整现场交付。

> ZiZu 已具备核心数据主干、告警和调度控制底座，但尚不能宣称完整光储充 EMS 已经交付就绪。真实设备控制和完整 EMS 现场验收仍需单独取得证据。

## 最新运行首页

已确认的视觉方向为**旗红、金色、亮银**与拟物化面板，面向 10.1 寸平板：日常运行优先，工程配置集中到一个入口。

![ZiZu v1.1.0 正式首页：10.1寸平板主视口1280×800，数据为公开测试样例](docs/images/ems-homepage-v1.1.0.png)

> 本图截取自 v1.1.0 正式前端生产构建，不是旧 Demo。为保护现场信息，基于仓库公开测试夹具配置示例数据，API 显示 `test`；设备、数值和策略均为示例，不是现场运行证据。生产站点仍区分当前值、最后值和未配置状态，不用示例数据填充。

## 核心结构

```text
真实节点树 → L0 原始点位 → L1 点位加工 → L2 全局实体
                                           ↓
                         告警 / 调度策略 / 控制 / 固定 EMS 工作台
```

| 部分 | 作用 | 用户看到什么 |
|---|---|---|
| 真实节点树 | 表示场站、系统和真实设备 | 光伏、储能、充电、并网、负荷及其设备 |
| L0 原始点位 | 保存设备实际上传的值、质量、时间和来源 | 原始数据的实时值、历史和链路状态 |
| L1 点位加工 | 完成映射、换算、状态解析、组合和强类型公式 | 从原始点位定义实体的数据来源与计算 |
| L2 全局实体 | 为所有上层功能提供稳定业务含义 | 实体的实时值、历史、质量和来源证据 |
| 上层应用 | 使用 L2 完成运行功能 | 告警、调度策略、控制和 EMS 工作台 |

L0、L1、L2 是所选真实节点的三个数据视角，不是三类物理子节点。点位、公式和实体不得伪装成节点树
层级。普通实施人员主要使用“原始数据”和“标准实体”两个页面：从 L0 选择点位、定义加工、预览结果并
发布 L2。点位加工模板只在同类设备需要复用时使用，不是首台设备接入的前置条件。
可写数值点只有在单一 Neuron `RW` 点位“直接使用”且显式填写安全边界后，才能发布为调度策略可选的可控 L2。

### 数据怎样运行

```text
设备 → Neuron → NanoMQ → 实时黑板 → 统一数据帧 → L1 计算 → committed L2
                                                                  ↓
                                              告警 / 调度策略 / 控制 / 页面
```

- 单站只有一个活动采集写者；实时黑板按默认 1 秒节拍冻结不可变数据帧。
- 有新观测或质量变化才产生新帧；值相同但采样时间更新仍是新观测，重复、倒退和迟到样本直接放弃。
- 数据库提交前不推送页面、不触发告警、不执行 JDM、不下发控制。
- 质量分为 `GOOD`、`UNCERTAIN`、`BAD`、`STALE`；非 `GOOD` 数据禁止进入自动控制。
- 每个 L2 都能追溯到实际 L0 观测、L1 修订、配置修订、质量和时间依据。
- 上层应用只能消费已提交 L2，不能直接依赖品牌点位或原始 MQTT。

## 功能模块

| 模块 | 主要能力 |
|---|---|
| 运行首页与设备监控 | 按真实节点和 committed L2 展示运行状态；设备筛选、六卡分页、实体 10/20 分页、历史和来源证据；未知、断流和最后值明确区分 |
| 节点与数据 | 真实节点 CRUD、Neuron 点位导入、L0 实时/历史、数据链诊断、点位加工、L2 实时/历史与来源 |
| 告警中心 | L2 告警规则、等级、触发与恢复、多码映射、10/20 行事件表、当前页批量确认、归档、HTTP 通知及投递记录 |
| 调度策略 | 选择多个 L2 输入、编辑原生 GoRules JDM、绑定多个可控 L2 输出，支持草稿、试算、发布、启停、决策、控制意图和回读；2充2放仅是可选起始模板 |
| 控制 | 人工和调度策略共用安全入口，经唯一 L0 写点下发，并以新 L2 回读确认结果 |
| 固定 EMS 工作台 | 按节点类型和标准 L2 展示已有的功率、SOC、趋势与告警；缺少站级 L2 时如实显示未配置，不用 Demo 数据补齐 |
| 系统工具 | MQTT、HTTP 通知、系统状态及管理员配置 |

平台不做多租户、解决方案包、设备实例中间层、第二套规则引擎、任意脚本、Redis、Kafka、新微服务或
自由页面设计器。统计计算属于 L1，结果仍是普通 L2，不建立新的“统计实体层”。

## 使用方式

### 1. 建立现场

在“节点与数据”中按真实关系建立场站、子系统和设备。节点树只描述现场拓扑，不放点位或公式。

### 2. 接入原始点位

在设备节点上配置 Neuron 接入并导入点位。进入“原始数据”检查：

- 点位是否出现；
- 当前值、数据时间和接收时间是否更新；
- 质量是否为 `GOOD`；
- `Neuron → MQTT → 数据接收 → 数据帧 → L0` 链路是否连通；
- 实时与历史是否能查询到同一个点位的数据。

L0 必须保留协议原值；例如设备上传 `0/1`，L0 仍显示 `0/1`。布尔含义、故障码和单位换算在 L1 定义。

### 3. 加工为全局实体

在原始数据中选择一个或多个 L0 点位，填写实体名称、业务标识、结果类型和单位，再选择加工方式：

- 直接使用；
- 比例与偏移换算；
- 枚举或状态解析；
- 多点组合；
- 强类型公式；
- 跨节点计算。跨节点输入只能选择其他节点的 L2。

先“检查结果”，确认输入绑定、类型、单位、质量传播和试算值，再发布。发布后在“标准实体”查看 L2 的
实时值、历史和来源证据。需要接入第二台同型号设备时，再把已验证加工保存为模板复用。

数值型原始点位未声明单位时，可在“直接使用”中填写真实工程单位；已有实体从“标准实体 → 模板与版本 →
编辑当前加工”补填输出单位，检查后发布。补填不换算数值，不修改 L0、实体身份、历史或控制限值；已有单位
不能直接改标，布尔值和跨节点 L2 也不能这样补单位。存在控制占用或其他节点加工依赖时，先解除对应占用。

### 4. 配置上层应用

- 在告警中心选择 L2，设置等级、触发值、恢复值和持续时间；需要外部通知时绑定 HTTP 通知配置。
- 调度策略的通用路径是：选择一个或多个 committed L2 输入并设置唯一别名 → 编辑原生 JDM 决策表 → 将输出别名绑定到已确认、可控且有安全边界的 L2。
- 新通用表使用 GoRules 原生 `collect` 和 `intents` 输出；每条命中规则显式给出 `action_id` 与 `target`。同一次结果不得重复控制同一 action 或同一实体；含糊或动态目标失败关闭。
- 保存草稿、试算、发布和启用是四个独立动作。试算只显示输入快照、命中结果和拟执行意图，不下发设备；发布冻结不可变修订，启用后才可能产生控制意图。
- 完整 JDM graph 是唯一事实来源。只有可无损往返的单一决策表才在原生表中编辑；复杂图继续使用完整规则图，不自动改写或降级。
- 2充2放保留为可选起始模板，其 SOC 和功率绑定继续执行专用类型、单位与安全边界校验。历史已存的旧 `&&` 条件图不会自动迁移，必须在原生表或完整图中显式改成 GoRules 原生区间，重新保存、试算、发布后才可使用。
- 对可控 L2 配置唯一写点、限值、联锁、权限、超时和回读条件。每个控制意图只下发一次；接口受理、JDM 命中或页面刷新都不代表设备成功，只有新 committed L2 回读匹配才算完成。
- EMS 工作台按稳定 L2 语义显示数据，不直接绑定品牌地址。

### 5. 验证并交付

沿固定主干逐层验收：

```text
节点 → L0 实时/历史 → L1 检查与发布 → L2 实时/历史/来源
     → 告警 → 调度策略 → 控制回读 → EMS 工作台
```

交付时锁定平台版本、镜像摘要、数据库 Schema、模板摘要和配置修订，并完成备份恢复、断线、STALE、
进程重启和配置并发验证。详细检查见 [验收清单](docs/acceptance-checklist.md)。

## 快速启动

### 前置条件

- Docker 与 Docker Compose
- Python 3.12+
- 已运行并可访问的 Neuron（需要接入现场协议时）

### 本机启动

```bash
git clone https://github.com/taidai/zizu.git
cd zizu
python scripts/bootstrap_runtime_secrets.py
docker compose up -d --build
docker compose ps
```

首次启动后创建唯一平台管理员，密码通过无回显交互输入：

```bash
docker compose exec backend python -m scripts.bootstrap_admin --username admin
```

默认配置按生产安全要求运行并强制 HTTPS。只有完全隔离的本机开发环境才可在 `.env` 中同时设置：

```env
DEPLOYMENT_MODE=development
ALLOW_INSECURE_DEV_SECRETS=true
AUTH_REQUIRE_HTTPS=false
```

随后访问 `http://127.0.0.1:9000`。生产环境必须使用 TLS 入口、非公开凭据和固定镜像摘要；不要使用
`latest`。常规不可变部署使用 `deploy/docker-compose.release.yml`，裁剪内核 e606 使用
`deploy/docker-compose.release.e606.yml`。

常用运维命令：

```bash
docker compose ps
docker compose logs -f backend
docker compose restart backend
docker compose down
```

`docker compose down` 不删除数据卷；不要使用 `down -v`，除非明确要永久删除数据库和运行数据。

## 本地开发与验证

后端：

```bash
cd backend
python -m pip install -e .
python -m unittest discover -s tests -p 'test_*.py'
```

前端：

```bash
cd frontend
npm ci
npm run dev
npm run build
```

无头浏览器验收需要先配置目标地址和测试身份，再运行：

```bash
cd frontend
npm run test:e2e:node
npm run test:e2e:alarm-http
npm run test:e2e:dispatch-strategy
```

提交或发布前必须再次按[验收清单](docs/acceptance-checklist.md)走通
“节点 → L0 → L1 → L2 → 告警”主干。页面能够打开不等于工业系统已经可交付。

## 技术栈

| 层 | 技术 |
|---|---|
| 协议接入 | Neuron |
| 消息总线 | NanoMQ / MQTT |
| 后端 | Python 3.12、FastAPI |
| 数据库 | PostgreSQL、TimescaleDB |
| 决策模型 | GoRules ZEN / JDM |
| 前端 | React 18、TypeScript、Vite、ECharts |
| 部署 | Docker Compose、不可变镜像摘要 |

## 文档

- [中英文技术架构说明](docs/ZIZU-TECHNICAL-ARCHITECTURE.md)
- [核心架构总纲](docs/superpowers/specs/2026-08-27-zizu-platform-core-architecture-design.md)
- [领域术语](CONTEXT.md)
- [架构决策记录](docs/adr/)
- [验收清单](docs/acceptance-checklist.md)
- [v1.0.4 集成、发布与现场复验记录](docs/reviews/2026-09-07-tablet-production-acceptance.md)
- [v0.9.9 历史现场部署记录](docs/deploy-1号机-v0.9.9-http.md)

文档冲突时，解释顺序为：核心架构总纲 → 最新 accepted ADR → 当前专项规格 → 历史记录。

## 许可证

ZiZu 按仓库中的[《十善业协议（Daśa-kuśala License）1.0》](LICENSE)授权。使用、修改或分发前请阅读
完整条款；该许可证包含用途限制和分发义务。