# Work Server

`Fastify + Knex + PostgreSQL` 기반의 범용 작업용 API 서버입니다.

## 추천 DB

- `PostgreSQL`
- 이유:
  - Node 생태계에서 검증된 조합
  - `Knex`로 CRUD와 DDL을 함께 다루기 편함
  - 운영/확장/마이그레이션 측면에서 무난함

## 실행

```bash
docker compose up -d
docker compose logs -f work-server
```

`work-server`는 HMR/watch 없이 빌드 산출물(`dist`)을 실행합니다. 컨테이너 재기동은 `docker compose up -d --build --force-recreate --no-deps work-server` 기준으로 최신 소스를 다시 빌드한 뒤 새 컨테이너를 띄웁니다.

호스트 프로젝트 루트와 동일한 문맥으로 서버 재기동을 처리하려면 별도 host runner도 함께 켭니다.

```bash
cd /home/how2ice/project/ai-code-app
npm run server-command:runner
```

## 환경 변수

기본 실행은 `.env.example` 값으로도 가능합니다.
로컬 환경에 맞는 값을 덮어쓰려면 `.env.example`를 참고해서 `.env`를 추가하면 됩니다.

주요 항목:

- `APP_TIME_ZONE`: Node 서버 런타임 기준 시간대. 기본값 `Asia/Seoul`
- `DB_TIME_ZONE`: 앱이 여는 DB 세션 시간대. 기본값 `Asia/Seoul`
- `DB_*`: PostgreSQL 접속 정보
- `PLAN_WORKER_ENABLED`: Plan 자동화 worker 활성화 여부
- `PLAN_WORKER_INTERVAL_MS`: Plan polling 주기
- `PLAN_GIT_REPO_PATH`: 브랜치 생성/병합 대상 저장소 경로
- `PLAN_MAIN_PROJECT_REPO_PATH`: main 반영 후 pull 받을 메인 루트 프로젝트 경로. 비우면 `PLAN_GIT_REPO_PATH`를 사용
- `PLAN_RELEASE_BRANCH`: 자동 merge 대상 release 브랜치명
- `IOS_NOTIFICATION_ENABLED`: iOS APNs 알림 활성화 여부
- `APNS_*`: Apple Push Notification 인증 키 정보
- `SERVER_COMMAND_DOCKER_SOCKET`: 서버 재기동 명령이 사용할 Docker Unix socket 경로. rootless Docker면 예: `/run/user/1000/docker.sock`
- `SERVER_COMMAND_API_BASE_URL`: `work-server`가 서버 재기동 요청을 위임할 host runner 주소
- `SERVER_COMMAND_API_ACCESS_TOKEN`: host runner 호출 토큰

서버 재기동 기능을 쓰려면 `work-server` 컨테이너가 Docker에 접근할 수 있어야 합니다. 기본값은 `/var/run/docker.sock`이며, rootless Docker 환경이면 `.env`에 `SERVER_COMMAND_DOCKER_SOCKET` 또는 `DOCKER_HOST=unix:///run/user/<uid>/docker.sock`를 맞춰 준 뒤 `work-server`를 다시 올려야 합니다.

기본 예시는 `http://host.docker.internal:3211/api`로 맞춰져 있어서, `work-server` 컨테이너가 아니라 호스트의 현재 프로젝트 루트에서 `restart-*.sh`를 실행합니다. 즉 `Server > Command`가 직접 CLI로 재기동한 것과 최대한 비슷한 문맥을 사용합니다.

## Codex Live

`Codex Live`는 현재 프로젝트 환경의 `main_project` 경로를 기준으로 실행됩니다. 기본값은 `PLAN_MAIN_PROJECT_REPO_PATH=/workspace/main-project`이며, 소스 수정이 필요하면 이 경로의 실제 프로젝트를 바로 수정합니다.

현재 운영 기준에서는 `Codex Live`, 일반 채팅, 작업메모 반영 요청 모두 **현재 프로젝트 루트의 로컬 `main` 작업본을 바로 수정**합니다. 별도 브랜치 생성이나 `release -> main` 동기화는 기본 전제로 사용하지 않으며, Git 관련 작업은 사용자가 명시적으로 요청할 때만 수행합니다.

브라우저 기준 접속 확인, 화면 검증, 외부 도메인 테스트는 **`https://test.sm-home.cloud/`를 기본 작업 도메인으로 사용**합니다. 별도 요청이 없는 한 `sm-home.cloud`나 `rel.sm-home.cloud`는 기본 검증 대상으로 삼지 않습니다.

채팅에서 파일, 문서, 이미지, 코드 같은 리소스를 제공할 때의 기본 공개 경로는 `public/.codex_chat/<chat-session-id>/resource/...`입니다. Codex가 원본 파일 경로만 답해도 서버가 이 위치로 세션 전용 사본을 만들고, 채팅에는 공개 URL을 다시 적어 줍니다.

채팅 첨부 파일도 같은 기준을 사용하며 `public/.codex_chat/<chat-session-id>/resource/uploads/...` 아래에 저장됩니다.

## Plan 자동화

`Plan` 게시판 항목을 작업 큐처럼 읽어 자동화할 수 있습니다.

현재 로컬 운영 모드에서는 아래 자동 브랜치 흐름을 기본 동작으로 강제하지 않습니다. 필요 시 사용자가 별도로 요청한 경우에만 사용합니다.

- `등록` 상태: worker가 읽어서 `feature/plan-{id}-{workId}` 브랜치 생성 시도
- 성공 시: `작업중`, `브랜치준비`
- 실패 시: `이슈`, 최근 오류 기록
- `개발완료` 상태: worker가 `release` 브랜치 병합 시도
- 병합 성공 시: `완료`
- 병합 실패 시: `이슈`

안전 조건:

- Git worktree가 깨끗해야 동작
- `release` 브랜치가 실제로 존재해야 병합 가능
- 실패 시 자동으로 `이슈` 상태와 오류 메시지를 남김

## 주요 API

- `GET /health`
- `GET /api/schema/tables`
- `POST /api/ddl/create-table`
- `POST /api/ddl/drop-table`
- `POST /api/ddl/add-column`
- `POST /api/ddl/drop-column`
- `POST /api/ddl/raw`
- `POST /api/crud/:table/select`
- `POST /api/crud/:table/insert`
- `PATCH /api/crud/:table/update`
- `DELETE /api/crud/:table/delete`
- `GET /api/plan/statuses`
- `POST /api/plan/setup`
- `GET /api/plan/items`
- `GET /api/plan/items/:id`
- `POST /api/plan/items`
- `PATCH /api/plan/items/:id`
- `DELETE /api/plan/items/:id`
- `POST /api/notifications/setup`
- `GET /api/notifications/tokens`
- `PUT /api/notifications/tokens/ios`
- `DELETE /api/notifications/tokens/ios`
- `POST /api/notifications/send-test`

## iOS 알림 연동

- 프론트에서 알림 `On` 시 `PUT /api/notifications/tokens/ios`로 APNs 토큰을 등록합니다.
- 프론트에서 알림 `Off` 시 또는 토큰이 폐기되면 `DELETE /api/notifications/tokens/ios`로 토큰을 제거합니다.
- Plan worker가 브랜치 준비, 자동 작업 완료/실패, release 반영 완료/실패, main 반영 완료/실패 시 등록된 iOS 토큰으로 APNs 알림을 전송합니다.