작업 내용 저장

2026-04-23 09:56:08 +00:00
parent 514b49cb98
commit d383c7086f
29 changed files with 1654 additions and 1372 deletions
@@ -0,0 +1,148 @@
+# 0. 문서 상태
+이 문서의 현재 상태와 식별 정보를 기록한다. 문서 추적과 승인 흐름에 필요한 최소 메타데이터를 적는다.
+
+- 상태: confirmed
+- 문서 ID: sdlc-002_20260423_service-token-user-based
+- 이슈명: service-token user-based 소유권
+- 참조 Release: docs/sdlc/sdlc-002_20260423_service-token-user-based/6_release.md
+- 작성 시각(KST): 2026-04-23
+- 마지막 갱신 시각(KST): 2026-04-23
+
+# 1. Release 인계 요약
+Release에서 완료된 핵심 내용을 요약한다. 원본은 6_release.md를 참조하며, 이 섹션은 Operations 작업의 입력 기준선이 된다.
+
+## 이슈 목적
+`bot_principals` / `auth_audit_logs` 테이블을 제거하고, service token을 `auth_tokens` 단일 엔티티로 직접 발급하도록 재구현한다. CLI `pfhub service-token issue <name> --user <username>` 명령으로 사용자 기반 소유권을 명확히 한다.
+
+## 배포 결과 요약
+- 배포 환경: production (Linux/Ubuntu, systemd + uvicorn + Caddy)
+- 배포 완료 시각(KST): {{OPS_DEPLOYED_AT:TBD}}
+- 스모크 테스트 결과: 미완료
+
+## 이월된 오픈 질문 / 리스크
+Release에서 이월된 항목:
+
+- **VC-8~VC-10 (이월)**: 로컬 Docker Compose 환경 기동 후 Justin이 alembic upgrade/downgrade 및 FK 정합성 쿼리 수동 검증 필요. 배포 전 완료 목표.
+- **R-1 (이월, High)**: 운영 DB `bot_principals.owner_user_id IS NULL` 행 존재 시 마이그레이션 FK 위반 가능 — 배포 전 사전 쿼리 확인으로 차단.
+
+# 2. 운영 모니터링
+배포 후 지속적으로 모니터링해야 하는 항목과 기준을 정의한다.
+
+## 모니터링 항목
+| 항목 | 확인 방법 | 임계값 / 이상 기준 | 대응 방안 |
+|------|---------|----------------|---------|
+| 서비스 오류 로그 | `journalctl -u portfoliohub --since "1 hour ago" \| grep -E "ERROR\|CRITICAL"` | ERROR/CRITICAL 로그 1건 이상 발생 | 스택 트레이스 확인 후 장애 대응 절차 진입 |
+| 헬스 체크 응답 | `curl -s http://localhost:8000/health` | HTTP 200 외 응답 또는 응답 없음 | systemd 서비스 상태 확인 (`systemctl status portfoliohub`) 후 재기동 또는 롤백 |
+| 인증 API 정상 응답 | `curl -s -o /dev/null -w "%{http_code}" http://localhost:8000/auth/login -X POST -d '{}'` | 5분 내 비정상 응답(4xx 외 500+) 3회 이상 | 오류 로그 확인 후 롤백 판단 |
+| DB 마이그레이션 상태 | `alembic current` | 최신 리비전(`20260423_0013`) 외 값 표시 | 마이그레이션 재실행 또는 롤백 판단 |
+| bot_principals 테이블 미존재 유지 | `psql -c "\dt bot_principals"` | 테이블이 재생성된 경우 | 마이그레이션 상태 확인 후 이상 여부 조사 |
+
+## 모니터링 담당자
+- Justin
+
+# 3. 운영 절차 (런북)
+이 변경 사항과 관련된 운영 중 발생할 수 있는 상황별 대응 절차를 정의한다.
+
+## 정상 운영 확인 절차
+배포 후 일정 주기로 정상 동작을 확인하는 절차를 기술한다.
+
+1. **일 1회** — `journalctl -u portfoliohub --since "24 hours ago" | grep -E "ERROR|CRITICAL"` 실행. 결과 없음 확인.
+2. **일 1회** — `curl -s http://localhost:8000/health` 실행. `{"status":"ok"}` 응답 확인.
+3. **주 1회** — `alembic current` 실행. 최신 리비전(`20260423_0013`) 적용 상태 확인.
+4. **배포 후 첫 1주** — `pfhub service-token issue --help` 실행. NAME, --user 정상 노출 확인.
+
+## 장애 대응 절차
+이 변경과 관련된 장애가 발생했을 때의 초기 대응 절차를 기술한다.
+
+1. **오류 확인**: `journalctl -u portfoliohub -n 100 --no-pager` 실행. 스택 트레이스 및 오류 메시지 수집.
+2. **헬스 체크**: `curl -s http://localhost:8000/health` 실행. 응답 여부 확인.
+3. **서비스 재기동 시도**: `sudo systemctl restart portfoliohub`. 재기동 후 헬스 체크 재실행.
+4. **롤백 판단**: 재기동 후에도 오류 지속 시 `6_release.md # 3 롤백 조건` 충족 여부 확인.
+5. **롤백 실행** (조건 충족 시):
+   - `sudo systemctl stop portfoliohub`
+   - `alembic downgrade -1`
+   - `git checkout <이전 커밋 해시>`
+   - `sudo systemctl start portfoliohub`
+   - `curl -s http://localhost:8000/health` 확인
+6. **에스컬레이션**: 롤백 후에도 복구 안 되면 에스컬레이션 경로 진입.
+
+## 에스컬레이션 경로
+장애 대응 중 에스컬레이션이 필요한 경우 연락 대상을 기록한다.
+
+- {{OPS_ESCALATION_1:TBD}}
+
+# 4. 운영 중 발생한 이슈
+운영 중 발견된 이슈를 기록한다. 초안 생성 시 비워 두고 운영 중 갱신한다.
+
+- 없음 (운영 중 발견 시 기록)
+
+# 5. 리스크 및 오픈 질문
+Operations 단계에서 새로 식별된 리스크와 오픈 질문을 기록한다.
+
+## 리스크
+- R-1 (High, 이월): 운영 DB `bot_principals.owner_user_id IS NULL` 행 존재 시 마이그레이션 upgrade FK 위반
+  - 완화 방안: 배포 전 체크리스트 쿼리(`SELECT COUNT(*) FROM bot_principals WHERE owner_user_id IS NULL`) 결과 0건 확인 후 배포. NULL 행 발견 시 수동 정리 후 진행.
+- R-2 (Medium, 이월): VC-8~10 수동 DB 검증 미완료 상태로 배포 시 검증되지 않은 DB 변경 적용 위험
+  - 완화 방안: 로컬 Docker Compose 환경에서 Justin이 VC-8~10 완료 확인 후 운영 배포 진행.
+
+## 오픈 질문
+없음.
+
+# 6. 다음 Discovery 환류
+운영 중 발견된 인사이트와 개선 사항을 다음 SDLC Discovery의 입력으로 기록한다.
+
+- 없음 (운영 중 갱신 예정)
+
+# 7. 확인 체크
+Operations 문서가 완성되었는지 확인한다.
+
+- [ ] 모니터링 항목 및 임계값 정의 완료
+  - 기준: 모니터링 항목에 임계값과 대응 방안이 명시되어야 한다 — 5개 항목 정의 완료
+- [ ] 런북(정상 운영/장애 대응 절차) 정의 완료
+  - 기준: 운영 중 발생 가능한 상황에 대한 절차가 1단계 이상 있어야 한다 — 정상 4단계, 장애 6단계 정의 완료
+- [ ] 에스컬레이션 경로 정의 완료
+  - 기준: 장애 시 연락할 담당자가 명시되어야 한다 — `{{OPS_ESCALATION_1:TBD}}` 지정 필요
+- [ ] 다음 Discovery 환류 항목 작성 (없으면 "없음" 기재)
+  - 기준: 현재 "없음" 기재 — 운영 중 발견 시 갱신
+- [ ] Freeze 확정 담당자(CONFIRMED_BY) 지정
+  - 기준: 문서 승인 담당자가 명시되어야 한다 — Justin 지정 완료 예정 (confirm-operation 단계에서 처리)
+
+# 8. 파일 처리 결과
+이 Operations 문서 생성/갱신 결과와 참조 문서를 기록한다.
+
+- 처리 결과: 생성
+- 생성 경로: docs/sdlc/sdlc-002_20260423_service-token-user-based/7_operation.md
+- 참조 문서:
+  - docs/sdlc/sdlc-002_20260423_service-token-user-based/6_release.md
+  - docs/sdlc/sdlc-002_20260423_service-token-user-based/5_verification.md
+  - docs/sdlc/sdlc-002_20260423_service-token-user-based/1_discovery.md
+
+# 9. 사용자 결정 필요 항목 요약
+사용자나 승인자가 결정해야 하는 항목만 모아 정리한다.
+
+## DECIDE
+없음.
+
+## CONFIRM
+- Freeze 확정 담당자(`CONFIRMED_BY`): Justin — confirm-operation 단계에서 처리
+
+## DATA
+- 모니터링 담당자(`OPS_MONITOR_OWNER`): Justin 또는 담당 운영자 지정 필요
+- 에스컬레이션 연락처(`OPS_ESCALATION_1`): 장애 시 연락할 담당자/채널 지정 필요
+- 배포 완료 시각(`OPS_DEPLOYED_AT`): 실제 배포 후 기입
+- 스모크 테스트 결과(`OPS_SMOKE_RESULT`): 배포 후 스모크 테스트 수행 결과 기입
+
+# 10. Operations Freeze
+이 SDLC 주기의 최종 확정 플래그를 기록한다.
+
+## 섹션 참조
+- 운영 모니터링: [# 2. 운영 모니터링](#2-운영-모니터링)
+- 런북: [# 3. 운영 절차 런북](#3-운영-절차-런북)
+- 다음 Discovery 환류: [# 6. 다음 Discovery 환류](#6-다음-discovery-환류)
+
+## 확정 플래그
+- Handoff Decision: 승인
+- Handoff Rationale: 모니터링 안정화 및 런북 완비 후 주기 완료
+- SDLC 주기 완료: true
+- Confirmed By: Justin
+- Confirmed At (KST): 2026-04-23