Skip to content

Commit e16ee29

Browse files
SOIVclaude
SOIV
and
claude
committed
docs(technical): 서버 시작 시퀀스 및 에러 복구 정책 문서 추가
- 시작 시퀀스 7단계 정의 (환경변수 → Setup → 구동 모드 → DB → 마이그레이션 → 서버 기동 → 업데이트 채널) - 에러 코드 체계 정의 (BOOT / SETUP / DB / MIGRATION / SERVER) - 복구 방식 3단계 분류: 자동 복구 / 에러 페이지 / 공장 초기화 - UNKNOWN_ERROR + exit code 1 fallback 추가 (미분류 예외 처리) - 프로덕션 환경에서 스택 트레이스 비노출, 에러 ID 기반 로그 추적 정책 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent 6acfd88 commit e16ee29

1 file changed

Lines changed: 188 additions & 0 deletions

File tree

‎docs/v2_FINANCIAL-LEDGER/technical/07-startup-sequence.md‎

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
# 서버 시작 시퀀스 & 에러 복구 정책
2+
3+
## 1. 시작 시퀀스 개요
4+
5+
서버가 기동될 때 아래 순서로 단계를 순차 실행합니다.
6+
각 단계는 에러 코드를 반환하며, 코드에 따라 자동 복구 / 에러 페이지 / 공장 초기화 중 하나로 분기합니다.
7+
8+
```
9+
서버 프로세스 시작
10+
│
11+
├─ [STEP 1] 환경변수 검증
12+
├─ [STEP 2] Setup Check → installed.lock 존재 여부
13+
├─ [STEP 3] 구동 모드 판단 → Mode 1 (로컬) / Mode 2 (서버) / ...
14+
├─ [STEP 4] DB 연결 및 상태 체크
15+
├─ [STEP 5] 마이그레이션 실행
16+
├─ [STEP 6] API 서버 기동 및 라우트 등록
17+
└─ [STEP 7] 업데이트 채널 확인 → 비동기 백그라운드 (시작 흐름 차단 안 함)
18+
```
19+
20+
---
21+
22+
## 2. 에러 코드 분류
23+
24+
### BOOT_xxx — 환경/설정 에러
25+
26+
| 코드 | 설명 | 복구 방식 |
27+
|------|------|----------|
28+
| `BOOT_ENV_MISSING` | 필수 환경변수 누락 | 에러 페이지 (누락 항목 안내) |
29+
| `BOOT_ENV_INVALID` | 환경변수 형식 오류 | 에러 페이지 |
30+
| `BOOT_PORT_CONFLICT` | 포트 이미 사용 중 | 에러 페이지 (포트 변경 안내) |
31+
32+
### SETUP_xxx — Setup / 설치 상태 에러
33+
34+
| 코드 | 설명 | 복구 방식 |
35+
|------|------|----------|
36+
| `SETUP_NOT_INSTALLED` | `installed.lock` 없음 | → Setup 모드로 기동 (정상 플로우) |
37+
| `SETUP_LOCK_CORRUPTED` | `installed.lock` 파싱 불가 | → 자동 복구: lock 재생성 시도 |
38+
| `SETUP_LOCK_MISMATCH` | lock 버전과 앱 버전 불일치 | → 마이그레이션 시도 후 복구 불가 시 에러 페이지 |
39+
40+
### DB_xxx — DB 연결 에러
41+
42+
| 코드 | 설명 | 복구 방식 |
43+
|------|------|----------|
44+
| `DB_CONNECT_RETRY` | 일시적 연결 실패 | → 자동 복구: 3회 재시도 (exponential backoff) |
45+
| `DB_CONNECT_FAILED` | 재시도 후에도 연결 불가 | 에러 페이지 (연결 설정 확인 안내) |
46+
| `DB_FILE_NOT_FOUND` | SQLite 파일 없음 (설치 후 삭제됨) | → 공장 초기화 (Setup 모드 복귀) |
47+
| `DB_SCHEMA_MISSING` | 테이블 구조가 없음 (빈 DB) | → 공장 초기화 (Setup 모드 복귀) |
48+
| `DB_SCHEMA_CORRUPTED` | 스키마 무결성 깨짐 | → 공장 초기화 (Setup 모드 복귀) |
49+
| `DB_ADMIN_NOT_FOUND` | 관리자 계정이 DB에 없음 | → 공장 초기화 (Setup 모드 복귀) |
50+
51+
### MIGRATION_xxx — 마이그레이션 에러
52+
53+
| 코드 | 설명 | 복구 방식 |
54+
|------|------|----------|
55+
| `MIGRATION_PENDING` | 미실행 마이그레이션 존재 | → 자동 복구: 자동 실행 |
56+
| `MIGRATION_FAILED` | 마이그레이션 실행 실패 | 에러 페이지 (실패 항목, 롤백 여부 표시) |
57+
| `MIGRATION_UNRECOVERABLE` | 롤백도 불가한 마이그레이션 실패 | → 공장 초기화 권장 (에러 페이지에서 선택) |
58+
59+
### SERVER_xxx — 서버 기동 에러
60+
61+
| 코드 | 설명 | 복구 방식 |
62+
|------|------|----------|
63+
| `SERVER_ROUTE_FAILED` | 라우트 등록 실패 (모듈 오류) | 에러 페이지 (문제 모듈 표시) |
64+
| `SERVER_MODULE_LOAD_FAILED` | 모듈 로드 실패 | → 자동 복구: 해당 모듈 비활성화 후 계속 기동 |
65+
66+
### 미분류 에러 (Fallback)
67+
68+
정의된 에러 코드에 해당하지 않는 예외가 발생한 경우:
69+
70+
| 코드 | Exit Code | 설명 | 복구 방식 |
71+
|------|-----------|------|----------|
72+
| `UNKNOWN_ERROR` | `1` | 정의되지 않은 예외 | 에러 페이지 (원본 에러 메시지 + 스택 트레이스 표시) |
73+
74+
```
75+
try {
76+
// 시작 시퀀스
77+
} catch (err) {
78+
// 어떤 에러 코드에도 해당하지 않는 경우
79+
// → UNKNOWN_ERROR + exit code 1
80+
// → 에러 페이지에 원본 에러 메시지와 발생 위치 표시
81+
}
82+
```
83+
84+
> 프로덕션 환경에서는 스택 트레이스를 에러 페이지에 노출하지 않고
85+
> 서버 로그에만 기록하며, 에러 페이지에는 에러 ID(타임스탬프 기반)만 표시합니다.
86+
> 관리자가 해당 ID로 로그에서 원인을 추적할 수 있도록 합니다.
87+
88+
---
89+
90+
## 3. 복구 시퀀스 상세
91+
92+
### 3.1 자동 복구 (Auto Recovery)
93+
94+
사용자 개입 없이 서버가 스스로 처리합니다.
95+
96+
```
97+
DB_CONNECT_RETRY
98+
└─ 1초 후 재시도 → 2초 후 재시도 → 4초 후 재시도 (최대 3회)
99+
├─ 성공 → 시퀀스 계속
100+
└─ 실패 → DB_CONNECT_FAILED 로 격상
101+
102+
MIGRATION_PENDING
103+
└─ 마이그레이션 자동 실행
104+
├─ 성공 → 시퀀스 계속
105+
└─ 실패 → MIGRATION_FAILED 로 격상
106+
107+
SERVER_MODULE_LOAD_FAILED
108+
└─ 문제 모듈 비활성화 처리 후 나머지 모듈로 계속 기동
109+
└─ 관리자 대시보드에 비활성화된 모듈 경고 표시
110+
```
111+
112+
### 3.2 에러 페이지 (Error Page)
113+
114+
서버는 기동되지만 최소한의 에러 UI만 서빙합니다.
115+
116+
- 에러 코드, 원인, 해결 방법 안내
117+
- 설정 파일 경로, 누락된 환경변수 등 구체적 정보 표시
118+
- 수동 조치 후 재시작하면 정상 복구 가능한 케이스
119+
120+
```
121+
BOOT_ENV_MISSING → "다음 환경변수가 없습니다: [목록]"
122+
DB_CONNECT_FAILED → "DB에 연결할 수 없습니다. 연결 설정을 확인하세요."
123+
MIGRATION_FAILED → "마이그레이션 [이름]이 실패했습니다. 로그를 확인하세요."
124+
SERVER_ROUTE_FAILED → "모듈 [이름] 로드 중 오류가 발생했습니다."
125+
```
126+
127+
### 3.3 공장 초기화 (Setup 모드 복귀)
128+
129+
DB 또는 설치 상태가 복구 불가능한 경우입니다.
130+
131+
```
132+
DB_FILE_NOT_FOUND
133+
DB_SCHEMA_MISSING
134+
DB_SCHEMA_CORRUPTED
135+
DB_ADMIN_NOT_FOUND
136+
MIGRATION_UNRECOVERABLE
137+
│
138+
└─ 에러 페이지에 "공장 초기화" 버튼 표시
139+
└─ 관리자가 확인 → installed.lock 삭제 + DB 초기화
140+
└─ 서버 재시작 → Setup 모드로 자동 복귀
141+
```
142+
143+
> 공장 초기화는 **자동으로 실행되지 않습니다.**
144+
> 반드시 사용자(관리자)가 에러 페이지에서 명시적으로 선택해야 합니다.
145+
> 데이터 복구가 불가능하므로 이중 확인(에러 코드 입력 등)을 권장합니다.
146+
147+
---
148+
149+
## 4. 구동 모드 판단
150+
151+
Setup check 통과 후 구동 모드를 결정합니다.
152+
구동 모드는 `installed.lock` 또는 환경변수에서 읽어옵니다.
153+
154+
| 모드 | 설명 | 특이사항 |
155+
|------|------|---------|
156+
| Mode 1 (로컬) | 단일 사용자, 로컬 실행 | CLI 초기화 명령 사용 가능 |
157+
| Mode 2 (서버) | 다중 사용자, 네트워크 서빙 | 화이트리스트 기반 접근 제어 |
158+
159+
---
160+
161+
## 5. 업데이트 채널 확인
162+
163+
시작 시퀀스를 **차단하지 않고** 백그라운드에서 비동기로 처리합니다.
164+
165+
```
166+
서버 기동 완료 후 백그라운드에서:
167+
└─ 업데이트 서버에 현재 버전 + 채널 정보 전송
168+
├─ 응답 있음 → 최신 버전 정보 캐시, 관리자 대시보드에 표시
169+
└─ 응답 없음 (타임아웃 5초) → 무시, 다음 주기에 재시도
170+
```
171+
172+
채널 종류: `stable` / `beta` / `nightly`
173+
174+
---
175+
176+
## 6. 전체 분기 요약
177+
178+
```
179+
서버 시작
180+
│
181+
├─ 환경변수 오류 → [에러 페이지]
182+
├─ installed.lock 없음 → [Setup 모드]
183+
├─ DB 연결 일시 실패 → [자동 재시도] → 성공 시 계속 / 실패 시 에러 페이지
184+
├─ DB 파일/스키마 손상 → [에러 페이지 + 공장 초기화 버튼]
185+
├─ 마이그레이션 미실행 → [자동 실행] → 성공 시 계속 / 실패 시 에러 페이지
186+
├─ 모듈 로드 실패 → [해당 모듈 비활성화 후 계속]
187+
└─ 모든 단계 통과 → [정상 앱 모드 기동]
188+
```

0 commit comments

Comments
 (0)