aiot-platform-cloud/AGENTS.md

# 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`

> **注意**：本 worktree **不走 OpenSpec 流程**（主仓 master 的 AGENTS.md 指向 OpenSpec，与本升级无关）。
> 本升级的权威 spec = `14-任务执行卡/` 下的任务卡。

---

## 一、项目背景

AIoT 平台 IoT 模块（`viewsh-module-iot`）v2.0 升级实施：

- **技术栈**：Spring Boot 3.5.9 + Spring Cloud 2025 + MyBatis Plus 3.5.15 + JDK 17+
- **目标**：规则引擎从硬编码演进为 DAG + 子系统模型 + 告警状态机 + 设备影子
- **范围**：89 个任务分 3 期，当前第一期 B1-B19（19 个后端任务）
- **前端配对**：`C:\workspace\vue\aiot-platform-ui-iot`（分支 `feat/iot-2.0`，承接 F1-F11）

---

## 二、任务卡系统（权威 spec）

所有任务的需求 / 验收 / 约束均在任务卡：

| 资源 | 绝对路径 |
|------|---------|
| 任务卡目录 | `C:\document\AIOT\开发者文档\03-IoT领域\升级设计方案\14-任务执行卡\` |
| 编写指南 | `14-任务执行卡\00-任务卡编写指南.md` |
| 目录说明 + Wave 依赖 | `14-任务执行卡\README.md` |
| 评审档案（决策背景） | `13-评审记录\01-10` + `11-决策记录` + `12-ACP调研` |
| 原始设计方案 | `C:\document\AIOT\开发者文档\03-IoT领域\升级设计方案\00-12.md` |

**本 worktree 任务范围**：仅 **B 开头后端任务**，第一期 B1-B19。
第二期 B20+、B29（RPC Outbox 样板）、第三期 B44（脚本沙箱样板）**本期禁止做**。

---

## 三、硬约束（所有 Agent 共守）

### 3.1 Git 边界

- **分支**：必须在 `feat/iot-2.0` 分支提交
  - 每次任务开始前 `git branch --show-current` 核对
- **禁止**：`git push`（任何远程推送）、`git push --force`、`git commit --no-verify`、`git commit --amend` 已推送的 commit
- **禁止**：`git checkout` 切换到其他分支
- **禁止**：在 `master` / `main` / 其他分支 commit

### 3.2 任务范围

- 第一期仅 B1-B19
- **禁止做** B20+、B29、B44（非第一期）
- 任务卡 `Files §2.3 不可修改` 里的文件**绝不触碰**

### 3.3 代码边界

- **禁止**修改 `viewsh-module-iot-server/**/rule/**` 旧规则代码（v1 保留到观察期后由 B67 清理）
- **禁止**让 `viewsh-module-iot-rule` 模块依赖 `viewsh-module-iot-server` 或 `viewsh-module-iot-gateway`
- 依赖方向：`rule → core → api`（单向）

### 3.4 质量门槛

- Acceptance Criteria 任一项未通过 → **不允许 commit**
- 测试必须全部通过（`mvn test`）
- 不跳过 pre-commit hook

---

## 四、任务执行标准流程

每个任务逐项遵循：

1. **Read 任务卡**：`14-任务执行卡/Bxx-*.md`（绝对路径）
2. **Read source_doc**：任务卡列出的原方案章节
3. **Read depends_on**：上游任务**实际代码产出**（不只看任务卡文字）
4. **按 Known Pitfalls 规避**已知问题
5. **TDD**：先写测试骨架，再写实现
6. **运行测试**：`mvn test -pl <相关模块>`
7. **逐项 check Acceptance Criteria**；任一未通过不 commit
8. **commit 规范**：
   ```
   [Bxx] 任务标题

   - 主要文件 1
   - 主要文件 2
   - Known Pitfalls 落地：⚠️ 评审 Xx

   Co-Authored-By: <AI 模型标识>
   ```
9. **更新任务卡** frontmatter：`status: completed` + `updated: <YYYY-MM-DD>`
10. 查 `README.md §3.3` 确认下游 Wave

---

## 五、关键技术约定（源自第 8 轮评审规范清单）

| 约定 | 规则 |
|------|------|
| SPI Provider 注册 | Spring `@Component` + `getType()` 索引；**禁用** `ServiceLoader` / `@SPI` |
| 模板变量格式 | `${data.x}` / `${meta.x}` / `${alarm.x}` / `${trigger.x}`；**禁用** `$[...]` 旧语法 |
| 分布式锁 | Redis `SET NX PX` + Lua 原子解锁；**禁用** `SETNX` 老语法 |
| RPC 状态更新 | **Outbox Pattern**（见 B29 样板）；禁止同事务内 send + update DB |
| 告警状态模型 | `ack_state` + `clear_state` + `archived` 三字段正交；**禁用**线性 4 枚举 |
| 规则链匹配 | 三层 key 查询后 **LinkedHashMap 去重** |
| Aviator 脚本 | **8 层沙箱防护**（见 B44 样板） |
| Agent 调用协议 | **A2A**（JSON-RPC 2.0 over HTTPS）；**禁用** "ACP" 命名（已合并到 A2A，见 12 号调研） |
| 枚举 DB 存储 | `TINYINT` + Java Enum 映射；**禁用** VARCHAR 枚举字符串 |
| JSON 字段查询 | 关键维度建关联表；**禁用** `JSON_CONTAINS` 高频查询 |
| 主键 | `BIGINT AUTO_INCREMENT`（与其他 module 一致） |
| 多租户 | 所有 DAO 带 `tenant_id` 过滤（沿用项目风格） |

---

## 六、测试与构建命令

```bash
# 单模块测试
mvn test -pl viewsh-module-iot/viewsh-module-iot-rule

# 整仓构建（验证依赖）
mvn clean install -DskipTests -pl viewsh-module-iot/viewsh-module-iot-rule -am

# 依赖树（验证 rule 模块不依赖 gateway/server）
mvn dependency:tree -pl viewsh-module-iot/viewsh-module-iot-rule

# 启动开发服务
cd viewsh-module-iot/viewsh-module-iot-server
mvn spring-boot:run
```

---

## 七、环境要求

- JDK 17+
- Maven 3.6+
- MySQL 5.7+ / 8.0+
- Redis 5.0+
- Nacos 2.0+（服务注册 / 配置中心）

任务卡 `启动前自检` 会要求 Agent 核对以上环境。

---

## 八、需要人工决策的场景

Agent 遇到以下情况**不得自动判断**，需停下通知人类：

- 测试连续失败 3 次
- Acceptance Criteria 有无法自动验证的项（如"文档可读性"）
- 任务卡 Known Pitfalls 中的取舍点
- 依赖任务实际产出与任务卡预期不符
- 单任务执行超过 2 小时
- 上游任务 status 未 verified

具体通知机制由各 Agent 工具决定（Claude Code 用 PushNotification，其他工具按各自机制）。

---

## 九、相关文档索引

| 文档 | 用途 |
|------|------|
| `CLAUDE.md`（同目录） | Claude Code 专有机制（/loop、subagent、checkpoint） |
| `14-任务执行卡/README.md` | 目录构成 + Wave 依赖图 |
| `14-任务执行卡/00-任务卡编写指南.md` | 任务卡字段规范 |
| `14-任务执行卡/01-Claude-Code执行设置指南.md` | 完整执行设置（含 worktree / 权限 / 并行） |
| `13-评审记录/08-轮次8-...md` | 系统边界 + 规范清单 + 55 patch |
| `13-评审记录/11-未决议题的用户决策记录.md` | 6 项用户决策（含双入口）|
| `13-评审记录/12-ACP协议与Agent调用方案调研.md` | A2A 选型依据 |
| `C:\workspace\vue\aiot-platform-ui-iot\AGENTS.md` | 前端对照 |

---

## 十、变更日志

- 2026-04-23 初建；IoT v2.0 第一期专用