# ZERRO Docs

이 디렉터리는 ZERRO 개발의 source of truth다. 루트의 `CLAUDE.md`와 `AGENTS.md`는 agent portal이고, 상세 판단은 이 문서 계층과 constitution을 따른다.

## Source of Truth 우선순위

1. `.specify/memory/constitution.md`
2. `docs/README.md`
3. `CLAUDE.md` / `AGENTS.md`
4. 세부 docs
5. 외부 Google Docs, Figma, GitHub Issue/PR

외부 자료와 repo 문서가 충돌하면 repo 문서를 먼저 갱신한 뒤 작업한다.

## Hierarchy

| 경로 | 역할 |
|---|---|
| `00-governance/` | 제품 운영 전제, 기술스택, workflow, conventions, setup |
| `10-product/` | 제품 범위, UI quality, glossary, RBAC, Figma inventory |
| `20-contracts/` | mock/backend API contract와 schema 기준 |
| `30-backend/` | Kotlin Spring backend 착수 기준, 구현 컨벤션, 외부 연동 정본 |
| `40-mobile/` | Expo APP working agreement, release, provider/policy |
| `50-web/` | Web/PC working agreement |
| `60-requirements/` | 원천 요구사항 분석, source provenance, compact raw extraction |
| `70-progress/` | current progress snapshot |
| `80-artifacts/` | generated HTML을 만드는 git-tracked review artifact data |

## Core Docs

| 문서 | 내용 |
|---|---|
| `00-governance/PROJECT_CONTEXT.md` | 제품 목적, 역할, 2인 분업, 7월 31일 목표 |
| `00-governance/TECH_STACK.md` | Kotlin Spring 중심 기술스택, frontend/app 방향, 미결정 기술 |
| `00-governance/DEVELOPMENT_WORKFLOW.md` | Figma 화면 기반 개발, mock API first, GitHub flow, 재택 sync |
| `00-governance/CONVENTIONS.md` | 구현·문서·계약 관리 규칙 |
| `00-governance/SETUP.md` | 현재 scaffold 전제와 bootstrap 준비 |
| `10-product/MVP_SCOPE.md` | 7월 10일 기능 범위와 대표 검수 흐름 |
| `10-product/UI_PRODUCTION_READINESS.md` | APP/Web/PC production-level UI 목표와 품질 gate |
| `10-product/GLOSSARY.md` | Google Sheet 기반 공통 용어, 표기, 구현 alias |
| `10-product/RBAC_MATRIX.md` | 역할, 플랫폼, 화면, action 권한 기준 |
| `10-product/FIGMA_INVENTORY.md` | 구현 기준 Figma Page/Frame 인벤토리 |
| `20-contracts/API_CONTRACT.md` | mock API first 계약, endpoint catalog, response/error envelope |
| `20-contracts/LOCATION_TRACKING_CONTRACT.md` | driver location, map/phone handoff, future `gps_track` 경계 |
| `20-contracts/PROVIDER_ADAPTER_CONTRACT.md` | file upload, OCR, PDF/document signed URL, phone/map/support handoff adapter 경계 |
| `20-contracts/REALTIME_PUSH_CONTRACT.md` | chat/notification realtime transport와 OS push provider 경계 |
| `30-backend/WORKING_AGREEMENT.md` | Kotlin Spring backend 착수 기준과 mock contract 승격 방식 |
| `30-backend/CONVENTIONS.md` | Kotlin Spring 구현 컨벤션과 작업 플로우 |
| `30-backend/OLBARO_OPEN_API.md` | 올바로 Open API 인증, 프로토콜, 인터페이스, 공통코드, 폴링/제출 규약 |
| `40-mobile/WORKING_AGREEMENT.md` | Expo 앱 작업 구조, Maestro, agent-device, testID 규칙 |
| `40-mobile/RELEASE_STRATEGY.md` | APP EAS build, channel, OTA branch, runtimeVersion 운영 기준 |
| `40-mobile/policies/AUTH_RBAC_BOUNDARY.md` | APP mock role routing과 실제 auth/RBAC decision 경계 |
| `40-mobile/policies/PROVIDER_POLICY.md` | APP 고객센터, 전화, 지도, 파일 viewer, upload provider, 외부 링크 정책 |
| `50-web/WORKING_AGREEMENT.md` | Web/PC 작업 구조, TypeScript, test-id, mock API 규칙 |
| `60-requirements/` | 기능/화면/데이터 요구사항 전수 분석과 source provenance |
| `70-progress/CURRENT.md` | 현재 진행 상태, open work, next priority |

## Current Decisions

- Backend는 Kotlin Spring으로 진행한다.
- Backend DB/ORM은 PostgreSQL 17 + JPA + Flyway로 진행한다(`constitution` 2.2.0과 동기화).
- Backend auth는 자체 JWT와 duties claim을 기준으로 한다(`constitution` 2.2.0과 동기화).
- Monorepo는 pnpm workspace + Turborepo로 진행한다.
- 먼저 APP/Web/PC UI를 Figma 기준으로 mock API와 함께 만든다.
- APP은 Expo SDK 56 단일 앱으로 만들고, 온보딩에서 배출자/배차담당자/운전자/처리자 role로 라우팅한다.
- APP 경로는 `apps/mobile`이며, `apps/app` 경로는 현재 사용하지 않는다.
- APP E2E는 Maestro deterministic flow와 `callstack/agent-device` AI based E2E를 함께 사용한다.
- APP 고객센터, 전화, 지도, 파일 viewer, upload provider, 외부 링크는 `40-mobile/policies/PROVIDER_POLICY.md`의 adapter/provider-pending 정책을 따른다.
- 운전자 위치와 future `gps_track` 범위는 `20-contracts/LOCATION_TRACKING_CONTRACT.md`를 따른다. continuous realtime GPS 관제는 MVP에서 제외하고, foreground event-time location evidence만 허용한다.
- file upload, OCR, PDF/document signed URL, phone/map/support handoff adapter shape는 `20-contracts/PROVIDER_ADAPTER_CONTRACT.md`를 따른다.
- APP/Web/PC chat realtime과 OS push 경계는 `20-contracts/REALTIME_PUSH_CONTRACT.md`를 따른다.
- APP UX 검수는 local/generated `artifacts/mobile/index.html`에서 시작한다. 단, 이 포털과 `artifacts/mobile/ux-flow/index.html`, `artifacts/mobile/maestro/index.html`은 사람이 읽기 위한 snapshot이며, 정본은 `apps/mobile/e2e/TEST_COVERAGE_GRAPH.md`, `70-progress/CURRENT.md`, `80-artifacts/ux-flow/mobile-index.json`이다.
- Web/PC는 Next.js `16.2.9` + App Router로 진행한다.
- Web/PC mock server는 Next.js Route Handlers, runtime validation은 Zod 기반 TypeScript-first schema로 진행한다.
- Web/PC E2E는 Playwright + AI Computer Use를 기준으로 한다.
- 7월 10일 기능 범위는 `10-product/MVP_SCOPE.md`의 Must/Should/Later 기준으로 관리한다.
- UI 품질 목표는 `10-product/UI_PRODUCTION_READINESS.md`를 따른다. MVP 기능 범위가 UI 품질을 낮추는 근거가 되지 않는다.
- 권한과 역할별 UI 변화는 `10-product/RBAC_MATRIX.md`를 기준으로 한다.
- APP auth/RBAC placeholder는 `40-mobile/policies/AUTH_RBAC_BOUNDARY.md` 기준으로 mock boundary와 actual backend decision을 분리한다.
- APP mock fixture 승격 기준은 `20-contracts/API_CONTRACT.md`, `40-mobile/WORKING_AGREEMENT.md`, `packages/mocks/README.md`를 함께 따른다.
- 공통 용어, 표기, 구현 alias는 `10-product/GLOSSARY.md`를 기준으로 한다.
- mock API 계약은 `20-contracts/API_CONTRACT.md`를 기준으로 관리하고 backend로 승격한다.
- 개발 통합 기준은 `develop` branch GitHub flow다.
- 주우철은 APP/기술 기준, 정정일은 Web/PC/backend/관측성을 주도한다.

## Open Decisions

확정되지 않은 기술은 임의로 채우지 않는다.

- queue/scheduler 구현 방식
- APP realtime native dependency와 push provider
- driver APP offline 전략
- backend/production CI provider와 gate 세부 구현
- production hosting/provider