---
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: "<module-name> | <change-type: add-module|cross-module|dependency-change> | <design-doc-path>"
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

```bash
# 动态注入：查看当前模块结构
!`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

```bash
# 动态注入：检查模块间 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`:
   ```go
   // rmdc-core/internal/router/router.go
   moduleGroup := r.Group("/api/{module}")
   moduleGroup.Use(middleware.AuthMiddleware())
   ```

3. Configure audit logging:
   ```go
   // 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)**: 模块间直接调用
```go
resp, err := http.Post("http://rmdc-exchange-hub:8080/api/commands/send", ...)
```

**MQTT (Async)**: 通过 exchange-hub 下发
```go
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

```json
{
    "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) |