156 lines
8 KiB
Markdown
156 lines
8 KiB
Markdown
# Ariadne
|
|
|
|
Ariadne는 여러 조직에서 발생하는 오류를 통합하고, 연결된 저장소와 읽기 전용 실행 환경을 분석해 수정·검증·병합 요청까지 이어 주는 플랫폼이다.
|
|
|
|
오류 분석과 수정 작업에는 IOP의 LLM 호출 및 CLI 실행 기능을 사용한다. 오류 이력, 조직과 권한, 연결 대상, 작업 흐름, 승인, 보고, 감사 기록의 기준 시스템은 Ariadne다.
|
|
|
|
## 현재 상태
|
|
|
|
Ariadne는 현재 기반 스캐폴드를 안정화하는 단계다.
|
|
|
|
- Go 서버의 설정, 로깅, PostgreSQL 연결, 마이그레이션, 조직 격리 기반과 상태 확인 endpoint가 구현되어 있다.
|
|
- Flutter 웹에는 반응형 운영 화면의 개요 스캐폴드가 있다.
|
|
- 외부 오류 입력과 IOP 실행·실패 형식은 버전별 JSON Schema로 관리한다.
|
|
- 현재 서버가 노출하는 HTTP endpoint는 `GET /healthz`와 `GET /readyz`다.
|
|
- 최초 사용자·조직 생성, 오류 수집 API, 분석·수정 workflow, 병합 요청 전달은 아직 제공하지 않는다.
|
|
|
|
제품 방향과 구현 순서는 [로드맵](agent-roadmap/ROADMAP.md)과 [전역 Milestone 실행 순서](agent-roadmap/priority-queue.md)에서 확인한다.
|
|
|
|
## 빠른 시작
|
|
|
|
### 요구 도구
|
|
|
|
- Go 1.24 이상
|
|
- Flutter 3.41.5 / Dart 3.11
|
|
- Docker Compose
|
|
|
|
### 서버와 PostgreSQL
|
|
|
|
개발용 PostgreSQL, 마이그레이션, 서버를 함께 실행한다.
|
|
|
|
```sh
|
|
docker compose up --build
|
|
```
|
|
|
|
실행 후 상태를 확인한다.
|
|
|
|
```sh
|
|
curl http://localhost:18080/healthz
|
|
curl http://localhost:18080/readyz
|
|
```
|
|
|
|
로컬 Go 도구로 서버를 직접 실행하려면 먼저 PostgreSQL만 시작하고 `.env.example`의 환경 변수를 내보낸다.
|
|
|
|
```sh
|
|
docker compose up -d database
|
|
set -a
|
|
. ./.env.example
|
|
set +a
|
|
make migrate
|
|
make run
|
|
```
|
|
|
|
직접 실행한 서버의 기본 주소는 `http://localhost:8080`이다. 데이터베이스 설정 없이도 서버는 시작할 수 있지만 `/readyz`는 준비되지 않은 상태를 반환한다.
|
|
|
|
### Flutter 웹
|
|
|
|
```sh
|
|
make client-get
|
|
cd apps/client
|
|
flutter run -d chrome
|
|
```
|
|
|
|
## 주요 명령
|
|
|
|
| 목적 | 명령 | 비고 |
|
|
|------|------|------|
|
|
| 전체 개발 환경 실행 | `docker compose up --build` | PostgreSQL, migration, Go 서버 |
|
|
| Go 서버 실행 | `make run` | `.env.example` 기준 환경 변수 필요 |
|
|
| DB migration 적용 | `make migrate` | migration 전용 DB 역할 사용 |
|
|
| Go build | `make build` | `go build ./...` |
|
|
| Go test | `make test` | `go test ./...` |
|
|
| Go 정적 검사 | `make vet` | `go vet ./...` |
|
|
| Go format | `make fmt` | `apps/`, `internal/`의 Go 파일 수정 |
|
|
| Flutter 의존성 설치 | `make client-get` | lockfile 강제 사용 |
|
|
| Flutter test | `make client-test` | 의존성 설치 포함 |
|
|
| Flutter 정적 분석 | `make client-analyze` | 의존성 설치 포함 |
|
|
| Flutter web release build | `make client-build` | 의존성 설치 포함 |
|
|
| 전체 기본 검사 | `make check` | Go build/test/vet와 Flutter test/analyze/build |
|
|
|
|
## 구조
|
|
|
|
| 경로 | 역할 |
|
|
|------|------|
|
|
| `apps/server/cmd/ariadne/` | Go 서버 진입점 |
|
|
| `apps/migrate/cmd/ariadne-migrate/` | 전용 DB migration 명령 |
|
|
| `apps/client/` | Flutter 웹 사용자 화면 |
|
|
| `internal/domain/` | 조직, 오류, 실패, 수정 작업의 핵심 모델과 규칙 |
|
|
| `internal/integration/` | IOP 등 외부 실행 계층과의 adapter 경계 |
|
|
| `internal/platform/` | 설정, 로깅, DB, HTTP 서버, bootstrap |
|
|
| `contracts/` | 외부 오류 입력과 IOP 실행·실패 JSON 계약 |
|
|
| `deploy/` | 개발·배포 기반 구성 |
|
|
| `docs/` | 사람을 위한 최신 구조·개발 가이드 |
|
|
| `agent-ops/` | AI 작업 규칙과 프로젝트 workflow |
|
|
| `agent-roadmap/` | 제품 방향, Phase, Milestone |
|
|
|
|
## 핵심 처리 정책
|
|
|
|
Ariadne는 다음 두 가지 수정 흐름을 지원하는 방향으로 개발한다.
|
|
|
|
- **수정 전 보고**: 오류 분석 → 수정 가능 여부와 수정안 보고 → 사용자 승인 → 수정 및 검증 → 병합 요청
|
|
- **자동 수정 후 보고**: 오류 분석 → 가능한 경우 자동 수정 및 검증 → 결과 보고와 병합 요청
|
|
|
|
자동 수정이 불가능하거나 검증에 실패하면 저장소를 변경하지 않고 분석 결과만 보고한다. 병합은 항상 사용자가 승인한다.
|
|
|
|
오류 입력 자격 증명은 조직과 프로젝트에 귀속된다. 입력 본문이 조직이나 프로젝트를 임의로 선택하지 않으며, 등록된 출처 규칙이 오류의 저장소와 읽기 전용 실행 환경을 결정한다.
|
|
|
|
IOP의 언어와 운영 관례는 공유하지만 IOP의 제어부·edge·실행 node 계층을 복제하지 않는다. Ariadne는 독립적으로 build·배포할 수 있어야 한다.
|
|
|
|
## 작업 맥락
|
|
|
|
- 작업 전 루트 [AGENTS.md](AGENTS.md)와 [프로젝트 규칙](agent-ops/rules/project/rules.md)을 먼저 확인한다.
|
|
- 변경 경로에 대응하는 domain rule을 코드 변경 전에 읽는다.
|
|
- `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)
|
|
- 로컬 활성 후보는 `agent-roadmap/current.md`, 공유 제품 방향은 [로드맵](agent-roadmap/ROADMAP.md)에서 확인한다.
|
|
- 조직 소유 데이터는 반드시 조직 범위 transaction과 강제 RLS 경계 안에서 접근한다.
|
|
- migration, 서버 runtime, identity 조회 DB 역할을 분리하고 runtime pool을 조직 범위 밖으로 노출하지 않는다.
|
|
- 운영 환경 연결은 읽기 전용이다. 별도 권한·승인 설계 없이 쓰기 기능이나 IOP의 직접 merge 권한을 추가하지 않는다.
|
|
- 로컬 형제 저장소를 정식 build dependency로 사용하지 않는다.
|
|
|
|
## 개발 흐름
|
|
|
|
1. 로드맵과 변경 경로의 domain rule에서 범위와 제약을 확인한다.
|
|
2. 기존 package와 directory 경계를 유지하며 구현한다.
|
|
3. DB 변경은 `internal/platform/database/migrations/`에 순서가 보장되는 새 migration으로 추가한다. 적용된 migration의 checksum은 바꾸지 않는다.
|
|
4. 변경 범위별 test와 정적 검사를 실행한다.
|
|
5. 전체 검증이 필요하면 `make check`를 실행한다.
|
|
|
|
PostgreSQL 권한·RLS 통합 검사는 Docker 사용 가능 여부와 전용 역할 환경 변수를 확인한 뒤 별도로 수행한다. 자세한 절차는 [개발 가이드](docs/development.md)를 따른다.
|
|
|
|
## 환경 변수
|
|
|
|
`.env.example`은 로컬 실행용 개발 값을 제공한다. 실제 비밀값이 있는 `.env`는 저장소에 commit하지 않는다.
|
|
|
|
| 이름 | 설명 | 필수 |
|
|
|------|------|------|
|
|
| `ARIADNE_ENVIRONMENT` | 실행 환경 이름, 기본값 `development` | 아니오 |
|
|
| `ARIADNE_HTTP_ADDRESS` | HTTP 수신 주소, 기본값 `:8080` | 아니오 |
|
|
| `ARIADNE_DATABASE_URL` | runtime 역할의 PostgreSQL 접속 주소 | DB 준비 상태에 필요 |
|
|
| `ARIADNE_DATABASE_IDENTITY_URL` | identity 조회 역할의 PostgreSQL 접속 주소 | DB 준비 상태에 필요 |
|
|
| `ARIADNE_DATABASE_MIGRATION_URL` | migration 전용 PostgreSQL 접속 주소 | migration 시 필요 |
|
|
| `ARIADNE_DATABASE_RUNTIME_ROLE` | 기대하는 runtime DB 역할 이름 | DB 사용 시 필요 |
|
|
| `ARIADNE_DATABASE_IDENTITY_ROLE` | 기대하는 identity DB 역할 이름 | DB 사용 시 필요 |
|
|
| `ARIADNE_MIGRATION_LOCK_TIMEOUT` | 동시 migration lock 대기 한도, 기본값 `30s` | 아니오 |
|
|
| `ARIADNE_IOP_ENDPOINT` | IOP 연결 주소 | 현재 아니오 |
|
|
| `ARIADNE_SHUTDOWN_TIMEOUT` | 정상 종료 대기 시간, 기본값 `10s` | 아니오 |
|
|
|
|
## 참고 문서
|
|
|
|
- [아키텍처와 책임 경계](docs/architecture.md)
|
|
- [개발 환경과 DB 변경 지침](docs/development.md)
|
|
- [외부 JSON 계약](contracts/README.md)
|
|
- [Flutter client 안내](apps/client/README.md)
|
|
- [프로젝트 로드맵](agent-roadmap/ROADMAP.md)
|