project-module-architecture

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

Safety Notice

This listing is imported from skills.sh public index metadata. Review upstream SKILL.md and repository scripts before running.

Copy this and send it to your AI assistant to learn

Install skill "project-module-architecture" with this command: npx skills add tencentblueking/bk-ci/tencentblueking-bk-ci-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 , english_name , creator , CHANNEL , approval_status , enabled , properties

T_PROJECT_APPROVAL

项目审批表 ID , PROJECT_ID , APPLICANT , APPROVAL_STATUS , APPROVER , TIPS_STATUS

T_PROJECT_UPDATE_HISTORY

项目更新历史 ID , PROJECT_ID , BEFORE_INFO , AFTER_INFO , OPERATOR

T_PROJECT_LABEL

项目标签定义 ID , LABEL_NAME , CREATE_USER

T_PROJECT_LABEL_REL

项目标签关联 ID , PROJECT_ID , LABEL_ID

4.2 用户相关表

表名 说明 核心字段

T_USER

用户信息表 USER_ID , NAME , BG_ID , DEPT_ID , CENTER_ID , USER_TYPE

T_USER_DAILY_LOGIN

用户登录记录 USER_ID , DATE , LOGIN_TIME , OS , IP

T_USER_LOCALE

用户语言设置 USER_ID , LANGUAGE

T_FAVORITE

用户收藏 service_id , username

4.3 服务与配置表

表名 说明 核心字段

T_SERVICE

服务信息表 id , name , english_name , link , status

T_SERVICE_TYPE

服务类型 id , title , english_title , weight

T_ACTIVITY

活动信息 ID , TYPE , NAME , LINK , STATUS

T_NOTICE

公告信息 ID , NOTICE_TITLE , EFFECT_DATE , INVALID_DATE

4.4 分片相关表

表名 说明 核心字段

T_SHARDING_ROUTING_RULE

分片路由规则 ID , CLUSTER_NAME , MODULE_CODE , DATA_SOURCE_NAME , TABLE_NAME , ROUTING_NAME , ROUTING_RULE

T_TABLE_SHARDING_CONFIG

表分片配置 ID , CLUSTER_NAME , MODULE_CODE , TABLE_NAME , SHARDING_NUM

T_DATA_SOURCE

数据源配置 ID , CLUSTER_NAME , MODULE_CODE , DATA_SOURCE_NAME , DS_URL

五、核心类速查

5.1 API 接口层

类名 路径前缀 职责

UserProjectResource

/user/projects

用户项目管理（创建/更新/查询）

ServiceProjectResource

/service/projects

服务间项目查询

OPProjectResource

/op/projects

运维项目管理

OPProjectServiceResource

/op/project/service

运维服务管理

OpenProjectResource

/open/projects

开放项目接口

ServiceProjectTagResource

/service/project/tags

项目标签服务

ServiceShardingRoutingRuleResource

/service/sharding/routing/rules

分片路由规则

ServiceProjectApprovalResource

/service/project/approval

项目审批服务

UserLocaleResource

/user/locale

用户语言设置

5.2 Service 层

类名 文件大小 职责

AbsProjectServiceImpl

77KB 项目核心服务（最大，抽象基类）

ProjectApprovalService

18KB 项目审批流程

ProjectTagService

16KB 项目标签管理

AbsShardingRoutingRuleServiceImpl

16KB 分片路由规则

AbsUserProjectServiceServiceImpl

19KB 用户项目服务

RbacProjectPermissionService

10KB RBAC 项目权限

I18nMessageServiceImpl

11KB 国际化消息

5.3 DAO 层

类名 文件大小 职责

ProjectDao

42KB 项目数据访问（最大）

ProjectApprovalDao

14KB 项目审批数据访问

ServiceDao

10KB 服务数据访问

ShardingRoutingRuleDao

7KB 分片路由数据访问

TableShardingConfigDao

6KB 表分片配置数据访问

UserDao

6KB 用户数据访问

六、核心流程

6.1 项目创建流程

用户请求 │ ▼ UserProjectResource.create() │ ▼ UserProjectResourceImpl.create() │ ▼ AbsProjectServiceImpl.create() │ ├─► 参数校验 │ ├─► 校验项目名称长度（2-64字符） │ ├─► 校验英文名格式（小写字母+数字+下划线） │ └─► 校验项目名/英文名唯一性 │ ├─► 权限校验 │ └─► projectPermissionService.verifyUserProjectPermission() │ ├─► 创建项目 │ ├─► 生成 projectId (UUID) │ ├─► projectDao.create() │ └─► 分配分片路由规则 │ ├─► 注册到权限中心 │ └─► authPermissionApi.createResource() │ └─► 发送项目创建事件 └─► projectDispatcher.dispatch(ProjectCreateBroadCastEvent)

6.2 项目查询流程

ServiceProjectResource.list() │ ▼ ServiceProjectResourceImpl.list() │ ▼ AbsProjectServiceImpl.list() │ ├─► 获取用户有权限的项目列表 │ └─► projectPermissionService.getUserProjects() │ ├─► 查询项目详情 │ └─► projectDao.listByEnglishName() │ └─► 组装返回数据 └─► ProjectVO

6.3 项目审批流程

┌─────────────────────────────────────────────────────────────────┐ │ 项目审批流程 │ ├─────────────────────────────────────────────────────────────────┤ │ 1. 用户提交创建/更新请求 │ │ UserProjectResource.create() / update() │ │ │ │ │ ▼ │ │ 2. 检查是否需要审批 │ │ ProjectApprovalService.checkApprovalRequired() │ │ │ │ │ ┌──────────────┴──────────────┐ │ │ │ │ │ │ ▼ ▼ │ │ 需要审批 不需要审批 │ │ 创建审批单 直接生效 │ │ status=PENDING status=APPROVED │ │ │ │ │ ▼ │ │ 3. 审批人审批 │ │ OPProjectResource.approve() │ │ │ │ │ ┌──────────────┴──────────────┐ │ │ │ │ │ │ ▼ ▼ │ │ 通过 驳回 │ │ status=APPROVED status=REJECTED │ │ 项目生效 通知用户 │ └─────────────────────────────────────────────────────────────────┘

七、与其他模块的关系

7.1 被依赖关系

Project 模块是基础模块，被所有其他微服务依赖：

┌─────────────────────────────────────────────────────────────────┐ │ Project 模块被依赖关系 │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │ process │ │ auth │ │ store │ │ repo │ │ │ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │ │ │ │ │ │ │ │ └────────────┴────────────┴────────────┘ │ │ │ │ │ ▼ │ │ ┌───────────────┐ │ │ │ project │ │ │ │ (基础模块) │ │ │ └───────────────┘ │ │ │ │ 其他依赖模块： │ │ - artifactory, dispatch, environment, ticket │ │ - quality, notify, log, openapi, metrics │ │ │ └─────────────────────────────────────────────────────────────────┘

7.2 服务间调用示例

// 其他服务调用 Project 服务获取项目信息 // 注意：这里的 projectId 参数实际是 T_PROJECT.english_name client.get(ServiceProjectResource::class).get( userId = userId, projectId = projectId, // ⚠️ 这是 english_name，不是 T_PROJECT.PROJECT_ID accessToken = null )

// 获取用户有权限的项目列表 client.get(ServiceProjectResource::class).list( userId = userId, productIds = null, channelCodes = null, sort = null, page = null, pageSize = null )

// 典型的 URL 路径示例： // GET /api/user/projects/{projectId}/pipelines // 这里的 {projectId} 就是 english_name，例如 "my-project-001"

八、项目属性扩展

8.1 ProjectProperties 结构

data class ProjectProperties( val pipelineDialectType: PipelineDialectType?, // 流水线方言类型 val pipelineAsCodeSettings: PipelineAsCodeSettings?, // PAC 设置 val pipelineLimit: Int?, // 流水线数量限制 val pluginDetailsDisplayOrder: PluginDetailsDisplayOrder?, // 插件详情显示顺序 val pipelineNameFormat: String?, // 流水线命名格式 val concurrencyQuota: Int? // 并发配额 )

8.2 SubjectScopes（可授权范围）

data class SubjectScopeInfo( val type: SubjectScopeType, // ALL_MEMBER / DEPARTMENT / USER / GROUP val id: String, // 部门ID / 用户ID / 组ID val name: String // 名称 )

九、分片路由机制

9.1 分片策略

Project 模块支持数据库分片，用于大规模部署：

// 分片路由规则分配 shardingRoutingRuleAssignService.assignShardingRoutingRule( projectId = projectId, moduleCodes = listOf( SystemModuleEnum.PROCESS, SystemModuleEnum.REPOSITORY, SystemModuleEnum.DISPATCH ) )

9.2 路由规则查询

// 获取项目的分片路由规则 client.get(ServiceShardingRoutingRuleResource::class).getShardingRoutingRuleByName( routingName = projectId, moduleCode = SystemModuleEnum.PROCESS )

十、开发规范

10.1 新增项目属性

  • 在 ProjectProperties 中添加字段

  • 在 ProjectVO 和 ProjectCreateInfo 中添加对应字段

  • 更新 ProjectDao 的查询和更新方法

  • 如需审批，更新 ProjectApprovalService

10.2 新增项目渠道

  • 在 ProjectChannelCode 枚举中添加渠道

  • 在 T_PROJECT 表的 CHANNEL 字段支持新值

  • 根据需要调整权限校验逻辑

10.3 项目查询示例

// 根据英文名查询项目（englishName 就是其他模块所说的 projectId） val project = projectDao.getByEnglishName( dslContext = dslContext, englishName = projectCode // projectCode = projectId = englishName )

// 查询用户有权限的项目 val projects = projectPermissionService.getUserProjects(userId)

// 分页查询项目列表 val page = projectDao.list( dslContext = dslContext, projectName = searchName, englishName = null, enabled = true, offset = offset, limit = limit )

// ⚠️ 重要：当其他模块传入 projectId 时，应该用 getByEnglishName 查询 // 例如 process 模块调用： // val projectInfo = client.get(ServiceProjectResource::class).get(projectId = "my-project") // 这里的 "my-project" 是 english_name

十一、常见问题

Q: projectId 和 englishName 的区别？ A: ⚠️ 这是一个常见的误解：

  • T_PROJECT.PROJECT_ID 是一个 UUID，但几乎没有实际用途

  • T_PROJECT.english_name 才是真正的项目标识

  • 其他所有模块接口中的 projectId 参数，实际上都是 english_name

  • 简单记忆：projectId = projectCode = englishName = T_PROJECT.english_name

Q: 如何判断项目是否启用？ A: 检查 T_PROJECT.enabled 字段，true 表示启用。

Q: 项目创建后如何通知其他服务？ A: 通过 ProjectCreateBroadCastEvent 事件广播，其他服务监听该事件进行初始化。

Q: 如何扩展项目属性？ A: 在 ProjectProperties 中添加字段，存储在 T_PROJECT.properties JSON 字段中。

Q: 保密项目和普通项目的区别？ A: 保密项目（authSecrecy=true ）有更严格的权限控制，只有明确授权的用户才能访问。

版本: 1.1.0 | 更新日期: 2025-12-11

更新说明:

  • v1.1.0: 修正 projectId 的真正含义说明，明确 T_PROJECT.english_name 才是其他模块所说的 projectId

Source Transparency

This detail page is rendered from real SKILL.md content. Trust labels are metadata-based hints, not a safety guarantee.

Open in GitHubOpen in ClawHub

Related Skills

Related by shared tags or category signals.

General

git-commit-specification

No summary provided by upstream source.

Repository SourceNeeds Review
53-tencentblueking
General

design-patterns

No summary provided by upstream source.

Repository SourceNeeds Review
53-tencentblueking
General

database-design

No summary provided by upstream source.

Repository SourceNeeds Review
45-tencentblueking
General

unit-testing

No summary provided by upstream source.

Repository SourceNeeds Review
41-tencentblueking