# 在线调试工作流功能 - 实现指南

## 📋 功能概述

这个功能允许开发者在 Gitea 的 Web 界面中在线调试 GitHub Actions 工作流。用户可以：

1. **输入或粘贴工作流 YAML 脚本**
2. **验证脚本语法**
3. **选择执行分支**
4. **立即执行工作流**
5. **查看完整执行日志和输出**

## 🔧 API 使用方法

### 1. 提交调试工作流

**请求：**
```
POST /api/v1/repos/{owner}/{repo}/actions/debug-workflow
Content-Type: application/json

{
  "workflow_content": "name: Debug Test\non: workflow_dispatch\njobs:\n  test:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v3\n      - run: echo 'Hello from debug workflow!'",
  "ref": "main",
  "inputs": {
    "custom_input": "value"
  }
}
```

**响应：**
```json
{
  "id": 123,
  "title": "[DEBUG] Debug Test",
  "status": "waiting",
  "workflow_id": "debug-workflow.yml",
  "ref": "main",
  "commit_sha": "abc123...",
  "created": "2025-11-14T10:00:00Z"
}
```

### 2. 获取调试工作流输出

**请求：**
```
GET /api/v1/repos/{owner}/{repo}/actions/debug-workflow/{run_id}
```

**响应：**
```json
{
  "run": {
    "id": 123,
    "title": "[DEBUG] Debug Test",
    "status": "success",
    "workflow_id": "debug-workflow.yml",
    "logs": [...],
    "created": "2025-11-14T10:00:00Z"
  },
  "workflow_content": "name: Debug Test\non: workflow_dispatch\n..."
}
```

## 💻 前端界面集成

建议在以下位置添加调试工作流界面：

### 位置 1: 仓库 Actions 页面
- 路由: `/repos/{owner}/{repo}/actions`
- 添加 "Debug Workflow" 标签页
- 显示工作流编辑器和执行按钮

### 位置 2: 工作流文件详情页面
- 当查看 `.gitea/workflows/*.yml` 文件时
- 添加 "Run Debug Mode" 按钮
- 使用文件内容作为默认值

### 位置 3: Web UI 模板建议
```html
<div id="workflow-debugger">
  <!-- Workflow YAML Editor -->
  <div class="workflow-editor">
    <textarea id="workflow-content" placeholder="Paste your GitHub Actions workflow YAML here..."></textarea>
  </div>

  <!-- Options -->
  <div class="debug-options">
    <label>Select Branch: <select id="ref-select">...</select></label>
    <label>Inputs: <textarea id="debug-inputs" placeholder="JSON format"></textarea></label>
  </div>

  <!-- Actions -->
  <button id="validate-workflow">Validate</button>
  <button id="run-workflow">Run Debug Workflow</button>

  <!-- Output -->
  <div id="debug-output" class="hidden">
    <div class="logs-viewer">
      <pre id="workflow-logs"></pre>
    </div>
  </div>
</div>
```

## 🔍 调试工作流的特殊标记

所有通过调试功能执行的工作流都会：

1. **WorkflowID**: 设置为 `debug-workflow.yml`（特殊标记）
2. **Title 前缀**: 添加 `[DEBUG]` 前缀
3. **Event**: 设置为 `workflow_dispatch`
4. **Status Tracking**: 完整记录所有执行步骤

这使得用户可以轻松区分调试运行和正式运行。

## 📊 数据流

```
┌─────────────────────────────────────────────────────────────────────┐
│                         用户操作                                      │
│                  输入工作流 YAML + 参数                              │
└──────────────────────────┬──────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────────────┐
│                      API /debug-workflow                            │
│        POST /api/v1/repos/{owner}/{repo}/actions/debug-workflow     │
└──────────────────────────┬──────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────────────┐
│              services/actions/debug_workflow.go                      │
│      DebugActionWorkflow()                                          │
│      - 验证 YAML 内容                                                │
│      - 创建临时 ActionRun                                            │
│      - 创建 ActionRunJob                                             │
│      - 保存工作流内容                                                │
└──────────────────────────┬──────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    工作流执行引擎                                     │
│              (现有的 Actions Runner)                                 │
│      - 解析工作流 YAML                                               │
│      - 创建 Jobs                                                     │
│      - 执行步骤                                                       │
│      - 记录输出                                                       │
└──────────────────────────┬──────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────────────┐
│                        查询运行结果                                   │
│        GET /api/v1/repos/{owner}/{repo}/actions/debug-workflow/{id} │
│      返回: run 信息 + workflow_content + logs                        │
└─────────────────────────────────────────────────────────────────────┘
```

## 🔐 安全考虑

1. **权限检查**: 只有具有仓库写权限的用户可以执行调试工作流
2. **Actions 启用**: 仓库必须启用 Actions 单元
3. **YAML 验证**: 所有提交的 YAML 都必须通过解析验证
4. **日志隔离**: 调试工作流的日志单独存储和标记
5. **Token 限制**: 调试工作流中的 token 应该有相同的限制

## 📝 日志输出

调试工作流的完整日志包括：

1. **工作流启动日志**
   - 触发时间
   - 执行用户
   - 分支信息

2. **每个 Job 的日志**
   - Job 名称和 ID
   - 步骤执行情况
   - 命令输出
   - 错误信息

3. **工作流完成日志**
   - 总执行时间
   - 最终状态
   - 任何错误总结

## 🚀 后续改进建议

1. **工作流模板库**
   - 提供常用工作流模板
   - 一键加载示例

2. **语法高亮**
   - 在编辑器中支持 YAML 语法高亮
   - 错误提示

3. **步骤预览**
   - 显示工作流中定义的所有 Job 和步骤
   - 验证 Actions 引用的有效性

4. **变量预测**
   - 自动完成 Gitea 环境变量
   - 显示可用的上下文

5. **历史记录**
   - 保存最近执行过的调试脚本
   - 快速重新运行

## 📚 相关文件

- `services/actions/debug_workflow.go` - 核心业务逻辑
- `routers/api/v1/repo/actions_debug.go` - API 端点
- `routers/api/v1/api.go` - 路由注册
- `models/actions/run.go` - ActionRun 数据模型
- `models/actions/run_job.go` - ActionRunJob 数据模型