---
name: edge-user-story-writer
description: edge_collector 用户故事编写规范。用于将协议适配、边缘功能、云平台功能、AI 分析、本地模型、前端页面、部署运维、稳定性治理等需求整理为用户故事、验收标准、边界、不包含范围和验证方式。
---

# edge_collector 用户故事编写

## 适用场景

- 协议适配：FANUC、西门子、Modbus、OPC UA 等。
- 边缘功能：WiFi、4G、内网穿透、端口转发、离线缓存、OTA。
- 云平台：设备管理、历史趋势、AI 分析、版本发布。
- 本地模型和 AI Provider 接入。
- 部署运维、远程同步、故障治理。
- 前端复杂页面或交互改造。

## 编写原则

- 面向用户价值，不从代码模块倒推需求。
- 保持故事小而可测，一个故事只交付一个清晰能力。
- 写清“不包含什么”，避免范围膨胀。
- 验收标准必须能通过接口、页面、日志、构建或远程验证证明。
- 对用户可见能力隐藏内部实现细节。

## 编号建议

```text
US-EDGE-001    边缘运行能力
US-CLOUD-001   云平台能力
US-PROTO-001   协议适配
US-AI-001      AI 分析
US-OPS-001     部署运维
US-UI-001      前端交互
```

如果项目已有编号体系，优先沿用已有体系。

## 标准模板

```markdown
### US-<TYPE>-<NUMBER>: <简短标题>

**角色**: <现场用户/运维人员/平台管理员/开发人员>
**优先级**: High/Medium/Low
**状态**: Draft/Ready/Done

#### 1. 用户故事

作为 <角色>，
我希望 <完成的动作或能力>，
以便 <获得的价值或解决的问题>。

#### 2. 背景与问题

- 当前现象：
- 影响：
- 触发场景：

#### 3. 范围

包含：
- 

不包含：
- 

#### 4. 业务场景图

> 简单配置项或单点文案修改可省略；复杂流程、云边链路、协议采集链路、部署流程、AI 分析数据流、前端多区域交互必须提供 SVG。

![业务场景图](./assets/<用户故事ID>-<简短标题>-业务场景图.svg)

#### 5. 验收标准

场景 1：<正常路径>
- Given：
- When：
- Then：
- 验证方式：

场景 2：<异常或边界路径>
- Given：
- When：
- Then：
- 验证方式：

#### 6. 规则与约束

- 

#### 7. 相关模块

- 前端：
- 后端：
- 边缘：
- 云端：
- 脚本/部署：

#### 8. 待确认

- [ ] 
```

## 业务场景图规则

以下用户故事必须生成 SVG，并在正文引用：

- 云边链路：边缘采集、上传、云端入库、云端展示。
- 协议链路：设备、驱动、点位、采集结果、异常恢复。
- 部署流程：构建主机、runtime、目标主机、服务重启、配置保护。
- AI 分析：数据选择、降采样、提示词、AI 调用、报告展示/导出。
- 前端复杂交互：多区域联动、弹窗流程、图表与报告、长任务状态。
- 稳定性治理：问题发现、排查、修复、验证、预防规则。

可省略 SVG 的场景：

- 单个字段默认值调整。
- 单个按钮文案或样式调整。
- 不涉及流程的简单配置说明。

SVG 生成要求：

- 使用 `edge-svg-diagram`。
- 放到用户故事文档同级或专题目录下的 `assets/`。
- 文件名建议：`US-<TYPE>-<NUMBER>-<简短标题>-业务场景图.svg`。
- 图中只写用户、业务对象、流程、状态和结果；不写 helper、SDK、库路径、AI Key、内部模型配置。
- 文档/方案型用户故事使用清晰、打印友好的图示风格；前端交互型用户故事可使用项目暗色 UI 风格。

## 当前项目常用验收方式

- 前端：页面操作、按钮 loading、错误提示、截图。
- 后端：接口请求/响应、权限、配置文件。
- 边缘：`systemctl status edge`、日志、设备采集点位。
- 云端：`cloud-server` 状态、历史数据、AI 分析接口。
- 部署：`package.sh`、`deploy_cloud.sh`、`scripts/migrate_edge.sh`。
- 数据：原始点数、降采样点数、上传策略解释。

## 与其他 skill 协作

- 需求不清时先用 `edge-requirement-interview`。
- 规则较多时用 `edge-business-rule-extractor`。
- 复杂交互先用 `edge-prototype-design`。
- 复杂流程或链路图用 `edge-svg-diagram`，并把 SVG 引用进用户故事。
- 写完后用 `edge-user-story-reviewer`。
- 后续详细设计用 `edge-design-doc-writer`。

## 注意

- 不把实现方案写成用户故事正文，可放到“相关模块”或后续详细设计。
- 不把 helper、SDK、库路径、AI Key、内部模型配置写进用户可见故事。
- 对部署类故事，必须写清是否会重启服务、是否影响运行配置。