# RMDC 详细设计说明书 (DDS)

**产品名称**: RMDC (Runtime Management & DevOps Center)  
**版本**: v1.0  
**编制日期**: 2026-01-06

---

## 1. 系统架构

### 1.1 整体架构图

```mermaid
graph TB
    subgraph "前端层"
        Portal[RMDC Portal<br/>Vue3 + Vuetify3]
    end
    
    subgraph "网关层"
        Core[rmdc-core<br/>API Gateway + 鉴权]
    end
    
    subgraph "业务层"
        Jenkins[rmdc-jenkins-branch-dac<br/>构建管理]
        Project[rmdc-project-management<br/>项目管理]
        Audit[rmdc-audit-log<br/>审计日志]
        UserAuth[rmdc-user-auth<br/>用户权限]
        ExHub[rmdc-exchange-hub<br/>消息网关]
    end
    
    subgraph "通信层"
        MQTT[(MQTT Broker)]
    end
    
    subgraph "边缘层"
        WD[rmdc-watchdog<br/>边缘代理]
        Node[watchdog-node<br/>主机代理]
        Agent[watchdog-agent<br/>业务启动器]
    end
    
    subgraph "外部服务"
        JenkinsS[(Jenkins)]
        MinIO[(MinIO)]
        PG[(PostgreSQL)]
    end
    
    Portal --> Core
    Core --> Jenkins & Project & Audit & UserAuth & ExHub
    
    Jenkins --> JenkinsS & MinIO
    Project & Jenkins & Audit --> PG
    ExHub <--> MQTT
    MQTT <-.公网.-> WD
    WD <--> Node & Agent
```

### 1.2 技术栈

| 层级 | 技术 |
|------|------|
| 前端 | Vue3, TypeScript, Vuetify3 |
| 后端 | Go 1.21+, Gin, GORM |
| 数据库 | PostgreSQL 13+ |
| 消息 | MQTT (Eclipse Mosquitto) |
| 存储 | MinIO |
| 容器 | Docker, Kubernetes |

---

## 2. 模块职责

### 2.1 模块清单

| 模块 | 职责 | 关键能力 |
|------|------|----------|
| **rmdc-core** | API网关 | 路由、鉴权、限流 |
| **rmdc-jenkins-branch-dac** | Jenkins管理 | 分支权限、构建触发、DCU |
| **rmdc-project-management** | 项目管理 | CRUD、一级授权 |
| **rmdc-exchange-hub** | 消息网关 | MQTT中继、指令管理 |
| **rmdc-watchdog** | 边缘代理 | K8S操作、二级授权 |
| **rmdc-audit-log** | 审计日志 | 日志记录、查询导出 |
| **rmdc-user-auth** | 用户权限 | RBAC、权限分配 |

### 2.2 模块依赖关系

```mermaid
graph LR
    Core[rmdc-core] --> Jenkins & Project & Audit & UserAuth & ExHub
    
    Jenkins --> Common
    Project --> Common
    ExHub --> Common
    UserAuth --> Common
    
    Common[rmdc-common<br/>公共接口]
```

---

## 3. 通信架构

### 3.1 MQTT Topic设计

| Topic | 方向 | 用途 |
|-------|------|------|
| `wdd/RDMC/command/up` | 上行 | Watchdog发送指令 |
| `wdd/RDMC/message/up` | 上行 | Watchdog发送数据 |
| `wdd/RDMC/command/down/{project_id}` | 下行 | 下发指令 |
| `wdd/RDMC/message/down/{project_id}` | 下行 | 下发数据 |

### 3.2 消息格式

```json
{
    "message_id": "uuid",
    "type": "command|message",
    "project_id": "namespace_xxx",
    "command_type": "k8s_exec|host_exec|register|...",
    "timestamp": 1704501234567,
    "version": "1.0",
    "signature": "hmac-sha256",
    "payload": {...}
}
```

---

## 4. 安全架构

### 4.1 认证授权

| 层级 | 机制 |
|------|------|
| 用户认证 | JWT Token |
| API授权 | RBAC + 资源ACL |
| MQTT认证 | 用户名密码 + TLS |
| 数据加密 | AES-256-GCM |

### 4.2 TOTP双层授权

```
一级授权: project-management ↔ watchdog
  - 8位验证码
  - 30分钟有效期
  - SHA256算法
  
二级授权: watchdog ↔ agent/node
  - 6位验证码
  - 30秒有效期
  - SHA1算法
```

---

## 5. 数据模型

### 5.1 核心实体

```mermaid
erDiagram
    users ||--o{ user_permissions : has
    projects ||--o{ auth_info : has
    jenkins_organizations ||--o{ jenkins_repositories : contains
    jenkins_repositories ||--o{ jenkins_branches : contains
    jenkins_branches ||--o{ jenkins_builds : contains
    
    users {
        int64 id PK
        string username UK
        string password
        string role
    }
    
    projects {
        int64 id PK
        string project_id UK
        string name
        string namespace UK
        string status
    }
    
    jenkins_organizations {
        int64 id PK
        string name UK
    }
```

---

## 6. API设计规范

### 6.1 设计原则

1. **使用POST + RequestBody**: 所有API优先使用POST
2. **避免PathVariables**: 资源标识放入RequestBody
3. **避免RequestParams**: 查询参数放入RequestBody
4. **统一响应格式**: `{code, message, data}`

### 6.2 接口命名规范

| 操作 | 后缀 | 示例 |
|------|------|------|
| 列表 | `/list` | `/api/projects/list` |
| 详情 | `/detail` | `/api/projects/detail` |
| 创建 | `/create` | `/api/projects/create` |
| 更新 | `/update` | `/api/projects/update` |
| 删除 | `/delete` | `/api/projects/delete` |

---

## 7. 部署架构

### 7.1 K8S部署

```yaml
# 核心服务
rmdc-core: Deployment (replicas: 2)
rmdc-jenkins-branch-dac: 集成在rmdc-core
rmdc-project-management: 集成在rmdc-core
rmdc-exchange-hub: Deployment (replicas: 1)
rmdc-frontend: Deployment (replicas: 2)

# 边缘服务
rmdc-watchdog: Deployment (replicas: 1, 每项目独立)
rmdc-watchdog-node: DaemonSet (每节点一个)
```

### 7.2 网络架构

```
内网 ←→ MQTT Broker (公网暴露) ←→ 边缘网络
```

---

## 8. 相关文档

| 文档 | 内容 |
|------|------|
| [1-rmdc-PRD.md](file:///c:/Users/wddsh/Documents/IdeaProjects/ProjectAGiPrompt/8-CMII-RMDC/1-rmdc-system/1-rmdc-PRD.md) | 产品需求文档 |
| [1-jenkins-branch-dac-DDS.md](file:///c:/Users/wddsh/Documents/IdeaProjects/ProjectAGiPrompt/8-CMII-RMDC/2-Jenkins模块/1-jenkins-branch-dac-DDS.md) | Jenkins模块DDS |
| [prompts/1-system-overview-prompt.md](file:///c:/Users/wddsh/Documents/IdeaProjects/ProjectAGiPrompt/8-CMII-RMDC/1-rmdc-system/prompts/1-system-overview-prompt.md) | 系统架构提示词 |
| [prompts/3-api-development-prompt.md](file:///c:/Users/wddsh/Documents/IdeaProjects/ProjectAGiPrompt/8-CMII-RMDC/1-rmdc-system/prompts/3-api-development-prompt.md) | API开发规范 |
| [prompts/4-postman-testing-prompt.md](file:///c:/Users/wddsh/Documents/IdeaProjects/ProjectAGiPrompt/8-CMII-RMDC/1-rmdc-system/prompts/4-postman-testing-prompt.md) | Postman测试用例 |