Issue Outsource Platform

Appearance

データフロー設計 ​

1. Issue取得 → AI開発 → MR提出 → レビュー → 報酬確定フロー ​

メインフロー全体図 ​

mermaid
sequenceDiagram
    participant M as マネージャー
    participant App as 管理画面
    participant API as Backend API
    participant DB as PostgreSQL
    participant GL as GitLab
    participant E as 業務委託エンジニア
    participant Bot as Slack/Discord Bot

    Note over M,Bot: Phase 1: Issue作成
    M->>App: Issue作成（報酬額設定）
    App->>API: POST /api/issues
    API->>GL: GitLab API: Create Issue
    GL-->>API: Issue作成完了
    API->>DB: Issue + 報酬情報保存
    API->>Bot: 新規Issue通知
    Bot-->>E: 通知配信

    Note over M,Bot: Phase 2: Issue取得・開発
    E->>GL: Issueを確認・アサイン
    GL-->>API: Webhook: issue assigned
    API->>DB: アサイン情報更新
    API->>Bot: アサイン通知
    E->>E: AI(Claude Code)で開発
    E->>GL: MR作成（報告資料含む）
    GL-->>API: Webhook: MR opened
    API->>DB: MRステータス更新

    Note over M,Bot: Phase 3: レビュー
    API->>Bot: レビュー依頼通知
    M->>GL: MRレビュー（報告資料確認）
    alt 修正要求
        M->>GL: レビューコメント
        GL-->>API: Webhook: note created
        API->>Bot: FB通知
        E->>GL: 修正コミット
        GL-->>API: Webhook: MR updated
    end
    M->>GL: MR承認
    GL-->>API: Webhook: MR approved

    Note over M,Bot: Phase 4: 報酬確定
    M->>GL: MRマージ
    GL-->>API: Webhook: MR merged
    API->>DB: Issue完了・報酬確定
    API->>Bot: 報酬確定通知

各フェーズのデータ状態遷移 ​

mermaid
stateDiagram-v2
    [*] --> Open: Issue作成
    Open --> Assigned: エンジニアがアサイン
    Assigned --> InProgress: 開発着手
    InProgress --> InReview: MR作成
    InReview --> InProgress: FB対応
    InReview --> Approved: MR承認
    Approved --> Done: MRマージ
    Done --> Paid: 報酬確定
    Paid --> [*]

    Open --> Cancelled: Issue取消
    Assigned --> Open: アサイン解除
    Cancelled --> [*]

2. GitLab Webhook処理フロー ​

受信・処理アーキテクチャ ​

mermaid
graph LR
    GL["GitLab"] -->|Webhook POST| CFW["Cloudflare Workers<br/>(Webhook Receiver)"]
    CFW -->|署名検証| CFW
    CFW -->|イベント転送| API["FastAPI<br/>(Event Processor)"]
    API -->|状態更新| DB["PostgreSQL"]
    API -->|通知トリガー| Bot["Slack/Discord Bot"]

処理対象Webhookイベント ​

イベントトリガー処理内容
issue (open)Issue作成DB登録、通知配信
issue (update)Issue更新DB更新、ラベル変更検知
issue (close)Issue完了ステータス更新
note (issue/MR)コメント追加レビューFB検知、通知
merge_request (open)MR作成レビュー依頼通知、ステータス更新
merge_request (update)MR更新修正コミット検知
merge_request (merge)MRマージ報酬確定処理、ステータス更新
merge_request (approved)MR承認承認ステータス更新

Webhook処理の詳細フロー ​

mermaid
flowchart TD
    A[Webhook受信] --> B{署名検証}
    B -->|失敗| C[403 Forbidden]
    B -->|成功| D{イベント種別判定}

    D -->|Issue Event| E[Issue Handler]
    D -->|MR Event| F[MR Handler]
    D -->|Note Event| G[Note Handler]
    D -->|その他| H[無視 / ログ]

    E --> I{アクション判定}
    I -->|open| J[DB登録 + 通知]
    I -->|update| K[DB更新 + 差分検知]
    I -->|close| L[ステータス更新]

    F --> M{アクション判定}
    M -->|open| N[MR登録 + レビュー依頼通知]
    M -->|merge| O[報酬確定処理]
    M -->|approved| P[承認ステータス更新]
    M -->|update| Q[修正検知]

    G --> R[コメント保存 + FB通知]

3. 通知フロー ​

通知トリガー一覧 ​

トリガー通知先チャネルメッセージ内容
新規Issue作成全エンジニアSlack/DiscordIssue概要、報酬額、リンク
Issueアサインマネージャー、該当エンジニアSlack/Discordアサイン情報
MR作成レビュアー（マネージャー）Slack/DiscordMRリンク、レビュー依頼
レビューFB該当エンジニアSlack/DiscordFBコメント内容
MR承認該当エンジニアSlack/Discord承認通知
報酬確定該当エンジニア、経理Slack/Discord報酬額、Issue情報
予算超過警告マネージャーSlack/Discordプロジェクト名、超過額
進捗遅延警告マネージャーSlack/Discordプロジェクト名、遅延状況

通知処理アーキテクチャ ​

mermaid
graph TD
    Event["イベント発生"] --> Dispatcher["Notification Dispatcher"]

    Dispatcher --> Filter["通知ルール判定"]
    Filter --> Template["メッセージテンプレート生成"]

    Template --> SlackAdapter["Slack Adapter"]
    Template --> DiscordAdapter["Discord Adapter"]

    SlackAdapter --> SlackAPI["Slack Web API"]
    DiscordAdapter --> DiscordAPI["Discord API"]

通知メッセージフォーマット例 ​

Slack/Discord 共通フォーマット:

[Issue Outsource] 新規Issue作成
━━━━━━━━━━━━━━━━━━━━
プロジェクト: {project_name}
Issue: #{issue_id} {issue_title}
報酬: ¥{reward_amount}
ラベル: {labels}
期限: {due_date}
━━━━━━━━━━━━━━━━━━━━
🔗 {issue_url}

4. データモデル概要 ​

主要エンティティ ​

mermaid
erDiagram
    PROJECT ||--o{ ISSUE : has
    ISSUE ||--o{ MERGE_REQUEST : has
    ISSUE ||--o| REWARD : has
    USER ||--o{ ISSUE : assigned_to
    USER ||--o{ MERGE_REQUEST : created_by
    PROJECT ||--o| BUDGET : has

    PROJECT {
        int id PK
        string name
        string gitlab_project_id
        string description
        datetime created_at
    }

    ISSUE {
        int id PK
        int project_id FK
        string gitlab_issue_id
        string title
        string status
        int assignee_id FK
        datetime created_at
        datetime completed_at
    }

    REWARD {
        int id PK
        int issue_id FK
        decimal amount
        string status
        datetime confirmed_at
    }

    MERGE_REQUEST {
        int id PK
        int issue_id FK
        string gitlab_mr_id
        string status
        int author_id FK
        datetime created_at
        datetime merged_at
    }

    USER {
        int id PK
        string gitlab_user_id
        string name
        string email
        string role
    }

    BUDGET {
        int id PK
        int project_id FK
        decimal total_amount
        decimal consumed_amount
        decimal reserved_amount
    }

5. API エンドポイント概要 ​

認証 ​

メソッドパス説明
GET/api/auth/loginGitLab OAuthログイン開始
GET/api/auth/callbackOAuth コールバック
POST/api/auth/logoutログアウト
GET/api/auth/me現在のユーザー情報取得

プロジェクト ​

メソッドパス説明
GET/api/projectsプロジェクト一覧（予算・消化率付き）
GET/api/projects/:idプロジェクト詳細
GET/api/projects/:id/kanbanカンバンデータ取得
GET/api/projects/:id/budget予算詳細
GET/api/projects/:id/analytics進捗分析・ETA

Issue ​

メソッドパス説明
GET/api/issuesIssue一覧
GET/api/issues/:idIssue詳細
POST/api/issuesIssue作成
PATCH/api/issues/:idIssue更新
POST/api/issues/:id/assignアサイン

Webhook ​

メソッドパス説明
POST/api/webhooks/gitlabGitLab Webhook受信

報酬 ​

メソッドパス説明
GET/api/rewards報酬一覧
POST/api/rewards/:id/confirm報酬確定