AGENT SKILL

20-build-pipeline

暂无简介

License 许可
MIT
所属仓库
devwinsoft/devian
最近更新
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 경로에 사용.

상세 정책: devian-unity/03-ssot § foundationVersion

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

상세 정책: devian-unity/03-ssot § sampleFolder


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

상세 규칙: 03-ssot/SKILL.md § Sample-target Domain

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/*.json
  • devian/input/Domains/Game/*.xlsx
  • devian/input/Protocols/Game/**

Verification Checklist

  1. {configJson} (예: input/build_config.json)에 samplePackages 키가 존재하지 않는다 (빌더 내부 상수로 이관됨).
  2. {configJson} (예: input/build_config.json)에 staticUpmPackages 키가 존재하지 않는다 (금지 필드).
  3. 빌드 후 각 도메인에 대해 Samples~/{DomainKey}Package/Runtime/Generated/{DomainKey}.g.cs 가 존재한다.
  4. 빌드 후 각 프로토콜에 대해 Samples~/{ProtocolGroup}Protocol/Runtime/Generated/*.g.cs 가 존재한다.
  5. 빌드 후 위 3, 4의 Packages 미러 경로에도 동일 파일이 존재한다.
  6. framework-cs/upm/com.devian.domain.{key}/ 디렉토리가 존재하지 않는다 (레거시 삭제 완료).
  7. framework-cs/upm/com.devian.protocol.{suffix}/ 디렉토리가 존재하지 않는다 (레거시 삭제 완료).

Verification Checklist (Dependencies)

  • framework-cs/upm/**/package.json에서 com.devian.core, com.devian.unity dependency가 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 번들/복사 흐름

04 同仓库更多 Skills