ProjectAGiPrompt/1-AgentSkills/developing-rmdc-system/SKILL.md

name: developing-rmdc-system description: Guides development and architecture decisions for the RMDC (Runtime Management & DevOps Center) platform. Use when creating new modules, understanding module dependencies, implementing cross-module features, or reviewing system-level changes. Keywords: RMDC, architecture, module, dependency, API gateway, MQTT, watchdog, exchange-hub, authorization. argument-hint: " | <change-type: add-module|cross-module|dependency-change> | " allowed-tools: - Read - Glob - Grep - Bash

RMDC System Development Guide

System Overview

RMDC (Runtime Management & DevOps Center) 是以项目(K8s Namespace)为核心维度的统一运维与交付平台。通过"边缘代理(Watchdog) + 消息总线(Exchange-Hub)"架构打通内外网边界。

Architecture Layers

┌─────────────────────────────────────────────────────────────┐
│ Presentation    │ Vue3 + Vuetify3 + TypeScript              │
├─────────────────────────────────────────────────────────────┤
│ Gateway         │ rmdc-core (API Gateway + Auth + Routing)  │
├─────────────────────────────────────────────────────────────┤
│ Business        │ jenkins-dac | project-mgmt | user-auth    │
│                 │ audit-log | notice-center | monitor       │
├─────────────────────────────────────────────────────────────┤
│ Communication   │ rmdc-exchange-hub (MQTT Gateway)          │
├─────────────────────────────────────────────────────────────┤
│ Message Broker  │ MQTT Broker (EMQX/Mosquitto)              │
├─────────────────────────────────────────────────────────────┤
│ Edge            │ rmdc-watchdog → watchdog-node/agent       │
├─────────────────────────────────────────────────────────────┤
│ Data            │ PostgreSQL 13+                            │
└─────────────────────────────────────────────────────────────┘

---

Module Registry

Module	Responsibility	Tech Stack	Depends On
rmdc-core	API Gateway, Auth, Routing	Go + Gin	rmdc-common
rmdc-jenkins-branch-dac	Jenkins DAC, Build Mgmt	Jenkins API, MinIO	rmdc-common, rmdc-audit-log
rmdc-exchange-hub	MQTT Gateway, Command Lifecycle	MQTT, PostgreSQL	rmdc-common, rmdc-project-mgmt
rmdc-watchdog	Edge Proxy, K8S Ops, L2 Auth	K8S API, TOTP	rmdc-common
rmdc-project-management	Project CRUD, L1 Auth Center	PostgreSQL	rmdc-common, rmdc-audit-log
rmdc-audit-log	Audit Logging	PostgreSQL	rmdc-common
rmdc-user-auth	User Auth, RBAC	JWT, PostgreSQL	rmdc-common

详细依赖矩阵见 reference/module-dependencies.md

---

Plan Phase

当开始 RMDC 相关开发任务时，首先执行以下检查：

1. Identify Affected Modules

# 动态注入：查看当前模块结构
!`ls -la 8-CMII-RMDC/`

# 动态注入：搜索涉及的模块设计文档
!`grep -rnE "module|模块|service|接口" 8-CMII-RMDC/1-rmdc-system/ | head -30`

2. Produce Checklist

• 确定变更涉及的模块列表
• 确认是否涉及跨模块通信（MQTT/HTTP）
• 确认是否涉及契约变更（API/Event/Schema）
• 确认是否涉及授权层级变更（L1/L2）
• 确认是否需要数据库迁移

3. Decision Points

Decision	Options	Impact
New module vs extend existing	新增模块需注册到rmdc-core	路由、鉴权、审计
Sync vs Async communication	HTTP同步 / MQTT异步	延迟、可靠性
L1 vs L2 authorization	project-mgmt(L1) / watchdog(L2)	安全边界

---

Verify Phase

Cross-Module Compatibility Checklist

• API Gateway: rmdc-core 路由配置已更新
• Authentication: JWT claims 字段兼容
• RBAC: 权限点已在 rmdc-user-auth 注册
• Audit: 审计日志已按模块分表配置
• MQTT Topics: 新增 topic 已在 exchange-hub 注册
• Authorization: L1/L2 授权流程已验证

Dependency Verification

# 动态注入：检查模块间 import 关系
!`grep -rn "import.*rmdc-" --include="*.go" . | grep -v vendor | head -20`

# 动态注入：验证 go.mod 依赖
!`cat go.mod | grep -E "rmdc-|wdd.io"`

Integration Points

From	To	Protocol	Verify
rmdc-core	Business modules	HTTP/Internal	路由注册
Business modules	exchange-hub	HTTP	指令下发
exchange-hub	MQTT Broker	MQTT Pub/Sub	Topic 配置
MQTT Broker	watchdog	MQTT	公网连通性
watchdog	watchdog-node/agent	HTTP/gRPC	内网通信

---

Execute Phase

Adding New Business Module

1. Create module directory following structure:

   rmdc-{module-name}/
   ├── cmd/main.go
   ├── configs/
   ├── internal/
   │   ├── config/
   │   ├── dao/
   │   ├── handler/
   │   ├── model/{dto,entity}/
   │   └── service/
   └── pkg/
   

2. Register routes in rmdc-core:

   // rmdc-core/internal/router/router.go
   moduleGroup := r.Group("/api/{module}")
   moduleGroup.Use(middleware.AuthMiddleware())
   

3. Configure audit logging:

   // Add module to determineModule() in audit_service.go
   case strings.Contains(path, "/{module}/"):
       return "{module}"
   

4. Update RBAC permissions in rmdc-user-auth

Cross-Module Communication

HTTP (Sync): 模块间直接调用

resp, err := http.Post("http://rmdc-exchange-hub:8080/api/commands/send", ...)

MQTT (Async): 通过 exchange-hub 下发

exhub.SendCommand(ctx, &Command{
    ProjectID:   projectID,
    CommandType: "k8s_exec",
    Payload:     payload,
})

---

Pitfalls

1. 循环依赖: 业务模块间禁止直接 import，必须通过 rmdc-common 定义接口
2. JWT Claims 不一致: 修改 JWT 结构需同步更新所有解析方验证逻辑
3. MQTT Topic 命名冲突: 新增 topic 前必须检查 reference/mqtt-topics.md
4. L1/L2 授权边界模糊: 平台侧操作走 L1(project-mgmt)，边缘侧操作走 L2(watchdog)
5. 审计日志遗漏: 新模块必须配置独立审计表并注册到 DAOManager
6. 数据库连接池耗尽: 每个模块独立配置连接池，注意总数不超过 PostgreSQL max_connections
7. MQTT QoS 选择错误: 指令类消息必须使用 QoS=1，状态类可用 QoS=0

---

Related Skills

• developing-rmdc-core - API Gateway 开发
• developing-rmdc-jenkins-dac - Jenkins DAC 模块开发
• developing-rmdc-exchange-hub - MQTT 网关开发
• developing-rmdc-watchdog - 边缘代理开发
• developing-rmdc-project-mgmt - 项目管理模块开发
• developing-rmdc-audit-log - 审计日志模块开发
• developing-rmdc-user-auth - 用户认证模块开发
• designing-rmdc-contracts - API/事件契约设计
• managing-rmdc-migrations - 数据库迁移管理
• implementing-rmdc-observability - 可观测性实现

---

Quick Reference

Tech Stack

Layer	Technology
Frontend	Vue3, TypeScript, Vuetify3
Backend	Go 1.21+, Gin, GORM
Database	PostgreSQL 13+
Message	MQTT (EMQX/Mosquitto)
Storage	MinIO
Container	Docker, Kubernetes

API Response Format

{
    "code": 0,
    "message": "success",
    "data": {...}
}

Authorization Layers

Layer	Scope	Validity	Algorithm
L1 (一级)	project-mgmt ↔ watchdog	30 min	SHA256, 8-digit
L2 (二级)	watchdog ↔ agent/node	30 sec	SHA1, 6-digit (TOTP)