잘나스
# ZALNAS 통합 콘텐츠 플랫폼 전체 개발계획서
> **구현 작업자 안내:** 실제 개발은 기능 단위 계획과 검토 지점을 나누어 진행한다. 각 단계는 테스트 가능한 완성 단위로 구현하고, 선행 단계가 완료 기준을 충족한 뒤 다음 단계로 넘어간다.
- 문서 버전: 1.0
- 작성일: 2026-09-17
- 중앙 원본 시스템: ZALNAS
- 1차 개발 대상: Boardgame Cozyon
- 2차 개발 대상: Event Cozyon
- 문서 목적: 중앙 CMS, 수동 작성, ChatGPT 계정 기반 포스팅봇, 공개 서비스, 사이트별 콘텐츠 사본과 배포 구조를 하나의 실행 계획으로 확정
## 1. 목표와 핵심 결정
ZALNAS를 모든 전문 콘텐츠의 유일한 작성·수정 원본으로 확장한다. 관리자는 ZALNAS에서 직접 콘텐츠를 작성할 수 있고, 포스팅봇도 같은 콘텐츠 모델에 초안을 생성한다. 승인된 콘텐츠는 ZALNAS 공개 서비스에서 조회할 수 있으며, 각 전문 블로그에는 읽기 전용 사본으로 동기화한다.
1차 목표는 Boardgame Cozyon을 중앙 CMS와 포스팅봇에 연결해 실제 서비스하는 것이다. 2차 목표는 1차에서 검증한 공통 플랫폼을 재사용해 Event Cozyon을 추가하는 것이다.
두 블로그의 기반은 서로 다르므로 배포 어댑터를 분리한다.
| 구분 | Boardgame Cozyon | Event Cozyon |
| --- | --- | --- |
| 개발 경로 | `C:\laragon\www\boardgame.cozyon` | `C:\laragon\www\event.cozyon` |
| 개발 URL | `http://boardgame.cozyon.test` | `http://event.cozyon.test` |
| 운영 URL | `https://boardgame.cozyon.kr` | `https://event.cozyon.kr` |
| 공개 기반 | Astro 7 정적 사이트 | ZALNAS 게시판 모듈 기반 PHP 사이트 |
| 콘텐츠 사본 | Boardgame MariaDB의 Post·Game | Event MariaDB의 게시판 글·행사 메타 |
| 공개 반영 | Build API → Astro SSG → atomic release | 게시판 DB 트랜잭션 → 기존 게시판 공개 화면 |
| 소스 배포 | 로컬 검증 → `main` Push → CI 검증 → 운영 자동 배포 | 로컬 검증 → `main` Push → CI 검증 → 운영 자동 배포 |
모든 개발 소스 변경은 예외 없이 `로컬 개발 사이트 수정·검증 → GitHub main Push → 자동 운영 배포` 순서로 진행한다. 운영 서버에서 소스를 직접 수정하지 않는다. ZALNAS, Boardgame과 Event는 각각의 저장소 CI 검증을 통과한 동일 commit을 운영에 자동 배포한다. 세 사이트 모두 별도 테스트 사이트 배포 단계를 두지 않는다.
## 2. 개발 범위
### 2.1 공통 플랫폼
- ZALNAS 중앙 콘텐츠 CMS
- 사이트·콘텐츠·버전·출처·분류·미디어 관리
- 수동 작성과 포스팅봇 초안의 단일 편집·검수 흐름
- ZALNAS 공개 보드게임·이벤트 서비스 메뉴
- 사이트별 읽기 전용 사본 동기화
- Transactional Outbox 기반 전달 보장
- 콘텐츠 버전, 해시, 멱등키와 정합성 검사
- 사이트별 빌드·공개 상태 추적
- ChatGPT 계정 기반 Codex 작업자
- 관리자 승인 전 자동 공개 금지
- 감사 로그, 사용량, 오류와 재시도 기록
### 2.2 1차 Boardgame 범위
- 게시글 유형: `review`, `strategy`, `guide`, `news`, `column`, `feature`
- Game 전문 데이터 작성·수정·버전 관리
- 게시글과 Game·카테고리·태그·작성자 연결
- 보드게임 포스팅봇과 구조화된 JSON 결과
- Boardgame 사본 DB 동기화
- 기존 Boardgame 관리자 페이지 유지와 `replica` 모드 추가
- 기존 Build API·Astro Loader·SEO·검색·RSS·Sitemap 재사용
- 기존 build queue·Docker Builder·atomic release 재사용
- ZALNAS 공개 보드게임 목록·Game·게시글 상세
### 2.3 2차 Event 범위
- 콘서트·공연·행사·지역축제 전문 데이터
- 행사 후보·출처·변경·취소·종료 상태 관리
- 이벤트 포스팅봇과 구조화된 JSON 결과
- Event 게시판 글과 행사 메타의 트랜잭션 동기화
- 기존 게시판 canonical·sitemap·회원·관리자 기능 유지
- ZALNAS 공개 이벤트 목록·행사·게시글 상세
### 2.4 초기 제외 범위
- 승인 없는 완전 자동발행
- ChatGPT 웹 화면의 브라우저 자동 조작
- 사용권한이 불명확한 이미지 자동 수집
- AI 이미지 자동 생성
- 사이트별 DB의 관리자 직접 콘텐츠 수정
- ZALNAS와 개별 사이트 간 DB 계정 공유
- MariaDB 물리 복제
- Boardgame Astro를 Event Cozyon에 적용하는 작업
- Event 게시판을 Astro로 재작성하는 작업
- 모든 사이트 Front-end 저장소를 ZALNAS 저장소로 합치는 작업
## 3. 현재 시스템 기준
### 3.1 ZALNAS
- PHP 8.5.9 기반 명시 라우트 MVC 구조다.
- 요청 흐름은 `public/index.php → config/routes.php → Controller → Service/Model → View/JSON`이다.
- 관리자 메뉴는 `app/Modules/Admin/AdminMenu.php`에서 관리한다.
- 개발은 `http://zalnas.test`, 운영은 `https://zalnas.kr`이다.
- `main` Push는 검증 후 운영 `Deploy Production`으로 연결된다.
- 중앙 CMS 기능은 기존 Board 모듈에 억지로 넣지 않고 별도 콘텐츠 플랫폼 모듈로 구현한다.
### 3.2 Boardgame Cozyon
- PHP CMS와 MariaDB가 콘텐츠 원본이고 Astro 7이 Build API를 읽어 정적 사이트를 생성하는 현재 구조가 있다.
- Post, Game, 분류, 이미지, Build API, build queue, Docker Builder와 atomic release가 구현돼 있다.
- 기존 관리자 `/admin`은 삭제하지 않는다.
- 로컬 개발에서는 기존 작성 기능을 유지하고 운영에서는 ZALNAS 사본 조회·동기화·빌드 관리 중심으로 전환한다.
- 별도 테스트 사이트는 사용하지 않으며, 소스 변경은 로컬 검증과 `main` Push 후 CI를 통과한 동일 commit을 운영에 자동 배포한다.
### 3.3 Event Cozyon
- ZALNAS 게시판 모듈을 실행 원본으로 사용하는 PHP 사이트다.
- 별도 테스트 사이트가 없고 개발과 운영만 존재한다.
- 게시판 제목·본문·카테고리는 기존 게시판 테이블에 저장한다.
- 행사 전용 구조는 별도 메타테이블에 저장하고 기존 게시판 URL과 기능을 유지한다.
- 소스 변경은 로컬 Harness와 GitHub CI를 통과한 `main` commit을 운영에 자동 배포하도록 기존 수동 운영 workflow를 전환한다.
## 4. 목표 아키텍처
```text
관리자 수동 작성 ─┐
├─ ZALNAS 중앙 콘텐츠 플랫폼
포스팅봇 자동작성 ─┘ ├─ 원본 콘텐츠·버전·출처
├─ 공개 서비스 화면
├─ 동기화 Outbox
└─ 작업·사용량·감사 로그
│
┌──────────────────┴──────────────────┐
│ │
▼ ▼
Boardgame 동기화 어댑터 Event 동기화 어댑터
│ │
▼ ▼
Boardgame 읽기 전용 사본 DB Event 게시판 사본 DB
│ │
▼ ▼
Build API → Astro SSG 기존 게시판 공개 화면
│
▼
atomic release
```
### 4.1 책임 경계
| 시스템 | 책임 |
| --- | --- |
| ZALNAS | 콘텐츠 원본, 수동 작성, AI 초안, 검수, 버전, 출처, 미디어, 사이트별 발행 명령 |
| ChatGPT 작업자 | 격리된 입력으로 구조화된 초안 생성, 사용량과 오류 반환 |
| Boardgame 사본 | 승인된 Post·Game 사본 저장, Astro Build API, 빌드·release 상태 |
| Boardgame Astro | 정적 HTML, 검색 index, Sitemap, RSS, SEO와 전문 디자인 |
| Event 사본 | 승인된 게시판 글과 행사 메타 저장, 게시판 서비스와 Event 구조화 데이터 |
ZALNAS 장애 시에도 각 블로그의 마지막 사본과 공개 release는 유지한다. 다만 ZALNAS가 복구될 때까지 신규 작성·수정·발행은 중단한다.
## 5. 콘텐츠 원본과 공개 사본 원칙
1. ZALNAS DB만 콘텐츠 작성 원본이다.
2. 개별 블로그 DB에는 승인된 공개 버전만 저장한다.
3. 개별 블로그의 일반 관리자 계정은 사본 콘텐츠를 수정할 수 없다.
4. 동기화 전용 인증 경로만 사본을 생성·갱신·비공개 처리한다.
5. 동일 콘텐츠는 전역 `content_id`와 증가하는 `version`으로 식별한다.
6. 낮은 버전은 거부하고 같은 버전의 재전송은 성공으로 처리한다.
7. 삭제·공개 취소는 물리 삭제가 아니라 새 tombstone 버전으로 전달한다.
8. ZALNAS 공개 화면과 전문 블로그는 같은 승인 버전을 표시한다.
9. 전문 블로그 공개 성공 전에는 ZALNAS 공개 화면도 해당 버전을 공개 완료로 표시하지 않는다.
10. 콘텐츠와 이미지의 정합성을 함께 관리한다.
## 6. ZALNAS 메뉴와 공개 서비스
### 6.1 관리자 메뉴
```text
보드게임 콘텐츠
├─ 대시보드
├─ 게시글 관리
├─ 게임 정보
├─ 포스팅봇
├─ 미디어
└─ 발행·동기화
이벤트 콘텐츠
├─ 대시보드
├─ 게시글 관리
├─ 행사 정보
├─ 포스팅봇
├─ 미디어
└─ 발행·동기화
```
1차에서는 보드게임 그룹을 완성하고 이벤트 그룹은 노출하지 않는다. 2차에서 동일한 공통 shell을 사용해 이벤트 그룹을 활성화한다.
### 6.2 ZALNAS 사용자 사이트 좌측 서브메뉴
ZALNAS 관리자 메뉴와 별도로 일반 사용자가 보는 사이트 좌측 서브메뉴에 `보드게임` 그룹을 만든다. 서브메뉴의 명칭과 정보구조는 현재 Boardgame Astro 공개 내비게이션과 동일하게 구성한다.
```text
보드게임
├─ 홈
├─ 리뷰
├─ 전략
├─ 가이드
├─ 뉴스
├─ 칼럼
└─ 게임
```
| 메뉴 | ZALNAS 경로 | Boardgame 대표 경로 |
| --- | --- | --- |
| 홈 | `/boardgames/` | `/` |
| 리뷰 | `/boardgames/reviews/` | `/reviews/` |
| 전략 | `/boardgames/strategy/` | `/strategy/` |
| 가이드 | `/boardgames/guides/` | `/guides/` |
| 뉴스 | `/boardgames/news/` | `/news/` |
| 칼럼 | `/boardgames/columns/` | `/columns/` |
| 게임 | `/boardgames/games/` | `/games/` |
좌측 서브메뉴는 기존 ZALNAS `MenuService`와 서브메뉴 그룹 동작을 사용한다. 현재 항목이 속한 `보드게임` 그룹이 자동으로 열리고, 링크와 화면의 현재 메뉴 상태가 일치해야 한다. `feature` 콘텐츠는 Boardgame Astro 현재 공개 내비게이션에 독립 메뉴가 없으므로 좌측 서브메뉴에 새 항목을 추가하지 않고 홈·관련 콘텐츠 영역에서 노출한다.
2차에서는 같은 원칙으로 사용자 사이트 좌측 서브메뉴에 `이벤트` 그룹을 추가한다.
```text
이벤트
├─ 홈
├─ 콘서트
├─ 공연
├─ 행사
└─ 지역축제
```
ZALNAS 공개 화면은 중앙 DB의 `published` 버전을 읽는다. Boardgame과 Event 전문 사이트가 검색엔진 대표 주소이며, ZALNAS의 동일 전문 페이지는 전문 사이트 URL을 canonical로 사용한다. ZALNAS 목록은 통합 탐색 허브 역할을 하고 전문 사이트로 이동하는 링크를 제공한다.
### 6.3 편집 화면 공통 원칙
- 수동 작성과 포스팅봇 초안은 같은 편집 화면을 사용한다.
- 출처와 생성 초안을 나란히 비교한다.
- 자동 저장 대신 명시적 버전 저장을 기본으로 한다.
- 현재 원본 버전, 사이트 사본 버전과 공개 release를 한 화면에 표시한다.
- 미리보기는 저장되지 않은 입력을 안전하게 정제한 뒤 표시한다.
- 관리자 승인 없이 `published` 상태로 전환하지 않는다.
## 7. 중앙 데이터 모델
ZALNAS에는 다음 테이블을 순서대로 추가한다. 실제 컬럼명은 기존 DB 명명 규칙을 따르되 역할과 제약은 유지한다.
| 테이블 | 역할 |
| --- | --- |
| `content_sites` | `boardgame`, `event` 사이트 식별과 공개 URL·활성 상태 |
| `content_items` | 콘텐츠 전역 ID, 사이트, 유형, 현재 상태와 현재 버전 |
| `content_versions` | 제목, 요약, 본문, SEO, 승인된 불변 버전 |
| `content_sources` | 공식 출처 URL, 확인일, 출처 유형과 내용 지문 |
| `content_taxonomies` | 사이트별 카테고리·태그 |
| `content_taxonomy_links` | 콘텐츠와 분류 관계 |
| `media_assets` | 원본, 파생본, 해시, 크기, alt, caption, credit, license |
| `content_media_links` | 대표·본문·OG 이미지 관계 |
| `content_prompt_versions` | 사이트와 글 유형별 프롬프트 버전 |
| `content_bot_jobs` | 생성 작업과 상태·재시도·시간 제한 |
| `content_bot_usage_logs` | 모델, 토큰, 실행시간과 오류 |
| `content_outbox` | 승인된 버전의 사이트별 전달 작업 |
| `content_replica_states` | 사이트 사본 버전, 해시, 응답과 확인 시각 |
| `content_build_jobs` | 사이트 빌드·공개 release 상태 |
| `boardgame_games` | 보드게임 전문 구조화 데이터 |
| `boardgame_content_games` | 게시글과 Game 관계 |
| `event_events` | 행사 일정·장소·예매·상태 정보 |
### 7.1 공통 식별자
- `content_id`: 환경 간에 바뀌지 않는 UUID 또는 ULID
- `version`: 콘텐츠별 1부터 증가하는 정수
- `schema_version`: 전송 payload 계약 버전
- `content_hash`: 정규화된 공개 payload의 SHA-256
- `idempotency_key`: `{site_key}:{content_id}:{version}`
- `source_kind`: `human` 또는 `posting_bot`
- `status`: `draft`, `review`, `approved`, `syncing`, `published`, `unpublished`, `archived`
### 7.2 Boardgame 전문 데이터
- 한국어 제목, 원제와 별칭
- 퍼블리셔, 디자이너, 아티스트와 출시년도
- 최소·최대 인원, 추천 인원, 플레이 시간과 연령
- 난이도, 상호작용, 운, 협상과 다운타임
- 카테고리, 메커니즘, 테마와 언어 의존도
- 확장판 관계
- 편집부 평가, 장점과 단점
- 공식 URL, BGG ID와 동영상 식별자
- Cover, Hero, Gallery와 OG 이미지
### 7.3 Event 전문 데이터
- 행사명과 행사 유형
- 시작·종료 일시와 시간대
- 회차
- 장소명, 주소와 지역
- 가격과 예매·참여 방법
- 관람 연령
- 주최·주관과 문의처
- 공식 URL과 확인일
- 예정·진행·종료·취소 상태
- 근거 출처와 마지막 검증 시각
## 8. 콘텐츠 생명주기
```text
자료 등록
↓
수동 작성 또는 포스팅봇 초안
↓
draft
↓
관리자 검수
↓
review
↓
승인 버전 고정
↓
approved
↓
Outbox 전달과 사이트 사본 저장
↓
syncing
↓
전문 사이트 공개 확인
↓
published
```
수정은 기존 버전을 덮어쓰지 않고 새 버전을 만든다. 공개 취소와 삭제도 새 버전으로 기록해 모든 사본에서 같은 상태를 재현할 수 있게 한다.
## 9. ChatGPT 계정 기반 포스팅봇
ChatGPT 웹 브라우저나 쿠키를 자동 조작하지 않는다. 신뢰할 수 있는 전용 작업자에서 공식 Codex CLI에 ChatGPT 계정으로 로그인하고 `codex exec` 비대화형 실행을 사용한다.
```text
ZALNAS 작업 대기열
↓ HTTPS
격리된 전용 작업자
↓
codex exec --ephemeral --json --output-schema
↓
도메인 JSON Schema 검증
↓
ZALNAS 초안·사용량 반환
```
### 9.1 실행 원칙
- 초기에는 사용자의 ChatGPT 계정으로 로그인한 신뢰 PC 또는 비공개 작업자를 사용한다.
- 완전 무인 운영이 필요하고 지원되는 ChatGPT 워크스페이스를 사용하는 경우 서비스 계정과 만료 가능한 접근 토큰을 검토한다.
- 작업자는 원문 자료만 포함된 임시 디렉터리에서 실행한다.
- 기본 read-only sandbox를 사용한다.
- 저장소, DB 비밀번호, 배포 SSH 키와 운영 secret에 접근시키지 않는다.
- JSON Schema를 통과한 결과만 ZALNAS 초안으로 저장한다.
- 인증 만료, 사용 제한과 schema 오류는 자동 공개하지 않고 관리자에게 표시한다.
- 초기 동시 실행 수는 1개로 제한한다.
### 9.2 포스팅봇 공통 단계
1. 공식·허용 출처 수집과 중복 후보 탐지
2. 사실 필드 추출과 출처 연결
3. 본문·요약·SEO 통합 작성
4. 구조·금칙어·출처·사실 일치 검사
5. 관리자 검수와 수정
6. 승인 버전 생성
### 9.3 도메인별 Schema
- Boardgame Schema: Post 공통 필드, Game 전문 필드, 관련 Game, 이미지·SEO·분류
- Event Schema: 게시글 공통 필드, 행사 일정·장소·가격·예매·상태·출처
- 확인하지 못한 값은 추정하지 않고 `null`과 검수 경고로 반환한다.
### 9.4 사용량과 운영 기록
- 작업 ID와 콘텐츠 ID
- 시작·종료 시각
- 사용 모델
- 입력·캐시·출력 토큰
- 재시도 횟수
- 실행 결과와 안전하게 정리한 오류
- 프롬프트·Schema 버전
- 작업자 인증 상태
- 관리자 수정량과 승인 결과
정확한 달러 비용 계산은 ChatGPT 계정 방식의 1차 범위에서 제외한다.
## 10. 사본 동기화와 정합성
### 10.1 Transactional Outbox
승인 버전과 `content_outbox` 행을 같은 DB 트랜잭션으로 저장한다. 별도 Worker가 대기 작업을 인수해 대상 사이트에 전송한다. 원본 저장 성공 후 전달 작업이 사라지는 이중 쓰기 문제를 방지한다.
### 10.2 동기화 계약
```json
{
"siteKey": "boardgame",
"contentId": "01K5EXAMPLE00000000000000",
"contentVersion": 7,
"contentType": "review",
"status": "published",
"schemaVersion": "1.0",
"contentHash": "sha256:9d5f4b67f486ab4c3032f23bd47f28e5357f781e571555fbf4d947922b4d8f7a",
"idempotencyKey": "boardgame:01K5EXAMPLE00000000000000:7",
"payload": {
"slug": "catan-review",
"title": "카탄 리뷰",
"status": "published"
}
}
```
### 10.3 수신 규칙
- 같은 멱등키의 재요청은 기존 결과를 반환한다.
- 사본보다 낮은 버전은 `409 stale_version`으로 거부한다.
- 같은 버전인데 해시가 다르면 `409 hash_conflict`로 중단한다.
- 본문·전문 메타·관계는 하나의 DB 트랜잭션으로 저장한다.
- 성공 응답에는 사본 버전, 해시와 사이트 로컬 식별자를 포함한다.
- 사본 저장이 성공한 뒤에만 Build 또는 공개 확인을 시작한다.
### 10.4 정합성 검사
사이트별 manifest는 `content_id`, 최신 버전, 상태와 해시를 반환한다. ZALNAS는 발행 직후, 빌드 직전과 하루 1회 manifest를 비교한다.
- 누락된 콘텐츠 재전송
- 오래된 버전 재전송
- 해시 불일치 차단과 관리자 경고
- 원본에서 비공개된 사본 tombstone 재전송
- 실패 반복 작업을 dead-letter 상태로 분리
## 11. 미디어 이중화
ZALNAS가 원본 이미지와 저작권 메타데이터를 관리한다. 공개 사이트가 ZALNAS 장애에 의존하지 않도록 승인된 콘텐츠의 이미지를 사이트별 영구 저장소에 복제한다.
- 원본 파일은 비공개 저장
- 공개 파생본은 WebP 우선
- 파일 해시와 크기 검증
- alt, caption, credit, source URL과 license 필수 관리
- 사이트 사본 URL을 payload에 기록
- 콘텐츠 공개 전에 필수 이미지 복제 완료 확인
- 이미지 복제 실패 시 텍스트만 발행할지 관리자 선택
Boardgame은 기존 `/uploads` 영구 volume과 이미지 검증 구조를 재사용한다. Event는 기존 게시판·에디터 업로드 저장소와 충돌하지 않는 사이트 전용 동기화 경로를 사용한다.
## 12. 1차 개발 - Boardgame Cozyon
### 12.1 목표
ZALNAS에서 보드게임 게시글과 Game을 수동 또는 포스팅봇으로 작성하고, 관리자 검수 후 Boardgame 사본 DB로 동기화해 Astro 사이트에 공개한다.
### 12.2 작업 패키지 1 - 중앙 콘텐츠 기반
**ZALNAS 주요 파일 후보**
- Modify: `config/routes.php`
- Modify: `app/Modules/Admin/AdminMenu.php`
- Create: `migrations/20260917_content_platform.sql`
- Create: `app/Models/ContentModel.php`
- Create: `app/Models/ContentVersionModel.php`
- Create: `app/Services/Content/ContentWorkflowService.php`
- Create: `app/Services/Content/ContentValidationService.php`
- Create: `scripts/tests/content_platform_schema_test.php`
- Create: `scripts/tests/content_workflow_test.php`
**구현·검증 순서**
- [ ] 스키마 계약 테스트를 먼저 추가하고 신규 테이블 부재로 실패하는지 확인한다.
- [ ] 공통 테이블 migration과 명시적 rollback SQL을 작성한다.
- [ ] 초안 생성, 버전 저장, 검수, 승인과 공개 상태 전이를 구현한다.
- [ ] 관리자 승인 없이 `published`로 갈 수 없음을 테스트한다.
- [ ] 같은 콘텐츠의 버전 증가와 불변 승인 버전을 테스트한다.
### 12.3 작업 패키지 2 - 보드게임 전문 모델
**ZALNAS 주요 파일 후보**
- Create: `app/Models/BoardgameGameModel.php`
- Create: `app/Services/Content/BoardgameSchemaService.php`
- Create: `app/Controllers/AdminBoardgameContentController.php`
- Create: `app/Views/admin/content/boardgame/posts.php`
- Create: `app/Views/admin/content/boardgame/post-form.php`
- Create: `app/Views/admin/content/boardgame/games.php`
- Create: `app/Views/admin/content/boardgame/game-form.php`
- Create: `scripts/tests/boardgame_content_schema_test.php`
**구현·검증 순서**
- [ ] 기존 Boardgame Post·Game 필드를 기준으로 검증 계약을 작성한다.
- [ ] 게시글 유형, slug, 상태와 Game 전문 필드 검증을 구현한다.
- [ ] 인원과 플레이 시간 최소·최대 역전 방지를 테스트한다.
- [ ] 게시글과 Game·분류·태그 관계를 저장한다.
- [ ] 기존 Boardgame 관리자 입력 화면의 유용한 구조를 참고하되 ZALNAS 공통 UI 규칙으로 구현한다.
### 12.4 작업 패키지 3 - ZALNAS 공개 보드게임 서비스
**ZALNAS 주요 파일 후보**
- Create: `app/Controllers/BoardgameContentController.php`
- Create: `app/Services/Content/BoardgamePresentationService.php`
- Create: `app/Views/content/boardgame/index.php`
- Create: `app/Views/content/boardgame/game.php`
- Create: `app/Views/content/boardgame/article.php`
- Modify: `config/submenu.default.php`
- Modify: `app/Services/MenuService.php` only if the existing group contract cannot express the required current-state behavior
- Modify: `app/Controllers/SitemapController.php`
- Create: `scripts/tests/boardgame_public_routes_test.php`
- Create: `scripts/tests/boardgame_public_seo_test.php`
- Create: `scripts/tests/boardgame_submenu_contract_test.php`
**공개 경로 후보**
- `/boardgames/`
- `/boardgames/reviews/`
- `/boardgames/strategy/`
- `/boardgames/guides/`
- `/boardgames/news/`
- `/boardgames/columns/`
- `/boardgames/games/{slug}`
- `/boardgames/{type}/{slug}`
ZALNAS 상세 화면은 Boardgame 전문 URL을 canonical로 사용하고, 화면 데이터와 구조화 데이터가 동일한 버전을 사용하도록 검증한다. 사용자 사이트 좌측 `보드게임` 그룹과 홈·리뷰·전략·가이드·뉴스·칼럼·게임 서브메뉴가 Boardgame Astro의 공개 메뉴와 동일한 순서로 표시되는지 테스트한다.
### 12.5 작업 패키지 4 - 보드게임 포스팅봇
**ZALNAS 주요 파일 후보**
- Create: `app/Models/ContentBotJobModel.php`
- Create: `app/Services/Content/BotJobService.php`
- Create: `app/Services/Content/PromptVersionService.php`
- Create: `app/Controllers/AdminBoardgameBotController.php`
- Create: `app/Views/admin/content/boardgame/bot.php`
- Create: `schemas/boardgame-post.schema.json`
- Create: `scripts/tests/content_bot_job_test.php`
- Create: `scripts/tests/boardgame_bot_schema_test.php`
**작업자 주요 파일 후보**
- Create: `workers/content-bot/poll.php`
- Create: `workers/content-bot/run-codex.ps1`
- Create: `workers/content-bot/README.md`
작업자는 ZALNAS의 인증된 작업 API로 작업을 가져오고 결과·사용량·오류만 반환한다. 작업자 자격증명과 ChatGPT 인증정보는 ZALNAS DB와 Git에 저장하지 않는다.
### 12.6 작업 패키지 5 - Boardgame 사본 수신
**Boardgame 주요 파일 후보**
- Modify: `database/migrations/001_initial.sql` 또는 새 migration 추가
- Create: `app/Replication/ReplicaPayload.php`
- Create: `app/Replication/ReplicaStore.php`
- Create: `app/Http/ReplicaApiController.php`
- Modify: `public/index.php`
- Modify: `app/Content/PostRepository.php`
- Modify: `app/Content/GameRepository.php`
- Create: `tests/content-replication.php`
사본에는 `source_content_id`, `source_version`, `content_hash`와 마지막 동기화 시각을 저장한다. 기존 Post·Game·관계와 같은 트랜잭션 안에서 갱신한다.
### 12.7 작업 패키지 6 - Boardgame 관리자 역할 전환
- 로컬 `boardgame.cozyon.test/admin`은 `standalone` 모드를 유지한다.
- 테스트·운영 검증에는 `replica` 모드를 제공한다.
- `replica` 모드에서 일반 관리자 콘텐츠 쓰기 요청은 서버에서 `403`으로 거부한다.
- 콘텐츠 목록은 원본 ID, 버전, 해시와 동기화 상태를 표시한다.
- 동기화 재검사, Astro 재빌드와 release 상태 화면은 유지한다.
- 기존 로그인, 이미지 검증, Build API와 queue 기능을 재사용한다.
### 12.8 작업 패키지 7 - Astro 연계와 공개
- 기존 Build API의 published 필터를 유지한다.
- 기존 Zod Post·Game Schema와 중앙 payload 계약을 맞춘다.
- 사본 저장 성공 후 기존 `build_jobs`에 작업을 등록한다.
- Astro `pnpm run verify`를 통과한 release만 전환한다.
- 실패 시 기존 `current` release를 유지한다.
- ZALNAS에는 사본 저장, build, health check와 공개 URL 결과를 각각 반환한다.
- 코드 배포는 `main` Push 후 CI 검증이 성공해야 같은 commit을 운영에 자동 배포한다.
- 운영 자동 배포 또는 health check 실패 시 기존 운영 소스와 `current` release를 자동 복원한다.
### 12.9 1차 완료 기준
- ZALNAS에서 보드게임 게시글과 Game을 수동 작성할 수 있다.
- ChatGPT 계정 기반 포스팅봇이 같은 초안 모델을 생성한다.
- 관리자 승인 전 외부 공개되지 않는다.
- ZALNAS 공개 메뉴에서 승인된 동일 콘텐츠를 볼 수 있다.
- ZALNAS 사용자 사이트의 좌측 `보드게임` 그룹이 Astro와 동일한 홈·리뷰·전략·가이드·뉴스·칼럼·게임 메뉴를 제공한다.
- Boardgame 사본 DB에 같은 ID·버전·해시가 저장된다.
- 같은 요청을 반복해도 중복 Post·Game이 생기지 않는다.
- Astro build 실패 시 기존 사이트가 유지된다.
- Boardgame 전문 URL의 canonical, JSON-LD, Sitemap, RSS와 검색 index가 일치한다.
- 기존 Boardgame 관리자와 rollback 기능이 유지된다.
- 최소 20건을 같은 날 생성·검수·발행해 오류와 수정률을 확인한다.
## 13. 2차 개발 - Event Cozyon
### 13.1 시작 조건
2차는 다음 조건이 모두 충족된 뒤 시작한다.
- 1차 공통 콘텐츠·버전·Outbox가 운영에서 안정적으로 동작
- Boardgame 20건 시험에서 중복·유실·해시 충돌 없음
- 포스팅봇 인증 만료와 재시도 복구 확인
- 사이트별 Schema와 동기화 어댑터 분리 검증
### 13.2 작업 패키지 1 - 이벤트 전문 모델
**ZALNAS 주요 파일 후보**
- Create: `app/Models/EventContentModel.php`
- Create: `app/Services/Content/EventSchemaService.php`
- Create: `app/Controllers/AdminEventContentController.php`
- Create: `app/Views/admin/content/event/posts.php`
- Create: `app/Views/admin/content/event/event-form.php`
- Create: `schemas/event-post.schema.json`
- Create: `scripts/tests/event_content_schema_test.php`
공통 CMS, 버전, 출처, 미디어와 포스팅봇 queue는 1차 구현을 재사용하고 행사 필드와 검증만 확장한다.
### 13.3 작업 패키지 2 - ZALNAS 공개 이벤트 서비스
**공개 경로 후보**
- `/events/`
- `/events/{event-type}/`
- `/events/{slug}`
공식 출처, 마지막 확인일, 일정, 장소, 가격, 예매와 상태를 표시한다. 종료·취소 행사는 상태를 명확히 표시하고 Event Cozyon 전문 URL을 canonical로 사용한다.
### 13.4 작업 패키지 3 - Event 게시판 동기화 어댑터
**Event 주요 파일 후보**
- Create: `app/Controllers/InternalContentSyncController.php`
- Create: `app/Services/EventContentReplicaService.php`
- Create: `app/Models/EventArticleMetaModel.php`
- Create: `migrations/20260917_event_article_meta.sql`
- Modify: `config/routes.php`
- Modify: `modules/board`의 공개 표현 연계 지점
- Create: `scripts/tests/event_content_sync_test.php`
- Create: `scripts/tests/event_structured_data_test.php`
게시판 제목·본문·카테고리는 기존 `board_data` 구조에 저장하고, 행사 전문 필드는 `event_article_meta`에 분리한다. 두 저장은 하나의 DB 트랜잭션으로 처리한다.
### 13.5 게시판 기반 공개 규칙
- 기존 게시판 글 번호와 URL 호환성을 유지한다.
- ZALNAS `content_id`와 Event `board_data.no` 매핑을 보존한다.
- 같은 멱등키로 새 게시글을 중복 생성하지 않는다.
- 행사 수정은 기존 게시글과 메타를 갱신한다.
- 취소·종료는 기존 URL을 유지하면서 상태를 표시한다.
- 게시판 HTML은 기존 허용 목록으로 정제한다.
- Event JSON-LD와 화면의 일정·장소·상태가 일치해야 한다.
### 13.6 2차 완료 기준
- ZALNAS에서 행사 콘텐츠를 수동 작성할 수 있다.
- 포스팅봇이 출처 기반 행사 초안을 생성한다.
- 승인된 버전이 Event 게시판과 메타테이블에 원자적으로 저장된다.
- 수정·취소·종료가 같은 게시글 URL에 반영된다.
- 재시도로 중복 게시글이 생성되지 않는다.
- ZALNAS와 Event 공개 화면이 같은 콘텐츠 버전을 표시한다.
- canonical, Sitemap과 Event JSON-LD가 실제 화면과 일치한다.
- Event 저장소 Harness와 운영 배포 후 smoke가 통과한다.
- Event 소스는 로컬 검증과 `main` Push 후 CI를 거쳐 운영에 자동 배포된다.
## 14. 동기화 API와 보안
사이트별 인증과 권한을 분리한다. Boardgame token으로 Event 데이터를 쓸 수 없어야 한다.
### 14.1 ZALNAS 작업자 API
```text
POST /api/internal/v1/content-bot/jobs/claim
POST /api/internal/v1/content-bot/jobs/{id}/complete
POST /api/internal/v1/content-bot/jobs/{id}/fail
GET /api/internal/v1/content-bot/schemas/{siteKey}
```
### 14.2 사이트 사본 API
```text
POST /api/internal/v1/replica/contents
GET /api/internal/v1/replica/contents/{contentId}
GET /api/internal/v1/replica/manifest
POST /api/internal/v1/replica/builds
GET /api/internal/v1/replica/builds/{buildId}
```
### 14.3 필수 방어
- 사이트별 HMAC 또는 서비스 token
- 요청 시각과 nonce 검증
- 멱등키 필수
- 요청 본문 크기 제한
- 허용된 site key와 content type만 처리
- HTML 정제
- URL·이미지 host 정책
- 준비된 statement
- 요청과 결과 감사 로그
- secret은 ignored 설정 또는 Docker secret에만 저장
- API 응답에서 내부 경로·SQL·token 숨김
- 네트워크가 가능하면 Docker internal network로 제한
## 15. SEO와 공개 URL 정책
- 전문 사이트를 검색엔진 대표 주소로 유지한다.
- ZALNAS 동일 전문 상세는 전문 사이트 canonical을 출력한다.
- ZALNAS 통합 목록은 자체 canonical을 사용한다.
- Boardgame은 Astro의 Article·Game·Breadcrumb JSON-LD를 유지한다.
- Event는 게시판 화면과 일치하는 Event·Breadcrumb JSON-LD를 출력한다.
- draft, review, preview, 관리자, 내부 API와 검색 조건 페이지는 색인하지 않는다.
- 콘텐츠 공개 취소 시 sitemap과 검색 index에서 제거한다.
- 공개 URL을 변경하면 301 redirect map을 함께 제공한다.
## 16. 저장소와 배포 전략
### 16.1 저장소 분리
| 저장소 | 변경 책임 |
| --- | --- |
| `https://github.com/ShinChoongSoo/zalnas.git` | 중앙 CMS, 공개 허브, 포스팅봇 queue, Outbox와 사이트 어댑터 호출 |
| `https://github.com/ShinChoongSoo/boardgame.cozyon.git` | 사본 수신, 운영 관리자, Build API, Astro와 release |
| `https://github.com/ShinChoongSoo/event.cozyon.git` | 사본 수신, 게시판·행사 메타, 공개 표현 |
사이트 Front-end 코드는 각 저장소에 유지한다. 콘텐츠 데이터는 Git에 저장하지 않는다.
### 16.2 공통 소스 개발·배포 원칙
모든 저장소는 다음 순서를 강제한다.
```text
로컬 개발 사이트 소스 수정
↓
변경과 직접 관련된 로컬 검증
↓
Conventional Commit으로 main 커밋·Push
↓
GitHub Actions 전체 필수 검증
↓
운영 소스 백업과 배포 사전검사
↓
운영 자동 배포
↓
운영 URL health check
↓ 실패
자동 rollback과 실패 보고
```
- 운영 서버에서 직접 소스를 수정하지 않는다.
- 자동 운영 배포는 CI와 환경별 사전검사를 통과한 동일 commit만 사용한다.
- DB migration은 호환 가능한 forward migration을 우선하고 배포 전 백업을 필수로 한다.
- 애플리케이션 배포 실패 시 소스와 release를 복원하고, 적용 중인 DB migration의 복구 전략을 별도로 실행한다.
- 운영 smoke가 실패하면 배포 성공으로 처리하지 않는다.
- Git에 저장하지 않는 콘텐츠·미디어·secret·runtime 데이터는 소스 동기화로 삭제하거나 덮어쓰지 않는다.
- ZALNAS는 현재 `main` Push 기반 자동 운영 배포를 유지한다.
- Boardgame은 별도 테스트 배포 없이 `main` CI 성공 후 `Deploy Production`을 자동 실행하도록 변경한다.
- Event는 별도 테스트 사이트가 없으므로 `main` Push CI 성공 후 `Deploy Production`을 자동 실행하도록 변경한다.
### 16.3 배포 순서
1차 Boardgame:
```text
Boardgame 사본 API와 migration 구현·검증
↓
Boardgame main Push와 GitHub Actions 검증
↓
운영 백업·사전검사·DB migration
↓
동일 commit 운영 자동 배포·Astro build·rollback 검증과 smoke
↓
ZALNAS 중앙 CMS·포스팅봇·공개 허브 구현
↓
ZALNAS main Push와 운영 자동 배포
↓
운영 통합 smoke
```
2차 Event:
```text
Event 게시판 사본 API·메타 migration 구현
↓
Event 로컬 Harness와 DB 복구 검증
↓
Event main Push
↓
GitHub CI와 운영 자동 배포
↓
ZALNAS 이벤트 모듈 활성화·Push
↓
운영 통합 smoke
```
## 17. 테스트 전략
### 17.1 ZALNAS
- 관리자 권한과 메뉴 접근
- 콘텐츠 상태 전이
- 승인 버전 불변성
- 수동 작성과 포스팅봇의 동일 모델 저장
- 사이트별 Schema 검증
- 출처 필수와 중복 판정
- Outbox 트랜잭션
- 재시도·시간 초과·dead-letter
- 사이트별 token 격리
- 공개 메뉴의 상태 필터와 canonical
- 미디어 해시·저작권 메타 검증
### 17.2 Boardgame
- 사본 API 인증·nonce·멱등성
- 낮은 버전과 해시 충돌 거부
- Post·Game·관계 트랜잭션
- `replica` 모드 관리자 쓰기 거부
- Build API published 필터
- Astro Zod Schema
- 정적 build, 검색, Sitemap, RSS와 JSON-LD
- health check 실패 시 이전 release 복원
### 17.3 Event
- 사본 API 인증·재전송 방지
- 게시판 글·행사 메타 트랜잭션
- 수정·취소·종료 상태
- HTML 정제와 URL 검증
- 동일 멱등키 중복 글 방지
- 게시판 canonical·sitemap 회귀
- Event JSON-LD
### 17.4 통합
- 수동 작성 → 승인 → 사본 → 공개 전체 흐름
- 포스팅봇 → 검수 → 승인 → 공개 전체 흐름
- 응답 유실 후 같은 요청 재전송
- 버전 순서가 뒤바뀐 요청
- 이미지 복제 일부 실패
- 사본 저장 성공 후 Build 실패
- ZALNAS 중단 상태에서 전문 사이트 기존 서비스 유지
- ZALNAS 복구 후 manifest 재조정
- 비밀값이 응답·로그·Git·정적 산출물에 없는지 검사
## 18. 백업과 복구
- DB migration 전 환경별 schema·data 백업을 만든다.
- 콘텐츠 DB와 미디어 snapshot의 시점을 맞춘다.
- ZALNAS 원본, Boardgame 사본과 Event 사본을 별도 백업한다.
- 소스 rollback과 콘텐츠 rollback을 구분한다.
- 승인 버전은 삭제하지 않고 새 버전으로 되돌린다.
- Boardgame Astro는 이전 release symlink 전환으로 복구한다.
- Event는 게시판 DB 복구 SQL과 소스 배포 backup을 함께 준비한다.
- 복구 후 `content_id`, 버전과 해시 manifest를 다시 비교한다.
## 19. 운영 관측과 관리자 지표
- 사이트별 원본·사본 버전 차이
- 동기화 대기·진행·실패 건수
- 평균 동기화 지연
- Build 성공률과 평균 시간
- 마지막 성공 release
- 포스팅봇 성공·실패·재시도
- 평균 토큰과 생성 시간
- 관리자 수정률
- 중복 후보와 차단 건수
- 출처 누락과 오래된 검증일
- 이미지 복제 실패
- 인증 만료와 작업자 상태
## 20. 단계별 실행 순서와 Gate
### 단계 0 - 계약 확정
- 사이트 키, 콘텐츠 유형과 URL 확정
- 중앙·사본 Schema 확정
- canonical 정책 확정
- ChatGPT 계정 유형과 작업자 위치 확정
- 백업·복구 책임 확정
**Gate:** 세 저장소의 현재형 문서와 계약이 모순 없이 일치한다.
### 단계 1 - ZALNAS 공통 CMS 기반
- 공통 DB와 상태 전이
- 관리자 공통 shell
- 미디어·출처·버전
- Outbox와 사본 상태
**Gate:** 수동 초안부터 승인 버전과 Outbox 생성까지 로컬 통합 테스트가 통과한다.
### 단계 2 - Boardgame 전문 CMS와 공개 서비스
- Game과 Post 편집
- ZALNAS 공개 보드게임 화면
- 전문 사이트 canonical
**Gate:** 수동 작성 콘텐츠가 ZALNAS에서 정확히 표시된다.
### 단계 3 - Boardgame 사본과 Astro
- 사본 API
- `replica` 관리자 모드
- 기존 Build API·Astro·release 연결
**Gate:** 같은 버전이 ZALNAS, 사본 DB와 Astro 공개 화면에 표시된다.
### 단계 4 - 보드게임 포스팅봇
- 작업 queue와 전용 작업자
- JSON Schema 출력
- 검수·승인·사용량
**Gate:** 최소 20건의 생성·검수·발행에서 중복과 데이터 유실이 없다.
### 단계 5 - Boardgame 운영 전환
- 운영 백업
- 사본 migration
- CI 성공 commit의 운영 자동 배포
- 통합 smoke와 rollback 확인
**Gate:** 운영 공개와 복구 절차가 실제로 검증된다.
### 단계 6 - Event 전문 CMS와 포스팅봇
- 1차 공통 모듈 재사용
- 행사 Schema·출처·상태
- ZALNAS 공개 이벤트 화면
**Gate:** 행사 초안과 승인 버전 검증이 통과한다.
### 단계 7 - Event 게시판 동기화
- 게시판·메타 트랜잭션
- 수정·취소·종료
- Event JSON-LD
**Gate:** Event 게시판의 기존 기능과 URL 회귀 없이 통합 테스트가 통과한다.
### 단계 8 - Event 운영 전환
- 운영 DB 백업
- 호환 migration과 GitHub 운영 자동 배포
- 통합 smoke와 정합성 검사
**Gate:** 최소 20건 시험과 수정·취소 사례가 정상 처리된다.
## 21. 전체 완료 기준
- ZALNAS가 두 전문 분야 콘텐츠의 유일한 작성 원본이다.
- 수동 작성과 포스팅봇이 같은 콘텐츠·버전·검수 모델을 사용한다.
- ZALNAS 공개 메뉴에서 같은 승인 콘텐츠를 볼 수 있다.
- Boardgame은 읽기 전용 사본과 Astro 정적 release로 서비스한다.
- Event는 읽기 전용 사본과 기존 게시판으로 서비스한다.
- 개별 사이트 관리자에서 원본 콘텐츠를 직접 수정할 수 없다.
- 재시도로 중복 콘텐츠가 생기지 않는다.
- 버전 역전과 해시 충돌을 탐지한다.
- ZALNAS 장애 중에도 마지막 전문 사이트 공개본이 유지된다.
- ZALNAS 복구 후 정합성 검사가 누락 사본을 복구한다.
- 전문 사이트를 SEO 대표 주소로 유지한다.
- 비밀값과 ChatGPT 인증정보가 Git, DB 일반 필드, 로그와 정적 결과물에 노출되지 않는다.
- 각 저장소의 관련 Harness와 운영 smoke가 통과한다.
- DB·미디어·release 복구 절차가 문서화되고 실제 검증된다.
- 모든 소스 변경이 로컬 개발 → GitHub Push → 운영 자동 배포 순서를 따른다.
## 22. 위험과 대응
| 위험 | 대응 |
| --- | --- |
| 중앙 DB 장애 | 사이트별 사본과 마지막 정적 release 유지, 복구 후 manifest 재조정 |
| 이중 쓰기 유실 | Transactional Outbox 사용 |
| 중복 발행 | 멱등키와 사이트별 unique 제약 |
| 버전 순서 역전 | 증가 버전 비교와 낮은 버전 거부 |
| 같은 버전 내용 불일치 | SHA-256 해시 충돌 차단 |
| 이미지 중앙 의존 | 사이트별 미디어 복제 또는 독립 저장소 사용 |
| 사이트별 Schema 결합 | 공통 Core와 Boardgame·Event 어댑터 분리 |
| SEO 중복 | 전문 사이트 canonical, ZALNAS는 통합 허브 역할 |
| ChatGPT 인증 만료 | 작업 중지, 재로그인 상태 표시, 자동 공개 금지 |
| 잘못된 AI 사실 | 공식 출처 필수, 미확인 값 경고, 관리자 승인 |
| Build 실패 | 기존 release 유지와 rollback |
## 23. 구현 문서와 Source of Truth
개발이 시작되면 다음 문서를 현재형 Source of Truth로 분리한다.
- ZALNAS: 중앙 콘텐츠 모델, 상태 전이, 작업자·Outbox와 공개 허브
- Boardgame: 사본 API, `replica` 관리자 모드, Build API와 Astro release
- Event: 게시판 사본 계약, 행사 메타와 공개 표현
- 공통 계약: versioned JSON Schema, 오류 코드, 멱등성, manifest와 해시 규칙
과거 Event 포스팅봇 계획서는 직접 게시판 발행 방식의 역사 자료로 남기고, 실제 구현 판단은 이 통합 계획과 이후 작성할 사이트별 상세 설계를 우선한다.
## 24. 공식 OpenAI 문서 기준
포스팅봇 작업자 구현 전에 아래 공식 문서를 다시 확인한다.
- 인증: https://learn.chatgpt.com/ko-KR/docs/auth
- 비대화형 `codex exec`: https://learn.chatgpt.com/ko-KR/docs/non-interactive-mode
- 서비스 계정: https://learn.chatgpt.com/ko-KR/docs/enterprise/service-accounts
현재 공식 문서 기준으로 Codex CLI는 ChatGPT 로그인과 API 키 로그인을 지원하고, `codex exec`는 JSONL 출력과 JSON Schema 기반 구조화 결과를 지원한다. 서비스 계정은 지원되는 ChatGPT 워크스페이스와 요금제 조건을 확인한 뒤 도입한다.
## 25. 최종 권장안
첫 구현은 Boardgame에 집중한다. ZALNAS의 공통 CMS와 보드게임 전문 편집·포스팅봇·공개 허브를 만든 뒤, Boardgame 사본 DB와 기존 Astro 배포 체계를 연결한다. 이 과정에서 콘텐츠 버전, 사본 동기화, 이미지 복제, 공개 확인과 장애 복구를 실제로 검증한다.
1차가 안정화되면 공통 플랫폼을 수정하지 않고 Event 전문 Schema와 게시판 어댑터를 추가한다. Event Cozyon은 Astro로 바꾸지 않고 기존 ZALNAS 게시판 기반을 유지한다.
```text
1차: ZALNAS 중앙 CMS + Boardgame 전문 모듈 + 포스팅봇
+ Boardgame 사본 DB + Astro 서비스
2차: ZALNAS Event 전문 모듈 + 이벤트 포스팅봇
+ Event 게시판 사본 + 기존 게시판 서비스
```
이 순서는 공통 기반을 한 번만 만들고, 서로 다른 Front-end와 저장 구조를 사이트별 어댑터로 분리해 장기 확장성과 장애 격리를 함께 확보한다.
