20-build-pipeline
暂无简介
- License 许可
- MIT
- 最近更新
- 2026-04-12
- Stars
- ★ 0
- Forks
- 0
03 SKILL.md 正文
20-build-pipeline
Status: ACTIVE
AppliesTo: v10
0. 목적
- 특정 게임이 아니라 도메인/프로토콜이 동적으로 바뀌는 빌드를 표준화한다.
DomainKey와ProtocolGroup이 추가될 때마다 빌드 산출물이 자동으로 늘어나는 구조를 정의한다.- 빌드 입력/설정/산출물 원칙을 명확히 하여 빌더 구현과의 불일치를 제거한다.
1. 적용 범위
적용 대상
framework-ts/tools/builder/build.js기반 빌드 전반- 입력:
{buildInputJson}(예:input/build_input.json) - 설정:
{configJson}(예:input/build_config.json)
비대상
- 런타임 실행 로직
- 에러/로그 표준 (→
skills/devian/80-tools/11-builder/21-build-error-reporting/SKILL.md)
2. 용어
| 용어 | 정의 |
|---|---|
| DomainKey | 도메인 식별자 (예: Game, Common) |
| ProtocolGroup | 프로토콜 그룹 식별자 (예: Game) |
| buildInputJsonDir | buildInputJson 파일이 위치한 디렉토리. 상대경로 해석의 기준 |
| {tempDir} | 빌드 중간 산출물이 생성되는 staging 디렉토리 |
| {configJson} | 빌드 설정 파일 (출력 경로 등 정의) |
3. 빌드 실행
스크립트 실행
bash input/build.sh -[target] <buildInputJson>
직접 실행
node framework-ts/tools/builder/build.js -[target] <buildInputJson>
-[target]은 빌드 타겟 옵션:-all(기본값),-domain-code,-protocol,-domain-data<buildInputJson>은 빌드 입력 JSON 파일 경로 (예:input/build_input.json)- 빌더는
buildInputJson을 읽고, 그 안의configPath로 설정 파일을 로드한다. build.sh에서 target 옵션 생략 시 기본값-all
Build Target 정의 및 Phase 매핑: 03-ssot/SKILL.md § Build Target
4. 입력 파일 스펙 (build json)
최상위 필드
| 필드 | 타입 | 설명 |
|---|---|---|
version |
string | 빌드 스펙 버전 |
configPath |
string | 설정 파일 경로 (buildInputJsonDir 기준 상대경로) |
tempDir |
string | staging 디렉토리 경로 |
domains |
object | 도메인 정의 (map 형태) |
protocols |
array | 프로토콜 정의 (배열 형태) |
domains (map)
{
"DomainKey": {
"contractDir": "Domains/Game",
"contractFiles": ["*.json"],
"tableDir": "Domains/Game",
"tableFiles": ["*.xlsx"]
}
}
- key는
DomainKey(예:"Game","Common") contractDir,tableDir는 buildInputJsonDir 기준 상대경로
protocols (array)
[
{
"group": "Game",
"protocolDir": "./Protocols/Game",
"protocolFiles": ["C2Game.json", "Game2C.json"]
}
]
group은ProtocolGroup식별자
5. 설정 파일 스펙 ({configJson} 예시)
csConfig (C# 출력)
| 필드 | 필수 | 설명 |
|---|---|---|
moduleDir |
✓ | C# 모듈 출력 디렉토리 |
generateDir |
옵션 | C# 생성 코드 디렉토리 (미지정 시 moduleDir 사용) |
tsConfig (TypeScript 출력)
| 필드 | 필수 | 설명 |
|---|---|---|
moduleDir |
✓ | TS 모듈 출력 디렉토리 |
generateDir |
옵션 | TS 생성 코드 디렉토리 (미지정 시 moduleDir 사용) |
upmConfig (UPM 패키지)
| 필드 | 필수 | 설명 |
|---|---|---|
sourceDir |
✓ | UPM 소스 디렉토리 |
packageDir |
✓ | UPM 패키지 출력 디렉토리 |
tableConfig (데이터 출력)
| 필드 | 필수 | 설명 |
|---|---|---|
tableDirs |
✓ | 테이블 출력 디렉토리 배열 |
stringDirs |
✓ | String 테이블 출력 디렉토리 배열 |
CRITICAL:
{configJson}에dataConfig키가 존재하면 빌드가 즉시 FAIL한다 (deprecated). tableConfig의 각 Dir 배열에 대해 해당 데이터 유형이 출력된다.
Sample Package (내부 상수)
샘플 패키지 대상은 com.devian.foundation 하나뿐이며, 빌더 내부 상수(UPM_FOUNDATION)로 고정한다.
{projectConfigJson}에 samplePackages 키는 불필요하며 존재하지 않는다.
staticUpmPackages 키는 금지이며 존재 시 FAIL.
foundationVersion (필수)
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
foundationVersion |
string | ✓ | Foundation 패키지 버전. 빌더가 package.json 동기화 및 SampleSync 경로에 사용. |
sampleFolder (선택)
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
sampleFolder |
string | ❌ | Assets/Samples 루트 경로. 생략 시 SampleSync 단계를 건너뜀. |
"sampleFolder": "../framework-cs/apps/UnityExample/Assets/Samples"
동기화 경로:
{sampleFolder}/{displayName}/{version}/{sampleName}/Runtime/Generated/*.cs
{sampleFolder}/{displayName}/{version}/{sampleName}/Editor/Generated/*.cs
{displayName}:com.devian.foundation/package.json에서 읽음{version}:{projectConfigJson}의foundationVersion에서 읽음{sampleName}:Samples~/하위 폴더명- Generated 코드(
.cs)만 복사,.meta보존, 수동 코드 미접촉 - 대상 Sample 폴더가 없으면 skip
6. 산출물 규칙
원칙
- 도메인/프로토콜 추가에 따라 출력이 늘어남 (동적)
- 개별 도메인 고정표 대신 템플릿 기반으로 산출물 경로가 결정됨
- 정확한 디렉토리/파일 배치는 빌더 구현이 SSOT
Target별 산출물 범위
| Target | 산출물 |
|---|---|
-domain-code |
C# Domain 모듈, TS Domain 모듈, UPM Domain 패키지 |
-protocol |
C# Protocol 모듈, TS Protocol 모듈, Protocol Sample (Samples~/{ProtocolGroup}Protocol/) |
-domain-data |
NDJSON 파일, pb64 파일 (tableConfig dirs) |
-all |
위 모두 |
C# Domain 템플릿
{csConfig.generateDir}/Devian.Domain.{DomainKey}/
TypeScript Domain 템플릿
{tsConfig.generateDir}/devian-domain-{domainKeyLower}/
UPM Domain 템플릿 (Sample-target)
모든 도메인은 com.devian.foundation/Samples~/에 샘플로 생성된다. 독립 UPM 패키지(com.devian.domain.{key})는 생성하지 않는다 (레거시, 삭제 완료).
{upmConfig.sourceDir}/com.devian.foundation/Samples~/{SampleName}/
SampleName 컨벤션: {DomainKey}Package (동적 파생, 하드코딩 금지)
- 빌더 구현:
DevianToolBuilder.getSampleName(domainName, 'Package')→${domainName}Package - 예:
Common→CommonPackage,Sound→SoundPackage,Game→GamePackage
Protocol 템플릿 (동일 원칙)
C#: {csConfig.generateDir}/Devian.Protocol.{ProtocolGroup}/
TS: {tsConfig.generateDir}/devian-protocol-{protocolGroupLower}/
Protocol Sample-target: Protocol은 독립 UPM 패키지가 아니라 com.devian.foundation/Samples~/에 샘플로 생성된다:
{upmConfig.sourceDir}/com.devian.foundation/Samples~/{ProtocolGroup}Protocol/
SampleName 컨벤션: {ProtocolGroup}Protocol (동적 파생, 하드코딩 금지)
- 빌더 구현:
DevianToolBuilder.getSampleName(groupName, 'Protocol')→${groupName}Protocol - 예:
Game→GameProtocol
기존
com.devian.protocol.{suffix}독립 UPM은 레거시 (삭제 대상). 상세 규칙: 03-ssot/SKILL.md § Sample-target Protocol
데이터 산출물
일반 테이블 (tableConfig.tableDirs):
{tableDir}/ndjson/{TableName}.json
{tableDir}/pb64/{TableName}.asset
String Table (tableConfig.stringDirs):
{stringDir}/ndjson/{Language}/{TableName}.json
{stringDir}/pb64/{Language}/{TableName}.asset
- 복수 타겟 가능 (각 Dir 배열의 모든 경로에 복사)
- 도메인 폴더 미사용: 최종 경로에
{DomainKey}폴더 없음 - 동일 파일명 충돌 시 빌드 FAIL (조용한 덮어쓰기 금지)
7. Hard Rules
Staging 규칙
{tempDir}는 staging 전용이며 커밋 금지- 빌드 완료 후 staging에서 최종 위치로 복사됨
필수 필드 FAIL
| 조건 | 결과 |
|---|---|
tableConfig.tableDirs 누락 |
즉시 FAIL |
tableConfig.stringDirs 누락 |
즉시 FAIL |
Forbidden 필드 FAIL
아래 필드가 존재하면 즉시 FAIL 처리됨:
| 위치 | Forbidden 필드 |
|---|---|
{configJson} |
dataConfig (deprecated) |
domains[*] |
csTargetDir |
domains[*] |
tsTargetDir |
domains[*] |
dataTargetDirs |
protocols[*] |
csTargetDir |
protocols[*] |
tsTargetDir |
protocols[*] |
upmName |
protocols[*] |
upmTargetDir |
총 8개 금지 필드. 하나라도 발견되면 빌드가 중단된다.
8. 예시
Game 도메인/프로토콜 예제의 상세 설명은 별도 스킬 문서를 참조한다:
예제 정책:
skills/devian-examples/01-policy/SKILL.md
예제 입력 위치:
devian/input/Domains/Game/*.jsondevian/input/Domains/Game/*.xlsxdevian/input/Protocols/Game/**
Verification Checklist
{configJson}(예:input/build_config.json)에samplePackages키가 존재하지 않는다 (빌더 내부 상수로 이관됨).{configJson}(예:input/build_config.json)에staticUpmPackages키가 존재하지 않는다 (금지 필드).- 빌드 후 각 도메인에 대해
Samples~/{DomainKey}Package/Runtime/Generated/{DomainKey}.g.cs가 존재한다. - 빌드 후 각 프로토콜에 대해
Samples~/{ProtocolGroup}Protocol/Runtime/Generated/*.g.cs가 존재한다. - 빌드 후 위 3, 4의 Packages 미러 경로에도 동일 파일이 존재한다.
framework-cs/upm/com.devian.domain.{key}/디렉토리가 존재하지 않는다 (레거시 삭제 완료).framework-cs/upm/com.devian.protocol.{suffix}/디렉토리가 존재하지 않는다 (레거시 삭제 완료).
Verification Checklist (Dependencies)
framework-cs/upm/**/package.json에서com.devian.core,com.devian.unitydependency가 0개여야 한다.framework-cs/apps/UnityExample/Packages/**/package.json에서도 위 dependency가 0개여야 한다.
9. Reference
빌더 (SSOT)
framework-ts/tools/builder/build.js
입력/설정 예시
input/build_input.json— 빌드 입력 예시input/build_config.json— 설정 파일 예시
관련 스킬
| 스킬 | 설명 |
|---|---|
skills/devian/10-module/03-ssot/SKILL.md |
전체 SSOT 정책 |
skills/devian/80-tools/11-builder/21-build-error-reporting/SKILL.md |
빌드 에러/로그 표준 |
skills/devian-examples/01-policy/SKILL.md |
Game 예제 정책 |
skills/devian-unity/02-unity-bundles/SKILL.md |
UPM 번들/복사 흐름 |