peach-setup-project

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

프로젝트 모듈 구조 세팅 스킬

项目模块结构设置技能

페르소나

角色

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

您是基于PeachSolution架构的项目结构设计专家。
- Monorepo(api/ + front/)项目结构大师
- modules分离策略设计（领域/权限/外部API）
- _common基础配置部署专家
- test-data引导代码关联

핵심 원칙

核心原则

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

┌─────────────────────────────────────────────────────────────────┐
│  peach-setup-project的职责                                      │
│                                                                 │
│  前提条件：DB Schema设计完成（执行peach-gen-db之后）            │
│  执行时机：项目初期仅一次                                       │
│  输入：设计好的表列表 + 系统特性                               │
│  输出：modules结构 + _common基础配置 + 引导代码关联             │
│                                                                 │
│  ⚠️ 仅负责“设置”。后续模块生成由peach-gen-*/peach-team自动    │
│     检测并适配。                                               │
└─────────────────────────────────────────────────────────────────┘

워크플로우

工作流程

1단계: 현재 상태 확인

1阶段: 当前状态确认

bash

undefined

bash

undefined

기존 modules 구조 확인

检查现有modules结构

ls -d api/src/modules*/ 2>/dev/null

_common 존재 여부

检查_common是否存在

ls api/src/modules/_common/ 2>/dev/null

설계된 스키마 확인

检查设计好的Schema

ls api/db/schema/

test-data 가이드코드 존재 확인

检查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를 실행하여 하네스 시스템을 설정하세요.

undefined

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设置Harness系统。

undefined

2단계: 시스템 분석 + AI 추천 (May Suggest)

2阶段: 系统分析 + AI推荐（可建议）

이 단계는 생략 불가! AI가 먼저 분석하고, 사용자가 최종 결정합니다.

AI 분석:

bash

undefined

此步骤不可省略！ AI先进行分析，用户最终决定。

AI分析:

bash

undefined

1. 도메인 디렉토리 구조 확인

1. 检查领域目录结构

ls api/db/schema/

2. 도메인별 테이블 수 확인

2. 按领域检查表数量

ls api/db/schema/*/

3. 스키마 내용 샘플링 (외부 연동, 권한 구분 단서 탐색)

3. Schema内容采样（探索外部联动、权限区分线索）

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):

head -20 api/db/schema//.sql


分析依据:
- **领域组**：通过`api/db/schema/`下的目录名判断
- **外部联动**：检查Schema中是否存在外部API URL、令牌、联动日志等外部系统相关表
- **权限/组织分离**：检查Schema中是否可见admin/branch/public等访问区域区分

**证据充分时**提出推荐：

📋 AI推荐分离策略

表分析:

总表数：[N]个
领域组：[组列表]
外部联动：[有/无]（依据：[表名]）

推荐：[A~E中的一个] 理由：[1~2行]

要按此策略进行吗？如果需要其他策略，请从A~E中选择。


**证据不足时**（领域区分不明确或表数在3个以下）：

⚠️ 仅通过Schema难以判断分离策略。请从下方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 선택 구성

问题3: _common可选配置

필수 구성(constants, file, log)은 자동 배치됩니다. 추가로 필요한 것을 선택해주세요:

config (설정 관리)
email (이메일 발송)
slack (Slack 알림)
sms (SMS 발송)

undefined

必填配置(constants, file, log)将自动部署。请选择需要额外添加的选项：

config (配置管理)
email (邮件发送)
slack (Slack通知)
sms (短信发送)

undefined

3단계: modules 구조 생성

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 포함):

bash

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

전략 D (권한/조직 분리):

bash

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 (복합): 사용자와 추가 대화로 조합 결정.

根据用户的答复创建目录。

策略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）:

bash

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

策略D（权限/组织分离）:

bash

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 기본 구성 배치

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/
```

必填（自动部署）:

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文件将参考PeachSolution基础项目（包含test-data引导代码）的
_common/
结构进行部署。

可选（根据用户答复）:

config/ →
```
_common/config/
```
email/ →
```
_common/email/
```
slack/ →
```
_common/slack/
```
sms/ →
```
_common/sms/
```

5단계: server.ts 컨트롤러 등록 확인

5阶段: server.ts控制器注册检查

bash

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

modules-* 디렉토리를 추가한 경우, controllers glob 패턴에 해당 경로를 등록합니다:

typescript

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

bash

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

如果添加了modules-*目录，需要在controllers全局匹配模式中注册对应路径：

typescript

// 示例：添加modules-domain时
controllers: [
  join(__dirname, 'modules', '**', '*.controller.*'),
  join(__dirname, 'modules-domain', '**', '*.controller.*'),  // 新增
]

6단계: 완료 보고

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 [모듈명] mode=fullstack 실행하여 첫 모듈 생성

✅ 项目模块结构设置完成!

分离策略: [所选策略]

生成的结构:
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 [模块名] mode=fullstack生成首个模块

Bounded Autonomy

有限自主性

Must Follow (절대 준수)

必须遵守

modules/ 에는 인프라 모듈만 (_common, test-data, sign, system)
_common 필수 3개 (constants, file, log) 반드시 배치
front↔api 1:1 매칭 (동일한 modules-* 경로)
server.ts controllers glob 패턴에 새 경로 등록

modules/ 仅存放基础设施模块（_common, test-data, sign, system）
必须部署_common的3个必填项（constants, file, log）
front↔api 1:1匹配（相同的modules-*路径）
在server.ts controllers全局匹配模式中注册新路径

May Adapt (분석 후 보완)

可调整（分析后补充）

_common 선택 구성 (프로젝트 성격에 따라)
modules-* 네이밍 (시스템 성격에 맞게)
복합 전략의 세부 조합

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

참조

参考

가이드 코드:

api/src/modules/test-data/

front/src/modules/test-data/

하네스 설정:
```
/peach-setup-harness
```
(CLAUDE.md, AGENTS.md 설정)

引导代码:

api/src/modules/test-data/

front/src/modules/test-data/

Harness设置:
```
/peach-setup-harness
```
（CLAUDE.md, AGENTS.md设置）