## 소개
### 시도하고자 했던 것과 그 이유
기사 아이디어 수집부터 원고 작성, 근거 확인, 검증, 승인 요청까지의 과정을 하나의 흐름으로 관리하는 Sean AI 편집국을 만들고자 했다.
기존에는 기사 작성·자료 정리·검증·승인 기록이 여러 문서와 도구에 흩어져 있었다. 특히 AI가 만든 내용을 바로 발행하면 사실 오류나 근거 누락이 생길 수 있으므로, 다음 원칙을 가진 안전한 편집 시스템이 필요했다.
- 기사 상태와 승인 이력을 남긴다.
- 근거·상충 정보·수치의 최신성·원고 연결 여부를 확인한다.
- 승인 전에는 외부 발행을 차단한다.
- AI 자동화 기능도 실제 운영 승인 전까지 비활성화한다.
## 진행 방법
### 사용한 도구와 활용 방법
- Codex: 요구사항 정리, 설계 검토, 코드 작성·수정, 테스트와 오류 분석
- Next.js·TypeScript: 편집국 웹 화면과 API 구현
- Supabase·PostgreSQL: 기사 원장, 근거, 검증 결과, 승인 상태 저장
- Vitest·Playwright·Chromium: 단위·계약·통합·화면 E2E 테스트
- GitHub Pull Request·Actions: 최신 work-dev 기준 통합과 원격 검증
- Markdown·DOCX: 설계서, 추적표, 검증 기록, 사용설명서 작성
### 핵심 프롬프트 전문
아래 프롬프트를 중심으로 작업 범위를 단계별로 나누어 개발을 진행했다.
```text
Sean AI 편집국의 M3.4 실제 업무 동작 연결을 진행해줘.
목표:
실제 기사 1편을 대상으로 화면에서 다음 흐름을 실행한다.
DRAFTED → VERIFYING → DB 기준 검증 기록 → APPROVAL_PENDING
조건:
1. 기사 상태 전환은 DB의 원자 함수와 낙관적 버전 검사를 사용한다.
2. 검증 결과는 DB 원장을 기준으로 근거, 상충, 수치 최신성,
원고 연결 누락, 필수 필드를 다시 계산한다.
3. 승인 요청에는 대상 기사, 버전, 묶음 해시, 권한 검사를 적용한다.
4. SUPABASE_SERVICE_ROLE_KEY가 없으면 실제 작업을 수행하지 말고
명확한 오류를 반환한다.
5. 실제 AI 호출, 외부 발행, 예약 발행, CMS·SNS 쓰기는 이번 범위에서
반드시 차단한다.
6. 화면의 핵심 버튼은 실제 API를 호출하고 결과를 다시 조회해 표시한다.
7. OpenAPI 계약, 추적표, 단위·계약·통합·E2E 시험을 함께 갱신한다.
8. 로컬과 원격 검증 결과를 구분해 보고하고, 검증되지 않은 기능은
완료로 표시하지 않는다.
작업 후 다음을 보고해줘.
- 변경 파일과 핵심 구현 내용
- 상태 전이와 차단 조건
- 시험 결과
- 미완성 범위와 다음 작업
```
### 진행 흐름
1. 먼저 기사 헌법, 업무 프로세스, 데이터 설계, API 설계 문서를 기준으로 삼았다.
2. 정적 합성 화면과 DB 읽기 상태를 구분했다.
3. 화면 버튼을 실제 상태 전환·검증 API에 연결했다.
4. 발행 기능은 의도적으로 403 EXTERNAL_PUBLICATION_DISABLED를 반환하도록 차단했다.
5. 로컬 검증 후 최신 work-dev에서 통합 후보 PR을 만들고 원격 CI로 재검증했다.
### 활용한 화면 캡처
기존 사용설명서 제작 과정에서 확인한 화면 캡처를 사례 자료로 함께 남겼다.
## 결과와 배운 점
### 결과
- 기사 상태 전환 API와 검증 실행 API를 연결했다.
- DRAFTED → VERIFYING → APPROVAL_PENDING 흐름을 구현했다.
- 검증 결과와 승인 요청을 DB 원장에 기록하도록 했다.
- 외부 발행과 실제 AI 호출은 계속 차단했다.
- 로컬에서는 21개 시험 파일과 123개 시험이 통과했다.
- 프로덕션 빌드와 API 기반 E2E가 통과했다.
- 원격에서는 quality, database, Chromium 8개 화면 E2E를 통과한 후보를 만들었다.
### 배운 점과 나만의 꿀팁
1. 화면이 보인다고 기능이 완성된 것은 아니다. 버튼이 안내 메시지만 보여주는지, 실제 DB 작업을 수행하는지 반드시 구분해야 한다.
2. 완료 기준을 먼저 문서로 고정해야 한다. “실제 DB 읽기”, “가짜 기능 없음”, “외부 발행 차단”을 기준으로 정하니 제품 승인 여부를 객관적으로 판단할 수 있었다.
3. 안전한 실패가 중요하다. DB가 연결 되지 않았을 때 합성 데이터를 조용히 바꾸지 않고 오류를 반환하게 한 것이 핵심이었다.
4. 최신 브랜치에서 통합해야 한다. 오래된 로컬 기준으로 작업하면 최신 work-dev의 export나 문서를 덮어쓸 수 있다.
5. 검증 결과를 섞지 않는다. 로컬 성공, 원격 quality 성공, database 실패처럼 검증 종류별 결과를 따로 기록해야 한다.
### 시행착오
- 초기에는 일부 화면 버튼이 실제 작업 없이 안내 메시지만 표시했다.
- 로컬 작업 트리가 원격 최신 기준보다 오래되어 통합 과정에서 기존 export가 덮어써지는 문제가 발생했다.
- GitHub Actions에서 Supabase 포트 충돌로 database 검증이 한 차례 실패했다.
- PR 생성 후 work-dev에 접근성 문서가 추가되어 병합 충돌이 발생했다.
- 기존 PR을 억지로 병합하지 않고 최신 work-dev 기준의 PR #15를 별도로 만들어 안전하게 보류했다.
### 현재 도움이 필요한 부분
현재는 기술적으로 검증된 통합 후보가 있으나, PR #15의 새 CI 검증이 생성되지 않아 work-dev 병합을 보류한 상태다. 다음 단계에서는 다음 항목을 확인해야 한다.
- PR #15의 quality·database·Chromium 검증 재실행
- 실제 DB 연결 화면에서 기사 1편의 전체 흐름 확인
- Sean의 최종 제품 승인
- 승인 후 발행 기능을 별도 범위로 설계
### 앞으로의 계획
1. PR #15의 최신 CI를 확인한다.
2. 실제 Supabase DB 연결 화면에서 상태·검증·승인 요청 흐름을 재현한다.
3. 사용자가 이해하기 쉬운 편집국 운영 화면으로 개선한다.
4. AI 호출과 외부 발행은 별도의 승인·권한·감사 기준을 마련한 뒤 단계적으로 연다.
## 도움 받은 글 (옵션)
이번 사례는 별도의 외부 글보다 다음 내부 기준 문서를 중심으로 진행했다.
- [기사 작성 기획서](sean-editor/docs/01_기사_작성_기획서.md)
- [업무 프로세스와 승인 규칙](sean-editor/docs/04_업무_프로세스와_승인_규칙.md)
- [시스템 구조와 API 설계서](sean-editor/docs/08_시스템_구조와_API_설계서.md)
- [개발과 시험 계획서](sean-editor/docs/10_개발과_시험_계획서.md)
- [M3.4 실제 업무 동작 연결 기록](sean-editor/docs/29_M3.4_실제_업무_동작_연결_기록.md)
> 이 사례의 현재 상태는 “안전한 통합 후보 완성”이다. work-dev 병합과 Q3 최종 제품 승인은 아직 완료하지 않았다.
