---
name: developing-watchdog
description: Guides development of rmdc-watchdog edge agent module including K8S operations, MQTT messaging, authorization management, and node/agent coordination. Use when implementing watchdog features, adding K8S actions, modifying heartbeat logic, or debugging authorization flows. Keywords: watchdog, edge-agent, k8s-operator, mqtt, authorization, heartbeat, node, agent.
argument-hint: "<feature-type>: k8s-action | heartbeat | mqtt-handler | node-comm | auth-flow"
allowed-tools:
  - Read
  - Glob
  - Grep
  - Bash
  - Edit
  - Write
---

# Developing rmdc-watchdog

rmdc-watchdog 是部署在项目环境的边缘代理，职责包括：二级授权中心、K8S操作代理、指令接收执行、监控数据上报。

## 动态上下文注入

```bash
# 查看项目结构
!`ls -la rmdc-watchdog/internal/`

# 查找现有Handler实现
!`grep -rn "func.*Handler" rmdc-watchdog/internal/handler/`

# 查找MQTT消息路由
!`grep -n "case\|switch" rmdc-watchdog/internal/service/message_router.go`
```

## Plan

根据 `$ARGUMENTS` 确定开发类型：

| 类型 | 产物 | 影响模块 |
|------|------|----------|
| k8s-action | `pkg/k8s/client.go`, `service/k8s_service.go` | exchange-hub指令定义 |
| heartbeat | `handler/heartbeat_handler.go`, `service/auth_service.go` | watchdog-agent同步修改 |
| mqtt-handler | `service/mqtt_service.go`, `service/message_router.go` | exchange-hub Topic契约 |
| node-comm | `service/node_service.go` | watchdog-node API同步 |
| auth-flow | `service/auth_service.go`, `dao/auth_dao.go` | project-management授权契约 |

**决策点**：
1. 是否新增MQTT消息类型？→ 需同步 exchange-hub
2. 是否修改心跳结构？→ 需同步 watchdog-agent
3. 是否修改K8S指令参数？→ 需同步 octopus-operator

## Verify

- [ ] TOTP验证逻辑：一级(8位/30分钟/SHA256) vs 二级(6位/30秒/SHA1)
- [ ] K8S操作边界：仅允许审计过的操作(logs/exec/scale/restart/delete/get/apply)
- [ ] MQTT Topic格式：`wdd/RDMC/{command|message}/{up|down}/{project_id}`
- [ ] 时间戳校验：|now - timestamp| < 5分钟
- [ ] Node通信：HTTP + Tier-Two TOTP认证
- [ ] 执行结果上报：包含 command_id, status, exit_code, output, duration

```bash
# 验证编译
!`cd rmdc-watchdog && go build ./...`

# 验证单元测试
!`cd rmdc-watchdog && go test ./internal/... -v`
```

## Execute

### 添加新K8S操作

1. 在 `pkg/k8s/client.go` 添加K8S API方法
2. 在 `internal/service/k8s_service.go` 的 switch 添加 case
3. 更新 `K8sExecCommand` 结构（如需新参数）
4. 同步更新 exchange-hub 指令下发定义

### 添加新指令类型

1. 在 `message_router.go` 添加路由分支
2. 创建对应 Handler 和 Service
3. 同步更新 exchange-hub 指令下发

### 修改心跳逻辑

1. 修改 `auth_service.go` 的 `VerifyHeartbeat`
2. 同步修改 watchdog-agent 心跳发送
3. 更新 DTO 结构

## Pitfalls

1. **TOTP层级混淆**：一级授权(project-management↔watchdog)与二级授权(watchdog↔agent/node)使用不同参数
2. **时间偏移未处理**：授权文件需计算 `timeOffset = now - firstAuthTime`
3. **Node离线未检测**：转发主机指令前需 `CheckHostOnline(host_id)`
4. **日志截断遗漏**：业务故障日志仅回传最近300行
5. **密钥公网传输**：tier_one_secret/tier_two_secret 必须通过配置文件离线部署，禁止MQTT传输
6. **响应TOTP缺失**：双向验证要求服务端返回TOTP供客户端校验
7. **心跳间隔不一致**：watchdog→exchange-hub 5秒；agent/node→watchdog 10秒（默认）

## Reference

- [状态机](reference/state-machine.md)
- [MQTT Topics](reference/mqtt-topics.md)
- [API端点](reference/api-endpoints.md)
- [安全机制](reference/security-mechanisms.md)