# Codex 작업 인계서

## 저장소 목적

이 저장소는 PHP/CodeIgniter 4 웹빌더와 Node.js 작업 오케스트레이터를 분리한 Flutter 앱 자동 생성·빌드 플랫폼입니다.

## 먼저 읽을 파일

1. `README.md`
2. `docs/ARCHITECTURE.md`
3. `docs/IMPLEMENTATION_STATUS.md`
4. `docs/INSTALL.md`
5. `database/schema.sql`
6. `web/app/Libraries/AppDefinitionService.php`
7. `orchestrator/src/buildPipeline.js`
8. `flutter_template/overlay/lib/main.dart`

## 변경 원칙

- PHP는 사용자·조직·앱 설정·결제·관리 화면을 담당합니다.
- Node는 긴 작업, Flutter/Xcode/Android 명령, 스토어 업로드만 담당합니다.
- 브라우저 입력으로 셸 명령 문자열을 조립하지 마십시오.
- 앱 설정은 브라우저 준비도 검사와 `AppDefinitionService`, Node `validation.js`에서 함께 검증합니다.
- 빌드 시 `apps.definition_json`을 직접 사용하지 말고 `app_versions` 스냅샷을 사용합니다.
- PHP 트랜잭션이 커밋되기 전에 Node가 외래키 레코드를 조회하게 만들지 마십시오.
- 자격증명 원문을 DB, 로그, 예외 메시지 또는 Git에 남기지 마십시오.
- 기존 기능을 삭제하거나 임의로 단순화하지 말고 전체 흐름을 유지한 상태에서 확장합니다.

## 권장 다음 작업 순서

### 1. 설치 검증

```bash
./scripts/healthcheck.sh
./scripts/validate_source.sh
cd web && composer install
cd ../orchestrator && npm install
```

MariaDB 10.11에 `database/schema.sql`, `database/seed.sql`을 적용하고 `DRY_RUN=true` 상태에서 앱 생성부터 산출물 다운로드까지 확인합니다.

### 2. PG 결제 어댑터

- 사용할 결제사 확정(예: 토스페이먼츠 또는 포트원)
- 서버 승인 API와 웹훅 서명 검증
- 결제 이벤트 멱등성 및 거래 상태 전이
- 요금제 변경 시 `organizations.plan_code`와 구독 기간을 하나의 트랜잭션으로 갱신
- 환불·실패·연체 처리 테스트

### 3. Android 서명 프로필

- `signing_credentials` 테이블 추가
- 앱별 keystore 업로드와 AES-GCM 암호화
- 빌드 작업 중 임시 복호화
- `android/key.properties`와 Gradle signingConfig 주입
- 작업 종료 후 키 파일 삭제

### 4. iOS 서명

- 인증서 `.p12`, 비밀번호, provisioning profile 저장
- 임시 Keychain 생성과 import
- profile UUID 확인
- `ExportOptions.plist` 생성
- 빌드 종료 후 Keychain 및 파일 제거

### 5. 아이콘 업로드 연동

- PHP 업로드 검증
- 공개 웹루트 밖 원본 저장
- `scripts/generate_assets.py` 실행 작업 추가
- 생성 리소스를 Android/iOS 프로젝트에 복사
- 미리보기 및 스토어 아이콘 생성

### 6. 스토어 메타데이터

- 다국어 설명·키워드·카테고리·연령등급 테이블
- 스크린샷 세트 관리
- Google Play listing/images API
- App Store Connect localizations/screenshots API
- 최종 제출 전 사람 승인 단계

## Codex에 사용할 시작 프롬프트

```text
이 저장소는 기존 기능을 모두 유지해야 한다. 먼저 README.md, docs/ARCHITECTURE.md,
docs/IMPLEMENTATION_STATUS.md, database/schema.sql을 읽어라. 변경 전에 관련 PHP,
Node, Flutter 흐름을 추적하고, 수정 후 전체 파일을 제공하며 scripts/validate_source.sh를
통과시켜라. 첫 작업은 Android 서명 프로필을 앱별로 암호화 저장하고 빌드 작업 중에만
복호화하여 key.properties와 Gradle signingConfig를 주입하는 기능이다.
```

## 완료 기준

- 신규 기능의 DB 변경과 롤백 방법 문서화
- 조직·앱 소유권 확인
- CSRF/HMAC/암호화 유지
- 실패·취소·재시도 시 데이터 정합성 유지
- 비밀값 로그 미노출
- 출시된 Android versionCode와 iOS build number 재사용 방지 유지
- PHP/JS/Python 구문 검사와 PHP/Node 스모크 테스트
- DRY RUN 통합 흐름 재검증
- 관련 MD 업데이트