zeaslity/ProjectAGiPrompt

Fork 0

Files

zeaslity 631cce9e1e RMDC系统设计文档整体转换为SKILL

2026-01-21 16:15:49 +08:00

40 KiB

Raw Blame History

RMDC 项目管理模块详细设计说明书 (DDS)

产品名称: RMDC 项目管理模块 (rmdc-project-management)
版本: v5.0
编制日期: 2026-01-16

1. 概述

1.1 模块定位

rmdc-project-management 是 RMDC 系统的核心业务模块，负责维护以 K8s Namespace 为粒度的"项目"全生命周期管理。该模块通过与 rmdc-work-procedure（工单模块）深度集成，实现了基于 Git Flow 思想的"草稿-审核-发布"的版本控制流程。

1.2 核心职责

项目全生命周期管理: 创建、维护（编辑/通过工单）、发布、归档/删除
版本控制: 记录项目配置的变更历史，支持版本回溯与差异对比（Diff）
细粒度权限控制: 基于 ACL 的权限控制，精确到用户与项目模块
授权管理: 管理项目的一级 TOTP 授权信息，与 Watchdog 交互

1.3 版本修订历史

版本	日期	修订内容
v1.0	2026-01-06	初始版本
v2.0	2026-01-12	增加生命周期状态机设计
v3.0	2026-01-14	完善草稿版本设计、细化权限模型、优化数据库结构
v4.0	2026-01-15	新增项目与工单模块状态同步机制设计（HTTP回调、状态映射表、风险处理）
v5.0	2026-01-16	状态同步机制从HTTP回调改为接口注入方式，HTTP回调方案移至备选文档

2. 系统架构

2.1 模块依赖关系

graph TB
    subgraph 核心层
        Core[rmdc-core<br/>API Gateway]
    end

    subgraph 业务协作
        PM[rmdc-project-management]
        WP[rmdc-work-procedure<br/>工单流程]
        UA[rmdc-user-auth<br/>用户认证/权限]
        Aud[rmdc-audit-log<br/>审计日志]
    end

    subgraph 边缘交互
        EH[rmdc-exchange-hub<br/>消息网关]
        WD[rmdc-watchdog]
    end

    Core --> PM
    PM -->|用户鉴权/查询| UA
    PM -->|项目权限管理| UA
    PM -->|发起审批/接收回调| WP
    PM -->|记录操作日志| Aud
    PM -->|下发授权指令| EH
    EH <--> WD

3. 项目生命周期管理

3.1 生命周期状态机

引入明确的生命周期状态机，管理项目从创建到销毁的全过程。

状态	说明	触发动作	权限
INIT	项目元数据已创建，等待详细信息录入	超级管理员创建项目	SuperAdmin
DRAFTING	正在进行初始信息填写（关联填写工单）	指定填写人保存/编辑	填写人/SuperAdmin
REVIEWING	初始信息或变更信息提交审核	提交审核	SuperAdmin
RELEASED	审核通过，正常运行中	审核通过	All (View)
MODIFYING	存在活跃的变更工单（不影响主线运行）	发起修改工单	Owner/SuperAdmin
ARCHIVED	软删除状态，不可见但保留数据	删除项目	SuperAdmin

3.2 状态转换图

stateDiagram-v2
    [*] --> INIT: 创建项目
    
    INIT --> DRAFTING: 分配填写人
    
    DRAFTING --> DRAFTING: 保存草稿
    DRAFTING --> REVIEWING: 提交审核
    
    REVIEWING --> DRAFTING: 审核打回
    REVIEWING --> RELEASED: 审核通过
    
    RELEASED --> MODIFYING: 发起修改工单
    RELEASED --> ARCHIVED: 归档删除
    
    MODIFYING --> MODIFYING: 保存草稿
    MODIFYING --> REVIEWING: 提交变更审核
    MODIFYING --> RELEASED: 撤销变更/审核通过
    
    ARCHIVED --> [*]
    
    note right of RELEASED: 项目认证状态=official
    note right of DRAFTING: 支持多次保存草稿
    note right of MODIFYING: 可同时存在多个变更工单

3.3 生命周期与工单状态映射

工单事件	工单目标状态	项目生命周期状态	说明
create	created	INIT→DRAFTING	创建填写工单
draft_save	in_progress	DRAFTING/MODIFYING(保持)	保存草稿
complete	pending_review	REVIEWING	提交审核
resubmit	pending_review	REVIEWING	被打回后重新提交
return	returned	DRAFTING	审核人打回
approve	approved→closed	RELEASED	审核人通过

3.4 状态同步机制设计

3.4.1 设计原则

项目模块（rmdc-project-management）与工单模块（rmdc-work-procedure）之间需要双向协作：

项目 → 工单：项目模块调用工单模块创建/转换工单
工单 → 项目：工单状态变更后同步更新项目生命周期状态

当前系统采用 "模块化单体"架构，所有模块运行在 rmdc-core 同一进程中，因此采用 接口注入（依赖注入） 方式实现模块间回调，而非 HTTP 回调。

备选方案：如未来需要微服务化部署，可参考 HTTP回调设计方案

3.4.2 架构设计（接口注入方式）

sequenceDiagram
    participant Frontend as 前端
    participant PM as rmdc-project-management
    participant Core as rmdc-core
    participant WP as rmdc-work-procedure
    
    Note over Core: 启动时注入回调接口
    Core->>PM: 注入 WorkflowTransitioner
    Core->>WP: 注入 ProjectLifecycleUpdater
    
    Note over PM,WP: 提交审核流程
    Frontend->>PM: POST /api/project/draft/submit
    PM->>WP: workflowTransitioner.TransitionWorkflow(complete)
    WP->>WP: 状态机转换 (in_progress → pending_review)
    WP->>PM: projectLifecycleUpdater.SetLifecycleToReviewing()
    PM->>PM: 更新 lifecycle_status = REVIEWING
    WP-->>PM: 返回新状态
    PM-->>Frontend: 返回成功响应

3.4.3 接口定义

项目模块调用工单模块的接口：

// WorkflowTransitioner 工单状态转换接口
// 由 rmdc-core 在初始化时注入，项目模块通过此接口调用工单模块
type WorkflowTransitioner interface {
    // TransitionWorkflow 触发工单状态转换
    // @param workflowID string - 工单ID
    // @param event string - 事件类型 (complete/submit/resubmit等)
    // @param operatorID uint64 - 操作人ID
    // @param operatorName string - 操作人姓名
    // @param remark string - 操作备注
    // @return newStatus string - 工单新状态
    // @return error - 错误
    TransitionWorkflow(workflowID, event string, operatorID uint64, 
                       operatorName string, remark string) (newStatus string, err error)
}

工单模块回调项目模块的接口：

// ProjectLifecycleUpdater 项目生命周期状态更新接口
// 由 rmdc-core 在初始化时注入，工单模块状态变更时调用
type ProjectLifecycleUpdater interface {
    // UpdateLifecycleStatus 更新项目生命周期状态
    UpdateLifecycleStatus(projectID, lifecycleStatus string) error
    
    // SetLifecycleToDrafting 设置为填写中状态（工单被打回后）
    SetLifecycleToDrafting(projectID string) error
    
    // SetLifecycleToReviewing 设置为审核中状态（提交审核时）
    SetLifecycleToReviewing(projectID string) error
    
    // SetLifecycleToReleased 设置为已发布状态（审批通过时）
    SetLifecycleToReleased(projectID string) error
    
    // SetLifecycleToModifying 设置为变更中状态（发起修改工单时）
    SetLifecycleToModifying(projectID string) error
}

3.4.4 依赖注入流程

在 rmdc-core/cmd/main.go 中完成模块间的依赖注入：

// 1. 初始化项目和工单服务
projectSvc := projectHandler.RegisterRoutes(r, dbs.Project, authMiddleware)
workflowSvc := workflowHandler.RegisterRoutes(r, dbs.Workflow, authMiddleware)

// 2. 注入工单→项目的回调（状态同步）
projectCallbackSvc := initProjectWorkflowCallbacks(dbs.Project)
workflowSvc.SetProjectLifecycleUpdater(projectCallbackSvc)

// 3. 注入项目→工单的调用（创建/转换工单）
workflowCreator := initProjectWorkflowCreator(workflowSvc)
projectSvc.SetWorkflowCreator(workflowCreator)

workflowTransitioner := initProjectWorkflowTransitioner(workflowSvc)
projectSvc.SetWorkflowTransitioner(workflowTransitioner)

3.4.5 接口注入方式的优势

特性	说明
简单高效	进程内调用，无网络开销
类型安全	编译期检查接口实现
事务一致性	可在同一数据库事务中执行
无需重试	不涉及网络失败，无需复杂的重试机制
开发调试	调试更简单，堆栈清晰

3.4.6 与 HTTP 回调的对比

特性	接口注入（当前实现）	HTTP 回调
模块解耦	⚠️ 接口级解耦	✅ 完全解耦
分布式支持	❌ 不支持	✅ 支持
性能	✅ 进程内调用	⚠️ 网络开销
复杂度	✅ 简单直接	⚠️ 需要重试/幂等处理
适用场景	模块化单体架构	微服务架构

如果未来系统需要微服务化，可参考 HTTP回调设计方案进行迁移。

3.5 详细状态映射表

根据工单类型和事件，映射到项目生命周期状态：

3.5.1 填写工单 (project_detail)

工单事件	工单From状态	工单To状态	项目生命周期状态	说明
`create`	-	`created`	`INIT→DRAFTING`	创建填写工单，分配填写人
`accept`	`assigned`	`in_progress`	`DRAFTING` (保持)	填写人开始填写
`draft_save`	`in_progress`	`in_progress`	`DRAFTING` (保持)	保存草稿
`submit/complete`	`in_progress`	`pending_review`	`REVIEWING`	提交审核
`return`	`pending_review`	`returned`	`DRAFTING`	审核人打回
`resubmit`	`returned`	`pending_review`	`REVIEWING`	重新提交
`approve`	`pending_review`	`approved`	`RELEASED`	审核通过，项目发布
`revoke`	any	`revoked`	`INIT`	撤销工单，恢复初始状态

3.5.2 修改工单 (project_modify)

工单事件	工单From状态	工单To状态	项目生命周期状态	说明
`create`	-	`created`	`RELEASED→MODIFYING`	发起修改工单
`accept`	`assigned`	`in_progress`	`MODIFYING` (保持)	开始修改
`draft_save`	`in_progress`	`in_progress`	`MODIFYING` (保持)	保存草稿
`submit/complete`	`in_progress`	`pending_review`	`REVIEWING`	提交审核
`return`	`pending_review`	`returned`	`MODIFYING`	审核人打回
`resubmit`	`returned`	`pending_review`	`REVIEWING`	重新提交
`approve`	`pending_review`	`approved`	`RELEASED`	审核通过，合并修改
`revoke`	any	`revoked`	`RELEASED`	撤销工单，恢复发布状态

3.6 回调处理实现

工单模块状态转换后，自动调用已注入的 ProjectLifecycleUpdater 接口更新项目状态：

// 工单模块 - 状态转换后触发项目状态更新
func (s *WorkflowService) handleProjectLifecycleCallback(workflow *entity.Workflow, event string) {
    // 从业务载荷中获取项目ID
    projectID, ok := workflow.BusinessPayload["project_id"].(string)
    if !ok || projectID == "" {
        return
    }
    
    // 根据事件类型更新项目生命周期状态
    if s.projectLifecycleUpdater != nil {
        switch event {
        case entity.EventApprove:
            s.projectLifecycleUpdater.SetLifecycleToReleased(projectID)
        case entity.EventReturn:
            s.projectLifecycleUpdater.SetLifecycleToDrafting(projectID)
        case entity.EventComplete, entity.EventResubmit:
            s.projectLifecycleUpdater.SetLifecycleToReviewing(projectID)
        }
    }
}

4. 权限控制模型

4.1 设计原则

权限控制分为 功能权限 (RBAC) 和 数据权限 (ACL)，数据权限需精确到项目模块级别。

重要决策：项目权限相关表设计在 rmdc-user-auth 模块中，由该模块统一管理所有权限数据。

4.2 功能权限 (RBAC)

权限代码	说明	角色
`project:create`	创建项目	SuperAdmin
`project:delete`	删除/归档项目	SuperAdmin
`project:edit`	直接编辑项目	SuperAdmin
`project:edit_workflow`	通过工单编辑项目	User (有ACL权限)
`project:auth_manage`	一级/二级授权管理	SuperAdmin
`project:permission_manage`	项目权限分配	SuperAdmin

4.3 数据权限 (ACL) - 模块级别

4.3.1 权限模块定义

模块代码	模块名称	说明
`basic_info`	基本信息模块	项目名称、命名空间、省份城市等
`business_info`	部署业务模块	部署人、部署时间、系统版本等
`environment_info`	部署环境模块	主机信息、网络环境、域名等
`middleware_info`	部署中间件模块	MySQL、Redis、EMQX等中间件配置
`authorization_info`	项目授权模块	TOTP授权信息（仅SuperAdmin）

4.3.2 权限类型

权限类型	说明
`view`	查看权限（可查看项目信息，可发起修改工单）
`export`	导出权限（可导出项目信息）

说明：编辑权限通过工单系统实现，拥有 view 权限的用户可以发起修改工单，由 SuperAdmin 审批后生效。

4.4 权限规则

SuperAdmin: 拥有所有项目的所有模块的全部权限，可直接修改
Admin: 可以访问自己被授权的项目模块，可以向普通用户转授权限
Normal User: 只能访问被授权的项目模块，修改需通过工单
项目填写人: 自动获得该项目的查看权限
授权模块: 仅 SuperAdmin 可见

5. 版本控制设计 (GIT-like)

5.1 设计原则

采用统一版本表设计，将正式版本和草稿版本存储在同一张表中，通过 version_type 字段区分。

5.2 版本类型

版本类型	代码	说明
正式版本	`official`	审核通过后的正式版本，构成版本历史
填写草稿	`fill_draft`	项目创建时填写人的草稿
修改草稿	`modify_draft`	发起变更工单时的草稿

5.3 版本与工单关系

填写草稿: 与填写工单 1:1 关联
修改草稿: 与修改工单 1:1 关联
正式版本: 审核通过后由草稿转化而来
一个项目可以有多个修改草稿（对应多个修改工单）

5.4. 版本快照机制

每次审核通过后，系统自动生成一个完整快照存储到 project_versions 表中。

5.4.1 快照结构

// VersionSnapshot 版本快照结构
type VersionSnapshot struct {
    BasicInfo        *BasicInfo        `json:"basic_info"`
    DeployBusiness   *DeployBusiness   `json:"deploy_business"`
    DeployEnv        *DeployEnv        `json:"deploy_env"`
    DeployMiddleware *DeployMiddleware `json:"deploy_middleware"`
}

5.4.2 快照生成时机

场景	版本号	版本类型	说明
项目首次审批通过	v1	official	项目初始版本
修改工单审批通过	v(N+1)	official	增量版本
超管直接修改	v(N+1)	official	重要：超管直改也必须生成新版本
用户保存草稿	0	fill_draft/modify_draft	临时版本，不计入历史

5.4.3 超级管理员直改与版本一致性

问题风险：如果超级管理员直接修改 projects 表数据而不生成版本历史，会导致版本链断裂，后续基于旧版本的工单 Diff 结果将失效或产生误导。

解决方案：超级管理员的 "Direct Edit" 操作必须被视为一次自动审批通过的事务：

原子操作：更新 projects 表 + 插入 project_versions 表必须在同一数据库事务中完成。
版本归属：生成的 Version 记录中，workflow_id 为空（或特定系统标识），committer_id 记录为 SuperAdmin ID，commit_message 强制填写或自动生成（如 "SuperAdmin Direct Update"）。
结果：确保 projects.current_version 永远指向最新的 project_versions.version。

5.4.4 并发修改与冲突检测 (Optimistic Locking)

由于超级管理员可能在其他用户编辑草稿期间直接修改项目，需要引入乐观锁机制处理冲突。

冲突场景：

用户 A 基于 v3 版本创建草稿（Draft based on v3）。
超级管理员直接修改项目，版本升级为 v4（Current = v4）。
用户 A 提交草稿审核。

处理策略：

提交时校验：工单提交/审核接口需校验 draft.base_version == project.current_version。
冲突提示：如果版本不一致，后端返回 409 Conflict 错误。
前端交互：
- 提示用户："项目已被修改，当前草稿已过期"。
- 提供 "Rebase" (变基) 选项：将当前草稿的修改重新应用到最新的 v4 版本上（即自动合并，若有字段冲突则让用户手动解决）。
- 或者提供 "Diff Check"：让用户查看当前草稿与最新 v4 的差异，决定是否覆盖或调整。

5.5 版本 Diff 算法

采用 JSON Diff 算法，对比两个版本快照的差异。

5.5.1 差异结构

// DiffResult 差异结果
type DiffResult struct {
    Module     string       `json:"module"`       // 模块名称
    FieldDiffs []FieldDiff  `json:"field_diffs"`  // 字段差异列表
}

// FieldDiff 字段差异
type FieldDiff struct {
    FieldPath  string      `json:"field_path"`   // 字段路径 如 "deploy_business.deployer_name"
    FieldName  string      `json:"field_name"`   // 字段中文名
    OldValue   interface{} `json:"old_value"`    // 旧值
    NewValue   interface{} `json:"new_value"`    // 新值
    ChangeType string      `json:"change_type"`  // add/modify/delete
}

5.5.2 Diff 实现

// CompareVersions 比较两个版本的差异
// @param baseVersion 基准版本（通常是较早的版本或 master）
// @param targetVersion 目标版本（通常是较新的版本或草稿）
// @return []DiffResult 差异结果列表，按模块分组
func (s *VersionService) CompareVersions(
    ctx context.Context, 
    baseVersion, targetVersion *VersionSnapshot,
) ([]DiffResult, error) {
    var results []DiffResult
    
    // 分模块对比
    modules := []struct {
        Name   string
        Base   interface{}
        Target interface{}
    }{
        {"基本信息", baseVersion.BasicInfo, targetVersion.BasicInfo},
        {"部署业务", baseVersion.DeployBusiness, targetVersion.DeployBusiness},
        {"部署环境", baseVersion.DeployEnv, targetVersion.DeployEnv},
        {"部署中间件", baseVersion.DeployMiddleware, targetVersion.DeployMiddleware},
    }
    
    for _, m := range modules {
        diffs := s.diffJSON(m.Base, m.Target)
        if len(diffs) > 0 {
            results = append(results, DiffResult{
                Module:     m.Name,
                FieldDiffs: diffs,
            })
        }
    }
    return results, nil
}

5.6 版本历史查询

5.6.1 版本列表结构

// VersionHistory 版本历史记录
type VersionHistory struct {
    Version       int       `json:"version"`        // 版本号
    VersionType   string    `json:"version_type"`   // 版本类型
    CommitMessage string    `json:"commit_message"` // 变更说明
    CommitterID   int64     `json:"committer_id"`   // 提交人 ID
    CommitterName string    `json:"committer_name"` // 提交人姓名
    WorkflowID    string    `json:"workflow_id"`    // 关联工单 ID
    CreatedAt     time.Time `json:"created_at"`     // 创建时间
    ChangeSummary string    `json:"change_summary"` // 变更摘要（如：修改了 3 个字段）
}

5.6.2 版本历史 API

方法	路径	描述
POST	`/api/project/version/list`	获取版本历史列表
POST	`/api/project/version/detail`	获取指定版本详情
POST	`/api/project/version/diff`	对比两个版本差异
POST	`/api/project/version/diff-with-current`	对比指定版本与当前版本差异

5.7 前端展示设计

5.7.1 版本历史页面

┌─────────────────────────────────────────────────────────────────┐
│  项目版本历史 - [项目名称]                                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ●──v3 (当前版本)  2026-01-14 15:30  张三                        │
│  │   └─ 变更说明: 更新部署环境信息                                │
│  │   └─ 关联工单: #WF-20260114-001                              │
│  │                                                              │
│  ●──v2              2026-01-10 10:00  李四                      │
│  │   └─ 变更说明: 修改中间件配置                                  │
│  │   └─ 关联工单: #WF-20260110-002                              │
│  │                                                              │
│  ●──v1 (初始版本)   2026-01-05 09:00  王五                       │
│      └─ 变更说明: 项目初始填写                                    │
│      └─ 关联工单: #WF-20260105-001                              │
│                                                                 │
│  [查看详情]  [对比版本]                                          │
└─────────────────────────────────────────────────────────────────┘

5.7.2 Diff 对比页面

┌─────────────────────────────────────────────────────────────────┐
│  版本对比: v2 → v3                                               │
├─────────────────────────────────────────────────────────────────┤
│  模块: 部署环境                                                  │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │ 字段           │ v2 (旧值)        │ v3 (新值)             │  │
│  ├───────────────────────────────────────────────────────────┤  │
│  │ 主机台数       │ 3                │ 5                     │  │
│  │ 主要公网 IP    │ 10.0.0.1         │ 192.168.1.100         │  │
│  │ 域名 URL       │ -                │ www.example.com [新增] │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                 │
│  模块: 部署中间件                                                │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │ 字段              │ v2 (旧值)     │ v3 (新值)             │  │
│  ├───────────────────────────────────────────────────────────┤  │
│  │ MySQL.内网端口    │ 3306          │ 3307                  │  │
│  └───────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

6. 数据模型设计

6.1 设计决策

决策点	决策	理由
JSONB vs 分表	使用JSONB存储	1. 项目信息结构复杂但查询简单 2. 版本快照需完整存储 3. 减少JOIN提升性能
草稿存储位置	project_versions表	统一版本管理，方便Diff比较
权限表位置	rmdc-user-auth模块	统一权限管理，便于跨模块授权

6.2 ER 图

erDiagram
    projects ||--o{ project_versions : has
    projects ||--o{ project_workflows : has
    projects ||--|| project_auth_configs : has
    
    projects {
        bigint id PK
        string project_id UK
        string name
        string namespace UK
        string lifecycle_status
        string certification_status
        bigint detail_filler_id
        string detail_filler_name
        int current_version
        jsonb basic_info
        jsonb deploy_business
        jsonb deploy_env
        jsonb deploy_middleware
        datetime created_at
        datetime updated_at
        datetime deleted_at
    }
    
    project_versions {
        bigint id PK
        string project_id FK
        int version
        string version_type
        bigint user_id
        string workflow_id
        jsonb snapshot_data
        string commit_message
        bigint committer_id
        string committer_name
        datetime created_at
        datetime updated_at
    }
    
    project_workflows {
        bigint id PK
        string project_id FK
        string workflow_id UK
        string workflow_type
        string status
        datetime created_at
    }
    
    project_auth_configs {
        bigint id PK
        string project_id FK
        string tier_one_secret
        int time_offset
        bool totp_enabled
        string auth_type
        int auth_days
        datetime created_at
        datetime updated_at
    }

表关系说明：

关系	说明
`projects` → `project_versions`	一对多，一个项目有多个版本记录（含草稿）
`projects` → `project_workflows`	一对多，一个项目可关联多个工单
`projects` → `project_auth_configs`	一对一，一个项目对应一个授权配置

字段说明：

表	字段	说明
projects	lifecycle_status	INIT/DRAFTING/REVIEWING/RELEASED/MODIFYING/ARCHIVED
projects	certification_status	draft/pending/official
project_versions	version_type	official/fill_draft/modify_draft
project_versions	workflow_id	关联 rmdc-work-procedure 模块的工单 ID
project_workflows	workflow_type	fill(填写)/modify(修改)

注意：workflow_id 字段引用 rmdc-work-procedure 模块的 workflows 表，属于跨模块关联，不在本模块ER图中展示外部表结构。

6.3 主表 DDL - projects

// Project 项目主表
type Project struct {
    ID                int64           `gorm:"primaryKey;autoIncrement" json:"id"`
    ProjectID         string          `gorm:"type:varchar(64);uniqueIndex;not null" json:"project_id"`
    Name              string          `gorm:"type:varchar(128);not null" json:"name"`
    Namespace         string          `gorm:"type:varchar(64);uniqueIndex;not null" json:"namespace"`
    
    // 生命周期状态
    LifecycleStatus   string          `gorm:"type:varchar(32);default:'INIT'" json:"lifecycle_status"`
    // 认证状态 (draft/pending/official)
    CertificationStatus string        `gorm:"type:varchar(32);default:'draft'" json:"certification_status"`
    
    // 当前正式版本号
    CurrentVersion    int             `gorm:"default:0" json:"current_version"`
    
    // 主版本数据 (使用JSONB存储，便于版本快照)
    BasicInfo         json.RawMessage `gorm:"type:jsonb" json:"basic_info"`
    DeployBusiness    json.RawMessage `gorm:"type:jsonb" json:"deploy_business"`
    DeployEnv         json.RawMessage `gorm:"type:jsonb" json:"deploy_env"`
    DeployMiddleware  json.RawMessage `gorm:"type:jsonb" json:"deploy_middleware"`
    
    // 项目填写人
    DetailFillerID    int64           `json:"detail_filler_id"`
    DetailFillerName  string          `gorm:"type:varchar(64)" json:"detail_filler_name"`
    
    // 审计字段
    CreatedBy         int64           `json:"created_by"`
    CreatedByName     string          `gorm:"type:varchar(64)" json:"created_by_name"`
    
    common.BaseModel
}

6.4 版本表 DDL - project_versions

// ProjectVersion 项目版本表 (含草稿)
type ProjectVersion struct {
    ID            int64           `gorm:"primaryKey;autoIncrement" json:"id"`
    ProjectID     string          `gorm:"type:varchar(64);index;not null" json:"project_id"`
    
    // 版本号 (正式版本递增, 草稿为0)
    Version       int             `gorm:"not null;default:0" json:"version"`
    
    // 版本类型: official/fill_draft/modify_draft
    VersionType   string          `gorm:"type:varchar(32);not null" json:"version_type"`
    
    // 草稿所属用户ID (仅草稿类型有值)
    UserID        int64           `gorm:"index" json:"user_id"`
    UserName      string          `gorm:"type:varchar(64)" json:"user_name"`
    
    // 关联工单ID (1:1关系, 仅草稿类型有值)
    WorkflowID    string          `gorm:"type:varchar(64);index" json:"workflow_id"`
    
    // 完整快照数据
    SnapshotData  json.RawMessage `gorm:"type:jsonb" json:"snapshot_data"`
    
    // 变更信息
    CommitMessage string          `gorm:"type:varchar(255)" json:"commit_message"`
    CommitterID   int64           `json:"committer_id"`
    CommitterName string          `gorm:"type:varchar(64)" json:"committer_name"`
    
    CreatedAt     time.Time       `json:"created_at"`
    UpdatedAt     time.Time       `json:"updated_at"`
}

6.5 项目工单关联表 DDL - project_workflows

// ProjectWorkflow 项目与工单关联表
type ProjectWorkflow struct {
    ID           int64     `gorm:"primaryKey;autoIncrement" json:"id"`
    ProjectID    string    `gorm:"type:varchar(64);index;not null" json:"project_id"`
    WorkflowID   string    `gorm:"type:varchar(64);uniqueIndex;not null" json:"workflow_id"`
    
    // 工单类型: fill(填写)/modify(修改)
    WorkflowType string    `gorm:"type:varchar(32);not null" json:"workflow_type"`
    
    // 工单状态 (冗余存储，便于查询)
    Status       string    `gorm:"type:varchar(32)" json:"status"`
    
    CreatedAt    time.Time `json:"created_at"`
    UpdatedAt    time.Time `json:"updated_at"`
}

6.6 权限表 DDL (位于 rmdc-user-auth 模块)

// ProjectACL 项目权限表 (模块级别)
type ProjectACL struct {
    ID           int64     `gorm:"primaryKey;autoIncrement" json:"id"`
    ProjectID    string    `gorm:"type:varchar(64);index;not null" json:"project_id"`
    UserID       int64     `gorm:"index;not null" json:"user_id"`
    
    // 模块代码: basic_info/business_info/environment_info/middleware_info/authorization_info
    ModuleCode   string    `gorm:"type:varchar(32);not null" json:"module_code"`
    
    // 权限类型
    CanView      bool      `gorm:"default:false" json:"can_view"`
    
    // 授权信息
    GrantedBy    int64     `json:"granted_by"`
    GrantedAt    time.Time `json:"granted_at"`
    
    UpdatedAt    time.Time `json:"updated_at"`
}

7. 接口设计 (API)

7.1 项目管理接口

方法	路径	描述	权限
POST	`/api/project/list`	获取项目列表 (自动过滤ACL)	Login
POST	`/api/project/detail`	获取项目详情 (Master版本)	View ACL
POST	`/api/project/create`	创建项目	SuperAdmin
POST	`/api/project/update`	直接更新项目	SuperAdmin
POST	`/api/project/delete`	删除项目 (软删除)	SuperAdmin
POST	`/api/project/export`	导出项目信息	Export ACL

7.2 版本管理接口

方法	路径	描述	权限
POST	`/api/project/version/list`	获取版本历史列表	View ACL
POST	`/api/project/version/detail`	获取指定版本详情	View ACL
POST	`/api/project/version/diff`	获取版本差异	View ACL

7.3 草稿管理接口

方法	路径	描述	权限
POST	`/api/project/draft/get`	获取当前用户的草稿	View ACL
POST	`/api/project/draft/save`	保存草稿	View ACL
POST	`/api/project/draft/submit`	提交审核	View ACL
POST	`/api/project/draft/discard`	放弃草稿	View ACL

7.4 权限管理接口 (SuperAdmin)

方法	路径	描述	权限
POST	`/api/project/permission/list`	获取项目权限列表	SuperAdmin
POST	`/api/project/permission/grant`	授予权限	SuperAdmin
POST	`/api/project/permission/revoke`	撤销权限	SuperAdmin
POST	`/api/project/permission/batch`	批量设置权限	SuperAdmin

8. 业务流程

8.1 项目创建流程

sequenceDiagram
    participant Admin as 超级管理员
    participant PM as rmdc-project-management
    participant WP as rmdc-work-procedure
    participant User as 填写人

    Admin->>PM: POST /api/project/create
    PM->>PM: 创建Project记录 (status=INIT)
    PM->>WP: 创建project_detail工单
    WP-->>PM: 返回workflow_id
    PM->>PM: 创建ProjectVersion草稿记录
    PM->>PM: 创建ProjectWorkflow关联记录
    PM-->>Admin: 返回项目创建成功

    PM->>User: 通知填写人
    User->>PM: POST /api/project/draft/save
    PM->>PM: 更新ProjectVersion草稿
    User->>PM: POST /api/project/draft/submit
    PM->>WP: 状态转换为pending_review
    PM->>PM: 更新lifecycle_status=REVIEWING

8.2 项目与工单关系

关系类型	项目状态	说明
项目:填写工单 = 1:1	INIT/DRAFTING	项目创建时只能有一个填写工单
项目:修改工单 = 1:N	RELEASED/MODIFYING	已发布项目可以有多个修改工单
用户:修改工单 = 1:1 (per project)	-	非SuperAdmin用户同一项目只能有一个活跃修改工单

9. 安全与规范

9.1 敏感字段加密

遵循系统规范，以下字段必须加密存储 (AES-256):

DeployBusiness.AdminPassword
DeployEnv.SSHPassword
DeployEnv.ManagementPassword
DeployMiddleware.*.AdminPassword

9.2 审计日志

所有对 projects 表的写操作均需通过 rmdc-audit-log 记录：

Resource: project
Action: create, update, publish_version, delete, permission_grant
Payload: 记录关键变更字段

10. 附录

10.1 基本信息结构体

10.1 基本信息结构体 (BasicInfo)

type BasicInfo struct {
    Province         string `json:"province"`         // 省份
    City             string `json:"city"`             // 城市 (级联)
    IndustryContact  string `json:"industry_contact"` // 行业组人员姓名
    IndustryPhone    string `json:"industry_phone"`   // 行业组人员电话
    ProjectNature    string `json:"project_nature"`   // 项目性质: research(科研)/test(测试)/trial(试用)/market(市场化)/sub_platform(二级平台)
}

10.2 业务部署结构体 (DeployBusiness)

type DeployBusiness struct {
    DeployerName      string `json:"deployer_name"`       // 部署人姓名
    DeployerPhone     string `json:"deployer_phone"`      // 部署人电话
    DeployStartTime   string `json:"deploy_start_time"`   // 部署开始时间
    DeployEndTime     string `json:"deploy_end_time"`     // 部署结束时间
    SystemVersion     string `json:"system_version"`      // 部署系统版本
    SystemType        string `json:"system_type"`         // 系统类型: business/fly-control/supervisor
    MainEntrance      string `json:"main_entrance"`       // 业务主要入口URL
    AdminUsername     string `json:"admin_username"`      // 系统超管用户名
    AdminPassword     string `json:"admin_password"`      // 系统超管密码 (加密存储)
}

10.3 部署环境结构体 (DeployEnv)

type DeployEnv struct {
    // 主机信息
    Hosts             []HostInfo `json:"hosts"`
    
    // 网络环境
    NetworkType       string     `json:"network_type"`     // internal(完全内网)/single_public(单主机公网)/full_public(全访问公网)
    MainPublicIP      string     `json:"main_public_ip"`   // 主要公网IP
    DomainURL         string     `json:"domain_url"`       // 域名URL
    SSLEnabled        bool       `json:"ssl_enabled"`      // 是否开启SSL
    
    // 管理方式
    ManagementType    string     `json:"management_type"`  // bastion(堡垒机)/whitelist(白名单)/vpn
    ManagementURL     string     `json:"management_url"`   // 管理后台URL
    ManagementUser    string     `json:"management_user"`  // 管理后台用户名
    ManagementPwd     string     `json:"management_pwd"`   // 管理后台密码 (加密存储)
    
    // 统计信息
    HostCount         int        `json:"host_count"`       // 主机台数
    TotalCPU          int        `json:"total_cpu"`        // CPU总核数
    CPUModel          string     `json:"cpu_model"`        // CPU型号
    TotalMemory       int        `json:"total_memory"`     // 内存总大小(GB)
    TotalStorage      int        `json:"total_storage"`    // 存储总大小(GB)
}

type HostInfo struct {
    Hostname          string `json:"hostname"`
    InternalIP        string `json:"internal_ip"`
    PublicIP          string `json:"public_ip"`
    CanAccessPublic   bool   `json:"can_access_public"` // 能否访问公网
    SSHPort           int    `json:"ssh_port"`
    SSHUser           string `json:"ssh_user"`
    SSHPwd            string `json:"ssh_pwd"`           // SSH密码 (加密存储)
    Role              string `json:"role"`              // master/worker/storage
}

10.4 部署中间件结构体 (DeployMiddleware)

type DeployMiddleware struct {
    MySQL         MiddlewareInfo `json:"mysql"`
    Redis         MiddlewareInfo `json:"redis"`
    EMQX          MiddlewareInfo `json:"emqx"`
    MinIO         MiddlewareInfo `json:"minio"`
    InfluxDB      MiddlewareInfo `json:"influxdb"`
    Nacos         MiddlewareInfo `json:"nacos"`
    K8SDashboard  MiddlewareInfo `json:"k8s_dashboard"`
}

// MiddlewareInfo 通用中间件信息
type MiddlewareInfo struct {
    PublicIP        string `json:"public_ip"`
    PublicPort      int    `json:"public_port"`
    InternalIP      string `json:"internal_ip"`
    InternalPort    int    `json:"internal_port"`
    K8SAddress      string `json:"k8s_address"`     // K8S集群内访问地址 (Service Name)
    K8SPort         int    `json:"k8s_port"`
    AdminUser       string `json:"admin_user"`
    AdminPwd        string `json:"admin_pwd"`       // 超管密码 (加密存储)
    Version         string `json:"version"`         // 中间件版本
}

10.5 项目授权信息结构体 (AuthorizationInfo)

注意：此结构对应 project_auth_configs 表，通常不作为 JSONB 存储在 projects 表中，而是通过关联表存储。此处列出仅供各种 DTO 参考。

type AuthorizationInfo struct {
    TierOneSecret    string    `json:"tier_one_secret"`    // 一级TOTP密钥
    TimeOffset       int       `json:"time_offset"`        // 允许时间偏移(秒)
    TOTPEnabled      bool      `json:"totp_enabled"`       // 是否开启TOTP
    TierTwoSecret    string    `json:"tier_two_secret"`    // 二级TOTP密钥 (来自Watchdog)
    
    AuthType         string    `json:"auth_type"`          // permanent(永久)/time_limited(限时)
    AuthDays         int       `json:"auth_days"`          // 授权有效期(天)
    AuthorizedAt     time.Time `json:"authorized_at"`      // 授权时间
    RevokedAt        time.Time `json:"revoked_at"`         // 撤销授权时间
    IsOffline        bool      `json:"is_offline"`         // 是否离线授权
}

10.6 相关文档

文档	说明
项目管理PRD	产品需求文档
项目状态说明	状态转换说明
工单模块DDS	工单流程设计
用户权限DDS	用户权限设计

40 KiB Raw Blame History Unescape Escape