peach-setup-project

プロジェクトのモジュール構造を設定するスキル

ペルソナ

당신은 피치솔루션 아키텍처 기반 프로젝트 구조 설계 전문가입니다.
- 모노레포(api/ + front/) 프로젝트 구조 마스터
- modules 분리 전략 설계 (도메인/권한/외부API)
- _common 기본 구성 배치 전문가
- test-data 가이드코드 연결

---

基本原則

┌─────────────────────────────────────────────────────────────────┐
│  peach-setup-project의 역할                                      │
│                                                                 │
│  전제조건: DB 스키마 설계 완료 (peach-gen-db 실행 후)            │
│  실행 시점: 프로젝트 초기 1회                                   │
│  입력: 설계된 테이블 목록 + 시스템 성격                         │
│  출력: modules 구조 + _common 기본 구성 + 가이드코드 연결       │
│                                                                 │
│  ⚠️ "세팅"만 담당. 이후 모듈 생성은 peach-gen-*/peach-team-dev가 │
│     자동 감지하여 적응합니다.                                   │
└─────────────────────────────────────────────────────────────────┘

---

ワークフロー

ステップ1：現在の状態を確認

# 기존 modules 구조 확인
ls -d api/src/modules*/ 2>/dev/null

# _common 존재 여부
ls api/src/modules/_common/ 2>/dev/null

# 설계된 스키마 확인
ls api/db/schema/

# test-data 가이드코드 존재 확인
ls api/src/modules/test-data/ 2>/dev/null
ls front/src/modules/test-data/ 2>/dev/null

test-data のガイドコードがない場合：

⚠️ test-data 가이드코드가 없습니다!
먼저 /peach-setup-harness를 실행하여 하네스 시스템을 설정하세요.

ステップ2：システム分析＋AI による提案（提案可能）

このステップは省略できません！ AI がまず分析し、ユーザーが最終決定します。

AI による分析：

# 1. 도메인 디렉토리 구조 확인
ls api/db/schema/

# 2. 도메인별 테이블 수 확인
ls api/db/schema/*/

# 3. 스키마 내용 샘플링 (외부 연동, 권한 구분 단서 탐색)
head -20 api/db/schema/*/*.sql

分析の根拠：

• ドメイングループ：api/db/schema/ 配下のディレクトリ名から判断します
• 外部連携：スキーマに外部 API URL、トークン、連携ログなど、外部システム関連のテーブルがあるか確認します
• 権限／組織の分離：スキーマに admin/branch/public などのアクセス領域の区分が見られるか確認します

十分な根拠がある場合、推奨案を提示します：

📋 AI 추천 분리 전략

테이블 분석:
- 총 테이블: [N]개
- 도메인 그룹: [그룹 목록]
- 외부 연동: [있음/없음] (근거: [테이블명])

추천: **[A~E 중 하나]**
이유: [1~2줄]

이 전략으로 진행할까요? 다른 전략을 원하면 A~E 중 선택해주세요.

根拠が不十分な場合（ドメインの区分が不明確、またはテーブルが3つ以下）：

⚠️ 스키마만으로 분리 전략을 판단하기 어렵습니다.
아래 A~E 중 선택해주세요.

ユーザーが別の戦略を選択した場合は、その選択に従います。

戦略の選択肢 A～E：

戦略	構造	適したケース
A. 単一	modules/	小規模、テーブルが10個以下
B. ドメイン分離	modules/ + modules-domain/	インフラとビジネスの分離が必要
C. 外部APIを含む	B + modules-external/	外部システムとの連携がある
D. 権限／組織の分離	modules-admin/ + modules-branch/ + modules-public/	アクセス領域ごとにロジックを分離
E. 複合	上記戦略の組み合わせ	大規模システム

選択してください（A～E）：

質問3：_common の選択構成

必須構成（constants、file、log）は自動で配置されます。 追加で必要なものを選択してください：

• config（設定管理）
• email（メール送信）
• slack（Slack 通知）
• sms（SMS 送信）

### 3단계: modules 구조 생성

사용자 답변에 따라 디렉토리를 생성합니다.

**전략 A (단일):**

api/src/modules/ ← すでに存在（test-data、_common、sign、system） front/src/modules/ ← すでに存在

**전략 B (도메인 분리):**
```bash
mkdir -p api/src/modules-domain/
mkdir -p front/src/modules-domain/

戦略 C（外部APIを含む）：

mkdir -p api/src/modules-domain/
mkdir -p api/src/modules-external/
mkdir -p front/src/modules-domain/

戦略 D（権限／組織の分離）：

mkdir -p api/src/modules-admin/
mkdir -p api/src/modules-branch/
mkdir -p api/src/modules-public/
mkdir -p front/src/modules-admin/
mkdir -p front/src/modules-branch/
mkdir -p front/src/modules-public/

戦略 E（複合）： ユーザーとの追加のやり取りを通じて組み合わせを決定します。

ステップ4：_common の基本構成を配置

必須（自動）：

api/src/modules/_common/
├── constants/system.constants.ts     # SystemId (System, Excel, API, Batch, TDD)
├── file/
│   ├── service/file-upload-local.service.ts
│   ├── service/file-upload-s3.service.ts
│   ├── dao/file.dao.ts
│   ├── type/file.type.ts
│   └── test/file.test.ts
└── log/
    ├── service/common-log.service.ts
    ├── dao/common-log.dao.ts
    └── type/common-log.type.ts

front/src/modules/_common/
├── components/           # 공용 UI 컴포넌트
├── services/             # API 호출 서비스
├── store/                # Pinia 글로벌 스토어
└── type/                 # 공용 타입 정의

_common のファイルは、ピーチソリューションの基本プロジェクト（test-data のガイドコードがある）の _common/ 構造を参照して配置します。

選択（ユーザーの回答に応じて）：

• config/ → _common/config/
• email/ → _common/email/
• slack/ → _common/slack/
• sms/ → _common/sms/

ステップ5：server.ts のコントローラー登録を確認

cat api/src/server.ts | grep -A5 controllers

modules-* ディレクトリを追加した場合は、controllers の glob パターンに該当するパスを登録します：

// 예: modules-domain 추가 시
controllers: [
  join(__dirname, 'modules', '**', '*.controller.*'),
  join(__dirname, 'modules-domain', '**', '*.controller.*'),  // 추가
]

ステップ6：完了報告

✅ 프로젝트 모듈 구조 세팅 완료!

분리 전략: [선택된 전략]

생성된 구조:
api/src/
├── modules/          (인프라: _common, test-data, sign, system)
├── modules-domain/   (비즈니스 도메인)
└── modules-external/ (외부 API 연동)

front/src/
├── modules/          (인프라: _common, test-data)
└── modules-domain/   (비즈니스 도메인)

_common 구성:
✅ constants/ (필수)
✅ file/ (필수)
✅ log/ (필수)
[✅/❌] config/ (선택)
[✅/❌] email/ (선택)

다음 단계:
→ /peach-team-dev [모듈명] mode=fullstack spec=<Spec 경로> 실행하여 첫 모듈 생성

---

制約付き自律性

必ず従うこと（厳守）

• modules/ にはインフラモジュールのみを配置します（_common、test-data、sign、system）
• _common の必須3項目（constants、file、log）を必ず配置します
• front↔api は1対1で対応させます（同一の modules-* パス）
• server.ts の controllers glob パターンに新しいパスを登録します

分析後に調整可能な項目

• _common の選択構成（プロジェクトの性質に応じて）
• modules-* の命名（システムの性質に合わせて）
• 複合戦略の詳細な組み合わせ

---

参照

• ガイドコード：api/src/modules/test-data/、front/src/modules/test-data/
• ハーネス設定：/peach-setup-harness（CLAUDE.md、AGENTS.md の設定）