基于华为云码道（CodeArts）端到端开发机器人管理平台 — 实操指导文档

基于华为云码道（CodeArts）端到端开发机器人管理平台 — 实操指导文档

本文档以 A公司 机器人集群管理平台 为实战案例，手把手指导开发者如何利用华为云码道（CodeArts）从零开始，完成需求分析 → 架构设计 → 编码实现 → 测试验证 → 部署上线的端到端开发全流程。

---

目录

1. 项目概览
2. 环境准备与项目初始化
3. 需求分析与规格定义
4. 架构设计与技术选型
5. 编码实现 — 前端页面开发
6. 编码实现 — 数据层与业务逻辑
7. 编码实现 — 可视化与实时交互
8. 测试验证
9. 部署上线
10. 迭代演进 — 接入真实数据
11. 华为云码道核心能力速查
12. 常见问题与最佳实践

---

1. 项目概览

1.1 什么是机器人管理平台？

A公司 机器人集群管理平台是一个面向机器人运营团队的 实时监控与调度管理前端系统，核心能力包括：

能力域	说明
实时监控	24 台机器人的位置、状态、遥测数据一览无余
任务调度	负载均衡 + 距离优先策略，管理任务分配与执行
集群管理	机器人注册、项目创建与分配、固件版本管理、维护排程
数据分析	集群运行数据洞察与趋势分析
远程控制	远程操控、暂停/恢复、重启机器人（UI 已预留）

1.2 项目技术画像

维度	选型
前端框架	纯原生 HTML + CSS + JavaScript（零依赖）
可视化	原生 SVG 手绘（地图、图表、机器人剪影）
样式方案	CSS 变量 + 暗色主题 + 玻璃拟态
数据层	前端内存数组（预留 MQTT + ROS2 接入）
构建/打包	无（纯静态文件）
后端/数据库	无（当前为前端模拟，可扩展）

1.3 最终交付物

Robot Management Platform/
├── index.html          # 页面骨架（288 行）
├── css/style.css       # 全局样式（415 行）
├── js/
│   ├── data.js         # 数据与配置常量
│   ├── dashboard.js    # 仪表盘组件
│   ├── drawer.js       # 机器人详情抽屉
│   ├── pages.js        # 页面路由与动态页面
│   ├── search.js       # 全局搜索
│   └── app.js          # 初始化与事件绑定
├── README.md
└── LICENSE             # MIT 协议

---

2. 环境准备与项目初始化

2.1 开发环境要求

工具	版本要求	用途
华为云码道（CodeArts）	最新版	AI 辅助编码、需求分析、测试生成
浏览器	Chrome 90+ / Edge 90+	运行与调试
Git	2.30+	版本管理
Python 或 Node.js	可选	本地静态服务器（非必须）

2.2 在华为云码道中创建项目

1. 打开华为云码道 IDE，选择「打开文件夹」或「从仓库克隆」
2. 创建项目根目录 Robot Management Platform
3. 初始化 Git 仓库：

git init
git remote add origin <你的仓库地址>

4. 创建 .gitignore 文件：

.DS_Store
*.log
.vscode/
.idea/
node_modules/
.env
.env.local

2.3 与华为云码道对话 — 让 AI 帮你搭建脚手架

在码道对话窗口中输入：

帮我创建一个机器人集群管理平台的前端项目，要求：
- 纯原生 HTML + CSS + JavaScript，零依赖
- 暗色科技风主题，玻璃拟态设计
- 包含 index.html、css/style.css、js/app.js 等基础文件
- 先搭建页面骨架，包含侧边栏导航和主内容区

码道会自动生成项目骨架代码，你只需确认并微调即可。

提示：码道支持自然语言描述需求，直接生成可运行代码。对于复杂页面，建议分步骤描述，逐步构建。

---

3. 需求分析与规格定义

3.1 使用码道的规格驱动开发（SDD）能力

华为云码道内置 Spec-Driven Development 工作流，可从自然语言需求自动生成结构化规格文档。

在码道中输入：

我需要开发一个机器人集群管理平台，核心功能包括：
1. 总览仪表盘：展示 KPI、空间地图、状态分布、吞吐量图表、事件流
2. 机器人集群管理：卡片展示、状态筛选、注册新机器人
3. 实时地图：2D/3D 切换的空间定位
4. 任务调度：任务列表、新建任务、调度策略
5. 项目管理：项目卡片、新建项目
6. 固件与模型：机型管理、固件版本
7. 维护计划：维护排程
8. 数据洞察：KPI 汇总、趋势图表
9. 系统设置：功能开关、参数配置
10. 全局搜索：快捷键唤起，跨实体搜索

码道将自动生成 spec.md（需求规格）和 design.md（设计文档），包含：

• EARS 格式需求：每个功能条目都有明确的触发条件、系统行为、验收标准
• 架构设计：模块划分、数据流、交互流程
• 任务拆分：可执行的开发任务清单

3.2 需求拆分示例

以「总览仪表盘」为例，码道可能生成如下任务拆分：

任务编号	任务描述	依赖	预估复杂度
T-01	定义 KPI 数据结构与时间区间配置	无	低
T-02	实现 KPI 卡片组件（6 项指标 + 联动切换）	T-01	中
T-03	实现 SVG 空间定位地图（8 分区 + 机器人光点）	T-01	高
T-04	实现状态分布条形图	T-01	低
T-05	实现 SVG 面积图（吞吐量趋势）	T-01	中
T-06	实现实时事件流（自动推送）	T-01	中
T-07	实现项目分配概览	T-01	低
T-08	实现机器人清单表格	T-01	中

---

4. 架构设计与技术选型

4.1 架构决策记录

在码道中，你可以让 AI 帮你记录和推演架构决策：

帮我分析这个项目的技术选型：
- 为什么选择纯原生而非 React/Vue？
- 数据层如何设计才能平滑过渡到真实后端？
- SVG 可视化的性能边界在哪里？

关键架构决策

决策点	选择	理由
前端框架	纯原生	零依赖、零构建、双击即运行；原型阶段无需框架开销
可视化	原生 SVG	数据量小（24 台机器人），SVG 足以胜任；避免引入图表库
数据层	全局常量数组	前端模拟，后续替换为 API 调用即可；数据结构即接口契约
路由	JS 条件渲染	单页应用，侧边栏切换显示/隐藏 section
样式	CSS 变量 + 原生	暗色主题统一管理，无预处理器依赖

4.2 模块依赖关系

index.html
  ├── css/style.css          (全局样式与主题变量)
  └── js/
      ├── data.js            (数据定义，被所有模块依赖)
      ├── pages.js           (页面路由，依赖 data.js)
      ├── dashboard.js       (仪表盘，依赖 data.js)
      ├── drawer.js          (详情抽屉，依赖 data.js)
      ├── search.js          (全局搜索，依赖 data.js)
      └── app.js             (入口，依赖以上所有模块)

4.3 数据模型设计

在码道中输入：

帮我设计机器人管理平台的数据模型，需要包含：
- 机器人（ID、名称、型号、状态、位置、项目、电量、任务、心跳、坐标）
- 项目（ID、名称、颜色、图标、描述）
- 任务（编号、机器人、描述、项目、状态、进度、优先级）
- 事件（时间、类型、标题、元信息）

码道将生成 data.js 的完整数据结构，例如：

const ROBOTS = [
  {id:'ATX-014', name:'阿特拉斯·甲', model:'Atlas-X2', status:'working',
   loc:'仓储A区', proj:0, bat:78, task:'巡检货架 R12-R18', seen:'2s', x:150, y:90},
  // ... 更多机器人
];

const STATUS = {
  working:  {label:'作业中',   cls:'b-working',   color:'#6366f1'},
  ready:    {label:'待命就绪', cls:'b-ready',     color:'#34d399'},
  charging: {label:'充电中',   cls:'b-charging',  color:'#fbbf24'},
  error:    {label:'故障',     cls:'b-error',     color:'#fb7185'},
  offline:  {label:'离线',     cls:'b-offline',   color:'#6b6b73'},
  maint:    {label:'维护中',   cls:'b-maint',     color:'#a855f7'},
};

---

5. 编码实现 — 前端页面开发

5.1 页面骨架（index.html）

在码道中描述页面结构：

帮我创建 index.html，要求：
- 暗色科技风，左侧固定侧边栏 + 右侧主内容区
- 侧边栏包含：品牌 Logo、9 个导航项（仪表盘/机器人/地图/任务/项目/固件/维护/洞察/设置）、底部搜索按钮
- 主内容区包含：顶部标题栏 + 可切换的内容区域
- 使用语义化 HTML 标签

码道生成的关键结构：

<body>
  <aside id="sidebar">
    <div class="brand">A公司</div>
    <nav>
      <button data-page="dashboard" class="active">总览</button>
      <button data-page="robots">机器人</button>
      <button data-page="map">地图</button>
      <!-- ... 更多导航 -->
    </nav>
    <button id="search-btn">搜索</button>
  </aside>
  <main>
    <header id="topbar">...</header>
    <section id="sec-dashboard">...</section>
    <section id="sec-dynamic"></section>
  </main>
</body>

5.2 页面路由（pages.js）

在码道中输入：

帮我实现单页应用的路由切换逻辑：
- 点击侧边栏按钮切换页面
- dashboard 页面是静态 HTML，其他页面动态渲染
- 切换时更新顶部标题和侧边栏高亮
- 支持 9 个页面：dashboard/robots/map/tasks/projects/firmware/maint/insights/settings

核心路由逻辑：

function switchPage(page) {
  document.querySelectorAll('#sidebar nav button').forEach(b =>
    b.classList.toggle('active', b.dataset.page === page));
  // 隐藏/显示对应 section
  if (page === 'dashboard') {
    document.getElementById('sec-dashboard').style.display = '';
    document.getElementById('sec-dynamic').style.display = 'none';
  } else {
    document.getElementById('sec-dashboard').style.display = 'none';
    const dyn = document.getElementById('sec-dynamic');
    dyn.style.display = '';
    dyn.innerHTML = renderPage(page);  // 动态渲染
  }
}

5.3 各功能页面开发

对于每个功能页面，你可以在码道中逐步描述需求，让 AI 生成代码。以下是以「机器人集群」页面为例的交互过程：

第一步：基础布局

帮我实现机器人集群页面：
- 卡片式网格布局（4 列）
- 每张卡片显示：机器人名称、型号、状态标签、位置、电量条、当前任务
- 点击卡片打开详情抽屉

第二步：状态筛选

给机器人集群页面添加状态筛选功能：
- 顶部筛选栏：全部/作业中/待命/充电中/故障/离线
- 点击筛选标签，只显示对应状态的机器人卡片
- 筛选标签显示各状态的机器人数量

第三步：注册新机器人

添加「注册新机器人」功能：
- 页面右上角「+ 注册」按钮
- 点击弹出模态框，包含表单：ID、名称、型号（下拉）、初始状态、项目、位置、电量
- 提交后添加到 ROBOTS 数组并刷新页面

码道技巧：分步描述比一次性描述全部需求效果更好。每一步确认代码正确后，再进入下一步。

---

6. 编码实现 — 数据层与业务逻辑

6.1 数据定义（data.js）

在码道中输入：

帮我创建 js/data.js，定义以下数据：
1. ROBOTS：24 台机器人数组，包含 5 种型号（Atlas-X1/X2、Spot-Mini、Handle-Pro、Digit-V3）
2. PROJECTS：5 个项目（仓储巡检、物流搬运、实验室清洁、安防巡逻、末端配送）
3. STATUS：6 种状态定义（作业中/待命/充电中/故障/离线/维护中）
4. EVENTS：初始事件列表，5 种事件类型（error/warn/task/charge/info）
5. RANGE_DATA：4 个时间区间的 KPI 数据（实时/24h/7d/30d）
6. LOCATIONS：12 个位置名称

6.2 任务动态生成

任务数据从机器人状态动态推导，而非硬编码：

// 在码道中输入：帮我实现任务动态生成逻辑，从 ROBOTS 数组中提取 working/charging 状态的机器人生成任务列表
function buildTasks() {
  return ROBOTS
    .filter(r => r.status === 'working' || r.status === 'charging')
    .map((r, i) => ({
      taskId: `#400${i + 1}`,
      robotIdx: ROBOTS.indexOf(r),
      desc: r.task,
      proj: r.proj,
      status: r.status === 'working' ? 'working' : 'charging',
      prog: Math.floor(Math.random() * 60) + 30,
      pri: ['普通', '紧急', '低'][Math.floor(Math.random() * 3)],
      start: `0${9 + Math.floor(i / 4)}:${String((i * 17) % 60).padStart(2, '0')}`
    }));
}

6.3 实时心跳模拟

在码道中输入：

帮我实现实时心跳模拟：
- 每 4 秒向事件流推送一条随机新事件
- 5 种事件类型：开始任务、接入充电、低电量预警、负载重平衡、完成任务
- 事件包含时间戳、类型、标题、元信息
- 事件列表保留最近 20 条

---

7. 编码实现 — 可视化与实时交互

7.1 SVG 空间定位地图

这是项目中最复杂的可视化组件。在码道中分步构建：

第一步：基础平面图

帮我用 SVG 绘制一个实验室平面图（520x360），包含 8 个分区：
仓储A区、仓储B区、产线L3、走廊M2、充电站、立库、实验室C区、分拣/测试
用矩形表示各分区，添加分区标签

第二步：叠加机器人光点

在平面图上叠加机器人位置光点：
- 根据 ROBOTS 数组的 x/y 坐标定位
- 光点颜色根据状态着色（working=靛蓝、ready=翡翠绿、charging=琥珀黄、error=玫瑰红）
- 光点带脉冲动画效果

第三步：3D 等距透视

帮我实现 3D 等距透视视图：
- 将 2D 平面图转换为等距投影
- 机器人显示为 3D 立柱，柱高 = 电量/活跃度
- 支持 2D/3D 模式切换按钮

7.2 SVG 面积图（吞吐量趋势）

帮我用 SVG 绘制面积图：
- X 轴：48 个数据点（模拟 48 小时）
- Y 轴：任务执行速率
- 面积填充使用渐变色（靛蓝到透明）
- 鼠标悬停显示数值 tooltip

7.3 机器人详情抽屉

帮我实现机器人详情抽屉组件：
- 从右侧滑入，宽度 420px
- 顶部：机器人名称 + 状态标签 + 关闭按钮
- 机器人剪影 SVG 图标
- 实时遥测：电量、温度、CPU、内存、运行时长、里程
- 当前任务信息 + 进度条
- 迷你定位地图
- 传感器状态列表（6 项）
- 近期活动时间线
- 操作按钮：远程控制、暂停、重启、日志

7.4 全局搜索

帮我实现全局搜索功能：
- 快捷键 Cmd+K / Ctrl+K 唤起搜索框
- 搜索范围：机器人 ID/名称/型号/位置、项目名称/描述、位置名称
- 结果按类型分组显示（机器人/项目/位置）
- 支持键盘上下导航 + Enter 选中
- 点击结果跳转到对应详情

---

8. 测试验证

8.1 使用码道自动生成测试

华为云码道支持自动生成单元测试。在码道中输入：

帮我为 js/data.js 中的数据验证逻辑生成单元测试，确保：
- ROBOTS 数组长度为 24
- 每台机器人的 status 值都在 STATUS 对象中定义
- 每台机器人的 proj 值都在 PROJECTS 数组范围内
- 电量值在 0-100 范围内

8.2 手动测试检查清单

页面	测试项	预期结果
仪表盘	KPI 卡片数值	6 项 KPI 正确显示
仪表盘	时间区间切换	切换后 KPI/分布/副标题联动更新
仪表盘	事件流	每 4 秒自动推送新事件
机器人	状态筛选	筛选后仅显示对应状态机器人
机器人	注册新机器人	表单提交后卡片列表更新
地图	2D/3D 切换	视图正确切换，机器人位置正确
任务	新建任务	表单提交后任务列表更新
搜索	快捷键唤起	Ctrl+K 打开搜索框
搜索	跨实体搜索	输入关键词返回分组结果
设置	功能开关	Toggle 切换状态正确
抽屉	遥测数据	电量/温度/CPU 等数据正确显示

8.3 浏览器兼容性测试

# 本地启动静态服务器
python -m http.server 8080
# 或
npx serve .

在 Chrome、Edge、Firefox 中分别访问 http://localhost:8080，验证功能一致性。

---

9. 部署上线

9.1 静态部署方案

由于项目是纯静态文件，部署方式极其灵活：

方案 A：华为云 OBS + CDN

# 1. 创建 OBS 桶
# 2. 上传项目文件
# 3. 配置静态网站托管
# 4. 绑定自定义域名 + CDN 加速

方案 B：华为云 CodeArts Deploy

1. 在 CodeArts 中创建部署任务
2. 配置目标主机（ECS）
3. 上传文件到 Nginx 静态目录
4. 配置 Nginx：

server {
    listen 80;
    server_name your-domain.com;
    root /var/www/robot-platform;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }
}

方案 C：GitCode Pages

git remote add gitcode https://gitcode.com/<user>/robot-management-platform.git
git push -u gitcode main
# 在 GitCode 项目设置中开启 Pages 服务

9.2 版本管理与发布流程

# 功能开发在 feature 分支
git checkout -b feature/dashboard

# 开发完成后合并到 main
git checkout main
git merge feature/dashboard

# 打标签发布
git tag -a v1.0.0 -m "首个正式版本"
git push origin v1.0.0

---

10. 迭代演进 — 接入真实数据

当前项目使用前端模拟数据，真实生产环境需要接入后端服务。以下是使用码道辅助演进的路径：

10.1 数据层重构

在码道中输入：

帮我将 data.js 中的硬编码数据重构为 API 调用模式：
- 创建 js/api.js，封装所有数据获取方法
- 使用 async/await 模式
- 保留本地 fallback 数据，API 不可用时降级到模拟数据
- 接口设计参考 RESTful 风格

生成的 API 层示例：

const API_BASE = '/api/v1';

async function fetchRobots() {
  try {
    const res = await fetch(`${API_BASE}/robots`);
    if (!res.ok) throw new Error(res.statusText);
    return await res.json();
  } catch (e) {
    console.warn('API 不可用，降级到本地数据', e);
    return ROBOTS;  // fallback
  }
}

10.2 实时数据接入

帮我实现 MQTT WebSocket 实时数据接入：
- 连接 MQTT broker，订阅 nexus/telemetry/+ 主题
- 收到遥测数据后更新对应机器人的状态/电量/位置
- 心跳超时检测：超过 1.2s 未收到心跳标记为离线
- 告警触发：电量 < 15% 或温度 > 55°C 时推送告警事件

10.3 后端服务开发

如需开发后端，可在码道中继续：

帮我用 Node.js + Express 开发机器人管理平台的后端 API：
- GET /api/v1/robots — 获取机器人列表
- GET /api/v1/robots/:id — 获取机器人详情
- POST /api/v1/robots — 注册新机器人
- PATCH /api/v1/robots/:id — 更新机器人状态
- GET /api/v1/tasks — 获取任务列表
- POST /api/v1/tasks — 创建新任务
- GET /api/v1/projects — 获取项目列表
- WebSocket /ws — 实时遥测数据推送

---

11. 华为云码道核心能力速查

能力	使用场景	触发方式
AI 对话编码	描述需求 → 生成代码	对话窗口直接输入自然语言
Spec-Driven Development	需求 → 规格 → 设计 → 任务	输入需求描述，自动生成 spec.md / design.md / tasks.md
代码搜索	快速定位函数/类/变量	语义搜索或符号搜索
代码图谱	分析调用链、依赖关系	查询函数的调用者/被调用者
单元测试生成	自动生成测试用例	选中代码 → 生成测试
Bug 修复	定位并修复代码缺陷	描述问题现象 → 自动定位 → 生成补丁
前端设计	生成高质量 UI 组件	描述界面需求 → 生成代码
文档生成	生成 PRD/技术设计文档	描述文档类型和内容
代码审查规则	自定义代码审查规范	生成规则文件 → 集成到审查流程
定时任务	定时执行检查/报告	设置 cron 表达式 + 执行提示词

码道高效使用技巧

1. 分步描述：复杂功能拆成多步，每步确认后再继续
2. 提供上下文：引用已有文件名和函数名，让 AI 理解项目结构
3. 迭代修正：生成代码后指出问题，让 AI 修正而非重写
4. 利用搜索：先用代码搜索了解现有实现，再让 AI 基于现有模式生成
5. 审查规则：为项目配置代码审查规则，确保 AI 生成代码符合团队规范

---

12. 常见问题与最佳实践

Q1：码道生成的代码不符合项目风格怎么办？

在项目根目录创建 AGENT.md 文件，写入代码规范：

## 代码规范
- 使用 CSS 变量管理主题色，不要硬编码颜色值
- JavaScript 使用 const/let，不用 var
- 函数命名使用 camelCase，常量使用 UPPER_SNAKE_CASE
- SVG 图标手绘风格，不使用外部图标库
- 所有交互组件必须支持键盘操作

码道会自动读取 AGENT.md 并遵循项目规范。

Q2：如何让码道理解项目上下文？

• 保持对话连续性：在同一会话中完成相关功能开发
• 引用文件路径：明确告诉 AI 要修改哪个文件
• 先搜索再生成：让 AI 先搜索相关代码，再基于现有模式生成

Q3：纯原生项目如何保证代码质量？

措施	说明
模块化	每个功能独立文件，职责单一
数据驱动	所有视图由数据数组驱动渲染
CSS 变量	主题色/间距/圆角统一管理
事件委托	使用事件委托减少监听器数量
降级策略	API 不可用时自动降级到本地数据

Q4：如何从原型平滑过渡到生产级应用？

原型阶段（当前）          →    生产阶段
─────────────────────────────────────────
前端内存数组              →    后端 API + 数据库
setInterval 模拟心跳      →    MQTT/WebSocket 实时推送
无用户认证                →    IAM 集成 + RBAC 权限
纯静态文件                →    前后端分离 + CI/CD
无日志/监控               →    APM + 日志采集

Q5：项目扩展建议

方向	具体措施
后端	Node.js/Python API + PostgreSQL + Redis
实时	MQTT Broker（EMQX）+ WebSocket 网关
认证	华为云 IAM / OAuth2.0
监控	Prometheus + Grafana
CI/CD	华为云 CodeArts Pipeline
容器化	Docker + 华为云 CCE
前端升级	Vue 3 / React + TypeScript + Vite

---

附录：开发时间线参考

阶段	主要工作	码道辅助点
第 1 天	项目初始化 + 页面骨架 + 数据定义	脚手架生成、数据模型设计
第 2 天	仪表盘（KPI + 地图 + 图表 + 事件流）	SVG 可视化生成、组件拆分
第 3 天	机器人集群 + 详情抽屉 + 搜索	卡片布局、表单生成、搜索逻辑
第 4 天	任务调度 + 项目管理 + 固件/维护	表格组件、CRUD 逻辑
第 5 天	数据洞察 + 系统设置 + 样式打磨	图表组件、Toggle 开关、CSS 调优
第 6 天	测试 + 修复 + 部署	测试生成、Bug 修复、部署配置

说明：以上时间线仅为参考，实际耗时取决于开发者经验和需求复杂度。使用码道可显著缩短编码时间。

---