수동 승인

manual_approval은 "누군가 확인해야 계속 진행"을 단계 수식자로 인코딩합니다: 실행이 그것을 설정한 단계에 도달하면 일시 중지되고, 승인되어야 단계 본체를 실행합니다. 승인 전에는 시스템이 그 단계와 그 하류의 어떤 동작도 실행하지 않습니다.

구성

  - step: apply_changes
    agent: executor
    input: "把已审核的变更应用到线上"
    manual_approval:
      enabled: true
      approvers:            # 平台用户 ID；留空 = 发起人 / 有执行权限者可批
        - "usr_team_lead"
      timeout: 86400        # 秒；24 小时无人批复自动拒绝
      approval_message: |
        请确认是否应用本轮变更。
        拒绝或超时不会做任何线上修改。

임의의 단계(agent、code、sub_workflow 등)에 붙일 수 있으며, 상태만 출력하는 경량 code 단계에 붙여 순수한 "인적 게이트"로 자주 사용됩니다.

매개변수

승인 프로세스

1. 실행이 manual_approval이 설정된 단계에 도달하면 일시 중지되고, 실행 상태가 AWAITING_APPROVAL로 바뀝니다
2. 승인 레코드를 생성하고 타임아웃 카운트를 시작합니다. 콘솔은 WebSocket으로 approval_request 실시간 알림을 받고, 승인자는 통지 이메일도 함께 받을 수 있습니다
3. 승인자는 세 통로 중 하나로 승인합니다: App 내 승인 목록, 메시지 내 원클릭 링크, API
4. 승인 → 단계 계속; 거부 → 단계를 실패로 처리(on_failure로 통지 분기를 연결 가능); 타임아웃 → 자동 거부

통로 1: App 내 승인 목록

콘솔의승인페이지는 귀하에게 보이는 모든 승인을 나열하며, 카드/표 두 가지 뷰와 상태 필터를 지원합니다. 승인 또는 거부 시 비고를 첨부할 수 있으며, 비고는 승인 레코드에 저장됩니다. reviewable_actions가 설정된 승인은 선택 가능하고 편집 가능한 표로 펼쳐집니다.

통로 2: 이메일 통지와 원클릭 링크

이메일 통지를 켜면 승인자(approvers를 지정하지 않았을 때는 실행 개시자)의 계정 이메일로 메일이 오며, 내용에는 워크플로와 단계명, 실행 ID, 심사 가능 동작 수, 타임아웃 안내("약 N시간 후 자동 거부"), approval_message의 설명 텍스트, 그리고 승인 목록으로 들어가는 링크가 포함됩니다.

이메일, Slack, Telegram처럼 요청 헤더를 커스터마이즈할 수 없는 메시지에는 원클릭 승인 링크도 삽입할 수 있습니다:

GET https://braidrun.com/api/webhook-trigger/approval/{approvalId}/approve?api_key=dyk_...
GET https://braidrun.com/api/webhook-trigger/approval/{approvalId}/reject?api_key=dyk_...

링크는 API Key로 인증하며(APPROVAL_RESPOND 범위), Key는 api_key 쿼리 파라미터에 둡니다. 링크 미리보기 봇(Slack 펼침, 이메일 클라이언트 프리페치)의 오작동을 방지하기 위해, 처음 열 때는 확인 페이지만 렌더링하고 어떤 동작도 실행하지 않습니다. 확인 버튼을 클릭하여 confirm=1을 붙여 다시 요청해야 비로소 실제로 승인됩니다. 페이지에는 no-store와 noindex 헤더가 있어 캐시나 검색 엔진 재생을 방지합니다.

통로 3: API

v1 오픈 API는 5개의 승인 엔드포인트를 제공하며, 모두 APPROVAL_RESPOND 권한 범위를 요구합니다:

# 批准（可附备注）
curl -X POST https://braidrun.com/api/v1/approvals/<approval-id>/approve \
  -H "Authorization: Bearer dyk_..." \
  -H "Content-Type: application/json" \
  -d '{"comment": "确认执行"}'

# 拒绝
curl -X POST https://braidrun.com/api/v1/approvals/<approval-id>/reject \
  -H "Authorization: Bearer dyk_..." \
  -H "Content-Type: application/json" \
  -d '{"comment": "本轮预算已用完"}'

editedItems는 그룹명 기준으로 선택/편집된 서브셋을 제출하며, 구조는 다음 절의 편집 가능한 승인표에 대응합니다. 전달하지 않으면 원본 그대로 전부 승인으로 간주됩니다.

편집 가능한 승인표(reviewable_actions)

일부 승인의 입도는 개별 제안 단위로 떨어집니다: 한 배치의 제안 중 일부만 실행하고, 개별 행은 수치를 바꿔야 합니다. reviewable_actions는 이런 승인을 표로 만듭니다 — 승인자가 실행할 행을 선택하고, editable: true로 표시된 열을 직접 편집한(예: 입찰가 변경) 뒤 승인을 클릭합니다.

    manual_approval:
      enabled: true
      timeout: 86400
      approval_message: |
        请审核本轮调价建议：可勾选要执行的行，并直接修改建议出价。
      reviewable_actions:
        - name: raise_bid
          title: 加价建议
          source_var: raise_bid_file           # 变量值 = 建议清单 JSON 数组文件路径
          output_var: raise_bid_approved_file  # 批准后 = 勾选/编辑后的子集文件路径
          key_field: item_id
          columns:
            - { key: item_name, label: 名称, editable: false }
            - { key: current_bid, label: 当前出价, type: number, editable: false }
            - { key: proposed_bid, label: 建议出价, type: number, editable: true }
            - { key: reason, label: 理由, editable: false }

• name — 그룹 내부명이며, 동시에 출력 파일 접두사로 사용됩니다(승인 후 엔진이 reviewed_<name>.json을 씀)
• source_var — 변수 하나를 가리키며, 변수 값은 상류 단계가 생성한 제안 목록(JSON 배열 파일 경로)입니다
• output_var — 승인 후 설정되는 변수이며, 값은 선택/편집된 서브셋 파일 경로입니다. 하류 실행 단계가 이것을 읽도록 바꾸면 승인된 행만 처리합니다
• key_field — 행 신분 필드로, 편집 후 이것에 따라 정렬합니다. 생략하면 배열 인덱스에 따라 정렬합니다
• columns — 표 열 정의. editable: true인 열은 승인자가 수정할 수 있고, type: number는 숫자 입력으로 렌더링됩니다

거부와 타임아웃: 무변경

승인 게이트의 핵심 약속은: 승인 전에는 시스템이 어떤 동작도 실행하지 않는다는 것입니다. 거부되거나 타임아웃될 때 —

• 단계 본체는 실행되지 않고, 그것에 의존하는 하류 단계도 트리거되지 않습니다
• on_failure 분기로 "승인 거부됨" 통지 또는 아카이브 단계를 연결할 수 있습니다
• 타임아웃은 시스템이 자동으로 거부하며 결정자는 system으로 기록됩니다. 각 승인 결정(결정자, 시간, 비고 포함)은 모두 감사 로그에 기록됩니다

관련 페이지

• API Key와 권한 범위
• v1 API 참조
• 서비스 재시작 후 자동 재개