# 开发产线 (SDLC Pipeline) 驾驶舱设计文档

## 设计理念

开发产线的用户界面采用**驾驶舱模式**设计。核心理念是：

- **像和大模型对话一样交互**：用户以自然语言描述需求，上传文件，Agent 自动分析和执行
- **状态信息直线展示**：产线进度以时间线/步骤条形式一目了然
- **详情按需展开**：点击步骤节点才展开具体内容（产物、日志、审批表单）

## 用户输入

统一为**类大模型交互界面**：

### 输入形式
```
┌─────────────────────────────────────────┐
│ 📎 已附加: design-doc.pdf  [×]         │
│                                         │
│ ┌─────────────────────────────────────┐ │
│ │ 请输入你的需求或回复...              │ │
│ │                                     │ │
│ │                                     │ │
│ └─────────────────────────────────────┘ │
│                           [📎] [发送 ⏎]│
└─────────────────────────────────────────┘
```

### 输入组件
| 组件 | 说明 |
|------|------|
| 正文输入框 | 多行文本，支持自然语言描述需求、回复Agent |
| 文件附件 | 支持上传多个文件（需求文档、设计稿、代码等） |
| 发送按钮 | 提交后触发 Agent 分析并推入产线 |

### 输入可触发的操作
- 新建迭代：描述需求 → Agent 自动创建迭代并启动产线
- 回复人工任务：填写表单 → Agent 继续执行
- 审批决策：approve / reject → 产线流转
- 补充信息：代码修复说明、环境配置等

## 驾驶舱布局

```
┌──────────────────────────────────────────────────────────┐
│ 驾驶舱标题栏：[项目选择器▾] [迭代选择器▾] [刷新]       │
├──────────────────────────────────────────────────────────┤
│ 统计卡片行：活跃项目 | 进行中迭代 | 待处理Bug | 待审批   │
├───────────────────────────┬──────────────────────────────┤
│  时间线面板 (40%)         │  对话面板 (60%)              │
│ ┌────────────────────────┐│ ┌──────────────────────────┐ │
│ │ 🟢 需求采集         ✓  ││ │ 🤖 Agent: 收到需求...     │ │
│ │ 🟢 需求评审         ✓  ││ │ 👤 你: 请增加XX功能      │ │
│ │ 🟡 表设计       进行中  ││ │ 🤖 Agent: 设计完成，     │ │
│ │ ⚪ CRUD设计     待执行  ││ │   请确认以下方案...      │ │
│ │ ⚪ API设计      待执行  ││ │                          │ │
│ │ ⚪ 设计评审       阻塞  ││ │ ┌──────────────────────┐ │ │
│ │ ⚪ 代码生成     待执行  ││ │ │ 输入需求或回复...    │ │ │
│ └────────────────────────┘│ │ │            [📎][发送] │ │ │
│                           │ │ └──────────────────────┘ │ │
│  [点击步骤展开详情→]       │ └──────────────────────────┘ │
└───────────────────────────┴──────────────────────────────┘
```

## 时间线设计

### 步骤节点状态
| 图标 | 状态 | 含义 |
|------|------|------|
| 🟢 ✓ | completed | 步骤已完成 |
| 🟡 ⟳ | running | 正在执行中 |
| ⚪ ○ | pending | 等待前置步骤完成 |
| 🔵 ⚠ | waiting | 等待人工输入/审批 |
| 🔴 ✗ | failed | 执行失败 |
| ⏭ ⊘ | skipped | 已跳过 |
| ⏸ ∥ | paused | 已暂停 |

### 时间线交互
- **直线排列**：步骤按 DAG 拓扑排序后垂直排列，连接线显示依赖关系
- **当前步骤高亮**：running/waiting 状态的步骤有脉冲动画
- **点击展开**：点击任意步骤节点，在右侧面板或弹窗中展示详情
- **详情内容**：
  - 步骤描述和配置
  - 输入/输出 artifact（支持 JSON 树形查看）
  - 执行日志
  - 如果是 human_task：显示表单或审批按钮
  - 如果是 failed：显示错误信息和重试按钮

### 步骤分组（时间段）
```
▼ 需求阶段
  🟢 需求采集
  🟢 需求评审
▼ 设计阶段
  🟡 表设计
  ⚪ CRUD设计
  ⚪ API设计
  ⚪ 设计评审
▼ 开发阶段
  ⚪ 代码生成
  ...
```

## 对话面板设计

### 消息类型
| 角色 | 样式 | 说明 |
|------|------|------|
| 🤖 Agent | 左对齐，深色背景 | 系统自动消息：分析结果、步骤状态变更 |
| 👤 用户 | 右对齐，蓝色背景 | 用户输入：需求、回复、审批 |
| ⚡ 系统 | 居中，灰色小字 | 系统事件：步骤开始/完成、Bug上报 |

### Agent 消息内容
- 需求分析结果
- 设计产出预览（表结构、CRUD清单）
- 代码审查报告
- 测试结果摘要
- 部署状态
- **人工任务请求**：表单字段、审批选项

### 用户消息触发
- 输入框发送 → 创建用户消息 → 调用 DSPY 处理 → Agent 回复

### 对话持久化
消息存储在数据库表 `sd_conversations` 中，与迭代关联。

## 数据模型

### sd_conversations（对话消息表）
| 字段 | 类型 | 说明 |
|------|------|------|
| id | str(32) | 主键 |
| iteration_id | str(32) | 关联迭代 |
| task_id | str(32) | 关联 Pipeline 任务 |
| step_name | str(100) | 关联步骤（可为空） |
| role | str(20) | agent / user / system |
| content | text | 消息正文 |
| attachments | text | 附件列表 JSON |
| created_at | timestamp | 创建时间 |

## 技术实现

### 页面路由
- `/sd_cockpit/` → 驾驶舱主页面
- `/sd_cockpit/timeline.dspy` → 时间线数据 API
- `/sd_cockpit/chat_messages.dspy` → 对话消息 API（GET 读取 / POST 发送）
- `/sd_cockpit/step_detail.dspy` → 步骤详情 API
- `/sd_cockpit/dashboard_data.dspy` → 统计卡片数据

### Bricks Widget 映射
| 设计元素 | Bricks 实现 |
|----------|------------|
| 时间线列表 | VBox + 自定义 styled VBox items |
| 对话面板 | VScrollPanel + VBox message bubbles |
| 输入框 | Form widget (textarea + submit) |
| 统计卡片 | ResponsableBox + VBox.card |
| 步骤详情 | Popup + urlwidget (加载 step_detail.ui) |
| 文件上传 | Form file field |
| 项目/迭代选择 | code dropdown widget |

### 跨模块调用
驾驶舱在 pipeline-sdlc 模块内，调用 pipeline_task API 时使用绝对路径：
```
entire_url('/pipeline_task/api/task_submit.dspy')
entire_url('/pipeline_task/api/task_detail.dspy')
entire_url('/pipeline_task/api/human_complete.dspy')
```

## 开发规范遵循

| 规范项 | 应用 |
|--------|------|
| 布局标准 | 四卡片 + filler 内容区，白底 SVG 图标 |
| DSPY 规范 | 零 import、return 代替 print、getID()、await get_user() |
| 跨模块调用 | 绝对路径 entire_url('/pipeline_task/api/...') |
| 部署铁律 | 本地改 → commit → push → 服务器 pull → 重启 → 浏览器验证 |
| DSPY async | 用 request._run_ns，不用 ServerEnv() |
| sor.U() | 只传2个参数 |
| 禁止 | 不直接改服务器原文，不动其他模块 |