Frame

한 줄 소개: 한국 회계기준(KSME · K-GAAP)을 따르는 복식부기 회계 백엔드. 법인마다 장부가 물리적으로 분리되고, 모든 쓰기는 되돌릴 수 없는 감사 로그로 남는다. 사람은 웹 화면으로, AI 에이전트는 MCP 75개 도구로 같은 장부를 다룬다.

주소

세 주소 모두 인증이 필요하다 — 로그인하지 않고 열면 401 이 돌아온다. 호스트 루트에는 아무것도 없으니 반드시 /frame/ 까지 붙여서 연다 (루트만 열면 404).

무엇을 하는가

• 복식부기 장부 — 차변·대변이 맞지 않는 분개는 애초에 기재되지 않는다. 분개 등록은 다층 검증을 통과해야 커밋된다.
• 법인별 격리 — 법인·펀드마다 별도 스키마. 한 법인의 조회가 다른 법인의 데이터에 닿지 않는다. 법인(corporate)과 펀드(개인투자조합·벤처투자조합)를 같은 평면에서 다룬다.
• append-only 원장 — 원천 거래(입출금)와 분개 라인은 수정·삭제 권한 자체가 없다. 정정은 역분개로만 한다. 모든 쓰기는 감사 로그에 1행씩 남는다.
• 원천 데이터 자동 적재 — 은행·카드·홈택스 등에서 받은 파일을 올리면 포맷을 자동 인식해 원천 거래로 적재한다. 한 번 인식한 포맷은 캐시되어 다음부터 즉시 처리된다.
• 재무제표 4종 — 재무상태표 · 손익계산서 · 현금흐름표(간접법) · 자본변동표. 시산표는 임의 시점으로 조회할 수 있다.
• 증빙 보관 — 모든 증빙은 내용 해시로 주소화해 보관하고, 분개에서 증빙까지 링크가 끊기지 않는지 정기적으로 검사한다.
• 결산 — 회계기간을 열고(open) → 가마감(soft close) → 확정(hard close) 으로 전이시킨다. 확정된 기간에는 기재가 막힌다. 전기 마감 잔액을 당기 기초로 이월한다.

쓰는 방법

인증

Microsoft 계정으로 로그인한다. MCP 클라이언트는 커넥터 등록 시 표준 OAuth(PKCE) 흐름을 타고, 브라우저는 같은 계정으로 SSO 한다. 인증되지 않은 MCP 요청에는 401 과 함께 인가 서버 위치를 알려주는 표준 메타데이터가 돌아가므로, 클라이언트가 흐름을 자동으로 이어간다.

권한은 법인 × 스코프로 부여된다.

앞의 셋은 위가 아래를 겸한다(close 를 가지면 read·write 도 된다). reopen 과 admin 은 그 사다리 밖이라 토큰에 그 이름이 그대로 있어야 하고, close 나 admin 이 reopen 을 대신 서지 못한다. 그래서 write 만 든 호출자가 allow_soft_closed=True 를 넘기면 기재가 아니라 SCOPE_INSUFFICIENT 를 받는다 — 그 인자는 호출자가 채우는 불리언이라, 인가가 평범한 write 뿐이면 write 스코프 하나로 소프트클로즈된 기간이 열린다.

환경 변수

frame 스택이 읽는 값 중 배치마다 손댈 수 있는 것은 아래 둘이다 — 하나는 앱(blue/green)이, 하나는 앞단 프록시가 읽는다. 비밀이 아니라 망 구성 정보라 vault 가 아니라 컨테이너 환경에 평문으로 둔다.

두 값이 말하는 것은 같은 체인의 앞뒤 홉이다. 프록시가 믿는 대역이 상류 홉을 덮지 못하면 프록시가 상류의 X-Forwarded-Proto 를 스푸핑으로 보고 버린 뒤 자기 평문 리스너의 스킴으로 덮어쓰고, 앱이 믿는 집합이 프록시 홉을 덮지 못하면 앱이 프록시가 붙인 그 헤더를 아예 보지 않는다 — 어느 한쪽만 자기 앞 홉을 놓쳐도 리다이렉트가 평문으로 나가고 Secure 쿠키가 붙지 않아 로그인이 이뤄지지 않는다. 실제로 났던 회귀가 그 두 모양이다: 프록시 설정에 신뢰 선언이 아예 없었고, 앱은 웹 서버 기본값이 loopback 하나뿐이라 컨테이너 네트워크로 들어온 프록시를 신뢰하지 못했다. 지금은 양쪽 기본값이 그 홉을 덮으므로 두 변수를 비워 둔 배치에서도 서고, 변수는 기본값을 통째로 대체한다 — 배치마다 믿어야 할 프록시가 다르기 때문이며, 셀프호스트 compose 는 그것으로 신뢰를 홉 하나로 좁힌다. 닫히지 않는 것도 적어 둔다: 프록시가 게시한 포트로 들어오는 요청의 소스 주소는 언제나 그 홉의 게이트웨이라 프록시는 터널과 호스트-로컬 피어를 구별하지 못하고 그 헤더를 그대로 넘긴다 — LAN·tailnet 피어는 프록시와 앱의 호스트 포트를 loopback 에만 묶어 닫고, 이 두 값이 닫는 것은 앱 직행 위조이며, 호스트-로컬까지 닫으려면 터널이 frame_edge 에 직접 붙어 그 주소 하나만 신뢰해야 한다(전용 인입 홉 = B-frame-edge-dedicated-ingress-hop).

외부 요청은 터널 → 프록시 → frame 순으로 오고 마지막 홉이 컨테이너 네트워크라, frame 이 보는 피어는 loopback 이 아니라 프록시 컨테이너의 주소다. 그 주소가 이 집합에 없으면 forwarded 헤더가 버려져 리다이렉트의 Location 이 https 에서 http 로 강등되고(트레일링 슬래시 리다이렉트에서 실제로 났던 증상), 로그인 감사 줄에 실제 클라이언트 IP 대신 프록시 주소가 남는다.

반대로 아무 피어나 믿게 두면 두 값이 요청자 선택값이 된다 — 감사 로그의 IP 도, 모든 리다이렉트의 스킴도. 그래서 신뢰를 주소가 아니라 소속으로 정의한다. frame_edge 는 리버스 프록시와 MCP blue/green 만 올라가는 전용 네트워크이고 서브넷이 compose 에 못박혀 있어 셀프호스트 배치가 두 변수에 주는 값이 그 네트워크를 글자 그대로 가리킨다(셋이 어긋나면 테스트가 잡는다). 프록시는 이 네트워크에만 붙어 있으므로 신뢰 집합에 드는 홉은 그것 하나뿐이다. frame 워커와 blueprint 는 종전 기본 네트워크로 같은 이름의 MCP 에 계속 닿지만, 그 홉의 주소는 이 서브넷 밖이라 그들이 보낸 forwarded 헤더는 무시된다 — 브라우저가 아니라 Bearer 토큰 API 클라이언트라 잃는 것이 없고, 대신 감사 IP 와 리다이렉트 스킴을 그들이 정할 수 없게 된다.

/health 응답에는 forwarded_proto 필드가 있다 — 신뢰하는 프록시가 보낸 X-Forwarded-Proto 를 앱이 실제로 반영했는지 배포 검증에서 확인할 수 있도록, 그 요청에 대해 해석된 스킴(https 또는 http)을 그대로 보고한다. 운영자 CLI 의 frame 스왑은 컷오버 뒤 프록시를 거쳐 이 값이 https 인지 확인한다.

AXE 클라우드 배치는 compose 를 운영자 CLI 가 생성해 frame_edge 도 이 두 변수도 없다 — 거기서는 코드·파일 기본값(loopback + RFC1918)이 그대로 서서 프록시가 계속 신뢰받는다. 기본값을 홉 서브넷으로 좁히지 않는 이유가 그것이다: 기본값이 착지할 수 있는 위상보다 좁으면 그런 배치가 조용히 자기 프록시를 불신하게 되고, 좁히기는 좁은 위상을 실제로 가진 compose 가 준다.

MCP 도구 75개

조회 — 잔액·재무제표

조회 — 분개·거래·증빙

조회 — 결의서·고정자산·급여

기재 — 분개

기재 — 적재·증빙

기재 — 고정자산·급여·정기분개

기재 — 거래처·계좌

결산

폐지 계정 잔액을 두고 마감과 이월의 답은 갈린다 — 마감 분개는 그 계정을 라인 단위로 열고, 이월은 통째로 막는다. 마감 분개는 폐지(기재불가) 계정에도 전기한다 — 마감 라인은 폐지 손익계정의 잔액을 0 으로 만들 뿐이라 재분류할 것이 없다. 이월은 반대다: 잔액이 남은 폐지 재무상태표 계정이 있으면 계정코드·계정명·잔액을 열거하며 거부하고 아무것도 전기하지 않는다 — 살아있는 계정으로 옮기는 재분류 분개를 전기한 뒤 다시 이월한다. closing_preview 는 폐지 상태의 손익계정을 retired_closing_accounts 로 함께 돌려주고, closing_commit 은 그 가운데 잔액을 정확히 0 으로 닫는 손익 라인에만 폐지 예외를 준다 — 이익잉여금 같은 도착지 계정이 폐지돼 있으면 ACCOUNT_NOT_POSTABLE 로 계정코드를 지목하며 거부하고 아무것도 전기하지 않는다(되살리거나 재분류한 뒤 다시 마감한다). 이월 미리보기(dry-run)는 폐지 잔액을 거부하는 대신 blocked 와 계정 목록으로 보고하고, 실제 전기에서만 거부한다. 미리보기가 실을 수 있는 막힘 코드는 넷이다 — ACCOUNT_NOT_POSTABLE(폐지된 계정이 아직 잔액을 들고 있다), POLICY_NOT_FOUND(새 기간 시작일을 덮는 회계정책 era 가 없어 이월 분개가 설 자리 자체가 없다), ACCOUNT_NOT_IN_DESTINATION_POLICY(잔액이 남은 계정코드가 도착 era 의 계정표에 없다 — 뒤에 오는 다른 era 의 정의를 빌려 세우지 않는다), ACCOUNT_TYPE_CHANGED_ACROSS_ERAS(한 계정코드의 부류가 잔액을 만든 era 와 도착 era 사이에서 갈렸다 — 어느 쪽 정의로 분류하든 답이 임의라 막는다). 넷 다 force_post 로 부르면 같은 이름의 에러로 거부되고 아무것도 전기하지 않으므로, 미리보기가 보고한 이유와 전기가 막히는 이유가 한 이름이다. 부류가 갈린 코드는 기여한 잔액들이 서로 상쇄돼 합이 0 이어도 판정한다 — 합으로 먼저 걸러 버리면 옛 era 의 미마감 손익이 도착 era 의 반대부호 잔액 뒤에 숨어 조용히 지나간다.

전기는 법인 단위로 직렬화된다 (아래 셋, frame 다음 ship · 2026-09). 원장에 전표를 세우는 트랜잭션은 — MCP 쓰기 경로만이 아니라 고정자산·세금계산서·펀드·스냅샷·적재 분류처럼 원장에 직접 쓰는 경로까지 — 전부 그 법인의 전기 잠금을 첫 문장으로 잡고 커밋까지 쥔다. 그래서 원장을 다시 읽어 내린 판정이 판정과 기재 사이에 무효가 되지 않는다. 마감 확정이 그 잠금 안으로 들어온 것이 이 축의 본론이다: closing_commit 은 잠금을 잡은 뒤 같은 트랜잭션 안에서 기간을 확인하고, 마감 라인을 다시 계산하고, 순이익을 대조하고, 전기하고, 기간을 소프트클로즈한다. 재계산이 트랜잭션 밖이던 동안에는 그 사이 커밋된 손익 전표 하나가 낡은 라인으로 마감되고 그 잔액이 마감되지 않은 채 닫힌 기간에 남았다 — 되돌리려면 전기된 마감을 역분개하고 기간을 다시 열어야 한다. 미리보기 뒤에 손익 전표가 커밋됐으면 마감은 조용히 새 잔액까지 닫지 않고 순이익 불일치로 거부한다. 전기되는 것은 호출자가 되돌려준 preview_spec 이 아니라 서버가 잠금 안에서 다시 계산한 그 분개이고, 넘어온 preview_spec 의 라인이 그것과 다르면 MATERIALITY_VIOLATION 으로 거부한다 — 미리보기는 제안이고 잠금 안 재계산이 정본이라, 한 분개를 승인했는데 성공 코드와 함께 다른 분개가 전기되는 쪽이 거부보다 나쁘다. 비교는 금액을 정규화하고 라인을 정렬해서 보므로, 미리보기를 JSON 으로 왕복시키거나 순서를 바꿔 넘겨도 걸리지 않는다.

마감된 기간의 판정은 잠금 안에서 한 번, 원장 옆에서 또 한 번. 사전 게이트는 잠금을 잡기 전에 나온 통과권이라, 그것을 쥐고 잠금 앞에 선 평범한 전표는 앞선 마감이 그 사이 기간을 닫고 커밋해도 자기 통과권만 보고 기재한다. 그래서 잠금 안 기간 재확인을 posted 로 서는 모든 전표로 넓혔다 — 예전에는 마감 전표에만, 그것도 호출자가 채워 넣는 문자열을 기준으로 걸려 있었다. 그리고 같은 판정을 DB 트리거가 원장 옆에서 한 번 더 한다: journal 에 posted 행이 들어올 때 entry_date 를 덮는 기간이 hard_closed 면 언제나, soft_closed 면 트랜잭션 로컬 설정 frame.allow_soft_closed 가 켜져 있지 않으면 거부다. 게이트를 호출 지점마다 복제하면 새 경로가 하나 생길 때 조용히 빠지므로(실제로 그렇게 빠져 있었다) 판정을 원장 옆에 못박았다 — 파이썬 층을 지나지 않는 직접 기재도, 다른 언어로 쓰인 자동분개도 같은 답을 받는다. 그 설정은 post_journal·reverse_journal 이 받는 명시적 인자 allow_soft_closed 가 켠다 — 이미 소프트클로즈된 기간에 전표를 세워야 하는 두 쓰기 도구다. 마감 자체는 그 인자를 쓰지 않는다: closing_commit 은 아직 열린 기간에 전기하고, 소프트클로즈는 같은 트랜잭션에서 그 뒤에 한다. 설정은 트랜잭션 로컬이라 커밋·롤백에서 저절로 풀린다. entry_date 를 덮는 기간이 아예 없으면 통과시킨다 — 첫 회계기간 이전의 과거 이관이 그 자리다.

닫힌 기간에서는 역분개 계보도 같은 문을 지난다. 수동으로 만든 반대 분개를 원본과 사후 연결하는 relink_reversal 과 링크만 채우는 백필은 원본의 상태와 역분개 링크를 고치므로, 원본의 기간이 닫혀 있으면 거부된다 — 두 함수 다 allow_soft_closed 를 켜지 않으므로 소프트클로즈도 예외가 아니고, 소프트클로즈든 하드클로즈든 close_period 재개방 전이(close 스코프)로 기간을 먼저 열어야 한다. 숫자는 한 푼도 움직이지 않지만 list_journals(status='reversed') 와 총계정원장의 역분개 숨김, 역분개 쌍 무결성 검사가 정확히 그 두 열을 읽는다 — 닫힌 해의 그림이 재개방 흔적 없이 바뀌는 것을 막는 것이 이 판정이다. 링크만 채우는 백필은 예전에 이 판정에서 면제돼 닫힌 해에도 돌았고, 그 면제는 날 SQL 이 하드클로즈된 해의 계보를 아무 잠금 없이 옮기는 길이기도 해서 함께 없어졌다.

이월의 폐지 판정은 도착 기간의 정책 era 에서 읽는다. 한 계정코드가 여러 회계정책 era 에 걸치면 era 마다 계정 행이 따로 있고 계정 수정은 한 era 만 바꾼다. 잔액을 era 행 단위로 묶던 동안에는 두 방향으로 어긋났다 — 옛 era 는 살아있고 도착 era 가 폐지면 게이트가 아무것도 못 본 채 이월이 전기에서 깨졌고, 반대면 이미 지나간 era 의 폐지 표시가 멀쩡한 이월을 막아 지나간 era 의 계정을 되살려야 풀렸다. 이제 잔액은 계정코드로 합치고 폐지 여부·계정명·유형은 새 기간 시작일을 지배하는 era — 이월 분개가 실제로 계정을 찾을 그 행 — 에서 읽는다(지배 era 판정은 전기와 같은 규칙이다). 도착 era 에 그 코드가 아예 없으면 전기 불가로 보고, 도중에 깨지느니 무엇을 재분류해야 하는지 알려 주며 막는다.

관리

공개 API — 스키마 목록

Frame 이 생산하는 사실(fact)의 타입 규격을 그대로 노출한다. 다른 서비스나 에이전트가 이 규격을 가져다 캐시·검증에 쓴다.

curl -H "Authorization: Bearer $TOKEN" \
  https://frame.axelabs.ai/frame/schemas

응답 봉투는 안정 형식이다.

{
  "version": "1.0",
  "service": "frame",
  "schemas": {
    "[email protected]": {
      "description": "단일 계정의 시점 잔액 (차변/대변 합계 + 순 잔액).",
      "produced_by": ["query_balance"],
      "key_fields": ["entity_id", "account_code", "as_of_date", "debit", "credit", "balance", "policy_id"]
    }
  }
}

현재 13종을 노출한다 — 잔액 · 시산표 · 분개 · 분개목록 · 원천거래 · 미결 · 결의서 · 고정자산 장부가액 · 손익계산서 · 재무상태표 · 현금흐름표 · 자본변동표 · 총계정원장.

• 인증 필요 — MCP 클라이언트와 동일한 토큰을 그대로 쓴다.
• 버전 — 스키마 ID 의 @1.0 접미사가 개별 스키마의 호환성을, 봉투의 version 이 응답 모양 자체의 변경을 나타낸다.

시작하기

1. 법인 등록 — 등록 시점에 KSME 표준 계정과목이 자동으로 복사된다. 별도 시딩 작업이 없다.
2. 원천 데이터 적재 — 은행·카드 거래내역 파일을 올린다. 포맷은 자동 인식된다. 처음 보는 포맷이면 몇 가지를 되묻고, 그 답을 캐시해 다음부터는 묻지 않는다.
3. 기초 잔액 등록 — 외부 회계법인 검수본 기준 시산표를 개시 분개로 기재한다.
4. 분개 — 자동 매칭이 붙는 건은 제안을 확인하고 커밋하고, 나머지는 직접 기재한다. 진척은 시산표로 매일 확인한다.
5. 마감 — 기간을 가마감 → 확정으로 전이시키고, 다음 기 기초로 이월한다.

관련 문서

• Blueprint — Frame 을 도구로 호출하는 워크스페이스
• UI (디자인 시스템)