1. 00-bkci-global-architecture (本文档) - 建立全局视图
   ↓
2. pipeline-model-architecture - 理解流水线模型
   ↓
3. process-module-architecture - 深入核心模块
   ↓
4. backend-microservice-development - 掌握开发规范

根据开发任务选择：
- 插件开发 → store + worker + pipeline-plugin-development
- 权限功能 → auth + common-technical-practices
- 调度优化 → dispatch + agent + supporting-modules-architecture
- 变量扩展 → pipeline-variable-management + utility-components

用户层 → 网关层 → 微服务层 → 构建机层 → 资源层

触发 → Process引擎 → Dispatch分配 → Agent领取 → Worker执行 → 状态回传

┌─────────────────────────────────────────────────────────────────────────────┐
│                           用户层 (User Layer)                                │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐ │
│  │  Web 前端   │  │  OpenAPI    │  │  Webhook    │  │  第三方系统集成     │ │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘  └──────────┬──────────┘ │
└─────────┼────────────────┼────────────────┼────────────────────┼────────────┘
          ▼                ▼                ▼                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                         网关层 (Gateway Layer)                               │
│                    OpenResty (Nginx + Lua)                                   │
│  • 路由转发 • 身份认证 • 限流熔断 • 服务发现(Consul)                         │
└─────────────────────────────────────────────────────────────────────────────┘
          ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                       微服务层 (Microservice Layer)                          │
│  核心: Project | Process | Auth | Store | Repository                         │
│  调度: Dispatch | Environment | Ticket                                       │
│  支撑: Artifactory | Log | Notify | Quality | Metrics                        │
│  开放: OpenAPI | WebSocket                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
          ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                        构建机层 (Build Machine Layer)                        │
│     Agent (Go) ──▶ Worker (Kotlin)                                           │
│     进程守护        任务执行、插件运行、日志上报                              │
└─────────────────────────────────────────────────────────────────────────────┘
          ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                        资源层 (Resource Layer)                               │
│     MySQL | Redis | RabbitMQ | ElasticSearch | 文件存储                      │
└─────────────────────────────────────────────────────────────────────────────┘

用户触发
    │
    ▼
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│ PipelineBuild   │────▶│ PipelineBuild   │────▶│ PipelineRuntime │
│ FacadeService   │     │ Service         │     │ Service         │
│ (权限校验)      │     │ (拦截器链)      │     │ (创建记录)      │
└─────────────────┘     └─────────────────┘     └────────┬────────┘
                                                         │
                                                         ▼
                                              ┌─────────────────────┐
                                              │ PipelineBuildStart  │
                                              │ Event → RabbitMQ    │
                                              └──────────┬──────────┘
                                                         │
    ┌────────────────────────────────────────────────────┘
    ▼
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│ BuildStart      │────▶│ StageControl    │────▶│ Container       │
│ Control         │     │ (责任链)        │     │ Control         │
└─────────────────┘     └─────────────────┘     └────────┬────────┘
                                                         │
                              ┌───────────────────────────┤
                              ▼                           ▼
                   ┌─────────────────┐         ┌─────────────────┐
                   │ Dispatch        │         │ TaskControl     │
                   │ (构建机分配)    │         │ (引擎侧Task)    │
                   └────────┬────────┘         └─────────────────┘
                            ▼
                   ┌─────────────────┐
                   │ Agent (Go)      │
                   │ (领取任务)      │
                   └────────┬────────┘
                            ▼
                   ┌─────────────────┐
                   │ Worker (Kotlin) │
                   │ (执行Task)      │
                   └────────┬────────┘
                            │ completeTask API
                            ▼
                   ┌─────────────────┐
                   │ 状态逐层回传    │
                   │ Task→Job→Stage  │
                   │ →Pipeline       │
                   └────────┬────────┘
                            ▼
                   ┌─────────────────┐
                   │ BuildEndControl │
                   │ (完成处理)      │
                   └────────┬────────┘
                            │
        ┌───────────────────┼───────────────────┐
        ▼                   ▼                   ▼
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Notify    │     │   Metrics   │     │  WebSocket  │
└─────────────┘     └─────────────┘     └─────────────┘

for {
    result := api.AskBuild()  // 向 Dispatch 请求任务
    if result.HasBuild {
        go runBuild(result.BuildInfo)  // 异步执行
    }
    time.Sleep(interval)
}

loop@ while (true) {
    val buildTask = EngineService.claimTask()  // 领取任务
    when (buildTask.status) {
        DO -> {
            val task = TaskFactory.create(buildTask.type)
            task.run(buildTask, buildVariables, workspace)
            EngineService.completeTask(result)  // 上报结果
        }
        WAIT -> Thread.sleep(sleepMills)
        END -> break@loop
    }
}

Task 完成 → PipelineBuildTaskService.finishTask()
         → 发送 PipelineBuildContainerEvent
         → Job 完成检查 → Stage 完成检查 → Pipeline 完成
         → Notify/Metrics/WebSocket

┌─────────────────────────────────────────────────────────────────┐
│           T_PIPELINE_BUILD_TASK 表数据示例                       │
├──────────────┬────────────────────┬──────────────────┬──────────┤
│ TASK_ID      │ TASK_NAME          │ TASK_ATOM        │ TASK_SEQ │
├──────────────┼────────────────────┼──────────────────┼──────────┤
│ startVM-1    │ Prepare_Job#1      │ dispatchVMStart  │ 1  系统  │
│ e-xxx-1      │ Bash               │ (空)             │ 2  用户  │
│ e-xxx-2      │ 代码拉取           │ (空)             │ 3  用户  │
│ end-1000     │ Wait_Finish_Job#1  │ (空)             │ 1000 系统│
│ stopVM-1001  │ Clean_Job#1        │ dispatchVMStop   │ 1001 系统│
└──────────────┴────────────────────┴──────────────────┴──────────┘

BK-CI 事件驱动方式（✅ 采用）：

Process 引擎
    │
    ├── 发送调度请求（PipelineAgentStartupEvent）
    ├── 立即返回，处理其他事件（其他流水线、其他 Job）
    │
... 时间流逝，构建机启动中 ...
    │
Worker 启动后
    ├── 调用 jobStarted API
    ├── 服务端发送 PipelineBuildContainerEvent
    │
引擎收到事件
    └── 继续执行该 Job 的后续 Task

                              ┌──────────┐
                              │ Project  │ ◀──── 所有服务的基础依赖
                              └────┬─────┘
                                   │
         ┌─────────────────────────┼─────────────────────────┐
         ▼                         ▼                         ▼
    ┌──────────┐             ┌──────────┐             ┌──────────┐
    │   Auth   │◀────────────│ Process  │────────────▶│  Store   │
    └────┬─────┘             └────┬─────┘             └──────────┘
         │           ┌────────────┼────────────┐
         │           ▼            ▼            ▼
         │     ┌──────────┐ ┌──────────┐ ┌──────────┐
         │     │Repository│ │ Dispatch │ │  Ticket  │
         │     └──────────┘ └────┬─────┘ └──────────┘
         │                       │
         │                       ▼
         │                ┌──────────┐
         │                │Environment│
         │                └────┬─────┘
         │                     ▼
         │              ┌────────────┐
         │              │Agent/Worker│
         │              └─────┬──────┘
         │                    ▼
         │     ┌──────────────────────────────────┐
         │     │  Log | Artifactory | Notify     │
         │     └──────────────────────────────────┘
         │                    │
         └───────────────────▶│
                              ▼
                       ┌──────────────┐
                       │   Metrics    │
                       └──────────────┘

Model (流水线模型)
├── name: String
├── stages: List<Stage>
│   └── Stage
│       ├── id: String (s-xxx)
│       ├── checkIn/checkOut: StagePauseCheck
│       └── containers: List<Container>
│           └── Container (Job)
│               ├── id: String (c-xxx)
│               ├── @type: vmBuild | normal | trigger
│               ├── dispatchType: DispatchType
│               └── elements: List<Element>
│                   └── Element (Task)
│                       ├── id: String (t-xxx)
│                       ├── @type: marketBuild | linuxScript | ...
│                       └── data: Map
├── triggers: List<Trigger>
├── params: List<BuildFormProperty>
└── setting: PipelineSetting

T_PROJECT
    │
    ├── T_PIPELINE_INFO (流水线信息)
    │       │
    │       ├── T_PIPELINE_RESOURCE (编排模型)
    │       ├── T_PIPELINE_SETTING (配置)
    │       └── T_PIPELINE_BUILD_HISTORY (构建历史)
    │               │
    │               ├── T_PIPELINE_BUILD_STAGE
    │               ├── T_PIPELINE_BUILD_CONTAINER
    │               ├── T_PIPELINE_BUILD_TASK
    │               └── T_PIPELINE_BUILD_VAR
    │
    ├── T_REPOSITORY (代码库)
    └── T_AUTH_RESOURCE (权限资源)