--- name: project-module-architecture description: Project 项目管理模块架构指南，涵盖项目 CRUD、成员管理、项目配置、标签管理、项目迁移。当用户开发项目管理功能、处理项目成员、配置项目属性或实现项目相关逻辑时使用。 --- # 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 项目渠道类型 ```kotlin 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 项目审批状态 ```kotlin 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 服务间调用示例 ```kotlin // 其他服务调用 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 结构 ```kotlin 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（可授权范围） ```kotlin data class SubjectScopeInfo( val type: SubjectScopeType, // ALL_MEMBER / DEPARTMENT / USER / GROUP val id: String, // 部门ID / 用户ID / 组ID val name: String // 名称 ) ``` ## 九、分片路由机制 ### 9.1 分片策略 Project 模块支持数据库分片，用于大规模部署： ```kotlin // 分片路由规则分配 shardingRoutingRuleAssignService.assignShardingRoutingRule( projectId = projectId, moduleCodes = listOf( SystemModuleEnum.PROCESS, SystemModuleEnum.REPOSITORY, SystemModuleEnum.DISPATCH ) ) ``` ### 9.2 路由规则查询 ```kotlin // 获取项目的分片路由规则 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 项目查询示例 ```kotlin // 根据英文名查询项目（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