project-module-architecture

Project 项目管理模块架构指南

模块定位: Project 是 BK-CI 的基础模块，负责项目的创建、管理、权限、配置等功能。所有其他微服务都依赖 Project 模块，项目是 BK-CI 中资源隔离的最小单位。

一、模块整体结构

1.1 子模块划分

src/backend/ci/core/project/
├── api-project/          # API 接口定义层
│   └── src/main/kotlin/com/tencent/devops/project/
│       ├── api/
│       │   ├── op/           # 运维接口（7文件）
│       │   ├── open/         # 开放接口
│       │   ├── service/      # 服务间调用接口（10文件）
│       │   └── user/         # 用户接口（6文件）
│       ├── constant/         # 常量定义
│       └── pojo/             # 数据对象（60+ 文件）
│           ├── code/         # 消息码
│           └── enums/        # 枚举定义
│
├── biz-project/          # 业务逻辑层
│   └── src/main/kotlin/com/tencent/devops/project/
│       ├── config/           # 配置类
│       ├── dao/              # 数据访问层（20+ 文件）
│       ├── dispatch/         # 事件分发
│       ├── jmx/              # JMX 监控
│       ├── listener/         # 事件监听
│       ├── pojo/             # 内部数据对象
│       ├── resources/        # API 实现（25+ 文件）
│       ├── service/          # 业务服务
│       │   ├── impl/         # 服务实现（15+ 文件）
│       │   └── permission/   # 权限服务
│       └── util/             # 工具类
│
├── api-project-sample/   # 示例 API（扩展用）
├── biz-project-sample/   # 示例业务（扩展用）
├── boot-project/         # Spring Boot 启动模块
└── model-project/        # 数据模型层（JOOQ 生成）

1.2 模块职责矩阵

模块	职责	核心类数量
api-project	REST API 接口定义、POJO	100+
biz-project	业务逻辑、API 实现	120+
model-project	JOOQ 数据模型	自动生成

二、核心概念

2.1 项目实体模型

┌─────────────────────────────────────────────────────────────────────────┐
│                           BK-CI 项目模型                                 │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  ┌──────────────────────────────────────────────────────────────────┐   │
│  │                        项目 (Project)                             │   │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐   │   │
│  │  │ PROJECT_ID  │  │ project_name│  │ english_name            │   │   │
│  │  │ (UUID,不用) │  │ (项目名称)   │  │ (真正的projectId!)      │   │   │
│  │  └─────────────┘  └─────────────┘  └─────────────────────────┘   │   │
│  │                                                                   │   │
│  │  ⚠️ 注意：其他模块说的 projectId 就是 english_name                │   │
│  │                                                                   │   │
│  │  ┌─────────────────────────────────────────────────────────────┐ │   │
│  │  │                    组织架构信息                              │ │   │
│  │  │  bgId/bgName | deptId/deptName | centerId/centerName        │ │   │
│  │  │  businessLineId/businessLineName                            │ │   │
│  │  └─────────────────────────────────────────────────────────────┘ │   │
│  │                                                                   │   │
│  │  ┌─────────────────────────────────────────────────────────────┐ │   │
│  │  │                    项目属性 (Properties)                     │ │   │
│  │  │  pipelineDialectType | pipelineAsCodeSettings              │ │   │
│  │  │  pipelineLimit | subjectScopes                             │ │   │
│  │  └─────────────────────────────────────────────────────────────┘ │   │
│  └──────────────────────────────────────────────────────────────────┘   │
│                                                                          │
│  ┌──────────────────────────────────────────────────────────────────┐   │
│  │                     关联资源                                      │   │
│  │  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐            │   │
│  │  │pipeline │  │ repo    │  │ ticket  │  │ env     │  ...       │   │
│  │  └─────────┘  └─────────┘  └─────────┘  └─────────┘            │   │
│  └──────────────────────────────────────────────────────────────────┘   │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

2.2 项目核心字段

字段	类型	说明
ID	Long	数据库自增主键
PROJECT_ID	String	项目唯一标识（UUID，仅内部使用，其他模块不使用此字段）
project_name	String	项目中文名称（唯一）
english_name	String	项目英文标识（唯一，这才是其他模块所说的 projectId）
creator	String	创建者
CHANNEL	String	项目渠道（BS/CODECC/AM等）
approval_status	Int	审批状态
enabled	Boolean	是否启用
is_secrecy	Boolean	是否保密项目
properties	JSON	项目扩展属性
subject_scopes	JSON	可授权人员范围

⚠️ 重要说明：projectId 的真正含义

在 T_PROJECT 表中，PROJECT_ID 字段是一个 UUID，但这个字段几乎没有实际用途。

对于其他所有微服务（process、auth、repository、artifactory 等）来说，它们接口中的 projectId 参数实际上指的是 T_PROJECT.english_name 字段！

例如：

• ServiceProcessResource.list(projectId) → 这里的 projectId 是 english_name
• ServiceAuthResource.validatePermission(projectId) → 这里的 projectId 也是 english_name
• URL 路径 /api/user/projects/{projectId}/pipelines → 这里的 {projectId} 是 english_name

命名约定：

• 在代码中，projectId / projectCode / englishName 都指同一个东西：T_PROJECT.english_name
• T_PROJECT.PROJECT_ID（UUID）基本不使用，可以忽略

2.3 项目渠道类型

enum class ProjectChannelCode(val code: String) {
    BS("BS"),           // 蓝盾平台
    CODECC("CODECC"),   // 代码检查
    AM("AM"),           // 应用市场
    GCLOUD("GCLOUD"),   // 游戏云
    GITCI("GITCI"),     // GitCI
    STREAM("STREAM"),   // Stream
    PAAS("PAAS"),       // PaaS
}

2.4 项目审批状态

enum class ProjectApproveStatus(val status: Int) {
    CREATE_PENDING(1),      // 创建审批中
    CREATE_APPROVED(2),     // 创建已通过
    CREATE_REJECTED(3),     // 创建已驳回
    UPDATE_PENDING(4),      // 更新审批中
    UPDATE_APPROVED(5),     // 更新已通过
    UPDATE_REJECTED(6),     // 更新已驳回
}

三、分层架构图

┌─────────────────────────────────────────────────────────────────────────┐
│                              请求入口                                    │
│                    HTTP Request / 服务间调用                             │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                         API 层 (api-project)                             │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐    │
│  │UserProject   │ │ServiceProject│ │OPProject     │ │OpenProject   │    │
│  │Resource      │ │Resource      │ │Resource      │ │Resource      │    │
│  │(用户项目管理) │ │(服务间调用)   │ │(运维管理)     │ │(开放接口)    │    │
│  └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘    │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐                     │
│  │ServiceProject│ │OPDataSource  │ │OPSharding    │                     │
│  │TagResource   │ │Resource      │ │RoutingRule   │                     │
│  │(项目标签)     │ │(数据源管理)   │ │(分片路由)     │                     │
│  └──────────────┘ └──────────────┘ └──────────────┘                     │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                       业务层 (biz-project)                               │
│  ┌──────────────────────────────────────────────────────────────────┐   │
│  │                      ResourceImpl 实现层                          │   │
│  │  UserProjectResourceImpl | ServiceProjectResourceImpl | ...      │   │
│  └──────────────────────────────────────────────────────────────────┘   │
│                                    │                                     │
│  ┌──────────────────────────────────────────────────────────────────┐   │
│  │                      Service 层                                   │   │
│  │  AbsProjectServiceImpl       - 项目核心服务（77KB，最大）          │   │
│  │  ProjectApprovalService      - 项目审批服务                       │   │
│  │  ProjectTagService           - 项目标签服务                       │   │
│  │  ProjectPermissionService    - 项目权限服务                       │   │
│  │  ShardingRoutingRuleService  - 分片路由服务                       │   │
│  │  UserLocaleService           - 用户语言服务                       │   │
│  └──────────────────────────────────────────────────────────────────┘   │
│                                    │                                     │
│  ┌──────────────────────────────────────────────────────────────────┐   │
│  │                      Permission 层                                │   │
│  │  ProjectPermissionServiceImpl     - 默认权限实现                  │   │
│  │  RbacProjectPermissionService     - RBAC 权限实现                 │   │
│  │  StreamProjectPermissionServiceImpl - Stream 权限实现             │   │
│  └──────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                         DAO 层 (biz-project/dao)                         │
│  ProjectDao (42KB) | ProjectApprovalDao | ShardingRoutingRuleDao        │
│  UserDao | ServiceDao | GrayTestDao | NoticeDao | ...                   │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                      数据层 (model-project + MySQL)                      │
│  数据库：devops_ci_project（共 15+ 张表）                                │
└─────────────────────────────────────────────────────────────────────────┘

四、核心数据库表

4.1 项目核心表

表名	说明	核心字段
T_PROJECT	项目信息表	ID, PROJECT_ID, project_name,

---

Content truncated.