# AI Code App

React + Vite + TypeScript 기반의 문서/샘플 허브 애플리케이션입니다. 현재 저장소는 공통 컴포넌트, 위젯 샘플, Markdown 문서 뷰어, Plan 게시판을 하나의 앱에서 탐색할 수 있도록 구성되어 있습니다.

## 임시 운영 메모

- 현재 저장소는 당분간 **로컬 전용 작업 모드**로 사용합니다.
- Git 원격 동기화, 브랜치 운영, 자동 병합/자동화는 잠시 중지한 상태로 간주합니다.
- Codex나 자동화 도구는 기본적으로 Git 작업 없이 **현재 프로젝트 루트의 `main` 작업본을 바로 수정**합니다.
- `채팅`, `Codex Live`, 일반 `작업메모`, `메모 반영` 요청도 같은 기준으로 해석합니다.
- 자동화 접수된 작업메모도 별도 브랜치 흐름을 이 문서에 고정하지 않고, 실제 운영 설정과 요청 문맥을 기준으로 처리합니다.
- 채팅 리소스와 첨부 파일은 `public/.codex_chat/<chat-session-id>/resource/...` 기준으로 제공하며, 업로드 파일은 `public/.codex_chat/<chat-session-id>/resource/uploads/...` 아래를 사용합니다.
- `public/assets/` 아래 리소스, `tmp-*` 캡처 파일, 대용량 바이너리 파일은 기본적으로 커밋하지 않습니다.
- 저장소에는 staged 자산 차단 훅이 연결되어 있으며, 의도적인 자산 커밋이 꼭 필요할 때만 `ALLOW_ASSET_COMMIT=1 git commit ...`으로 예외 처리합니다.

## 시작하기

```bash
npm install
npm run dev
```

## 확인용 Preview 컨테이너

실제 반영 화면을 확인할 때는 별도 preview 컨테이너를 사용합니다.

```bash
docker compose -f docker-compose.preview.yml up -d --build
```

- 로컬 preview 컨테이너 접속 주소: `http://127.0.0.1:4173`
- 외부 검증 도메인: `https://preview.sm-home.cloud/`
- preview 컨테이너는 현재 프로젝트 루트를 바인드 마운트하고 `vite build --watch`로 정적 산출물을 자동 재빌드합니다.
- 따라서 `https://preview.sm-home.cloud/`에서는 Vite HMR처럼 즉시 DOM이 바뀌지는 않지만, 소스 저장 후 재빌드가 끝나면 브라우저 새로고침만으로 최신 화면을 확인할 수 있습니다.
- API 프록시는 기본적으로 호스트의 `3100` 포트를 `host.docker.internal`로 바라봅니다.
- 포트나 API 대상 변경이 필요하면 `PREVIEW_APP_PORT`, `WORK_SERVER_URL` 환경변수를 사용합니다.

## 테스트용 컨테이너 운영 기준

- 테스트용 컨테이너는 현재 `ai-code-app-preview` 하나만 유지합니다.
- 이 컨테이너는 채팅 전용 테스트가 아니라 **현재 프로젝트 루트 기준 화면/기능 확인용 테스트 컨테이너**로 사용합니다.
- 화면 테스트, 소스 변경 검증, 최종 화면 확인은 `https://preview.sm-home.cloud/` 기준으로 진행합니다.
- `https://test.sm-home.cloud/`는 운영 비교나 프록시 점검이 꼭 필요할 때만 보조적으로 확인합니다.
- 위 프록시 기준은 임의로 바꾸지 말고, 변경이 필요하면 반드시 운영 목적을 먼저 문서에 남깁니다.
- 임시 테스트 컨테이너를 추가로 띄우지 말고, 필요 시 기존 `ai-code-app-preview`만 재기동합니다.
- 재기동은 다른 서비스까지 건드리지 않고 아래 명령으로 해당 컨테이너만 처리합니다.

```bash
docker compose -f docker-compose.preview.yml up -d --build --force-recreate --no-deps preview-app
```

- 저장소 설정에 없는 임시 테스트 컨테이너가 남아 있으면 정리 대상입니다.

## PhotoPrism

루트 `docker-compose.yml`에는 PhotoPrism와 MariaDB 서비스가 포함되어 있습니다.

```bash
cp .env.example .env
docker compose up -d photoprism photoprism-db
```

- 기본 접속 포트: `127.0.0.1:2342`
- 기본 사이트 URL: `https://photo.sm-home.cloud/`
- 원본 사진 경로: `/mnt/usb/photos`
- 원본 경로는 읽기 전용으로 마운트됩니다.
- `/mnt/usb/photos`가 호스트에 없으면 bind mount를 자동 생성하지 않고 기동이 실패합니다.

## 주요 스크립트

```bash
npm run dev
npm run build
npm run build:lib
npm run build:app
npm run preview
npm run docs:daily
npm run capture:component
npm run capture:menu
npm run capture:feature
npm run capture:fullscreen
npm run capture:plan-mobile
npm run plan:codex:once
```

## 프로젝트 구조

```text
src/
├─ app/
│  ├─ main/                # 메인 레이아웃과 상단/사이드 UI
│  └─ manifests/           # 문서/샘플 로딩 매니페스트
├─ components/
│  ├─ markdownPreview/     # Markdown 문서 목록/카드 렌더링
│  ├─ navigation/          # 섹션 메뉴와 폴더 트리
│  ├─ previewer/           # text/json/code/image/markdown 미리보기
│  ├─ search/              # 통합 검색 모달
│  ├─ status-badge/        # 상태 표현 UI
│  └─ window/              # 드래그/리사이즈 가능한 윈도우 UI
├─ features/
│  ├─ board/               # 작업 요청 게시판과 자동화 접수 화면
│  ├─ dashboard/           # 프로젝트 전용 대시보드 샘플
│  ├─ layout/              # 프로젝트 전용 레이아웃 문서
│  ├─ markdownPreview/     # 기능 레벨 Markdown 카드
│  └─ planBoard/           # Plan 게시판 화면과 API 연동
├─ layer/                  # 제스처/검색 레이어
├─ samples/                # 샘플 엔트리 레지스트리
├─ store/                  # 앱 전역 상태
└─ widgets/                # 위젯 단위 샘플과 공통 셸
docs/
├─ components/             # 컴포넌트 문서
├─ features/               # 기능 문서
├─ templates/              # 문서 템플릿
└─ worklogs/               # 날짜별 작업일지
```

## 앱 구성

- `APIs / Components`: 공통 컴포넌트 샘플 탐색
- `APIs / Widgets`: 위젯 샘플 탐색
- `Docs`: `docs/**/*.md`와 일부 `src/features/**/*.md` 문서 탐색
- `Plans / 작업 요청`: 게시글 1건 안에 여러 하위 요청을 묶고 자동화 접수를 추적
- `Plans`: 작업 항목, 조치 이력, 이슈 이력을 관리하는 Plan 게시판

## 문서 위치

- 전체 문서 가이드: `docs/README.md`
- 작업일지: `docs/worklogs`
- 기능 문서: `docs/features`
- 작업 요청 기능 문서: `docs/features/work-request-board.md`
- 컴포넌트 문서: `docs/components`
- 공통 컴포넌트 패키지 가이드: `src/components/README.md`
- 공통 위젯 패키지 가이드: `src/widgets/README.md`

## 공통 패키지 문서 규칙

- `src/components`, `src/widgets`처럼 여러 화면에서 공통 재사용되는 패키지에는 해당 패키지 하위 `README.md`를 둡니다.
- 패키지 하위 문서에는 최소한 목적, 하위 구조, export 또는 registry 기준점, 샘플 및 문서 연결 규약을 적습니다.
- 컴포넌트 또는 위젯 구조를 바꾸면 구현 파일만 수정하지 말고 해당 패키지 `README.md`와 관련 `docs/components/*.md`도 함께 점검합니다.

## 운영 메모

- 앱 문서는 Vite `import.meta.glob`으로 Markdown 파일을 수집합니다.
- 작업일지는 날짜별 파일로 누적하며 캡처 이미지는 `docs/assets/worklogs/YYYY-MM-DD/` 기준으로 관리합니다.
- Plan 자동화 스크립트는 `scripts/run-plan-codex-once.mjs`를 사용합니다.
- command runner는 별도 명시적 요청이 있을 때만 `npm run server-command:runner`로 직접 기동하거나 재기동합니다.
- 문서/작업일지 일일 정리는 `npm run docs:daily`와 `.github/workflows/daily-docs-maintenance.yml` 기준으로 실행합니다.

## 프로젝트 현황

<!-- AUTO_DAILY_DOCS:README_START -->
- 기준 일자: `2026-04-07` (Asia/Seoul)
- 작업일지: 9개
- 기능 문서: 2개
- 컴포넌트 문서: 8개
- 스크린샷 보관 폴더: 7개

최근 작업일지
- `2026-04-07` 작업일지
- `2026-04-06` 작업일지
- `2026-04-05` 작업일지
- `2026-04-04` 작업일지
- `2026-04-03` 작업일지
- `2026-04-02` 작업일지
- `2026-04-01` 작업일지
<!-- AUTO_DAILY_DOCS:README_END -->