|
|
# 아리(Ari) — AI Life OS
|
|
|
|
|
|
일·삶을 한곳에서 관리하는 한국어 AI 개인비서 **아리**의 MVP.
|
|
|
핵심 철학: **"적을 때는 분류하지 않는다 — 분류·배치·자동화는 아리가."**
|
|
|
사용자는 *읽고 탭 한 번*, 나머지는 아리가 합니다.
|
|
|
|
|
|
MVP 3페이지 — **작업(/tasks) · 인박스(/inbox) · 대시보드(/dashboard)**.
|
|
|
나머지 10개 내비 항목은 "준비 중" 플레이스홀더(내비 일관성 유지).
|
|
|
|
|
|
```
|
|
|
workspace/
|
|
|
├─ frontend/ Next.js 16 (App Router, TypeScript) · next-themes · SWR · Vitest · Playwright
|
|
|
├─ backend/ FastAPI · SQLite(SQLModel·Alembic) · Ollama 추상화(모델 비종속, heuristic 폴백)
|
|
|
├─ dev/ 개발 문서 (overview.md + phase-0~6)
|
|
|
└─ design-reference/ 원본 프로토타입 (픽셀 충실 재현 기준)
|
|
|
```
|
|
|
|
|
|
## 스택
|
|
|
|
|
|
| 레이어 | 선택 |
|
|
|
|---|---|
|
|
|
| 프론트엔드 | Next.js(App Router) + React 19 + TypeScript, 순수 CSS 변수 토큰, next-themes 테마 |
|
|
|
| 백엔드 | Python + FastAPI + SQLite(SQLModel + Alembic) |
|
|
|
| LLM | 로컬 Ollama + `LLMProvider` 추상화(모델 비종속, `OLLAMA_MODEL` 주입). 미가용 시 `HeuristicProvider` 폴백 |
|
|
|
| 테스트 | pytest(백엔드) / Vitest·Playwright·axe(프론트) |
|
|
|
|
|
|
## 빠른 시작
|
|
|
|
|
|
### 0) 사전 설치
|
|
|
Node ≥ 20 · pnpm · Python ≥ 3.11 · uv · (선택) Ollama
|
|
|
|
|
|
### 1) 의존성 + 환경변수 + 시드
|
|
|
|
|
|
```bash
|
|
|
make install # frontend(pnpm) + backend(uv) 의존성
|
|
|
|
|
|
cp backend/.env.example backend/.env # 필요 시 OLLAMA_MODEL 등 수정
|
|
|
cp frontend/.env.local.example frontend/.env.local
|
|
|
|
|
|
cd backend && uv run alembic upgrade head && uv run python -m app.seed && cd ..
|
|
|
```
|
|
|
|
|
|
### 2) (선택) Ollama — 모델 비종속
|
|
|
|
|
|
```bash
|
|
|
ollama serve &
|
|
|
ollama pull <설치할_모델> # backend/.env 의 OLLAMA_MODEL 과 일치시킬 것 (특정 모델 강제 아님)
|
|
|
```
|
|
|
|
|
|
> Ollama가 없거나 느리면 자동으로 규칙 기반(HeuristicProvider)으로 분류가 계속됩니다.
|
|
|
> `LLM_PROVIDER=heuristic` 로 강제할 수도 있습니다(테스트·오프라인).
|
|
|
|
|
|
### 3) 실행
|
|
|
|
|
|
```bash
|
|
|
make dev # backend :8000 + frontend :3000 (또는 scripts/dev.sh)
|
|
|
# http://localhost:3000 → / 는 /dashboard 로 리다이렉트
|
|
|
```
|
|
|
|
|
|
### 4) 스모크 / 테스트
|
|
|
|
|
|
```bash
|
|
|
make health # /api/health, /api/llm/health
|
|
|
make test # pytest + vitest
|
|
|
make lint # ruff + eslint
|
|
|
|
|
|
# E2E (백엔드는 리셋 허용 + heuristic 으로 기동해야 federation/a11y/responsive 전부 통과)
|
|
|
ARI_ALLOW_TEST_RESET=1 LLM_PROVIDER=heuristic uv run --directory backend uvicorn app.main:app --port 8000 &
|
|
|
cd frontend && pnpm exec playwright test
|
|
|
```
|
|
|
|
|
|
## 시드 초기화(데모 리셋)
|
|
|
|
|
|
```bash
|
|
|
cd backend && rm -f ari.db && uv run alembic upgrade head && uv run python -m app.seed
|
|
|
# 또는 E2E용(가드): ARI_ALLOW_TEST_RESET=1 로 기동 후
|
|
|
curl -X POST http://localhost:8000/api/_test/reset
|
|
|
```
|
|
|
|
|
|
## 환경변수
|
|
|
|
|
|
| 변수 | 위치 | 기본값 | 설명 |
|
|
|
|---|---|---|---|
|
|
|
| `OLLAMA_HOST` | backend `.env` | `http://localhost:11434` | Ollama HTTP 엔드포인트 |
|
|
|
| `OLLAMA_MODEL` | backend `.env` | (설치 모델 주입) | 분류용 모델명 — **비종속**(env로만 지정) |
|
|
|
| `LLM_PROVIDER` | backend env | `auto` | `auto`\|`ollama`\|`heuristic` (테스트/E2E는 `heuristic`) |
|
|
|
| `LLM_TIMEOUT` | backend env | `30` | 분류 1건 타임아웃(초). 초과 시 heuristic 폴백 |
|
|
|
| `DATABASE_URL` | backend `.env` | `sqlite:///./ari.db` | DB 경로 |
|
|
|
| `FRONTEND_ORIGIN` | backend `.env` | `http://localhost:3000` | CORS 허용 출처(콤마구분) |
|
|
|
| `ARI_ALLOW_TEST_RESET` | backend env | (미설정) | `1`이면 `/api/_test/reset` 허용(E2E 전용, 운영 403) |
|
|
|
| `NEXT_PUBLIC_API_BASE` | frontend `.env.local` | `http://localhost:8000` | 프론트가 호출할 백엔드 베이스 |
|
|
|
|
|
|
## 연합(federation) 흐름 — MVP의 핵심
|
|
|
|
|
|
1. **인박스**에 한 줄 적기 → 아리가 즉시 **작업/일정/아이디어 + 업무/개인 + 행선지 프로젝트**로 분류.
|
|
|
2. **확인(탭 한 번)** → 실제 `task`로 실체화(`materialized_task_id` 연결).
|
|
|
3. **작업 페이지**의 `개인 › 여행 — 한국`에 등장 — 개인 일도 숨기지 않고 업무 작업과 *같은 트리에서 필터로만* 구분.
|
|
|
4. 작업 데이터로 **리스크 레이더**(지연·쏠림·의존성)가 자동 재계산, **대시보드**가 작업/인박스/결재함을 집계.
|
|
|
|
|
|
## 데모 스크립트(약 3분)
|
|
|
|
|
|
1. 대시보드 진입 — 아침 브리핑/일정/할 일/목표/결재함·인박스 요약.
|
|
|
2. 인박스에서 `다음 주에 한국 놀러가는 비행기 티켓 사기` 캡처 → 자동 분류(작업/개인 › 여행 — 한국 + 이유).
|
|
|
3. "좋아요, 그렇게 해줘" → 실체화.
|
|
|
4. 작업 → 개인 필터 → 여행 — 한국에 등장(개인도 숨기지 않음).
|
|
|
5. 업무 필터 → 리스크 레이더 "분기 리포트가 오늘 마감인데 진행 중".
|
|
|
6. 대시보드 복귀 → 요약 반영.
|
|
|
|
|
|
## 문서
|
|
|
|
|
|
개발 문서 진입점은 `dev/overview.md`. 빌드 순서: `phase-0` → `phase-1` → `phase-2` → (`phase-3` 작업 → `phase-4` 인박스 → `phase-5` 대시보드) → `phase-6` 통합.
|