---
name: edge-bugfix
description: edge_collector 缺陷排查与根因修复流程。用于用户报告边缘侧、云平台、协议采集、前端白屏、部署同步、远程主机 CPU/内存异常、脚本失败、接口失败等 Bug 或异常时，按读取证据、根因定位、最小修复、定向验证和报告沉淀推进。
---

# edge_collector Bug 修复流程

## 适用范围

- 边缘服务：`collector`、`configurator`、`edge` systemd 服务。
- 云平台：`cloud_server`、`frontend/cloud_app`、`deploy_cloud.sh`。
- 前端：`frontend/config_app`、`frontend/cloud_app`。
- 协议采集：FANUC、西门子、Modbus、OPC UA、传感器等。
- 脚本/部署：`scripts/`、`package.sh`、`scripts/migrate_edge.sh`。
- 远程主机：82/87/94/97、云服务器 `119.45.4.75`。

## 核心原则

1. 先只读取证据，后修改。
2. 必须定位根因，禁止只修表面症状。
3. 不回滚用户改动，不清空运行配置。
4. 涉及远程同步默认使用既有项目脚本，不手写替代流程。
5. 修改后必须给出定向验证命令和关键结果。

## 排查流程

### 1. 收集现场

按问题类型优先读取：

- Git 状态：`git status --short`
- 相关日志：`logs/`、`journalctl -u edge`、`journalctl -u cloud-server`
- 配置：`runtime/edge/config/`、`collector/config/`、`configurator/config/`
- 前端：浏览器错误、接口响应、构建产物、路由
- 远程主机：`uptime`、`free -h`、`df -h`、`systemctl status`

远程数字主机遵循 `host-connection-defaults`；边缘同步遵循 `edge-sync-host`。

### 2. 定位根因

优先沿真实链路追踪：

```text
用户现象
  -> 前端页面 / API
  -> configurator 或 cloud_server
  -> collector / agent / 脚本
  -> 配置文件 / SQLite / 网络 / systemd
```

典型链路：

- 前端白屏：CSS -> DOM -> JS -> API -> 构建产物。
- 云端接口失败：前端代理 -> cloud_server 路由 -> 数据库/外部服务。
- 采集异常：设备配置 -> DriverRegistry -> 驱动日志 -> 协议依赖库。
- 同步后异常：构建主机架构 -> 打包产物 -> runtime 配置排除 -> systemd 重启。

### 3. 修复策略

- 小范围修改，不做无关重构。
- C++ 遵循 `cpp-coding-style`。
- 后端接口/配置遵循 `backend-conventions`。
- 前端遵循 `frontend-ui-conventions`、`frontend-debug`、`frontend-dialog`。
- Shell 遵循 `shell-scripting`。
- 第三方库遵循 `third-party-libs`。

### 4. 验证要求

按改动选择最小但可信的验证：

- JSON 配置：`jq empty <file>`
- C++ collector：`cmake --build build --target collector -j2`
- configurator/cloud_server：对应 target 或项目测试脚本。
- 前端：能运行 npm 的环境执行 `npm run build`。
- 边缘打包：`./package.sh --edge-only`
- 远程部署：按用户明确要求再同步/重启。

### 5. 报告沉淀

复杂 Bug 或远程事故修复后，在 `docs/` 下写简短报告，建议位置：

- 远程主机/设备类：`docs/鲁班猫*/`
- 协议类：`collector/docs/protocols/`
- 通用事故：`docs/`

报告至少包含：现象、根因、修复、验证、后续预防。