# Ariadne 프로젝트 규칙

## 응답 언어

- 사용자 응답과 프로젝트 문서는 한국어를 기본으로 작성한다.
- 코드 식별자, 환경 변수, 계약 필드명은 기존 영문 표기를 유지한다.

## 프로젝트 개요

Ariadne는 여러 조직에서 발생하는 오류를 통합하고, 저장소와 읽기 전용 실행 환경을 분석해 수정·검증·병합 요청까지 이어 주는 플랫폼이다. 오류 이력, 조직과 권한, 연결 대상, 수정 작업 흐름, 승인, 보고, 감사 기록의 기준 시스템은 Ariadne다.

## 주요 구조

| 경로 | 역할 |
|------|------|
| `apps/client/` | Flutter 웹 사용자 화면 |
| `apps/server/cmd/ariadne/` | Go 서버 진입점 |
| `apps/migrate/cmd/ariadne-migrate/` | 전용 데이터베이스 마이그레이션 명령 |
| `internal/domain/` | 오류, 조직, 실패, 수정 작업의 핵심 모델과 규칙 |
| `internal/integration/` | IOP 등 외부 실행 계층과의 어댑터 경계 |
| `internal/platform/` | 설정, 로깅, 데이터베이스, HTTP 서버, 부트스트랩 |
| `contracts/` | 외부 오류 입력과 IOP 실행·실패 JSON 계약 |
| `deploy/` | 개발·배포 기반 구성 |

## 기술 스택

- 서버: Go 1.24, Uber Fx, Zap
- 사용자 화면: Flutter 3.41.5 / Dart 3.11, Material 3
- 데이터베이스: PostgreSQL, pgx v5, 강제 행 수준 보안
- 계약: 버전이 명시된 JSON Schema
- 개발 환경: Docker Compose, Make

## 프로젝트 특화 컨벤션

### 조직 및 권한 경계

- 모든 프로젝트, 저장소, 실행 환경, 오류, 수정 작업, 감사 기록은 조직 범위를 가진다.
- 요청 본문의 조직 식별자를 신뢰하지 않는다. 조직 범위는 인증된 주체에서 결정한다.
- 오류 입력의 조직과 프로젝트는 인증된 `ingestion_source`에서 함께 결정한다.
- 조직 소유 데이터 접근은 `database.WithinOrganization` 안에서 수행하고 원시 연결 풀을 외부에 노출하지 않는다.
- 조직 소유 테이블을 추가할 때는 `organization_id`, 조직 범위 외래 키와 색인, 강제 RLS 정책, `database.runtimeTableAccess`의 최소 권한을 함께 추가한다.

### 데이터베이스 역할

- 마이그레이션, 서버 실행, 신원 조회 역할을 분리한다.
- 실행 역할과 신원 조회 역할에 슈퍼사용자, RLS 우회, 테이블 소유권을 부여하지 않는다.
- 신원 조회 경로는 검증된 `issuer + subject`로 활성 조직 멤버십만 조회하며 업무 데이터 권한을 갖지 않는다.
- 감사 기록과 승인 기록은 불변 이력으로 취급하고 실행 역할에 수정·삭제 권한을 주지 않는다.

### 수정 작업과 IOP 경계

- 운영 환경 연결은 읽기 전용이며 별도 권한·승인 설계 없이 쓰기 기능을 추가하지 않는다.
- 분석은 저장소 읽기 전용으로 수행하고 자동 수정은 격리된 작업 가지에서 검증한 뒤 병합 요청을 만든다.
- 병합은 항상 사용자 승인 대상이며 IOP에 운영 환경 쓰기나 직접 병합 권한을 전달하지 않는다.
- 수정 전 보고 방식은 승인된 수정안 해시와 실행 요청의 `proposal_digest`가 일치해야 한다.
- IOP는 LLM과 CLI 실행 계층이다. Ariadne 도메인과 저장 형식을 IOP의 내부 전송·모델 형식에 종속시키지 않는다.
- 로컬 형제 저장소를 정식 빌드 의존성으로 사용하지 않는다.

### 코드와 검증

- Go 코드는 `apps/`, `internal/` 아래에 두고 외부 연동 계약은 `contracts/`에서 버전별로 관리한다.
- 기존 Go 패키지 경계와 Flutter의 `features/`, `shared/` 구성을 우선한다.
- 마이그레이션 파일은 순서가 보장되는 이름을 사용하며 적용된 파일의 체크섬을 변경하지 않는다.
- 전체 기본 검사는 `make check`다.
- PostgreSQL 권한·RLS 통합 검사는 Docker 사용 가능 여부와 전용 역할 환경 변수를 먼저 확인한다.

## 도메인 매핑

| 경로 패턴 | 도메인 | rules.md |
|----------|--------|----------|
| `internal/domain/**` | domain-model | `agent-ops/rules/project/domain/domain-model/rules.md` |
| `internal/integration/**`, `contracts/**` | integrations | `agent-ops/rules/project/domain/integrations/rules.md` |
| `internal/platform/**`, `apps/server/**`, `apps/migrate/**`, `deploy/**` | platform | `agent-ops/rules/project/domain/platform/rules.md` |
| `apps/client/**`, `.fvmrc` | client | `agent-ops/rules/project/domain/client/rules.md` |