Atria는 개인 앱과 서비스가 함께 쓰는 백엔드입니다. 이 사이트는 관리자가 쓰는 패널이며 자바스크립트를 켜야 열립니다.
개발 AI와 자동화 도구는 아래 안내를 읽으세요. 같은 내용이 /llms.txt에 있습니다.
# Atria
> Atria는 개인 앱과 서비스가 함께 쓰는 백엔드입니다. 앱은 서버(BE)를 따로 만들지 않고 HTTP API만 불러서 업데이트 안내, 점검, 공지, 값(원격 설정), 초대코드 로그인, 사용 로그, 버그 신고, 파일 보관, JSON 문서 저장, 외부 API 중계, 폼 제출을 씁니다.
>
> For AI coding agents: start here when you are asked to add an Atria feature to an app. The full integration guide is linked below (written in Korean).
이 문서는 개발 AI(코딩 에이전트)가 읽는 시작 문서입니다. “Atria를 참고해서 ○○ 기능을 추가해줘” 같은 요청을 받았다면 아래 순서대로 진행하세요.
## 주소
- API 기본 주소: `https://api.atria.mksh.kr`. 앱이 보내는 모든 요청은 이 주소로 갑니다.
- 이 문서를 받은 사이트는 관리자가 로그인해서 쓰는 패널(관리 화면)입니다. API가 아니므로 패널 주소 뒤에 `/api/...`를 붙여 부르면 동작하지 않습니다. 패널은 사람만 쓸 수 있습니다.
## 문서
- [전체 연동 가이드](https://api.atria.mksh.kr/api/docs.md): Markdown. 요청과 응답 필드, 예시 코드, 오류 처리 규칙이 모두 있습니다. 구현하기 전에 꼭 읽으세요.
- [OpenAPI 3.1 명세](https://api.atria.mksh.kr/api/openapi.json): 기계 판독용 JSON.
- [연동 가이드 HTML 판](https://api.atria.mksh.kr/api/docs): 사람이 읽을 때 봅니다.
## 작업 순서
1. 아래 ‘기능 찾기’ 표에서 요청에 맞는 기능을 고릅니다.
2. 전체 연동 가이드를 위 링크 주소 그대로 받아서 표에 적힌 절과 3절(공통 규칙), 18절(오류 코드)을 읽습니다. 긴 문서이니 요약해 주는 도구 대신 `curl` 같은 방법으로 원문을 받아 해당 절을 직접 읽으세요. 이 문서는 길잡이일 뿐입니다. 요청 필드, 응답 형식, 오류 처리는 가이드를 따르고 추측하지 마세요.
3. 앱 저장소에서 기존 Atria 연동을 찾습니다(`atria_pk_`, `X-Atria-App-Key`, `/api/app/v1/` 검색). 있으면 그 앱 키, API 주소, 요청 함수, 토큰 저장 방식을 그대로 씁니다.
4. 앱 키가 저장소에도 요청에도 없으면 설정 한 곳(환경변수나 설정 파일, 예: `ATRIA_APP_KEY`)에서 읽게 만들고 값만 비워 둡니다. 멈춰서 묻지 말고 구현을 끝낸 뒤 사용자에게 채워 달라고 하세요. API 기본 주소는 위 값을 그대로 기본값으로 넣습니다.
5. 요청받은 기능만 붙입니다. 가이드의 예시 코드를 앱의 언어와 구조에 맞게 옮기세요.
6. 앱 키가 있으면 실제로 한 번 호출해 확인합니다. 호출은 실제 데이터로 남으니(버그 신고, 사용 로그, 문서) 시험용임을 알 수 있는 내용으로 보내세요.
7. 마지막에 ‘패널에서 할 일’을 사용자에게 알려 줍니다(아래 참고).
## 기능 찾기
| 이런 요청이면 | 기능 (패널 메뉴) | API | 가이드 절 | 패널에서 준비할 것 |
| --- | --- | --- | --- | --- |
| 업데이트 안내, 강제 업데이트, 점검 화면, 공지 | 버전·공지 | `POST https://api.atria.mksh.kr/api/app/v1/start` | 4 | ‘버전·공지’에서 최신·최소 버전, 점검, 공지 설정 |
| 원격 설정, 기능 켜기·끄기(플래그), 문구 바꾸기 | 값 | `POST https://api.atria.mksh.kr/api/app/v1/start` 응답의 `values` | 4, 6 | ‘값’에서 값 만들기 |
| 사용자 구분, 로그인, 초대받은 사람만 쓰기 | 초대코드 | `POST https://api.atria.mksh.kr/api/app/v1/pass`, `POST https://api.atria.mksh.kr/api/app/v1/logout` | 5 | ‘초대코드’에서 사람마다 코드 발급 |
| 이벤트 기록, 사용 분석 | 사용 로그 | `POST https://api.atria.mksh.kr/api/app/v1/events` | 7 | 없음 |
| 버그 신고, 문제 신고, 피드백 보내기 | 버그 신고 | `POST https://api.atria.mksh.kr/api/app/v1/bug-reports` | 8 | 없음 |
| 파일 올리기, 이미지 저장, 내려받기 링크 | 드라이브 | `https://api.atria.mksh.kr/api/app/v1/drive/files`, `GET https://api.atria.mksh.kr/api/files/{token}` | 9, 12 | ‘드라이브’에서 접근 방식 고르기 |
| 데이터 저장과 조회, 서버 없이 목록·기록 만들기 | 임시 DB | `https://api.atria.mksh.kr/api/app/v1/db/{collection}` | 10 | ‘임시 DB’에서 컬렉션 만들기 (앱은 컬렉션을 만들 수 없음) |
| OpenAI, Anthropic, Gemini, 날씨처럼 키가 필요한 외부 API 부르기 | 중계 | `https://api.atria.mksh.kr/api/relay/{slug}/{path}` | 11 | ‘값’에 키를 서버 전용 값으로 저장하고 ‘중계’에서 중계를 만든 뒤 중계 주소 복사. 웹 앱이면 중계의 ‘브라우저에서 호출 (CORS)’에 앱 주소 등록 |
| 사전 신청, 대기자 명단, 문의 받기 | 폼 | `POST https://api.atria.mksh.kr/api/v1/forms/{publicId}/submissions` | 13 | ‘폼’에서 폼을 만들고 공개 폼 ID 복사 |
| 결제 성공·실패 흐름 시험 | 목업 결제 | `POST https://api.atria.mksh.kr/api/app/v1/mock-payments/resolve` (서비스 BE에서는 `POST https://api.atria.mksh.kr/api/v1/mock-payments/resolve`) | 15 | ‘목업 결제’에서 목업 키 만들기 |
| 여러 명이 같이 쓰는 가입 코드 확인 (서비스 BE에서만) | 초대코드의 공용 코드 | `POST https://api.atria.mksh.kr/api/v1/invites/verify`, `redeem`, `release` | 14 | 공용 코드 발급, 프로젝트 설정에서 Integration API 키 만들기 |
| 사용자 삭제 같은 관리 작업을 패널에서 실행 (서비스 BE에서만) | Admin API | 서비스가 `/admin/*`를 직접 구현 | 17 | ‘Admin API’에 서비스 Base URL과 키 등록 |
‘Firebase 사용자’와 ‘배포’는 패널에서만 쓰는 기능이라 앱 코드에 붙일 것이 없습니다.
## 꼭 지킬 규칙
- 요청은 API 기본 주소(`https://api.atria.mksh.kr`)로만 보냅니다. 패널 주소는 API가 아닙니다.
- 앱 API(`/api/app/v1/*`)의 모든 요청에 `X-Atria-App-Key: <앱 키>` 헤더를 붙입니다. 앱 키(`atria_pk_…`)는 공개 값이라 앱 코드에 넣어도 됩니다. 환경(운영, 개발)마다 앱 키가 다릅니다.
- 앱 키 말고는 어떤 비밀값도 앱, 브라우저 코드, 저장소에 넣지 않습니다. Integration API 키(`atria_ik_…`)와 서비스 Admin API 키는 서비스 BE의 환경변수에만 두고, 외부 API 키는 패널의 ‘값’에 서버 전용 값으로 넣어 중계로 부릅니다.
- 오류는 메시지가 아니라 HTTP 상태 코드와 `error.code`로 구분합니다.
- `409 FEATURE_DISABLED`는 프로젝트에서 그 기능이 꺼져 있다는 뜻입니다. 코드를 고치지 말고 사용자에게 패널의 ‘기능 추가’에서 켜 달라고 하세요.
- `401 APP_KEY_INVALID`는 앱 키가 틀렸다는 뜻입니다. 사용자에게 프로젝트 설정 → 환경에서 앱 키를 다시 복사해 달라고 하세요.
- Atria가 응답하지 않아도 앱은 켜지고 동작해야 합니다. 앱 시작은 마지막으로 받은 응답을 쓰고, 사용 로그는 실패해도 화면을 막지 않습니다.
- 드라이브, 임시 DB, 중계는 패널에서 고른 접근 방식에 따라 앱 로그인 토큰이 필요합니다. 필요하면 초대코드 로그인(5절)을 함께 붙이고, `401 APP_TOKEN_REQUIRED`를 받으면 초대코드 입력 화면을 보여 줍니다.
## 패널에서 할 일
AI는 패널에 로그인할 수 없습니다. 작업을 마치면 아래에서 해당하는 것만 골라 사용자에게 알려 주세요.
1. 앱 키: 패널의 프로젝트 설정 → 환경에서 복사해 설정 자리에 넣기. 어느 파일의 어느 값인지 함께 알려 줍니다.
2. 기능 켜기: 패널의 ‘기능 추가’에서 이번에 쓴 기능 켜기.
3. 미리 만들 것: 표의 ‘패널에서 준비할 것’. 컬렉션 이름이나 접근 방식처럼 코드와 맞춰야 하는 값도 함께 알려 줍니다.
4. 패널에서 복사해 올 값: 중계 주소, 공개 폼 ID, 목업 키처럼 코드에 넣어야 하는 값과 넣을 자리.
패널의 각 기능 화면에는 그 프로젝트의 앱 키가 채워진 예시 코드와 ‘개발 AI에게 맡기기’ 문장이 있습니다. 사용자가 그 문장을 붙여 넣었다면 거기 적힌 앱 키와 주소를 쓰세요.