FRNC
FRNC — 프랜차이즈 창업 전 10초 리스크 체크
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 21 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/CLNS-KR/FRNC with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/CLNS-KR/FRNC'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/clns-kr--frnc)HTML
<a href="/listings/clns-kr--frnc"><img src="/api/listings/clns-kr--frnc/badge.svg" alt="findsafeskills safety rating" /></a>Install
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 373 lines
- # FRNC — 프랜차이즈 창업 전 10초 리스크 체크
- > **Franchise, simplified.** · KOREA FRANCHISE DISCLOSURE RISK CHECK
- 프랜차이즈 창업 전에 본부가 제시한 조건(정보공개서 수령 후 경과일, 가맹금 납부 방식,
- 예상매출 서면, 인테리어 지정, 영업지역, 폐점률, 법 위반 이력 등)을 **가맹사업법·시행령
- 조문과 대조**해 위험 신호·확인 체크리스트·질문·근거 조문을 돌려주는 웹·JSON API·MCP
- 서비스입니다. 계약서·특약 문구를 붙여넣으면 **확인이 필요한 문구와 본부에 요청할 수정
- 문구**를 짚어 주는 스캐너도 함께 제공합니다. 표준 라이브러리만 쓰고, 로그인·회원가입·
- 개인정보 입력이 없습니다.
- **확정 판정이 아닙니다.** 조건 판정은 `check_likely`(확인 필요 신호 있음) / `info_needed`(정보 부족) /
- `low_risk`(뚜렷한 위험 신호 없음) 세 가지뿐이고, 모든 응답에 면책과 근거 조문이 붙습니다.
- 문구 스캔은 `scan_flagged` / `scan_no_match` / `scan_text_needed` 세 가지이며, **0건이어도
- '안전·문제없음'을 쓰지 않습니다**.
- ---
- ## 1. 무엇을 보나 (핵심 8축)
- | 축 | 보는 것 | 근거 |
- |---|---|---|
- | 숙고기간 | 정보공개서·계약서를 받은 뒤 14일(자문 시 7일) 전 계약·입금 | 가맹사업법 제7조③, 제11조① |
- | 가맹금 | 예치기관 예치 또는 피해보상보험계약 | 제6조의5①, 시행령 제5조의8 |
- | 매출 정보 | 예상매출액 산정서·산출근거 서면 교부 | 제9조③⑤ |
- | 인테리어 | 본사 지정 100% 강제(구입강제) | 제12조①3, 시행령 별표 2 3.가 |
- | 영업지역 | 계약서 기재·계약 중 침해 금지 | 제12조의4, 제11조②5 |
- | 폐점률 | 최근 3년 가맹점 변동(신규·계약종료·계약해지) | 제9조①2 |
- | 법 위반 이력 | 공정위 시정조치·과징금·형벌선고 | 제9조①2 |
- | 해지·갱신 | 2개월 유예·서면 2회 통지, 갱신 10년 한도 | 제14조, 제13조 |
- 함정 코퍼스 **17건**(`src/franchise_kr/traps.json`)이 위 축과 그 밖의 조항(위약금, 필수품목·
- 판매목표, 필수품목 단가 미공개·차액가맹금 일방 인상, 판매가격 구속·재판매가격 유지,
- 광고·판촉비, 정보공개서 등록)을 덮습니다. 각 케이스의 `law_refs` 는
- 실조회한 조문 키와 1:1로 대조되며, 테스트가 그 대응을 강제합니다.
- ## 2. 검증한 것 (추측 금지)
- ### 2-1. 법령 — 법제처 OPEN API 실조회
- `law-verification.json` 은 `src/tools/verify_law_articles.py` 가 법제처 국가법령정보
- 공동활용 OPEN API(`law.go.kr/DRF`)로 받은 응답입니다. 조문 텍스트를 손으로 옮겨 적지
- 않았고, `조문내용`·`항`·`호`·`목` 구조를 그대로 보존했습니다.
- | 법령 | MST | 공포 | 시행 | 조문 |
- |---|---|---|---|---|
- | 가맹사업거래의 공정화에 관한 법률 | 288583 | 2026-08-04 | 2026-10-02 | 77 |
- | 가맹사업법 시행령 | 288453 | 2026-08-04 | 2026-08-04 | 64 |
- - 조문 **135개**, 별표 **17개**(불공정거래행위 유형·기준 별표 2 포함) 저장.
- - `get_law_article` 툴(`POST /v1/tools/get_law_article`)로 원문을 그대로 조회합니다.
- - OC 인증값은 파일·응답·로그에 남기지 않습니다.
- ### 2-2. 공정거래위원회 가맹정보 오픈API — 실호출 결과
- `src/tools/verify_ftc_apis.py` 가 후보 오퍼레이션을 **실제로 호출**해 응답 코드를 기록합니다.
- `NO_OPENAPI_SERVICE_ERROR`(12)는 오퍼레이션 이름이 틀렸다는 뜻이고,
- `SERVICE_KEY_IS_NOT_REGISTERED_ERROR`(30)은 이름은 맞지만 이 인증키가 해당 서비스에
- 등록되지 않았다는 뜻입니다. 2026-11-21 실측(`api-verification-2026-11-21.json`):
- - 호출 시도 **18개** → **승인 4개** · 키 미등록(30) **13개** · 오퍼레이션 미확인(12) **1개**
- - 문서 열람형(LINK) **3개**(정보공개서 목록·목차·본문)는 REST 오퍼레이션이 공개되어 있지 않음
- | 데이터셋 | 식별자 | 오퍼레이션 | 상태 |
- |---|---|---|---|
- | 브랜드 목록 | 15125467 | `getBrandinfo` | **승인** |
- | 가맹본부 일반 정보 | 15125450 | `getjnghdqrtrsGnlinfo2` | **승인** |
- | 브랜드 가맹점 및 직영점 | 15125490 | `getbrandFrcsDmsstus2` | **승인** |
- | 브랜드 가맹점 변경현황 | 15125491 | `getbrandFrcsFlctnstus` | **승인** |
- | 브랜드별 가맹점 현황(평균매출) | 15110241 | `getBrandFrcsStats` | 키 미등록 |
- | 브랜드별 창업 금액 | 15110265 | `getBrandFntnStats` | 키 미등록 |
- | 인테리어 비용 | 15125479 | `getbrandFrcsBzmnIntrrctinfo` | 키 미등록 |
- | 가맹금 정보 | 15125476 | `getbrandFrcsJnntinfo` | 키 미등록 |
- | 부담금 정보 | 15125475 | `getbrandFrcsbzmnAlotminfo` | 키 미등록 |
- | 예치금 정보 | 15125480 | `getbrandFrcsBzmnDepoinfo` | 키 미등록 |
- | 가맹본부 법 위반정보 | 15125463 | `getjnghdqrtrsLawVioltinfo` | 키 미등록 |
- | 법 위반 시정조치 | 15125464 | `getjnghdqrtrsCorecActninfo` | 키 미등록 |
- | 법 위반 형벌선고 | 15125466 | `getjnghdqrtrsPetyAdjuinfo` | 키 미등록 |
- | 브랜드 지식재산권 | 15125471 | `getbrandIprsinfo` | 키 미등록 |
- | 가맹기간 | 15125484 | `getbrandFrcsPdinfo` | 키 미등록 |
- | 브랜드 비교 목록 | 15125517 | `getbrandCompListinfo` | 키 미등록 |
- | 가맹본부 일반 변경 이력 | 15125452 | `getjnghdqrtrsGnlHist` | 키 미등록 |
- | 단위면적당 평균매출 | 15125494 | (오퍼레이션 미확인) | 미확인 |
- | 정보공개서 목록·목차·본문 | 15125569·15125570·15125571 | LINK | 문서 열람 |
- 아직 등록되지 않은 데이터셋의 **활용신청 주소**는 `https://www.data.go.kr/data/{식별자}/openapi.do`
- 이고, 서버는 신청 상태를 하드코딩하지 않고 응답의 `apply_urls` 와 `/v1/meta` 의
- `data_sources.apply_urls` 로 알려 줍니다.
- #### 브랜드 색인 — `getBrandinfo` 에는 이름 검색 파라미터가 없습니다
- `brandNm` 을 붙여도 무시되고 `pageNo`/`numOfRows` 로만 훑을 수 있습니다(2026-11-21 실측).
- 그래서 예전 코드는 1페이지 100건만 뒤져 `BBQ`·`교촌` 같은 브랜드를 못 찾았습니다.
- 지금은 **전체 페이지를 받아 색인**을 만들고, 조회는 그 색인을 먼저 봅니다.
- | 항목 | 값 |
- |---|---|
- | 색인 파일 | `data/brands_index.json.gz` (약 2.0MB 압축, 저장소·이미지에 포함) |
- | 수집 연도 | 2026·2025·2024·2023 (연도별 1만 건대, `numOfRows=1000` × 11~12페이지) |
- | 브랜드 수 | 44,567건(연도 중복 포함) · 이름·관리번호로 즉시 검색 |
- | 가맹점 수 | 승인된 **가맹점 및 직영점(15125490)** 도 연도별 전체 페이지(연간 18~20만 행)로 받아 40,195행에 합계 저장 |
- | 갱신 | `src/tools/sync_brands_index.py` + `.github/workflows/sync-brands-index.yml` (**주 1회**, 월 05:00 KST) |
- | 색인 신선도 | 45일 이내면 이름 미매칭을 확정으로 보고 실시간 순회를 생략(느린 전체 순회 방지) |
- ```bash
- PYTHONPATH=src python -m tools.sync_brands_index # 브랜드 목록 + 가맹점 수(약 4분)
- PYTHONPATH=src python -m tools.sync_brands_index --no-stores # 브랜드 목록만(약 1분)
- PYTHONPATH=src python -m tools.sync_brands_index --check # 네트워크 없이 색인 상태만
- ```
- 조회 순서는 ① **로컬 색인** ② **실시간 API 전체 페이지**(색인이 오래됐거나 관리번호로 조회할 때)
- ③ **내장 샘플** 이고, 응답의 `data_state`(live/sample)와 `data_source`(index/api/sample)가
- 근거를 밝힙니다. 색인으로 찾은 브랜드에는 **가맹점 수·직영점 수**가 바로 붙고(예: `BBQ` 가맹점
- 2,316개 · 직영 71개, 2026-11-21 조회), 인증키가 있으면 승인된 가맹점 변경현황(15125491)으로
- **연간 폐점률**(예: 2025년 연초 2,249 → 연말 2,316, 6.6%)까지 붙습니다.
- 못 찾았을 때는 "그 브랜드가 없다"고 단정하지 않고, 색인 규모·기준연도와 함께 표기 차이·
- 직영 브랜드 가능성을 안내합니다.
- > **15125490 은 시·도 행과 '전체' 합계 행을 함께 줍니다.** 둘을 모두 더하면 가맹점 수가 두 배가
- > 되어(2026-11-21 이전 코드: `BBQ` 4,632개) 폐점률도 절반으로 깎였습니다. 지금은 '전체' 행이
- > 있으면 그 값만 쓰고, 색인을 만들 때도 같은 규칙으로 합칩니다.
- > **15125491 은 `jngBizCrtraYr`+`brandMnno` 를 반드시 요구**해(전체 목록 호출은 코드 11) 색인에
- > 넣지 않고 실시간 조회에서만 붙입니다. 그래서 인증키가 없으면 연초·변동·폐점률이 비고,
- > `field_status.null` 이 그 이유를 적습니다.
- > 가맹점 수는 기준연도 자료의 **회계연도**(예: 2026년 자료 → 2025년 말) 값이며, 응답의
- > `base_year`(기준연도)와 `closure_rate_year`(회계연도)를 구분해 적습니다.
- ## 3. 빠른 실행
- ```bash
- cd projects/franchise-kr
- PYTHONPATH=src python -m franchise_kr.server # http://localhost:8787
- PYTHONPATH=src python -m franchise_kr.cli check --brand 샘플치킨 --days 0 --payment hq_account
- PYTHONPATH=src python -m franchise_kr.cli law "제7조"
- PYTHONPATH=src python -m unittest discover -s src/tests -t src/tests # 413 tests(색인 포함)
- PYTHONPATH=src python -m tools.sync_brands_index # 브랜드 색인 갱신(키 필요)
- ```
- 의존성 설치 단계가 없습니다(표준 라이브러리만). Python 3.12 기준.
- ### 환경변수
- `.env.example` 참고. `DATA_GO_KR_SERVICE_KEY` 는 선택입니다. 로컬에서는 프로젝트 루트의
- `.env`(gitignore)를 서버·CLI 진입점이 읽고, 없으면 색인만으로 동작합니다(가맹점 수는 색인에,
- 연초·변동·폐점률은 생략).
- `FRNC_BRANDS_INDEX` 로 색인 파일 경로를 바꿀 수 있습니다.
- `LAW_GO_KR_OC` 는 `law-verification.json` 을 다시 만들 때만 씁니다(서버는 쓰지 않음).
- 운영용(모두 선택):
- | 변수 | 기본 | 역할 |
- |---|---|---|
- | `FRNC_RATE_LIMIT_PER_MINUTE` | 240 | 일반 요청 분당 허용(0이면 끔) |
- | `FRNC_RATE_WRITE_PER_MINUTE` | 30 | 문의 등 쓰기 분당 허용 |
- | `FRNC_RATE_WINDOW_SECONDS` | 60 | 제한 창 |
- | `FRNC_INQUIRY_WEBHOOK_URL` | (없음) | 문의 접수 시 POST 알림(Slack·Discord·자체 엔드포인트) |
- | `FRNC_INQUIRY_WEBHOOK_CONTACT` | 꺼짐 | `1` 이면 알림에 연락처도 포함(기본은 미포함) |
- | `FRNC_INQUIRY_MIRROR` | (없음) | 문의 JSONL 미러 파일 — 재시작 시 DB 로 복구 |
- | `FRNC_ADMIN_TOKEN` | (없음) | `GET /v1/inquiries` 토큰(없으면 그 경로는 404) |
- ### 검증 자료 재생성
- ```bash
- LAW_GO_KR_OC=<OC> PYTHONPATH=src python -m tools.verify_law_articles # → law-verification.json
- DATA_GO_KR_SERVICE_KEY=<키> PYTHONPATH=src python -m tools.verify_ftc_apis # → api-verification-YYYY-MM-DD.json
- ```
- ## 3-1. 질문형 가이드 17종 (`/guides/`) — AI 인용·검색 유입
- 사람들이 AI·검색에 던지는 질문 하나에 답 하나를 두고, 인용되는 형식으로 만든 페이지입니다.
- | # | 가이드 | 질문 | 근거 조문 |
- |---|---|---|---|
- | 1 | 가맹계약 14일 숙고기간 | 정보공개서를 받은 지 14일이 안 됐는데 계약해도 되나요? | 제7조·제11조·시행령 제6조 |
- | 2 | 예상매출액 산정서 서면 교부 | 예상매출액 산정서는 꼭 받아야 하나요? | 제9조·시행령 제9조·제8조 |
- | 3 | 정보공개서 허위·과장 금지 | "최저 수익 보장"이라고 하면 믿어도 되나요? | 제9조·시행령 제8조·제6조의2 |
- | 4 | 직영점 1년 이상 운영 의무 | 직영점을 1년 이상 운영해야 하나요? | 제6조의3·시행령 제5조의5·제5조 |
- | 5 | 가맹금 예치제 의무 | 가맹금을 본사 계좌로 바로 보내도 되나요? | 제6조의5·시행령 제5조의8~10·제15조의2 |
- | 6 | 인테리어·집기 구입강제 금지 | 지정 업체만 써야 하나요? | 제12조·시행령 별표 2·제11조·제12조의2 |
- | 7 | 과중 위약금·손해배상 | 중도해지 위약금이 크면 과중한가요? | 제12조·시행령 제12조의2·별표 2 |
- | 8 | 광고·판촉비 사전 동의 | 광고비를 걷는데 점주 동의가 필요하나요? | 제12조의6·시행령 제13조의5·제13조의6 |
- | 9 | 창업 지원금 확인 순서 | 창업비용을 낸 뒤 지원금은 어떻게 찾나요? | (법령 판단 없음 · GRNT 연결) |
- | 10 | 영업지역 보호·중복 출점 | 영업지역 안에 본사가 직영점을 내면? | 제12조의4·제11조·시행령 제13조의4 |
- | 11 | 폐점률·개점률 보는 법 | 정보공개서의 폐점률은 어떻게 읽나요? | 시행령 별표 1·제9조 |
- | 12 | 2개월 유예·서면 2회 해지 | 갑자기 해지하겠다고 하면? | 제14조·시행령 제15조 |
- | 13 | 계약갱신·10년 한도 | 계약이 끝나갈 때 갱신을 요구할 수 있나요? | 제13조·시행령 제14조 |
- | 14 | 가맹점주 단체의 협의 요청 | 단체를 만들어 조건을 협의할 수 있나요? | 제14조의2·제14조의3 |
- | 15 | 분쟁조정 신청과 시효 | 다툼이 생기면 어디에 신청하나요? | 제16조·제21조·제22조·제28조·제32조의3 |
- | 16 | 필수품목·차액가맹금 확인 | 필수품목 가격과 차액가맹금은 어떻게 확인하나요? | 제11조②12·시행령 별표 1 5.나·6.가·별표 2 2.나·3.가 |
- | 17 | 판매가격 구속(재판매가격 유지) | 본사가 권장소비자가격을 지키라고 하면 따라야 하나요? | 제12조①2·시행령 별표 2 2.가·별표 1 6.라.3 |
- - 페이지의 **모든 숫자(14일·7일·2개월·40%·50%·70%·180일·1.7배·3.3㎡ 등)는 그 가이드가 인용한
- 조문 안에 실제로 있는지 테스트가 확인**합니다(`src/tests/test_guides.py`).
- `40%` 는 조문의 `100분의 40` 표기와 대조합니다.
- - `/sitemap.xml`(19 URL) · `/llms.txt`(가이드 17종 요약) · 홈 푸터·홈 카드·`/v1/meta` 의 `guides`
- 메타가 모두 같은 목록에서 생성됩니다.
- - 단정 표현 금지: "위법입니다 / 문제없습니다 / 안전합니다 / 무조건" 같은 확정 어구 0건을
- `src/tests/test_no_definitive_claims.py` 가 검사하고, "확정 판정 아님" 문구가 남아 있는지도 봅니다.
- ### 색 대비·스크립트 검증
- - `src/tests/test_a11y_contrast.py` — 라이트/다크 토큰 24쌍의 WCAG 대비를 **계산**해 4.5:1 이상인지
- 확인합니다(현재 최저 4.73:1). 토큰만 있고 조합이 어긋나는 경우를 잡습니다.
- - `src/tests/test_js_sanity.py` — esprima 없이 문자열·주석·정규식 리터럴을 걷어낸 코드로 괄호 균형,
- 템플릿 문자열 금지, `function` 형식, id 참조 존재를 검사합니다.
- ## 3-2. 특약·계약서 문구 스캔 (`scan_contract_text`)
- 계약서·특약·본사 안내 문구를 텍스트로 받아, **가맹사업법·시행령 별표 2**의 불공정 유형과
- 대조해 확인이 필요한 문구만 짚습니다. 결정적 규칙 엔진(정규식 12개 유형)이라 같은 문구는
- 언제 넣어도 같은 결과가 나옵니다.
- | # | 유형 | 무엇을 찾나 | 근거 조문 |
- |---|---|---|---|
- | 1 | 구입강제·지정업체 강제 | 인테리어·설비·원부자재를 지정업체로만, 타사 제품 금지 | 제12조·시행령 제13조·별표 2 3.가 |
- | 2 | 과중 위약금·손해배상 예정 | 잔여기간 로열티 전액, 보증금 몰수, 2~3배 배상, 위약금 20% 이상 | 제12조①5·시행령 제12조의2·별표 2 4.가 |
- | 3 | 일방적 즉시 해지 | 최고·통지·유예기간 없이 즉시 해지 | 제14조·시행령 제15조 |
- | 4 | 영업지역 미보장·인근 출점 | 영업지역 보장 없음, 본사 판단으로 인근 출점 | 제12조의4·시행령 제13조의4·제11조 |
- | 5 | 숙고기간 포기·동시 입금 | 14일 숙고기간 포기, 당일 계약, 계약과 동시 입금 | 제7조③·시행령 제6조·제11조 |
- | 6 | 가맹금 본사 직접 수령 | 본사 계좌 입금, 예치·보험 미이용 | 제6조의5·제15조의2·시행령 제5조의8 |
- | 7 | 광고·판촉비 일방 부담 | 점주 부담 광고비, 사전 동의 없는 판촉비 | 제12조의6·시행령 제13조의5·제13조의6 |
- | 8 | 매출·수익 보장 | 월 순수익 보장, 적자 보전, 수익 확실 단정 | 제9조·시행령 제8조·제9조 |
- | 9 | 영업시간 구속·심야 강제 | 본사가 영업시간 결정, 단축 불허, 24시간 영업 | 제12조의3·시행령 제13조의3 |
- | 10 | 갱신 거절 제한·과도한 경업금지 | 갱신 거절, 종료 후 장기 경업금지, 10년 초과 | 제13조·시행령 제14조·제12조 |
- | 11 | 필수품목 과다·단가 미공개·차액가맹금 인상 | 필수품목 단가·산정기준 미기재, 일반 공산품까지 지정, 차액가맹금 일방 인상 | 제11조②12·시행령 별표 1 5.나·6.가·별표 2 2.나·3.가 |
- | 12 | 판매가격 구속·재판매가격 유지 | 본사가 정한 가격 유지, 할인·변경 금지, 권장가 준수 의무, 가격 위반 제재 | 제12조①2·시행령 별표 2 2.가·별표 1 6.라.3 |
- - 항목마다 **원문 인용(사용자가 넣은 글자 그대로)**, 위험 등급, 실조회 조문 발췌, 왜 위험한지,
- **본부에 요청할 수정 문구 예시**가 붙습니다.
- - **0건이어도 "안전/문제없음"을 쓰지 않습니다.** 응답에는 항상 고정 문장이 붙습니다:
- "제시된 패턴에서 잡히지 않았을 뿐, 다른 특약이나 정보공개서 불일치가 있을 수 있어 원문 전체와
- 가맹거래사 확인이 필요합니다."(`engine.SCAN_NOT_A_CLEARANCE_KO`)
- - 부정 문장은 세지 않습니다("위약금을 부과하지 않는다" → 신호 아님). 붙여쓰기·줄바꿈 차이는
- 공백을 지운 사본에서 대조해 흡수하고, 인용은 원문 위치로 되돌려 잘라 냅니다.
- - 웹 홈에는 **"특약·계약서 문구 1초 스캔"** 카드와 샘플 3종(구입강제·과중 위약금·즉시 해지)
- 버튼이 있습니다. 붙여넣은 문구는 저장하지 않고, 통계에도 넣지 않습니다.
- - `src/tests/test_scan.py` 가 규칙·인용·오탐 0건·0건 단정 금지·법 조문 키·조문 앵커 일치를 검사합니다.
- - 판매가격 구속 규칙은 시행령 별표 2 2.가 단서를 그대로 반영해 **권장**과 **사전협의** 문구는
- 신호로 세지 않습니다("권장소비자가격을 알려 주고 참고하게 한다", "가격을 바꿀 때 사전에 협의한다").
- 본부가 정한 가격 유지·할인 금지·권장가 준수 의무·가격 위반 제재만 짚습니다.
- - 필수품목 규칙은 **단가·산정기준 미기재**, **일반 공산품까지 지정**, **차액가맹금 일방 인상**만
- 짚습니다. 품목별 공급가격과 산정기준을 별지에 적고 변경 시 통지하는 정상 문구는 세지 않습니다
- (`NORMAL_CLAUSES` 로 고정).
- **한계**: 정규식 규칙은 표시된 패턴만 찾습니다. 문장의 맥락, 예외 조항, 별지 특약 전체의
- 해석은 하지 않으며, 위법 여부 판정·계약서 검토가 아닙니다.
- ## 4. API · MCP
- ### 툴 7종
- | 툴 | 하는 일 |
- |---|---|
- | `check_franchise_risk` | 조건 → 위험 신호·판정·질문·체크리스트·법 조문·GRNT 연결 |
- | `scan_contract_text` | 계약서·특약 문구 → 확인 필요 문구·원문 인용·근거 조문·수정 요청 문구 |
- | `lookup_brand_disclosure` | 브랜드 1건 요약 — 승인된 데이터셋이 주는 값만(브랜드 목록·가맹점 및 직영점·변경현황, `data_source` 로 근거 표시), 비어 있는 필드는 `field_status.null` 이 이유·신청 주소를 밝힘 |
- | `compare_franchise_terms` | 두 프랜차이즈 조건 비교(비용·절차·위험 신호) |
- | `list_risk_cases` | 함정 코퍼스 17건(위험도·분류·키워드 필터, 조문 대조 여부) |
- | `get_law_article` | 실조회한 가맹사업법·시행령 조문 원문 |
- | `get_service_meta` | 판정 등급·8축·법령·API 승인 상태·개인정보 설계 |
- ### REST
- ```bash
- curl -s http://localhost:8787/v1/tools/check_franchise_risk -H 'Content-Type: application/json' -d '{
- "brand_name": "샘플치킨", "industry": "치킨",
- "franchise_fee_krw": "1,100만원", "interior_krw": "5,500만원",
- "disclosure_days_before": 0, "payment_route": "hq_account",
- "revenue_claim_ko": "월 5천 보장", "revenue_written": false
- }'
- ```
- 응답에는 `verdict`, `risk_score`, `risk_points`(이유·되돌리기 어려운 점·할 일·물어볼 것·조문),
- `unknown_points`, `questions_ko`, `checklist_ko`, `money`, `law_basis`, `next_steps`,
- `startup_support`(GRNT 링크), `disclaimer_ko` 가 들어 있습니다.
- - `GET /healthz` · `/v1/meta` · `/v1/stats` · `/v1/mcp` · `/llms.txt` · `/sitemap.xml`
- - `POST /v1/tools/{tool}` · `POST /v1/inquiry`(문의) · `GET /v1/inquiries`(문의 조회, `X-Admin-Token` 필요)
- - 문의(`/v1/inquiry`)는 `contact`·`topic`·`message` 외에 **선택** 필드 `cohort`(별칭 `source`)를 받습니다 —
- 무료 베타·소개 글 유입 구분 태그(`beta_pilot`, `citechart` 등 영문 소문자·숫자와 `._:-`, 40자).
- 없으면 종전과 동일하게 동작하고, 있으면 `inquiries.cohort`ㆍ미러 JSONLㆍ웹훅ㆍ`/v1/inquiries`
- 요약(`by_cohort`)에 남습니다. 공개 `/v1/stats`·`/healthz` 에는 넣지 않습니다.
- 웹 문의 폼도 `/?cohort=beta_pilot` 처럼 태그가 붙은 링크로 들어오면 그 값을 함께 보냅니다
- (형식이 틀리면 보내지 않음).
- - 요청 제한: 넘으면 `429` + `Retry-After`(기본 분당 240회, 문의 분당 30회, `/healthz` 예외).
- IP 는 저장하지 않고 프로세스 난수로 해시한 메모리 키만 씁니다(재배포 시 초기화).
- - 웹 UI `GET /` — **브랜드 정보공개서 조회 카드**(`/#brand-card`, 브랜드명 부분 일치·관리번호),
- 원클릭 프리셋 4개(당일 계약·본사 송금 / 구두 매출 보장 / 인테리어 100% 강제 / 정상 조건),
- **특약·계약서 문구 1초 스캔 카드(샘플 3종)**, 결과 요약 복사, 비식별 공유 링크
- 복사(`/?brand=...#check` 프리필), 다크 모드, 모바일 반응형. 공유 링크에는 **브랜드명만** 담고
- 금액·조건·연락처는 담지 않습니다.
- - 없는 주소(비-`/v1/`)는 JSON 이 아니라 **사람용 404 안내 페이지**를 돌려줍니다(다음에 할 일 링크).
- - 질문형 가이드 `GET /guides/` · `GET /guides/{slug}` — 17종. 각 페이지는 한 줄 답, 법이 정한
- 기준, 계약 전 체크포인트, 흔한 오해, FAQ, 근거 조문 원문을 담고 `FAQPage`·`BreadcrumbList`·
- `WebPage` JSON-LD 를 포함합니다. `/guides` 는 `/guides/` 로 301.
- ### MCP
- - Streamable HTTP: `POST /mcp` (JSON-RPC 2.0, `application/json` 한 덩어리, SSE 없음)
- - stdio: `PYTHONPATH=src python -m franchise_kr.mcp_stdio`
- - 서버 카드: `GET /.well-known/mcp/server-card.json`
- - 인증 없음. `initialize` → `tools/list` → `tools/call`.
- ## 5. 개인정보·익명성
- - 판정 폼은 **이름·연락처·주민등록번호를 받지 않습니다.** 브랜드명·금액·조건은 요청 처리
- 중에만 쓰고 저장하지 않습니다.
- - 익명 카운터는 `날짜 · 경로 · 툴 · 판정 등급 · 샘플/0건/오류 횟수`만 남깁니다.
- 금액·조건 입력은 통계에도 저장하지 않습니다.
- - 예외 하나: **결과가 0건으로 끝난 브랜드 조회어만** 개인식별 요소(전화번호·주민등록번호·
- 이메일·URL·@핸들·2자리 이상 숫자)를 지운 뒤 최대 30자로 `/v1/stats` 의
- `zero_result_queries` 에 익명 카운트합니다(`usage.sanitize_query`). 0건은 "그 브랜드가
- 없다"도 "안전하다"도 아니며, 응답에는 고정 안내(`live_api.ZERO_RESULT_NOTICE_KO`)가 붙습니다.
- - 유일한 예외는 하단 문의 카드에 이용자가 직접 적은 연락처로, 회신 목적으로만 별도 표에
- 두고 응답에 되비추지 않으며 180일 뒤 지웁니다.
- - 무료 플랜은 영구 디스크가 없어 재시작 때 DB 가 초기화됩니다. 그래서 문의는 **접수 성공 직후**
- ① 웹훅(`FRNC_INQUIRY_WEBHOOK_URL`) ② JSONL 미러(`FRNC_INQUIRY_MIRROR`)를 남길 수 있고,
- 미러가 있으면 서버가 다시 뜰 때 `notify.restore()` 가 SQLite 로 되돌려 놓습니다.
- 기본 웹훅 본문에는 **연락처를 넣지 않고**(접수번호·유형·미리보기만) 채널에 개인정보가
- 남지 않게 하며, 관리자 조회(`GET /v1/inquiries`, 토큰)에서만 연락처를 돌려줍니다.
- - 요청 제한은 IP 를 저장하지 않습니다 — 프로세스가 시작할 때 만든 난수로 해시한 메모리 키만
- 쓰고 창이 지나면 지웁니다. 막힌 요청은 `/v1/stats` 의 `flags.rate_limited` 횟수로만 남습니다.
- - 저장소에는 실명·연락처·직업·계정 같은 개인정보를 두지 않습니다. `src/tests/test_privacy.py`
- 가 휴대전화·주민등록번호·이메일·카드번호·인증키 패턴을 검사하고, 로컬 전용
- `.private-terms`(gitignore·dockerignore 대상)가 있으면 그 문자열까지 확인합니다.
- ## 6. 배포
- - `Dockerfile`: `python:3.12-slim`, 비루트 사용자, `HEALTHCHECK /healthz`, 표준 라이브러리만
- - `render.yaml`: Render Blueprint(도커, free, singapore, `/healthz`) — 서비스 이름 `frnc`,
- 공개 주소 `https://frnc.onrender.com`. `DATA_GO_KR_SERVICE_KEY` 는 `sync: false`(대시보드에서 입력).
- 문의를 오래 보관하려면 유료 영구 디스크를 붙이고 `FRNC_INQUIRY_MIRROR`(예: `/var/data/inquiries.jsonl`)와
- `FRNC_ADMIN_TOKEN` 을 함께 설정하세요(free 플랜은 재시작 때 DB 가 바뀝니다).
- - `server.json`: MCP 레지스트리 매니페스트(`io.github.CLNS-KR/frnc`, v0.1.9, 설명 100자 이하)
- - 고지 페이지(v0.1.9): `GET /privacy` · `GET /terms` · `GET /about` — 문의 연락처 180일 보관·삭제 요청 경로, 확정 판정 아님·전문가 자문 대체 아님, 공정위 정보공개서 출처와 3종 생태계 안내. 홈·가이드 푸터와 `sitemap.xml` 에서 이어집니다
- - 공유 카드(v0.1.9): `/static/og.png`(1200×630) + 홈·가이드·고지 페이지의 `canonical`·`og:image` 메타(파일이 없어도 표준 라이브러리 생성 PNG 로 200 유지)
- - 사용 통계 구분(v0.1.9): `/v1/stats` 의 `traffic.by_channel`·`traffic.by_client` — UA 원문·IP·쿠키는 저장하지 않습니다
- - `.github/workflows/publish-mcp-registry.yml`: `v*` 태그 push(또는 수동 실행) 때
- `mcp-publisher` 로 공식 레지스트리에 게시합니다. GitHub Actions OIDC 로 인증해
- 조직 네임스페이스를 쓰고, 게시 전에 단위 테스트·`server.json` 버전 대조·원격 `/mcp`
- 생존 확인을 거칩니다(원격 서버가 내려가 있으면 게시도 실패 — 의도된 동작).
- ## 7. 한계 (정직하게)
- 1. **확정 판정이 아니다.** 입력한 조건과 공개 조문의 대조일 뿐, 위법 여부·계약 효력을
- 판단하지 않습니다. 계약서 검토·법률 자문·신고 대행을 하지 않습니다.
- 2. 브랜드 조회는 승인된 데이터셋(18개 중 4개)으로 답합니다. 브랜드명·본부·업종·가맹사업
- 개시일은 색인(승인 15125467)에서, 가맹점 수·직영점 수는 승인된 15125490 에서(시·도 행과
- '전체' 행 중 '전체' 값 — 더하지 않습니다), 연초·신규·계약종료·계약해지·연간 폐점률은
- 승인된 15125491 에서 실시간으로 옵니다. **평균매출(15110241)·창업비용·법 위반 이력은
- 아직 미승인**이라 값이 `null` 이며, 응답의 `field_status.null` 이 항목별 사유·데이터셋 번호·
- 신청 주소를 밝힙니다(`null` 은 '0'도 '없음·문제없음'도 아닙니다). 정보공개서 등록번호·등록일은
- 가맹정보 데이터셋에 없어 항상 비어 있습니다.
- 서버에 인증키가 없으면 색인만으로 답하고(`data_state=live`, 가맹점 수는 색인 값), 비는 항목의
- 이유를 `field_status` 에 "인증키가 없어 실시간 재조회를 하지 않았습니다"로 적습니다.
- 응답 봉투가 문서와 다르면 `unexpected_shape` 로 남기고 **0건으로 단정하지 않습니다**.
- 3. 정보공개서 목록·목차·본문(15125569·15125570·15125571)은 data.go.kr 제공형태가 LINK라
- REST 로 부를 수 없습니다. 본문은 가맹사업정보제공시스템에서 열람해야 합니다.
- 4. 단위면적당 평균매출(15125494)은 오퍼레이션 이름을 확인하지 못해 `unverified` 로 남겼습니다.
- 5. 폐점률은 기준연도 **1년** 변동입니다(연초 = 자료가 없으면 연말 - 신규 + 종료 + 해지).
- '최근 3년' 통계가 아니며, 3년치를 모르는 값을 그렇게 부르지 않습니다 — 응답은
- `closure_rate_pct`·`closure_rate_year`·`closure_rate_basis_ko` 로 근거를 함께 줍니다.
- 색인의 브랜드 수는 연도별 목록을 합친 값이라 실제 브랜드 수와 다릅니다(중복 포함).
- 6. 문구 스캔은 정규식 규칙이 표시된 패턴만 찾습니다. 잡히지 않은 문구를 '적법'으로,
- 잡힌 문구를 '위법'으로 단정하지 않습니다. 문장 구조를 해석하는 모델이 아니라,
- 사람이 확인할 목록을 빠짐없이 같은 기준으로 만들어 주는 도구입니다.
- ## 8. 출처
- - 법령: 법제처 국가법령정보 공동활용 OPEN API (`law.go.kr/DRF`)
- - 가맹정보: 공정거래위원회 가맹정보 오픈API (`apis.data.go.kr/1130000`, data.go.kr)
- - 정보공개서 원문: 가맹사업정보제공시스템 (`franchise.ftc.go.kr`)
- - 창업 지원금: GRNT (`https://grnt-kr.onrender.com/`)
- - 같이 쓰는 도구: 수입·유통 규제 체크 CLNS (`https://clns-kr.onrender.com/`)
- MIT License.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.