# Autoflow 상세 설명서 — 무엇을, 왜, 어떻게

> 이 문서는 "버튼을 어떻게 누르나"가 아니라 **Autoflow 가 무엇이고, 왜 만들었고, 어떤 역할을 하며, 안에서 무슨 일이 일어나는지**를 설명합니다. 사용 절차는 화면 안의 안내로 충분하도록 만들었고, 이 문서는 판단·설명·영업에 쓰기 위한 것입니다.
>
> 정본 설계: `docs/AUTOFLOW_BUILD_PLAN.md` · 주소: https://flow.starplan.one · 2026-09-19 Phase 1 기준

---

## 1. 왜 만드는가

### 1-1. 우리가 반복해서 마주친 문제
지금까지 만든 서비스들을 운영하면서 **"사람이 브라우저를 열고 같은 일을 매일 반복하는 구간"** 이 계속 나왔습니다.

| 어디서 | 반복되던 일 | 우리가 임시로 한 것 |
|---|---|---|
| 셀러 콘솔 | 테무·타오바오·1688 에서 상품 정보 긁어오기, 오픈마켓에 등록 | 브라우저 브릿지·PC 에이전트를 셀러 전용으로 만듦 |
| 병원 포털 | 닥터나우·나만의닥터 등 5개 예약 플랫폼 접수 확인·수락 | 플랫폼별 유저스크립트·Electron 매크로를 따로 만듦 |
| 몰 운영 | 어드민에서 주문·상품 목록을 내려받아 정산표 만들기 | 사람이 매번 다운로드 |
| 마케팅 | 광고 관리자·애널리틱스에서 지표를 모아 보고서 작성 | 스크린샷을 찍어 카톡으로 |
| 세무·행정 | 세금계산서 발행 포털, 은행·카드사 거래내역 다운로드 | 월말마다 수작업 |

공통점은 셋입니다. ① 대상 사이트가 **API 를 안 준다**(또는 비싸다) ② 일은 단순하지만 **매일·매주 정해진 시각**에 해야 한다 ③ 로그인·2단계 인증·사내망 같은 **사람 세션**이 필요할 때가 있다.

그때마다 프로그램을 새로 짜는 대신, **"한 번 가르치면 대신 반복하는 범용 도구"** 를 만들어 두면 위의 모든 경우를 같은 방법으로 처리할 수 있습니다. 그것이 Autoflow 입니다.

### 1-2. 기존 도구로 안 되는 이유
- **전통 RPA(UiPath 등)**: 강력하지만 비싸고 무겁고, 화면 좌표·이미지 기반이라 사이트가 조금만 바뀌어도 깨집니다. 소상공인·1인 기업이 도입할 물건이 아닙니다.
- **Zapier 류 노코드 연동**: API 가 있는 서비스끼리만 이어집니다. "로그인해서 표를 긁어오는" 일은 못 합니다.
- **개발자가 짜는 스크립트(Puppeteer/Selenium)**: 잘 돌지만 만든 사람만 고칠 수 있고, 실행 기록·알림·비밀번호 관리·스케줄이 전부 따로입니다.

Autoflow 는 이 세 가지의 빈틈을 겨냥합니다. **스크립트의 힘 + 노코드의 접근성 + 운영에 필요한 기록·보안·알림을 처음부터 한 몸으로.**

### 1-3. 이 도구가 만들어 내는 가치
1. **시간**: 매일 20분짜리 반복 업무 하나가 연 80시간입니다. 플로우 하나가 그걸 없앱니다.
2. **증거**: 모든 실행이 스텝별 스크린샷·로그·산출물로 남습니다. "언제 뭘 받았는지" 를 사람이 기억할 필요가 없습니다.
3. **재사용**: 셀러·병원·몰 프로젝트에서 각각 만들던 자동화가 이제 플로우 파일 하나로 표현되고, 다른 고객에게 그대로 복사됩니다.
4. **상품**: "당신 회사의 반복 웹 업무를 자동화해 드립니다"는 크몽·기업 납품 어디서든 통하는 문장입니다. Autoflow 는 그 상품의 공장입니다.

---

## 2. 한 문장 정의

> **Autoflow 는 "사람이 브라우저에서 하는 반복 업무"를 플로우(절차서)로 적어 두면, 정해진 시각에 서버(또는 사무실 PC)가 대신 실행하고, 결과를 스크린샷·파일·알림으로 돌려주는 자동화 허브입니다.**

비유하자면 **"업무를 아는 신입 직원 + 그 직원의 업무 일지"** 입니다. 절차서(플로우)를 한 번 써 주면, 매일 아침 그 절차대로 사이트에 들어가 일을 하고, 한 걸음마다 화면을 찍어 일지(실행 이력)에 붙이고, 끝나면 카톡(텔레그램)으로 보고합니다. 절차서에 없는 일은 하지 않고, 막히면 멈춰서 어디서 막혔는지 사진과 함께 알려줍니다.

---

## 3. 역할 — 누가 무엇을 얻는가

| 역할 | 하는 일 | 얻는 것 |
|---|---|---|
| **업무 담당자(직원)** | 플로우를 실행하거나, 결과 산출물(CSV·파일)을 받는다 | 반복 작업에서 해방. 매일 아침 결과만 확인 |
| **관리자(사장·팀장)** | 어떤 업무가 자동화돼 있고 잘 도는지 대시보드로 본다 | 실패 즉시 알림, 실행 증거, 사람 의존도 감소 |
| **플로우 작성자(우리 또는 파워유저)** | 자연어 지시 → AI 초안 → 스텝 다듬기 → 금고에 자격증명 → 스케줄 | 코딩 없이(또는 최소한으로) 자동화 제작 |
| **STARPLAN(운영 대행)** | 고객사 플로우 제작·모니터링·사이트 변경 시 수리 | 월 운영 수익, 다른 프로젝트에 재사용 |

---

## 4. 무엇을 할 수 있고, 무엇을 하지 않는가

### 할 수 있는 것
- 웹사이트 **로그인**(아이디/비밀번호는 금고에서), 메뉴 이동, 클릭, 입력, 드롭다운 선택
- 화면의 **표를 CSV 로**, 목록을 JSON 으로, 특정 텍스트를 값으로 **추출**
- **파일 다운로드**(엑셀·PDF 등)를 산출물로 보관
- 페이지 **스크린샷**(증빙)
- 사람이 읽는 화면(대시보드 KPI 등)을 **AI 로 구조화 추출**(예: "일 매출·주문 수" → 숫자)
- 조건 분기(어떤 요소가 있으면/없으면 특정 스텝 건너뛰기), 실패 시 재시도, 실패해도 계속
- **스케줄 실행**(cron, KST), 수동 실행, **웹훅 트리거**(`POST /api/hooks/:flowId?key=…` — 본문 JSON 이 그 실행의 변수가 됨)
- **반복**(`loop` — 추출한 행마다, 또는 N 회) · **Google Sheets 에 행 추가**(`sheet_append`, 서비스 계정) · **직전 실행 대비 표 차이**(추가/삭제/변경 행 수)
- **텔레그램/웹훅 알림**(추출한 값을 문장에 끼워서)
- 실행 기록: 스텝별 상태·소요시간·스크린샷·로그·산출물

### 하지 않는 것 (의도적 경계)
- **사람 인증을 우회하지 않습니다.** 캡차 풀기, OTP 훔치기, 봇 탐지 회피는 만들지 않습니다. 2FA 가 필요한 사이트는 사람이 로그인해 둔 **PC 에이전트 모드**(Phase 2)로 그 세션을 씁니다.
- **약관이 자동화를 금지하는 사이트·타인 계정·대량 크롤링**은 대상이 아닙니다. 허용 호스트 목록으로 이동 범위를 제한합니다.
- **결제·송금 같은 되돌릴 수 없는 행동**은 기본적으로 사람이 마지막 버튼을 누르게 설계합니다(플로우는 "확인 화면까지" 만들고 알림으로 넘김).
- 화면 좌표·이미지 매칭 방식은 쓰지 않습니다. 항상 DOM(구조) 기준이라 반응형·해상도 변화에 강합니다.

### 잘 맞는 업무 / 안 맞는 업무
- **잘 맞음**: 매일 같은 사이트, 같은 순서, 결과가 표·파일·숫자로 나오는 일. 로그인 필요. API 없음.
- **안 맞음**: 매번 판단이 크게 달라지는 일(협상·상담), 결과가 사람의 글쓰기인 일, 사이트가 매일 구조를 바꾸는 곳(이 경우 AI 자가치유가 버티지만 한계가 있음).

---

## 5. 구성 요소와 각자의 역할

```
 사용자(브라우저) ──▶ ┌────────── Hub (flow.starplan.one, Next.js) ──────────┐
                    │ 플로우 편집기 · AI 초안 · 실행 이력 · 산출물 · 금고 · 설정 │
                    │            runs 테이블에 "queued" 한 줄을 넣는다            │
                    └───────────────┬──────────────────────┬────────────────┘
                                    │ (DB)                  │ (HTTPS, 토큰)
                     ┌──────────────▼──────────┐   ┌────────▼───────────────┐
                     │ Worker/Runner (서버)     │   │ Desktop Agent (PC)     │
                     │ 3초마다 queued 확인       │   │ 4초마다 pull            │
                     │ 헤드리스 Chrome 로 실행   │   │ 로컬 Chrome(사람 세션)  │
                     │ 스텝마다 스샷·로그 기록   │   │ 스텝마다 report         │
                     │ 스케줄(cron) 큐잉        │   │ + 녹화기(Phase 2)       │
                     └──────────────┬──────────┘   └────────┬───────────────┘
                                    └──────────┬────────────┘
                                   ┌───────────▼─────────────┐
                                   │ 대상 웹사이트(ERP·몰·포털) │
                                   └─────────────────────────┘
        곁가지: 금고(AES-256-GCM) · AI Planner/Locator(Anthropic) · 알림(텔레그램/웹훅) · 파일 저장소(/var/lib/autoflow)
```

| 구성 요소 | 역할 | 왜 분리했나 |
|---|---|---|
| **Hub** | 사람이 보는 전부. 플로우를 만들고, 실행을 "요청"하고, 결과를 본다 | 웹 앱은 크롬을 띄우지 않는다 → 가볍고, 여러 실행이 웹 요청을 막지 않음 |
| **Worker/Runner** | 큐에서 실행을 집어 실제로 브라우저를 조작한다. 스케줄도 여기서 큐잉 | 실행이 오래 걸리거나 죽어도 Hub 는 멀쩡. 동시 실행 수를 따로 조절 |
| **Desktop Agent** | 서버가 못 가는 곳(사내망·2FA·IP 제한)에서 같은 플로우를 실행. 브라우저 조작을 녹화해 플로우 초안을 만든다 | "사람 자리에서만 되는 일" 을 자동화 범위 안으로 끌어옴 |
| **AI Planner** | 자연어 → 플로우 초안, 셀렉터가 깨졌을 때 후보 중 고르기, 화면 텍스트 → 구조화 값 | 제작 시간을 시간 단위에서 분 단위로. 사이트 소폭 변경에 버팀 |
| **금고(Vault)** | 자격증명 암호화 보관. 플로우에는 `{{secret:키}}` 만 남음 | 플로우를 공유·복사해도 비밀은 따라가지 않음 |
| **알림** | 성공/실패/추출값을 텔레그램·웹훅으로 | 사람이 화면을 열지 않아도 결과가 옴 |

---

## 6. 핵심 개념

| 개념 | 뜻 | 데이터 |
|---|---|---|
| **플로우(Flow)** | 하나의 반복 업무 절차서. 이름·스텝 목록·스케줄·실행 모드·허용 호스트·실패 정책 | `flows` 한 행, `steps` 는 JSON(DSL v1) |
| **스텝(Step)** | 플로우의 한 동작(이동·클릭·입력…). `id`(s1, s2…) 로 서로 가리킴 | `flows.steps.steps[]` |
| **타깃(Target)** | 스텝이 다룰 화면 요소를 찾는 방법: `css` / `text`(보이는 글자) / `xpath` / `ai`(설명) | 스텝 안 |
| **변수** | `{{today:YYYY-MM}}` 날짜, `{{secret:erp.pass}}` 금고, `{{sales.rows}}` 앞 스텝 결과 | 실행 중 컨텍스트 |
| **실행(Run)** | 플로우를 한 번 돌린 기록. queued → running → ok / failed / canceled | `runs` |
| **스텝 기록** | 실행 안의 스텝별 결과: 상태·소요·스크린샷·로그·(AI 로 찾았다면) 제안 셀렉터 | `run_steps` + 파일 |
| **산출물(Artifact)** | 실행이 남긴 파일: 표 CSV, 목록 JSON, 다운로드 파일, 스크린샷 | `artifacts` + 파일 |
| **모드** | `server`(헤드리스, 기본) / `agent`(PC 에이전트) | `flows.mode` |
| **스케줄** | cron 5필드(KST). 워커가 매 분 검사해 큐에 넣음 | `flows.schedule_cron` |

---

## 7. 스텝 14종 — 목적·입력·실패 조건

| 타입 | 목적 | 주요 입력 | 실패하는 경우 | 남기는 것 |
|---|---|---|---|---|
| `goto` | 페이지 이동 | `url` | 허용 호스트 밖, 45초 내 로드 실패 | 스샷 |
| `click` | 버튼·링크 클릭 | `target` | 요소를 못 찾음(AI 힐링 후에도) | 스샷 |
| `type` | 입력칸에 글자 | `target`, `text`, `enter`, `clear` | 요소 없음 | 스샷(로그엔 비밀값 `***`) |
| `select` | 드롭다운 선택 | `target`, `value` | 요소·옵션 없음 | 스샷 |
| `wait` | 조건 대기 | `for: {css | urlIncludes | text | ms}` | 제한시간 초과 | 스샷 |
| `scroll` | 스크롤 | `to: top/bottom` 또는 `target` | — | 스샷 |
| `extract` | 데이터 추출 | `name` + `table{css}` / `list{css,fields}` / `text{css}` | 표·요소 없음 | **CSV/JSON 산출물** + 변수 |
| `download` | 파일 내려받기 | `target`, `saveAs` | 클릭 후 파일이 안 생김 | **파일 산출물** |
| `screenshot` | 증빙 캡처 | `name`, `full` | — | **이미지 산출물** |
| `ai_extract` | 화면 텍스트 → 구조화 값 | `name`, `schema{키:타입}`, `prompt` | AI 응답 불가 | JSON 산출물 + 변수 |
| `if` | 조건 분기 | `exists: target`, `then[]`, `else[]`(건너뛸 스텝 id) | — | 스샷 |
| `notify` | 알림 | `channel: telegram/webhook`, `text`, `url` | 채널 미설정·전송 실패 | 스샷 |
| `loop` | 반복 | `over: "{{items.data}}"`(앞 추출 배열) 또는 `count`(1~50), `steps[]`(반복할 스텝 id), `var`(기본 `item`) | 안쪽 스텝 실패(실패 정책 따름), `over` 가 배열이 아님 | 반복마다 안쪽 스텝 기록(`s10@0`, `s10@1`… 로그 앞 `i/N`) |
| `sheet_append` | Google Sheets 에 행 추가 | `sheetId`, `range`(`Sheet1!A:Z`), `rows: "{{sales.data}}"` 또는 `values[[…]]`, `serviceAccountSecret`(금고 키, 기본 `gsa`) | 서비스 계정 JSON 없음, 권한 없음(403 — 시트를 서비스 계정 이메일과 공유해야 함), 시트 없음(404) | 로그에 추가된 범위 |

공통 옵션: `label`(설명) · `retry`(0~3, 기본 1) · `timeoutMs` · `optional`(실패해도 건너뜀). 플로우 공통: `onError: stop | continue`, `allowHosts[]`, `vars{}`.
loop 안 스텝은 최상위 순서에서는 건너뛰고 loop 가 돌 때만 실행되며, 안에서 `{{item}}`(또는 `var` 이름)·`{{index}}` 를 쓸 수 있습니다. 표 CSV 를 만드는 extract 는 **직전 성공 실행의 같은 이름 CSV** 와 자동 비교해 `{{diff.added}}`·`{{diff.removed}}`·`{{diff.changed}}`(행 수, 첫 열 기준) 를 알림 문장에 끼울 수 있습니다.

### 요소 찾기 순서(모든 target 공통)
1. `css` 가 있으면 CSS 셀렉터로(보이는 요소만)
2. `text` 가 있으면 그 글자를 포함하는 요소를 XPath 로 — 여러 개면 **글자가 가장 짧은(가장 안쪽) 요소** 를 고름
3. `xpath`
4. 위가 모두 실패하고 `ai` 설명이 있거나 힐링이 켜져 있으면(기본), 페이지의 클릭 가능한 요소 후보(최대 80개: 태그·글자·이름·id)를 AI 에게 보여 주고 번호를 고르게 함 → 성공하면 **"제안 셀렉터"** 를 실행 기록에 남김(플로우를 자동으로 고치진 않음 — 사람이 보고 반영)

### 실행을 시작하는 네 가지 방법
| 방법 | 어떻게 | 언제 쓰나 |
|---|---|---|
| 지금 실행 | 플로우 화면의 [실행] 버튼 | 만들고 바로 확인할 때 |
| 스케줄 | 플로우의 cron(`7 9 * * 1-5` = 평일 09:07). 워커가 1분마다 도래한 플로우를 큐에 넣음 | 매일·매주 반복 |
| **웹훅 트리거** | 편집기에서 [웹훅 키 발급] → `POST https://flow.starplan.one/api/hooks/<플로우ID>?key=<키>` (또는 `Authorization: Bearer <키>`). 본문 JSON(16KB 이하)은 실행의 입력이 되어 스텝 안에서 `{{input.항목}}` 또는 바로 `{{항목}}` 으로 쓴다. 키를 재발급하면 이전 URL 은 즉시 무효 | 주문이 들어올 때, 다른 시스템(ERP·시트·Zapier 류)이 신호를 줄 때 |
| PC 에이전트 | 플로우 모드를 `agent` 로 두면 큐에 쌓인 실행을 페어링된 PC 의 앱이 가져가 그 PC 의 Chrome 으로 실행 | 사내망·로그인 세션이 필요한 사이트 |

### 실행 생애주기
```
[지금 실행 / 스케줄 / 웹훅 / 재실행]  →  runs: queued
        워커가 집음(FOR UPDATE SKIP LOCKED — 동시 워커 안전)  →  running (started_at)
        스텝 순서대로 실행, 각 스텝: 재시도 → 성공(ok) / optional 이면 skipped / 아니면 failed
        onError=stop 이면 첫 failed 에서 중단, continue 면 끝까지
        스텝 사이마다 '취소 요청' 확인 → 있으면 canceled 로 종료(진행 중 스텝은 끝까지)
  →  ok / failed / canceled (ended_at, error, summary{steps, ok, failed, skipped, artifacts, ai 토큰, diff})
```
- **취소**: 실행 상세 상단 [취소]. 큐 대기 중이면 즉시 `canceled`, 실행 중이면 플래그를 세워 다음 스텝 전에 멈춘다.
- **실패 지점부터 재실행**: 실패한 실행 상세의 [실패 스텝부터 재실행]. 그 앞 스텝은 `skipped`(재실행 시작점 이전)로 남기고, 같은 페이지에서 시작하도록 **직전 goto 하나만** 다시 실행한다.
- **실행 간 diff**: 같은 플로우의 직전 성공 실행과 이번 실행의 같은 이름 CSV 를 첫 열을 키로 비교해 `+추가 / -삭제 / ~변경` 행 수를 실행 상세에 보여 주고, 이후 스텝에서 `{{diff.added}}` 처럼 쓸 수 있다(예: "신규 주문 {{diff.added}}건" 알림).

---

## 8. AI 가 하는 일 / 하지 않는 일

| 하는 일 | 모델 | 어떻게 |
|---|---|---|
| **초안 작성** — "이 사이트 로그인해서 KPI 뽑아 텔레그램" → 9스텝 | claude-sonnet-5 | DSL 규칙을 시스템 프롬프트로 주고 JSON 만 받음. 결과는 zod 로 검증, 저장은 사람이 |
| **요소 찾기 힐링** — 셀렉터·글자로 못 찾을 때 후보 중 선택 | claude-haiku-4.5 | 후보 목록(글자·태그·name·id)만 전달. 입력값·비밀번호는 후보에 넣지 않음 |
| **구조화 추출** — 대시보드 텍스트에서 `{daily, monthly, orders}` | claude-haiku-4.5 | 페이지 본문 텍스트(최대 12,000자) + 스키마 |

**하지 않는 일**: 실행 순서를 즉흥적으로 바꾸지 않습니다. 스텝은 결정적이고, AI 는 "찾기·읽기·초안"에만 관여합니다. 그래서 같은 플로우는 같은 순서로 같은 행동을 하고, 문제가 생기면 어느 스텝인지 정확히 짚을 수 있습니다.

**비용 감각**: 초안 1회 ≈ 3~6원, 힐링 1회 ≈ 0.5원, ai_extract 1회 ≈ 3원(haiku). 실행 요약(summary.ai)에 토큰이 기록되어 플로우별 비용을 알 수 있습니다.

---

### 제안 셀렉터를 플로우에 반영하기
AI 힐링으로 요소를 찾은 스텝은 실행 상세에 "AI 로 찾음"과 함께 **제안 셀렉터**가 표시됩니다. [이 셀렉터로 플로우 고치기] 버튼을 누르면 그 스텝의 `target` 만 바뀌어 저장되므로(`PATCH /api/flows/:id/steps/:stepId`), 다음 실행부터는 AI 를 부르지 않고 바로 찾습니다. 힐링은 응급처치, 반영은 완치입니다.

---

## 9. 보안과 데이터

- **금고**: 값은 AES-256-GCM(서버 `.env SECRET_KEY`)으로 암호화해 DB 에 저장. API 는 "있음/없음·메모"만 돌려주고 값은 절대 응답에 넣지 않습니다. 실행 로그·제안 셀렉터·산출물 이름에서 금고 값과 같은 문자열은 `***` 로 치환합니다.
- **허용 호스트**: 설정(전역) 또는 플로우별 `allowHosts`. 목록 밖 도메인으로 `goto` 하면 즉시 실패 — 초안이 엉뚱한 사이트로 가는 사고를 막습니다.
- **파일**: 스크린샷·산출물은 웹루트 밖 `/var/lib/autoflow/runs/<id>/` 에 두고, 로그인한 어드민만 API 로 받습니다.
- **에이전트**: 페어링 코드 10분 만료, 토큰은 해시로만 저장, PC 로 보내는 금고 값은 **그 플로우가 참조하는 키만** 복호화해 HTTPS 로 전달.
- **어드민 로그인**: 비밀번호 1개(HMAC 세션 쿠키 7일). Phase 3 에서 조직·사용자·권한으로 확장.
- 원칙: 자동화 대상 사이트의 약관을 존중하고, 고객 자신의 계정·자신의 데이터에만 씁니다.

---

## 10. 서버 모드와 PC 에이전트 모드 — 왜 둘 다인가

| | 서버(헤드리스) | PC 에이전트 |
|---|---|---|
| 실행 위치 | 우리 서버(고정 IP, 24시간) | 고객 사무실 PC(사람 세션) |
| 잘 맞는 대상 | 공개 웹·일반 로그인 사이트·우리 서비스들 | 사내망/VPN 전용, IP 화이트리스트, OTP·인증서 로그인, "이미 로그인돼 있는" 브라우저 |
| 스케줄 | 워커가 24시간 | PC 가 켜져 있을 때(트레이 상주) |
| 만들기 | AI 초안 + 편집기 | **녹화**(사람이 한 번 시연) 또는 편집기 |
| 상태 | Phase 1 완료 | Phase 2 — 허브 쪽 API 완료, 앱은 win11 워커가 제작 중 |

두 모드가 **같은 플로우 파일**을 실행한다는 점이 핵심입니다. 서버에서 만들고 시험한 플로우를 모드만 바꿔 PC 로 보낼 수 있습니다.

---

## 11. 실제 활용 시나리오

1. **구매대행 정산** — 매일 08:37 오픈마켓 판매자센터 로그인 → 정산 예정 표 CSV → 텔레그램 "오늘 정산 N건 M원". (F2 데모가 이 골격)
2. **경영 아침 보고** — 여러 시스템(ERP·광고·애널리틱스)의 KPI 를 순서대로 방문해 `ai_extract` 로 숫자만 뽑아 한 줄 요약. (F1 데모)
3. **병원 접수 데스크** — 예약 플랫폼 5곳 새 접수 확인·수락 → 접수 표 추출 → 담당자 알림. 2FA 플랫폼은 PC 에이전트로.
4. **경쟁사 가격 모니터** — 상품 URL 목록을 돌며 가격 텍스트 추출 → 어제 산출물과 비교(Phase 1.5 diff) → 변동만 알림.
5. **세금계산서·거래명세 수집** — 월초 포털 로그인 → 기간 설정 → 엑셀 다운로드 → 산출물 보관(증빙 스샷 포함).
6. **재고 동기화** — 공급사 B2B 사이트 재고 표 → CSV → (웹훅) 우리 몰 재고 API 로 반영.
7. **사이트 헬스 체크** — 운영 중인 16개 서비스의 핵심 화면 방문 + 로그인 흐름 실행 → 실패만 알림(F3 데모의 확장).
8. **광고 리포트** — 광고 관리자에서 기간 리포트 다운로드 → 스프레드시트 append(Phase 1.5).
9. **데이터 이관** — 구 시스템 화면에서 목록 추출 → 새 시스템 입력 폼에 `type` 으로 채워 넣기(수백 건 반복은 `loop`, Phase 1.5).
10. **채용·행정 포털** — 지원자 목록 다운로드, 공공 포털 공고 확인 등 "로그인 + 표 + 다운로드" 패턴 전부.

---

## 12. 상품화 관점 (우리가 파는 방식)

- **누구에게**: 직원 1~20명 규모에서 "매일 누가 사이트 들어가서 뭘 내려받는" 일이 3개 이상 있는 회사(구매대행·유통·병의원·마케팅 대행·회계사무소).
- **무엇을**: ① 셋업(허브 계정·금고·알림) ② 플로우 제작 건당 ③ 월 운영(모니터링·사이트 변경 수리·리포트). 크몽 패키지로 치면 STANDARD=플로우 1개 제작, DELUXE=3개+스케줄+알림, PREMIUM=PC 에이전트 포함 운영.
- **차별점 문장**: "결과만 받아보세요. 실행마다 사진이 남고, 사이트가 바뀌어도 AI 가 먼저 버티고, 그래도 안 되면 저희가 고칩니다."
- **재사용**: 업종별 플로우 템플릿(정산·리포트·접수)을 쌓아 두면 두 번째 고객부터는 제작 시간이 반으로 줍니다.

---

## 13. 로드맵과 현재 상태

| Phase | 내용 | 상태(2026-09-20) |
|---|---|---|
| 1 | Hub 5화면, DSL v1 12스텝, 서버 러너, 금고, 스케줄러, AI 초안·힐링·추출, 텔레그램, 데모 F1~F3 | **완료·운영 중** |
| 1.5 | loop 스텝, Google Sheets append(`sheet_append`), 웹훅 트리거, 실행 간 diff, 취소, 실패 지점부터 재실행, 제안 셀렉터 원클릭 반영, 에이전트용 locate API — 러너·DSL·편집기·실행 상세 확장 + `npm test` | **완료·운영 중(2026-09-19 배포)** |
| 2 | PC 에이전트(Electron): 페어링·로컬 실행·트레이·**녹화기**·설치 파일 | 코어(A001)·녹화기(A002) 완료·병합. Windows 설치 파일은 `https://flow.starplan.one/downloads/latest.json` 이 가리키는 파일(A003 진행 중, 실기기 페어링·실행 검증 1회 성공) |
| 2.5 | 에이전트에서도 AI 힐링(허브 경유) | 이후 |
| 3 | 멀티테넌트(조직·사용자·권한), 사용량 과금, 템플릿 마켓 | 상품화 단계 |

---

## 14. 용어집

- **DSL(Domain Specific Language)**: 플로우를 적는 우리만의 작은 문법(JSON). 사람이 읽고 AI 가 쓸 수 있게 단순하게 유지.
- **헤드리스(headless)**: 화면 없이 도는 브라우저. 서버 모드가 이걸 씁니다.
- **셀렉터(selector)**: 화면 요소를 가리키는 주소(CSS/XPath). 사이트가 바뀌면 깨질 수 있어 글자·AI 로 보완합니다.
- **힐링(heal)**: 깨진 셀렉터 대신 AI 가 후보에서 골라 실행을 이어가는 것.
- **산출물(artifact)**: 실행이 만든 파일. CSV·JSON·다운로드 파일·스크린샷.
- **금고(vault)**: 암호화된 자격증명 저장소. 플로우엔 키 이름만.
- **cron**: `분 시 일 월 요일` 다섯 칸으로 적는 스케줄. 예 `7 9 * * 1-5` = 평일 09:07.
- **페어링(pairing)**: PC 에이전트를 허브에 등록하는 6자리 코드 절차.
- **웹훅 키(hook key)**: 플로우마다 발급하는 40자 비밀 문자열. 이 키만 알면 로그인 없이 그 플로우를 실행시킬 수 있으므로 외부 시스템에만 준다.
