216 lines
6.2 KiB
Markdown
216 lines
6.2 KiB
Markdown
|
# AGENTS.md — IoT v2.0 升级（前端）
|
|||
|
|
|
|||
|
|
> 本文档给所有 AI Agent（Claude Code / Cursor / Windsurf / Codex CLI / Aider 等）看
|
|||
|
|
> 遵循 [agents.md](https://agents.md/) 标准
|
|||
|
|
> 本 worktree 专用于 IoT 模块 v2.0 升级前端实施
|
|||
|
|
> 对应分支：`feat/iot-2.0`
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 一、项目背景
|
|||
|
|
|
|||
|
|
AIoT 前端（vben-admin 5.5.9 monorepo）IoT v2.0 升级前端：
|
|||
|
|
|
|||
|
|
- **技术栈**：Vue 3 + Ant Design Vue + Vben Admin 5.5.9 + pnpm 10+ + Node 20.19+ + Turborepo
|
|||
|
|
- **目标**：规则链 DAG 画布 + 子系统管理 + 告警正交状态机展示 + 派生物模型
|
|||
|
|
- **范围**：第一期 F1-F11（11 个前端任务）
|
|||
|
|
- **后端配对**：`C:\workspace\java17\aiot-platform-cloud-iot`（分支 `feat/iot-2.0`，承接 B1-B19）
|
|||
|
|
- **主工作应用**：`apps/web-antd/`（生产使用）
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 二、任务卡系统（权威 spec）
|
|||
|
|
|
|||
|
|
所有任务的需求 / 验收 / 约束在任务卡：
|
|||
|
|
|
|||
|
|
| 资源 | 绝对路径 |
|
|||
|
|
|------|---------|
|
|||
|
|
| 任务卡目录 | `C:\document\AIOT\开发者文档\03-IoT领域\升级设计方案\14-任务执行卡\` |
|
|||
|
|
| 目录说明 + Wave 依赖 | `14-任务执行卡\README.md` |
|
|||
|
|
| 评审档案 | `13-评审记录\01-10-轮次报告` + `11-决策记录` |
|
|||
|
|
|
|||
|
|
**本 worktree 任务范围**：仅 **F 开头前端任务**，第一期 F1-F11。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 三、硬约束（所有 Agent 共守）
|
|||
|
|
|
|||
|
|
### 3.1 Git 边界
|
|||
|
|
|
|||
|
|
- **分支**：`feat/iot-2.0`（worktree 绑定）
|
|||
|
|
- **禁止**：`git push`、`git push --force`、`--no-verify`、`--amend` 已推送的 commit
|
|||
|
|
- **禁止**：`git checkout` 切换分支（worktree 固定）
|
|||
|
|
- 本地 commit 即可，等人工 review 后再推送
|
|||
|
|
|
|||
|
|
### 3.2 任务范围
|
|||
|
|
|
|||
|
|
- 第一期仅 F1-F11
|
|||
|
|
- 禁止做 F12+（第二期起）
|
|||
|
|
|
|||
|
|
### 3.3 决策 5 双入口路由（**不可违反**）
|
|||
|
|
|
|||
|
|
- **保留**现有 `/iot/rule/scene/*`（v1 场景规则表单页）—— 不改不删
|
|||
|
|
- **新增** `/iot/rule/chain/*`（v2 DAG 画布）
|
|||
|
|
- 两入口平级共存，不做自动跳转
|
|||
|
|
- 灰度全量切换后再 `hidden: true`（v2.1 阶段处理）
|
|||
|
|
|
|||
|
|
### 3.4 代码边界
|
|||
|
|
|
|||
|
|
- **禁止**修改 `apps/web-antd/src/views/iot/rule/scene/*`
|
|||
|
|
- **禁止**修改 `apps/web-antd/src/router/routes/modules/iot.ts` 中现有 `scene` 路由项
|
|||
|
|
|
|||
|
|
### 3.5 质量门槛
|
|||
|
|
|
|||
|
|
- `pnpm check:type` 必须通过（TS 严格模式，**禁用 `any`**）
|
|||
|
|
- `pnpm lint` 必须通过
|
|||
|
|
- `pnpm test:unit` 必须通过
|
|||
|
|
- Acceptance Criteria 逐项通过才 commit
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 四、任务执行标准流程
|
|||
|
|
|
|||
|
|
1. **Read 任务卡**：`14-任务执行卡/Fxx-*.md`（绝对路径）
|
|||
|
|
2. **Read source_doc** + CLAUDE.md（本目录）
|
|||
|
|
3. **Read depends_on** 上游任务产出（含后端 VO 类型）
|
|||
|
|
4. **按 Known Pitfalls 规避**
|
|||
|
|
5. **实现 + Vitest 单元测试**
|
|||
|
|
6. **运行质检三连**：
|
|||
|
|
```bash
|
|||
|
|
pnpm check:type
|
|||
|
|
pnpm lint
|
|||
|
|
pnpm test:unit
|
|||
|
|
```
|
|||
|
|
7. **逐项 check Acceptance**；未全通过不 commit
|
|||
|
|
8. **commit 规范**（中文）：
|
|||
|
|
```
|
|||
|
|
[Fxx] 任务标题
|
|||
|
|
|
|||
|
|
- 主要文件 1
|
|||
|
|
- 主要文件 2
|
|||
|
|
- Known Pitfalls 落地：⚠️ 评审 Xx
|
|||
|
|
|
|||
|
|
Co-Authored-By: <AI 模型标识>
|
|||
|
|
```
|
|||
|
|
9. **更新任务卡** frontmatter：`status: completed` + `updated: <YYYY-MM-DD>`
|
|||
|
|
10. 查 `README.md §3.3` 下游 Wave
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 五、关键前端约定（第 8 轮评审 + 决策 5）
|
|||
|
|
|
|||
|
|
| 约定 | 规则 |
|
|||
|
|
|------|------|
|
|||
|
|
| **TypeScript 严格** | 不用 `any`；与后端 VO 类型对齐手动同步 `.d.ts` |
|
|||
|
|
| **依赖管理** | pnpm catalog（`pnpm-workspace.yaml`），**禁止**子 `package.json` 硬编码版本 |
|
|||
|
|
| **HTTP 请求** | `@vben/request`，**禁用** 原生 `fetch` / `axios` |
|
|||
|
|
| **状态管理** | Pinia |
|
|||
|
|
| **动态表单** | `@form-create/ant-design-vue`（已集成） |
|
|||
|
|
| **DAG 画布** | `@vue-flow/core`（F1 引入） |
|
|||
|
|
| **i18n** | 所有文案走 `t('iot.xxx')`，**禁止**硬编码中文；zh-CN / en-US 同步 |
|
|||
|
|
| **模板变量** | `${data.x}` / `${meta.x}` / `${alarm.x}` / `${trigger.x}`（与后端对齐），**禁用** `$[...]` |
|
|||
|
|
| **文件命名** | 组件 PascalCase（`DagCanvas.vue`），Composable `useXxx.ts` |
|
|||
|
|
|
|||
|
|
### 告警正交状态展示（评审 C1）
|
|||
|
|
|
|||
|
|
告警列表必须展示 **5 种组合**：
|
|||
|
|
|
|||
|
|
| 组合 | 颜色 |
|
|||
|
|
|------|------|
|
|||
|
|
| 活跃·未确认（ack=0, clear=0, archived=0） | 红 |
|
|||
|
|
| 活跃·已确认 | 橙 |
|
|||
|
|
| 已清除·未确认（关键运维场景） | **黄**（醒目） |
|
|||
|
|
| 已清除·已确认 | 绿 |
|
|||
|
|
| 已归档 | 灰 |
|
|||
|
|
|
|||
|
|
**禁止**退化为 3 态线性展示。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 六、测试与构建命令
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 类型检查
|
|||
|
|
pnpm check:type
|
|||
|
|
|
|||
|
|
# Lint
|
|||
|
|
pnpm lint
|
|||
|
|
|
|||
|
|
# 单元测试（Vitest）
|
|||
|
|
pnpm test:unit
|
|||
|
|
|
|||
|
|
# E2E（Playwright）
|
|||
|
|
pnpm test:e2e
|
|||
|
|
|
|||
|
|
# 开发服务器（端口 5666）
|
|||
|
|
pnpm dev:antd
|
|||
|
|
|
|||
|
|
# 生产构建
|
|||
|
|
pnpm build:antd
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 七、环境要求
|
|||
|
|
|
|||
|
|
- Node.js 20.19.0+
|
|||
|
|
- pnpm 10.0.0+
|
|||
|
|
|
|||
|
|
**首次进入 worktree 必做**：
|
|||
|
|
```bash
|
|||
|
|
pnpm install
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
node_modules 不跨 worktree 共享。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 八、后端 API 前置依赖
|
|||
|
|
|
|||
|
|
前端 F 任务多数依赖后端 API：
|
|||
|
|
|
|||
|
|
| 前端任务 | 依赖后端 API（来自 Bxx） |
|
|||
|
|
|---------|---------------------|
|
|||
|
|
| F3 属性面板 | B4/B5/B6 Provider metadata API |
|
|||
|
|
| F4 触发器表单 | B4 TriggerProvider metadata |
|
|||
|
|
| F5 条件表单 | B5 ConditionEvaluator metadata |
|
|||
|
|
| F6 动作表单 | B6 ActionProvider metadata |
|
|||
|
|
| F7 规则链列表 | B2 /iot/rule-chain/* API |
|
|||
|
|
| F9 子系统管理 | B10/B11 |
|
|||
|
|
| F10 告警列表 | B12 /iot/alarm-record/* |
|
|||
|
|
| F11 设备筛选 | B10/B11 |
|
|||
|
|
|
|||
|
|
若后端相关 B 任务未 completed：
|
|||
|
|
- F1/F2/F8 可独立开发
|
|||
|
|
- F3-F7/F9-F11 可先做 UI 骨架 + mock 数据，等后端就绪联调
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 九、需要人工决策的场景
|
|||
|
|
|
|||
|
|
Agent 遇以下情况不得自动判断，需停下通知：
|
|||
|
|
|
|||
|
|
- `pnpm check:type` / `lint` / `test:unit` 连续 3 次失败
|
|||
|
|
- Acceptance 有主观项（如 "UI 美观度"）
|
|||
|
|
- Known Pitfalls 的设计取舍
|
|||
|
|
- 上游后端 API schema 与任务卡预期不符
|
|||
|
|
- 视觉决策（颜色 / 布局细节未在任务卡规定）
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 十、相关文档索引
|
|||
|
|
|
|||
|
|
| 文档 | 用途 |
|
|||
|
|
|------|------|
|
|||
|
|
| `CLAUDE.md`（同目录） | Claude Code 专有机制 |
|
|||
|
|
| `14-任务执行卡/README.md` | 目录构成 |
|
|||
|
|
| `14-任务执行卡/01-Claude-Code执行设置指南.md` | 完整执行设置 |
|
|||
|
|
| `13-评审记录/11-未决议题的用户决策记录.md` | 决策 5 双入口 |
|
|||
|
|
| `C:\workspace\java17\aiot-platform-cloud-iot\AGENTS.md` | 后端对照 |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 十一、变更日志
|
|||
|
|
|
|||
|
|
- 2026-04-23 初建
|