gao/ljwx-project

Fork 0

Files

T

bruno e344b00500 first commit

2025-12-24 08:05:23 +08:00

24 KiB

Raw Permalink Blame History

Phase 1: 基础监控 - 详细任务清单

🎯 Phase 1 目标

让黑匣子变透明 - 在 1-2 周内实现：

能看到所有项目的当前状态
能追踪 Claude Code 的执行进度
能接收 GitHub Actions 的 CI/CD 状态
能展示项目健康度（简单规则）

验收标准： ✅ 一个页面能回答："哪些项目现在最危险？" ✅ 不看 GitHub/Plane，也能知道 LJWX-HEALTH 项目的进度

📋 任务清单

Sprint 1: 基础框架（Week 1）

🔹 TASK-001: 项目基础框架搭建

优先级: P0 预计工时: 4h 负责人: TBD

任务描述: 创建项目控制中心的基础框架，包括后端、前端和数据库的初始化。

实施步骤:

创建新仓库 ljwx-project-control-center
后端框架选择（二选一）：
- 方案A: Spring Boot 3.x（与 ljwx-health 技术栈一致）
- 方案B: FastAPI（快速开发）
前端框架：React + Vite + Ant Design / Shadcn
数据库：PostgreSQL 14+

项目结构：

ljwx-project-control-center/
├── backend/           # 后端服务
├── frontend/          # 前端应用
├── db/                # 数据库迁移
├── docs/              # 文档
├── docker/            # Docker配置
└── deploy/            # 部署配置

验收标准:

仓库创建并初始化
后端能成功启动（Hello World）
前端能成功启动（Hello World）
能通过 Docker Compose 一键启动所有服务

参考文档:

🔹 TASK-002: 数据库迁移与初始化

优先级: P0 预计工时: 3h 依赖: TASK-001

任务描述: 使用 Flyway 执行数据库迁移，创建项目控制中心的所有表结构。

实施步骤:

配置 Flyway（参考 ljwx-health 的配置）
将 SQL 迁移脚本放到 db/migration/ 目录
执行迁移：flyway migrate
验证表结构：psql -d pcc -c "\dt"

SQL 脚本位置: /Users/brunogao/work/codes/ljwx/ljwx-project/db/migration/V20251223_001__create_project_control_center_tables.sql

验收标准:

Flyway 配置正确
迁移脚本成功执行
所有表（20+ 张）创建成功
默认数据（阶段定义、风险规则）插入成功
能查询到默认的 6 个阶段和 8 条风险规则

测试命令:

-- 验证阶段定义
SELECT code, name, seq FROM t_phase_def ORDER BY seq;

-- 验证风险规则
SELECT code, name, category, severity FROM t_risk_rule ORDER BY category;

🔹 TASK-003: 项目 CRUD API 实现

优先级: P0 预计工时: 4h 依赖: TASK-002

任务描述: 实现项目的创建、查询、更新、删除（CRUD）基础接口。

API 列表:

POST /api/projects - 创建项目
GET /api/projects - 查询项目列表
GET /api/projects/{id} - 查询项目详情
PATCH /api/projects/{id} - 更新项目
DELETE /api/projects/{id} - 删除项目（逻辑删除）

实施步骤:

创建 Project Entity/Model
创建 ProjectRepository（JPA）或 DAO（MyBatis）
创建 ProjectService（业务逻辑）
创建 ProjectController（API 接口）
添加参数校验（Hibernate Validator）
添加审计字段自动填充（AOP）
编写单元测试

数据模型: 参考 t_project 表结构

验收标准:

所有 CRUD 接口实现
接口返回格式统一（参考 ljwx-health）
参数校验生效（code/name 必填）
审计字段自动填充
单元测试覆盖率 > 80%
Swagger/Knife4j 文档生成

测试用例:

# 创建项目
curl -X POST http://localhost:8080/api/projects \
  -H "Content-Type: application/json" \
  -d '{
    "code": "LJWX_HEALTH",
    "name": "灵境健康监测平台",
    "ownerUserId": 1,
    "targetDate": "2025-03-31",
    "businessObjective": "为用户提供全方位的健康监测服务"
  }'

# 查询项目列表
curl http://localhost:8080/api/projects

# 查询项目详情
curl http://localhost:8080/api/projects/1

🔹 TASK-004: 项目阶段状态机实现

优先级: P0 预计工时: 5h 依赖: TASK-003

任务描述: 实现项目阶段的状态机，支持阶段创建、推进、阻塞、完成。

API 列表:

GET /api/projects/{id}/phases - 查询项目的所有阶段
POST /api/projects/{id}/phases/{phaseCode}/start - 开始某阶段
POST /api/projects/{id}/phases/{phaseCode}/block - 阻塞某阶段
POST /api/projects/{id}/phases/{phaseCode}/complete - 完成某阶段

状态转换规则:

not_started → running → done
      ↓           ↓
    (无)      blocked → running

实施步骤:

创建 ProjectPhaseInstance Entity
创建阶段状态机服务 PhaseStateMachineService
实现状态转换逻辑（含校验）
创建 API 接口
添加事件日志（可选）
编写单元测试

验收标准:

创建项目时自动初始化所有阶段（状态为 not_started）
第一个阶段（需求）自动开始
只能开始"当前阶段"或"下一阶段"
阻塞时必须填写原因和级别
完成阶段后自动推进到下一阶段
状态转换非法时返回明确错误

测试用例:

# 1. 创建项目后，查询阶段
curl http://localhost:8080/api/projects/1/phases
# 预期: req=running, design=not_started, dev=not_started, ...

# 2. 完成需求阶段
curl -X POST http://localhost:8080/api/projects/1/phases/req/complete
# 预期: req=done, design=running

# 3. 阻塞开发阶段（错误：尚未开始）
curl -X POST http://localhost:8080/api/projects/1/phases/dev/block
# 预期: 400 Bad Request

🔹 TASK-005: 工作项 CRUD API 实现

优先级: P1 预计工时: 4h 依赖: TASK-003

任务描述: 实现工作项（任务/需求/Bug）的基础管理接口。

API 列表:

POST /api/projects/{projectId}/work-items - 创建工作项
GET /api/projects/{projectId}/work-items - 查询工作项列表（支持筛选）
GET /api/work-items/{id} - 查询工作项详情
PATCH /api/work-items/{id} - 更新工作项
DELETE /api/work-items/{id} - 删除工作项

实施步骤:

创建 WorkItem Entity
创建 Repository/Service/Controller
实现查询筛选（type, status, assignee, phase）
实现层级关系（Epic → Story）
添加需求追溯字段（original_requirement, acceptance_criteria）
编写单元测试

验收标准:

支持创建不同类型的工作项（epic/story/task/bug）
支持按 status/assignee/phase 筛选
支持父子关系（Epic → Story）
original_requirement 创建后不可修改
更新 requirement_frozen_at 后的变更会记录
单元测试覆盖率 > 80%

Sprint 2: 数据接入（Week 1）

🔹 TASK-006: Claude Code 主动上报 API 实现

优先级: P0 预计工时: 6h 依赖: TASK-002

任务描述: 实现 Claude Code 主动上报进度的接口，记录 AI Agent 的执行过程。

API 列表:

POST /api/ingest/agent/start - Agent 任务开始
POST /api/ingest/agent/progress - Agent 进度更新
POST /api/ingest/agent/complete - Agent 任务完成

实施步骤:

创建 AgentSession 和 AgentProgressEvent Entity
创建 AgentIngestService
实现 3 个接口
添加认证（Bearer Token）
添加请求签名校验（可选）
编写集成测试

验收标准:

能成功创建 Agent 会话
能记录进度事件
能标记会话完成/失败
能更新 last_active_at
认证失败返回 401
接口文档完整

集成文档: 参考 /Users/brunogao/work/codes/ljwx/ljwx-project/docs/claude-code-integration.md

🔹 TASK-007: GitHub Actions CI/CD 状态接入

优先级: P0 预计工时: 5h 依赖: TASK-002

任务描述: 通过 Webhook 接收 GitHub Actions 的 Pipeline 执行状态。

API 列表:

POST /api/ingest/ci/pipeline - 接收 Pipeline 状态

实施步骤:

创建 PipelineRun Entity
创建 CIIngestService
解析 GitHub Actions webhook payload
存储到数据库
在 ljwx-health 的 GitHub Actions 中配置 webhook
测试接收

GitHub Actions 配置: 在 .github/workflows/gitops-deploy.yml 中添加：

jobs:
  notify:
    runs-on: ubuntu-latest
    needs: [build, test, deploy]
    if: always()
    steps:
      - name: Notify Project Control Center
        run: |
          curl -X POST ${{ secrets.PCC_API }}/ingest/ci/pipeline \
            -H "Authorization: Bearer ${{ secrets.PCC_TOKEN }}" \
            -H "Content-Type: application/json" \
            -d '{
              "tenant_id": 1,
              "project_code": "LJWX_HEALTH",
              "source": "github_actions",
              "pipeline_id": "${{ github.run_id }}",
              "pipeline_name": "${{ github.workflow }}",
              "ref": "${{ github.ref }}",
              "commit_sha": "${{ github.sha }}",
              "status": "${{ job.status }}",
              "url": "https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}"
            }'

验收标准:

能接收 GitHub webhook payload
能解析出关键字段（status, duration, url）
能存储到 t_pipeline_run
ljwx-health 的 workflow 配置更新
测试：手动触发 workflow，验证数据写入

🔹 TASK-008: 测试报告接入（可选）

优先级: P2 预计工时: 3h 依赖: TASK-007

任务描述: 接收测试报告数据（JUnit/TestNG XML）。

API 列表:

POST /api/ingest/ci/test-report - 上传测试报告

实施步骤:

创建 TestReport Entity
解析 JUnit XML（使用库：junitparser / xmltodict）
存储到数据库
关联到 Pipeline Run

验收标准:

能解析 JUnit XML
能计算通过率
能关联到对应的 Pipeline

🔹 TASK-009: 部署事件接入

优先级: P1 预计工时: 3h 依赖: TASK-007

任务描述: 接收部署事件（Argo CD / Helm）。

API 列表:

POST /api/ingest/deploy/event - 接收部署事件

实施步骤:

创建 DeployEvent Entity
解析 Argo CD webhook payload
存储到数据库

Argo CD 配置: 在 Argo CD Application 中配置 webhook：

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: ljwx-health
spec:
  ...
  syncPolicy:
    automated:
      ...
    webhook:
      url: https://control.lingjingwanxiang.cn/api/ingest/deploy/event
      secret: $WEBHOOK_SECRET

验收标准:

能接收 Argo CD webhook
能记录部署成功/失败
能记录部署环境（dev/prod）

🔹 TASK-010: Prometheus 告警接入

优先级: P1 预计工时: 4h 依赖: TASK-002

任务描述: 接收 Prometheus Alertmanager 的告警通知。

API 列表:

POST /api/ingest/ops/incident - 接收告警

实施步骤:

创建 Incident Entity
解析 Alertmanager webhook payload
存储到数据库
配置 Alertmanager

Alertmanager 配置: 在 docker/alertmanager/alertmanager.yml 中添加：

receivers:
  - name: 'project-control-center'
    webhook_configs:
      - url: 'https://control.lingjingwanxiang.cn/api/ingest/ops/incident'
        http_config:
          bearer_token: 'your_token'

验收标准:

能接收 Alertmanager webhook
能解析告警级别（critical/warning）
能记录告警开始/恢复时间
能计算 MTTR

Sprint 3: 项目总览页（Week 2）

🔹 TASK-011: 项目总览 API 实现

优先级: P0 预计工时: 6h 依赖: TASK-006, TASK-007, TASK-009, TASK-010

任务描述: 实现项目总览接口，聚合所有关键信息。

API:

GET /api/projects/{id}/overview

返回数据结构:

{
  "project": {...},
  "current_phase": {
    "code": "test",
    "status": "running",
    "started_at": "2025-12-20T10:00:00Z",
    "planned_end": "2025-12-25T18:00:00Z"
  },
  "health": {
    "score": 72,
    "level": "yellow"
  },
  "kpis": {
    "ci_fail_rate_7d": 0.18,
    "deploy_success_rate_7d": 0.85,
    "incident_count_7d": 3
  },
  "agent_status": {
    "active_sessions": 1,
    "current_task": "实现用户登录",
    "progress": 0.6,
    "last_active": "2025-12-23T14:25:00Z"
  },
  "recent": {
    "pipelines": [...],  // 最近5次
    "deploys": [...],     // 最近5次
    "incidents": [...]    // 未关闭的
  }
}

实施步骤:

创建 ProjectOverviewService
聚合各表数据（project, phase, agent_session, pipeline_run, deploy_event, incident）
计算 KPIs（使用简单规则，暂不用复杂算法）
创建 API 接口
添加缓存（Redis，5分钟）

验收标准:

能返回项目完整概览
能显示当前阶段状态
能显示 Agent 执行状态
能显示最近的 CI/CD/部署/告警
响应时间 < 500ms

🔹 TASK-012: 前端 - 项目列表页

优先级: P0 预计工时: 5h 依赖: TASK-003

任务描述: 实现项目列表页面，展示所有项目的健康状态。

页面设计:

┌─────────────────────────────────────────────────────┐
│ 项目控制中心                              [+ 新建项目] │
├─────────────────────────────────────────────────────┤
│ 🔍 搜索: [________________]  状态: [全部▼]          │
├─────────────────────────────────────────────────────┤
│ 项目          阶段      健康度   最后活动   操作      │
├─────────────────────────────────────────────────────┤
│ 🟢 LJWX-HEALTH  开发中   85      5分钟前   [查看]   │
│ 🟡 LJWX-ADMIN   测试中   68      2小时前   [查看]   │
│ 🔴 LJWX-REPORT  开发中   45      6小时前   [查看]   │
└─────────────────────────────────────────────────────┘

实施步骤:

创建 ProjectList 组件
调用 GET /api/projects API
展示项目卡片（健康度用颜色区分）
添加筛选和搜索
添加"最后活动"实时更新（WebSocket 或轮询）

验收标准:

能显示所有项目
健康度用颜色区分（绿/黄/红）
能按状态筛选
能搜索项目名称/编码
点击"查看"跳转到详情页
移动端适配

🔹 TASK-013: 前端 - 项目详情页

优先级: P0 预计工时: 8h 依赖: TASK-011, TASK-012

任务描述: 实现项目详情页面，展示项目的完整信息。

页面布局:

┌──────────────────────────────────────────────────────┐
│ LJWX-HEALTH - 灵境健康监测平台                        │
├─────────────────┬────────────────────────────────────┤
│ 📊 概览          │  健康度: 🟡 72/100                 │
│ 🤖 AI Agent     │  阶段: 测试中 (预计 12/25完成)     │
│ 🔄 CI/CD        │  负责人: Bruno Gao                  │
│ 🚀 部署          │                                    │
│ 🚨 告警          │  原始需求:                          │
│ 📈 指标趋势      │  为用户提供全方位的健康监测...       │
└─────────────────┴────────────────────────────────────┘

┌──────────────────────────────────────────────────────┐
│ 🤖 AI Agent 执行状态                                  │
│ 正在执行: 实现用户登录功能 (预计 11:30完成)           │
│ 进度: ████████░░░░░░░░ 60% (3/5)                    │
│  ✅ 1. 设计数据库表                                   │
│  ✅ 2. 实现 API                                       │
│  🔄 3. 编写测试 (进行中...)                           │
│  ⏳ 4. 运行测试                                       │
│  ⏳ 5. 提交代码                                       │
└──────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────┐
│ 🔄 最近 CI/CD                                         │
│  ✅ #245 build-and-test (3分钟前) - 2m 15s           │
│  ❌ #244 build-and-test (1小时前) - Failed            │
│  ✅ #243 build-and-test (2小时前) - 2m 8s            │
└──────────────────────────────────────────────────────┘

实施步骤:

创建 ProjectDetail 组件
调用 GET /api/projects/{id}/overview API
实现各个区块（概览、Agent、CI/CD、部署、告警）
添加实时更新（WebSocket）
添加交互（点击查看详情、展开/收起）

验收标准:

能显示项目完整信息
能显示 Agent 执行进度（带进度条）
能显示最近的 CI/CD（成功/失败状态）
能显示最近的部署
能显示未关闭的告警
实时更新（最多5秒延迟）
移动端适配

🔹 TASK-014: 健康度评分算法实现（简化版）

优先级: P1 预计工时: 4h 依赖: TASK-011

任务描述: 实现简化的健康度评分算法（Phase 1 只用基础规则）。

评分逻辑（简化版）:

初始分: 100
扣分项:
  - CI 失败率 > 20%: -15分
  - 部署失败率 > 20%: -20分
  - 告警数量 > 3: -10分
  - Agent 卡住: -15分
  - 最后活动 > 6小时: -10分

结果:
  >= 80: green
  60-79: yellow
  < 60: red

实施步骤:

创建 HealthScoreService
实现评分逻辑
实现风险等级映射
添加单元测试

验收标准:

能根据 KPIs 计算健康度
能返回风险等级（green/yellow/red）
单元测试覆盖各种场景
性能：计算耗时 < 100ms

Sprint 4: 监控与告警（Week 2）

🔹 TASK-015: Agent 卡住检测定时任务

优先级: P1 预计工时: 3h 依赖: TASK-006

任务描述: 实现定时任务，检测长时间无响应的 Agent 会话。

检测逻辑:

-- 每5分钟执行
SELECT * FROM t_agent_session
WHERE status = 'running'
  AND last_active_at < NOW() - INTERVAL '30 minutes'
  AND is_deleted = FALSE;

处理流程:

标记为 stuck 状态
创建风险信号（AGENT_STUCK）
发送告警通知（企业微信/邮件）

实施步骤:

创建 AgentMonitorJob（Spring @Scheduled 或 Celery）
实现检测逻辑
实现告警推送
添加日志

验收标准:

定时任务正常运行
能检测到卡住的会话
能发送告警通知
日志记录完整

🔹 TASK-016: 简易预警列表（前端）

优先级: P1 预计工时: 3h 依赖: TASK-015

任务描述: 实现预警列表页面，展示所有风险信号。

页面设计:

┌──────────────────────────────────────────────────┐
│ 预警列表                       状态: [全部▼]      │
├──────────────────────────────────────────────────┤
│ 🔴 LJWX-HEALTH  Agent 卡住   30分钟前  [确认]   │
│ 🟡 LJWX-ADMIN   CI失败率高   2小时前   [查看]   │
└──────────────────────────────────────────────────┘

实施步骤:

创建 GET /api/warnings API
创建 WarningList 组件
实现筛选（项目、级别、状态）
实现确认/关闭操作

验收标准:

能显示所有预警
能按项目/级别筛选
能确认/关闭预警
实时更新

🔹 TASK-017: 部署到 K3s 集群

优先级: P2 预计工时: 6h 依赖: 所有后端和前端任务

任务描述: 将项目控制中心部署到 ljwx-health 的 K3s 集群。

实施步骤:

编写 Dockerfile（前端 + 后端）
编写 Helm Chart
配置 GitHub Actions（CI/CD）
配置 Argo CD Application
配置 Ingress（https://control.lingjingwanxiang.cn）
部署到集群
验证功能

验收标准:

镜像构建成功
Helm 部署成功
Ingress 配置正确
HTTPS 证书自动签发
能通过域名访问
能连接到 PostgreSQL
健康检查通过

📊 Phase 1 验收标准

功能验收

项目管理
- 能创建项目（LJWX-HEALTH）
- 能查看项目列表
- 能查看项目详情
阶段管理
- 能看到项目当前阶段
- 能手动推进阶段
AI Agent 追踪
- Claude Code 开始任务时自动上报
- 能实时看到执行进度
- 卡住超过 30 分钟自动告警
CI/CD 监控
- GitHub Actions 执行后自动同步
- 能看到最近的 Pipeline 状态
健康度评分
- 能显示项目健康度分数
- 能用颜色区分风险等级

性能验收

项目列表加载时间 < 1s
项目详情加载时间 < 2s
API 响应时间 P95 < 500ms

非功能验收

代码覆盖率 > 70%
接口文档完整（Swagger/Knife4j）
日志规范（结构化 JSON）
监控指标（Prometheus）

📅 时间规划

Week 1

Day 1-2: TASK-001 ~ TASK-005（基础框架 + CRUD）
Day 3-4: TASK-006 ~ TASK-010（数据接入）
Day 5: 联调测试

Week 2

Day 1-2: TASK-011 ~ TASK-013（总览页面）
Day 3: TASK-014 ~ TASK-016（健康度 + 预警）
Day 4-5: TASK-017（部署）+ 整体测试

🚀 快速开始

1. 克隆仓库

git clone <repo_url> ljwx-project-control-center
cd ljwx-project-control-center

2. 启动开发环境

# 启动 PostgreSQL
docker-compose up -d postgres

# 后端
cd backend
./gradlew bootRun  # 或 mvn spring-boot:run

# 前端
cd frontend
pnpm install
pnpm dev

3. 执行数据库迁移

cd backend
./gradlew flywayMigrate  # 或 mvn flyway:migrate

24 KiB

Raw Permalink Blame History

Phase 1: 基础监控 - 详细任务清单

🎯 Phase 1 目标

📋 任务清单

Sprint 1: 基础框架（Week 1）

🔹 TASK-001: 项目基础框架搭建

🔹 TASK-002: 数据库迁移与初始化

🔹 TASK-003: 项目 CRUD API 实现

🔹 TASK-004: 项目阶段状态机实现

🔹 TASK-005: 工作项 CRUD API 实现

Sprint 2: 数据接入（Week 1）

🔹 TASK-006: Claude Code 主动上报 API 实现

🔹 TASK-007: GitHub Actions CI/CD 状态接入

🔹 TASK-008: 测试报告接入（可选）

🔹 TASK-009: 部署事件接入

🔹 TASK-010: Prometheus 告警接入

Sprint 3: 项目总览页（Week 2）

🔹 TASK-011: 项目总览 API 实现

🔹 TASK-012: 前端 - 项目列表页

🔹 TASK-013: 前端 - 项目详情页

🔹 TASK-014: 健康度评分算法实现（简化版）

Sprint 4: 监控与告警（Week 2）

🔹 TASK-015: Agent 卡住检测定时任务

🔹 TASK-016: 简易预警列表（前端）

🔹 TASK-017: 部署到 K3s 集群

📊 Phase 1 验收标准

功能验收

性能验收

非功能验收

📅 时间规划

Week 1

Week 2

🚀 快速开始

1. 克隆仓库

2. 启动开发环境

3. 执行数据库迁移

4. 访问应用

📚 相关文档

🆘 遇到问题？

24 KiB Raw Permalink Blame History Unescape Escape

Phase 1: 基础监控 - 详细任务清单

🎯 Phase 1 目标

📋 任务清单

Sprint 1: 基础框架（Week 1）

🔹 TASK-001: 项目基础框架搭建

🔹 TASK-002: 数据库迁移与初始化

🔹 TASK-003: 项目 CRUD API 实现

🔹 TASK-004: 项目阶段状态机实现

🔹 TASK-005: 工作项 CRUD API 实现

Sprint 2: 数据接入（Week 1）

🔹 TASK-006: Claude Code 主动上报 API 实现

🔹 TASK-007: GitHub Actions CI/CD 状态接入

🔹 TASK-008: 测试报告接入（可选）

🔹 TASK-009: 部署事件接入

🔹 TASK-010: Prometheus 告警接入

Sprint 3: 项目总览页（Week 2）

🔹 TASK-011: 项目总览 API 实现

🔹 TASK-012: 前端 - 项目列表页

🔹 TASK-013: 前端 - 项目详情页

🔹 TASK-014: 健康度评分算法实现（简化版）

Sprint 4: 监控与告警（Week 2）

🔹 TASK-015: Agent 卡住检测定时任务

🔹 TASK-016: 简易预警列表（前端）

🔹 TASK-017: 部署到 K3s 集群

📊 Phase 1 验收标准

功能验收

性能验收

非功能验收

📅 时间规划

Week 1

Week 2

🚀 快速开始

1. 克隆仓库

2. 启动开发环境

3. 执行数据库迁移

4. 访问应用

📚 相关文档

🆘 遇到问题？

24 KiB

Raw Permalink Blame History