ariadne/docs/development.md

개발

요구 도구

• Go 1.24 이상
• Flutter 3.41.5 (.fvmrc)
• Docker Compose

서버

환경 변수는 .env.example을 기준으로 한다.

변수	기본값	의미
ARIADNE_ENVIRONMENT	development	실행 환경 이름
ARIADNE_HTTP_ADDRESS	:8080	HTTP 수신 주소
ARIADNE_DATABASE_URL	없음	PostgreSQL 접속 주소
ARIADNE_DATABASE_IDENTITY_URL	없음	신원·조직 목록 조회 전용 PostgreSQL 접속 주소
ARIADNE_DATABASE_MIGRATION_URL	없음	마이그레이션 전용 PostgreSQL 접속 주소
ARIADNE_DATABASE_RUNTIME_ROLE	없음	테이블 접근 권한을 받을 실행 역할
ARIADNE_DATABASE_IDENTITY_ROLE	없음	신원 조회만 허용할 데이터베이스 역할
ARIADNE_MIGRATION_LOCK_TIMEOUT	30s	동시 마이그레이션 잠금 대기 한도
ARIADNE_IOP_ENDPOINT	없음	IOP 연결 주소
ARIADNE_SHUTDOWN_TIMEOUT	10s	정상 종료 대기 시간

데이터베이스 주소가 없으면 서버의 생존 상태 확인은 가능하지만 준비 상태 확인은 실패한다.

go run ./apps/migrate/cmd/ariadne-migrate
go run ./apps/server/cmd/ariadne

검사

make check

서버와 화면을 따로 검사할 수도 있다.

go test ./...
go vet ./...
cd apps/client && flutter test && flutter analyze

기본 make check는 Flutter 웹 배포 산출물 빌드까지 포함한다.

데이터베이스 변경

마이그레이션은 internal/platform/database/migrations에 순서가 보장되는 이름으로 추가한다. 마이그레이션 명령은 아직 적용되지 않은 상향 마이그레이션만 실행하고, 이미 적용된 파일의 체크섬이 바뀌면 실패한다.

마이그레이션·서버 실행·신원 조회 역할은 반드시 분리한다. 마이그레이션 역할은 NOSUPERUSER BYPASSRLS, 나머지 두 역할은 NOSUPERUSER NOBYPASSRLS여야 한다. 서버 역할은 테이블 소유자가 아니어야 하며 개발용 Compose도 같은 경계를 사용한다.

현재 스캐폴드는 최초 사용자·조직 생성 API를 제공하지 않는다. 개발 데이터가 필요하더라도 실행 또는 신원 역할의 권한을 넓히지 말고, 관리 경계가 구현되기 전에는 별도 개발용 초기 데이터 절차로만 넣는다.

모든 조직 소유 테이블은 다음 조건을 만족해야 한다.

• organization_id가 NOT NULL
• 조직 범위를 포함한 외래 키 사용
• 조직 범위를 선두로 둔 조회 색인 제공
• 조직 행 수준 보안 정책 적용
• internal/platform/database/access.go에 최소 권한 명시

조직 소유 테이블이 권한 목록에 없거나 행 수준 보안과 정책이 빠져 있으면 마이그레이션과 서버 시작이 실패한다.

실제 PostgreSQL을 사용하는 통합 검사는 Docker 사용이 가능한 환경에서 별도로 실행해야 한다. 조직 A/B 교차 접근 차단, 불변 이력 권한, 세 역할의 권한과 동시 마이그레이션 잠금을 필수 항목으로 둔다.