gao/ljwx-project

Fork 0

Files

T

bruno e923c2da97 push to gitea

2025-12-25 19:51:50 +08:00

16 KiB

Raw Permalink Blame History

LJWX 项目管理实施指南

📋 目录

项目概览
项目生命周期管理
数据采集与自动化
使用场景示例
快速开始

📊 项目概览

当前项目列表

根据 /Users/brunogao/work/codes/ljwx 目录扫描，发现以下项目：

项目代码	项目名称	建议优先级	项目类型
LJWX_PROJECT	Project Control Center	P0	基础设施
LJWX_HEALTH	健康管理系统	P1	业务系统
LJWX_BOOKSTORE	书店管理系统	P1	业务系统
LJWX_RAG	RAG 知识库系统	P1	AI 应用
LJWX_DIFY	Dify 集成	P2	AI 应用
LJWX_CLAUDE	Claude 集成	P2	AI 应用
LJWX_OPTKIT	优化工具包	P2	工具库
LJWX_WEBSITE	官方网站	P2	前端项目
LJWX_STOCK	股票分析系统	P2	业务系统
LJWX_SOURCE	源码管理	P3	工具库
LJWX_INIT	初始化工具	P3	工具库

🔄 项目生命周期管理

Phase 1: 需求阶段 (Requirement)

目标：明确项目目标和需求

工作项类型：

Epic: 大型功能模块
Story: 用户故事

关键活动：

创建项目并设置基本信息
定义业务目标（businessObjective）
创建 Epic 划分功能模块
为每个 Epic 创建 Story
定义验收标准（acceptanceCriteria）

API 操作示例：

# 创建项目
curl -X POST http://localhost:18080/api/projects \
  -H 'Content-Type: application/json' \
  -d '{
    "code": "LJWX_HEALTH",
    "name": "健康管理系统",
    "description": "个人健康数据追踪与分析系统",
    "businessObjective": "提供健康数据可视化、趋势分析和健康建议",
    "ownerUserId": 1,
    "targetDate": "2025-06-30"
  }'

# 创建 Epic
curl -X POST http://localhost:18080/api/projects/1/work-items \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "epic",
    "title": "用户健康档案管理",
    "description": "实现用户基本健康信息录入、查询和管理功能",
    "priority": "p0",
    "originalRequirement": "用户需要能够记录身高、体重、血压等基础健康指标"
  }'

# 启动需求阶段
curl -X POST http://localhost:18080/api/projects/1/phases/req/start

PCC 自动监测：

✅ 需求完成度：Story 创建数量 / Epic 数量
✅ 需求冻结状态：Story.requirementFrozenAt 时间戳

Phase 2: 设计阶段 (Design)

目标：完成技术方案设计

工作项类型：

Task: 设计任务（数据库设计、API 设计、架构设计）

关键活动：

完成需求阶段
为每个 Story 创建设计 Task
产出设计文档（存储在 Git 或文档系统）
冻结需求（设置 requirementFrozenAt）

API 操作示例：

# 完成需求阶段
curl -X POST http://localhost:18080/api/projects/1/phases/req/complete

# 启动设计阶段
curl -X POST http://localhost:18080/api/projects/1/phases/design/start

# 创建设计任务
curl -X POST http://localhost:18080/api/projects/1/work-items \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "task",
    "title": "健康档案数据库表设计",
    "description": "设计 user_health_profile 表结构",
    "priority": "p0",
    "assigneeUserId": 1,
    "acceptanceCriteria": "- 完成 ER 图\n- 完成表结构 SQL\n- 评审通过"
  }'

PCC 自动监测：

✅ 设计覆盖率：设计 Task 数量 / Story 数量
✅ 设计评审状态

Phase 3: 开发阶段 (Development)

目标：编写代码实现功能

工作项类型：

Task: 开发任务
Bug: 开发过程中发现的缺陷

关键活动：

完成设计阶段
为每个 Story 创建开发 Task
关联 Git 提交
Agent 自动化开发（可选）

Agent 开发集成：

# 启动 Agent 自动开发
curl -X POST http://localhost:18080/api/ingest/agent/start \
  -H 'Content-Type: application/json' \
  -d '{
    "tenantId": 1,
    "projectCode": "LJWX_HEALTH",
    "sessionId": "agent-dev-20251225-001",
    "agentType": "claude-code",
    "taskDescription": "实现用户健康档案 CRUD API",
    "taskPlan": [
      {"step": 1, "description": "创建 Entity 和 Mapper"},
      {"step": 2, "description": "实现 Service 层业务逻辑"},
      {"step": 3, "description": "实现 Controller REST API"},
      {"step": 4, "description": "编写单元测试"}
    ],
    "workItemId": 5
  }'

# Agent 进度上报
curl -X POST http://localhost:18080/api/ingest/agent/progress \
  -H 'Content-Type: application/json' \
  -d '{
    "sessionId": "agent-dev-20251225-001",
    "eventType": "step_done",
    "stepIndex": 1,
    "message": "Entity 和 Mapper 创建完成"
  }'

# Agent 完成上报
curl -X POST http://localhost:18080/api/ingest/agent/complete \
  -H 'Content-Type: application/json' \
  -d '{
    "sessionId": "agent-dev-20251225-001",
    "status": "completed",
    "commitsCount": 4,
    "filesChanged": 8,
    "linesAdded": 320,
    "linesDeleted": 12
  }'

PCC 自动监测：

✅ 代码提交频率（Git Hooks）
✅ Agent 开发效率
✅ Bug 产生率

Phase 4: 测试阶段 (Testing)

目标：保证代码质量

工作项类型：

Bug: 测试发现的缺陷

关键活动：

CI/CD 自动测试
上报测试结果到 PCC
跟踪 Bug 修复

CI Pipeline 集成 (GitHub Actions / GitLab CI):

# .github/workflows/test.yml
name: Test & Report to PCC

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Run Tests
        run: mvn test

      - name: Report Pipeline to PCC
        run: |
          curl -X POST ${{ secrets.PCC_URL }}/ingest/ci/pipeline \
            -H 'Content-Type: application/json' \
            -d '{
              "tenantId": 1,
              "projectCode": "LJWX_HEALTH",
              "source": "github_actions",
              "pipelineId": "${{ github.run_id }}",
              "pipelineName": "Test & Build",
              "ref": "${{ github.ref }}",
              "commitSha": "${{ github.sha }}",
              "status": "success",
              "startedAt": "${{ github.event.head_commit.timestamp }}",
              "url": "${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
            }'

      - name: Report Test Results to PCC
        run: |
          curl -X POST ${{ secrets.PCC_URL }}/ingest/ci/test-report \
            -H 'Content-Type: application/json' \
            -d '{
              "tenantId": 1,
              "projectCode": "LJWX_HEALTH",
              "pipelineRunId": "${{ github.run_id }}",
              "framework": "junit",
              "total": 45,
              "passed": 43,
              "failed": 2,
              "skipped": 0
            }'

PCC 自动监测：

✅ 测试通过率（7天趋势）
✅ CI 失败率（7天趋势）
✅ 代码覆盖率

Phase 5: 部署阶段 (Deployment)

目标：发布到各个环境

环境：

dev: 开发环境
stg: 预发布环境
prod: 生产环境

部署上报：

# 部署成功上报
curl -X POST http://localhost:18080/api/ingest/deploy/event \
  -H 'Content-Type: application/json' \
  -d '{
    "tenantId": 1,
    "projectCode": "LJWX_HEALTH",
    "env": "prod",
    "status": "success",
    "version": "v1.2.0",
    "startedAt": "2025-12-25T10:00:00Z",
    "endedAt": "2025-12-25T10:05:23Z",
    "url": "https://health.lingjingwanxiang.cn"
  }'

# 部署失败上报
curl -X POST http://localhost:18080/api/ingest/deploy/event \
  -H 'Content-Type: application/json' \
  -d '{
    "tenantId": 1,
    "projectCode": "LJWX_HEALTH",
    "env": "prod",
    "status": "failed",
    "version": "v1.2.1",
    "startedAt": "2025-12-25T14:00:00Z",
    "endedAt": "2025-12-25T14:02:15Z"
  }'

PCC 自动监测：

✅ 部署成功率（7天趋势）
✅ 部署频率
✅ 回滚次数

Phase 6: 运维阶段 (Operations)

目标：监控系统运行状态

关键活动：

监控告警接入
故障工单跟踪
性能分析

告警集成 (Prometheus / Loki / Sentry):

# 从 Prometheus AlertManager 接收告警
curl -X POST http://localhost:18080/api/ingest/ops/incident \
  -H 'Content-Type: application/json' \
  -d '{
    "tenantId": 1,
    "projectCode": "LJWX_HEALTH",
    "env": "prod",
    "type": "alert",
    "severity": "critical",
    "title": "API 响应时间超过 3s",
    "description": "健康档案查询 API 平均响应时间达到 5.2s",
    "status": "open",
    "source": "prometheus",
    "startedAt": "2025-12-25T15:30:00Z",
    "externalUrl": "https://prometheus.example.com/alerts/123"
  }'

PCC 自动监测：

✅ 故障数量（7天趋势）
✅ MTTR（平均故障恢复时间）
✅ 严重故障数量

🤖 数据采集与自动化

1. Git Hooks 集成

在每个项目的 .git/hooks/post-commit 中添加：

#!/bin/bash
# .git/hooks/post-commit

PROJECT_CODE="LJWX_HEALTH"  # 根据项目修改
PCC_URL="http://localhost:18080"

COMMIT_SHA=$(git rev-parse HEAD)
COMMIT_MSG=$(git log -1 --pretty=%B)
AUTHOR=$(git log -1 --pretty=%an)

# TODO: 解析 commit message 提取 work item ID
# 例如: "feat: 实现健康档案查询 #WI-123"

echo "✅ Commit recorded: $COMMIT_SHA"

2. GitHub/GitLab CI 集成

参见上面的测试阶段示例。

3. Claude Code Agent 集成

使用 Claude Code 进行自动化开发时，在 Agent 配置中添加：

{
  "pcc": {
    "enabled": true,
    "endpoint": "http://localhost:18080/api/ingest/agent",
    "projectCode": "LJWX_HEALTH",
    "autoReport": true
  }
}

4. 监控系统集成

Prometheus AlertManager Webhook:

# alertmanager.yml
receivers:
  - name: 'pcc-webhook'
    webhook_configs:
      - url: 'http://localhost:18080/api/ingest/ops/incident'
        send_resolved: true

📖 使用场景示例

场景 1: 开始一个新功能开发

# 1. 创建项目（如果还没有）
PROJECT_ID=$(curl -s -X POST http://localhost:18080/api/projects \
  -H 'Content-Type: application/json' \
  -d '{
    "code": "LJWX_HEALTH",
    "name": "健康管理系统",
    "businessObjective": "个人健康数据追踪与分析"
  }' | jq -r '.id')

# 2. 启动需求阶段
curl -X POST http://localhost:18080/api/projects/$PROJECT_ID/phases/req/start

# 3. 创建 Epic
EPIC_ID=$(curl -s -X POST http://localhost:18080/api/projects/$PROJECT_ID/work-items \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "epic",
    "title": "用户健康档案",
    "priority": "p0"
  }' | jq -r '.id')

# 4. 创建 Story
STORY_ID=$(curl -s -X POST http://localhost:18080/api/projects/$PROJECT_ID/work-items \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "story",
    "title": "作为用户，我希望能够查看我的健康档案",
    "priority": "p0",
    "acceptanceCriteria": "- 显示身高体重\n- 显示血压记录\n- 显示历史趋势图"
  }' | jq -r '.id')

# 5. 完成需求，开始设计
curl -X POST http://localhost:18080/api/projects/$PROJECT_ID/phases/req/complete
curl -X POST http://localhost:18080/api/projects/$PROJECT_ID/phases/design/start

# 6. 完成设计，开始开发（使用 Claude Code Agent）
curl -X POST http://localhost:18080/api/projects/$PROJECT_ID/phases/design/complete
curl -X POST http://localhost:18080/api/projects/$PROJECT_ID/phases/dev/start

# 7. Agent 自动开发...

# 8. 完成开发，CI 自动测试上报

# 9. 部署到生产
curl -X POST http://localhost:18080/api/ingest/deploy/event \
  -H 'Content-Type: application/json' \
  -d '{
    "tenantId": 1,
    "projectCode": "LJWX_HEALTH",
    "env": "prod",
    "status": "success",
    "version": "v1.0.0"
  }'

# 10. 查看项目健康度
curl http://localhost:18080/api/projects/$PROJECT_ID/health

场景 2: 监控项目健康状态

# 获取项目概览
curl http://localhost:18080/api/projects/1/overview

# 返回示例：
{
  "project": { "code": "LJWX_HEALTH", "name": "健康管理系统" },
  "currentPhase": { "phaseCode": "ops", "status": "running" },
  "health": {
    "score": 85,
    "level": "green"
  },
  "kpis": {
    "scheduleVariance": -0.05,  // 进度超前 5%
    "ciFailRate7d": 0.12,       // 7天 CI 失败率 12%
    "testPassRate7d": 0.95,     // 7天测试通过率 95%
    "deploySuccessRate7d": 0.98,// 7天部署成功率 98%
    "incidentCount7d": 3,       // 7天故障数 3 个
    "mttrMin7d": 45             // 7天平均恢复时间 45 分钟
  },
  "recent": {
    "pipelines": [...],
    "deploys": [...],
    "incidents": [...]
  }
}

场景 3: 跨项目视图

# 列出所有项目
curl 'http://localhost:18080/api/projects?page=1&size=20'

# 筛选活跃项目
curl 'http://localhost:18080/api/projects?status=active'

# 搜索项目
curl 'http://localhost:18080/api/projects?q=健康'

🚀 快速开始

Step 1: 批量导入现有项目

创建脚本 scripts/import-projects.sh:

#!/bin/bash

PCC_URL="http://localhost:18080/api"

# 项目列表（根据实际情况修改）
declare -A PROJECTS=(
  ["LJWX_PROJECT"]="Project Control Center|基础设施|PCC 项目管理平台"
  ["LJWX_HEALTH"]="健康管理系统|业务系统|个人健康数据追踪与分析"
  ["LJWX_BOOKSTORE"]="书店管理系统|业务系统|在线书店管理平台"
  ["LJWX_RAG"]="RAG 知识库系统|AI应用|基于 RAG 的智能问答系统"
  ["LJWX_DIFY"]="Dify 集成|AI应用|Dify AI 平台集成"
  ["LJWX_CLAUDE"]="Claude 集成|AI应用|Claude AI 集成工具"
  ["LJWX_OPTKIT"]="优化工具包|工具库|性能优化工具集"
  ["LJWX_WEBSITE"]="官方网站|前端项目|灵境万象官方网站"
  ["LJWX_STOCK"]="股票分析系统|业务系统|智能股票分析工具"
  ["LJWX_SOURCE"]="源码管理|工具库|源码管理工具"
  ["LJWX_INIT"]="初始化工具|工具库|项目初始化脚手架"
)

for code in "${!PROJECTS[@]}"; do
  IFS='|' read -r name tags objective <<< "${PROJECTS[$code]}"

  echo "Creating project: $code - $name"

  curl -X POST "$PCC_URL/projects" \
    -H 'Content-Type: application/json' \
    -d "{
      \"code\": \"$code\",
      \"name\": \"$name\",
      \"description\": \"$objective\",
      \"businessObjective\": \"$objective\",
      \"ownerUserId\": 1
    }" | jq '.'

  sleep 1
done

echo "✅ All projects imported!"

运行导入：

chmod +x scripts/import-projects.sh
./scripts/import-projects.sh

Step 2: 访问前端查看项目

打开浏览器：http://localhost:13000

Step 3: 为重点项目设置阶段和工作项

选择一个重点项目（如 LJWX_HEALTH）开始详细管理：

# 获取项目 ID
PROJECT_ID=$(curl -s 'http://localhost:18080/api/projects?q=健康' | jq -r '.[0].id')

# 启动需求阶段
curl -X POST "http://localhost:18080/api/projects/$PROJECT_ID/phases/req/start"

# 创建第一个 Epic
curl -X POST "http://localhost:18080/api/projects/$PROJECT_ID/work-items" \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "epic",
    "title": "用户健康档案管理",
    "description": "实现用户基本健康信息的增删改查",
    "priority": "p0"
  }'

📈 最佳实践

1. 项目命名规范

使用统一前缀（LJWX_）
使用下划线分隔（LJWX_HEALTH）
大写字母，易于识别

2. 工作流规范

所有需求必须创建 Story
所有 Story 必须有验收标准
设计完成后冻结需求
CI 自动上报测试结果
生产部署必须上报

3. 数据质量保证

定期检查数据上报
监控 KPI 趋势
及时处理告警

4. 团队协作

明确 ownerUserId
工作项分配到人（assigneeUserId）
定期 Review 项目健康度

🔗 相关文档

📞 技术支持

如有问题，请提交 Issue：https://github.com/BrunoGaoSZ/ljwx-project/issues

16 KiB Raw Permalink Blame History Unescape Escape

LJWX 项目管理实施指南

📋 目录

📊 项目概览

当前项目列表

🔄 项目生命周期管理

Phase 1: 需求阶段 (Requirement)

Phase 2: 设计阶段 (Design)

Phase 3: 开发阶段 (Development)

Phase 4: 测试阶段 (Testing)

Phase 5: 部署阶段 (Deployment)

Phase 6: 运维阶段 (Operations)

🤖 数据采集与自动化

1. Git Hooks 集成

2. GitHub/GitLab CI 集成

3. Claude Code Agent 集成

4. 监控系统集成

📖 使用场景示例

场景 1: 开始一个新功能开发

场景 2: 监控项目健康状态

场景 3: 跨项目视图

🚀 快速开始

Step 1: 批量导入现有项目

Step 2: 访问前端查看项目

Step 3: 为重点项目设置阶段和工作项

📈 最佳实践

1. 项目命名规范

2. 工作流规范

3. 数据质量保证

4. 团队协作

🔗 相关文档

📞 技术支持

16 KiB

Raw Permalink Blame History