cloud
152 lines
4.6 KiB
Markdown
152 lines
4.6 KiB
Markdown
---
|
||
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。
|
||
|
||
|
||
|
||
#### 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、内部模型配置写进用户可见故事。
|
||
- 对部署类故事，必须写清是否会重启服务、是否影响运行配置。
|