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 新增项目属性

1. 在 ProjectProperties 中添加字段
2. 在 ProjectVO 和 ProjectCreateInfo 中添加对应字段
3. 更新 ProjectDao 的查询和更新方法
4. 如需审批，更新 ProjectApprovalService

10.2 新增项目渠道

1. 在 ProjectChannelCode 枚举中添加渠道
2. 在 T_PROJECT 表的 CHANNEL 字段支持新值
3. 根据需要调整权限校验逻辑

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