116 lines
5.9 KiB
Markdown
116 lines
5.9 KiB
Markdown
# 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 알림을 전송합니다.
|