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 推荐（May Suggest）

此步骤不可跳过！ 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 文件参考 Peach Solution 基础项目（含 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 一一对应（使用相同的 modules-* 路径）
• 在 server.ts 的 controllers glob 模式中注册新路径

可灵活调整（分析后补充）

• _common 可选配置（根据项目特点）
• modules-* 命名（根据系统特点）
• 复合策略的具体组合

---

参考

• 指南代码：api/src/modules/test-data/、front/src/modules/test-data/
• Harness 配置：/peach-setup-harness（CLAUDE.md、AGENTS.md 配置）