03 Ssot

03-ssot — Data

Status: ACTIVE AppliesTo: v10 ParentSSOT: skills/devian-core/03-ssot/SKILL.md

Scope

이 문서는 DATA 도메인(테이블, Contract, 스토리지) 관련 SSOT를 정의한다.

중복 금지: 공통 용어/플레이스홀더/입력 분리/머지 규칙은 Root SSOT가 정본이며, 이 문서는 재정의하지 않는다.

tableConfig 설정

DATA 도메인의 데이터 출력 타겟은 전역 tableConfig로 설정한다.

"tableConfig": {
  "tableDirs": ["../framework-cs/apps/UnityExample/Assets/Bundles/Tables"],
  "stringDirs": ["../framework-cs/apps/UnityExample/Assets/Bundles/Strings"],
  "soundDirs": ["../framework-cs/apps/UnityExample/Assets/Bundles/Sounds"]
}

필수 규칙:

• tableConfig의 각 Dir 배열은 필수 (빈 배열 허용)
• 빌더가 각 Dir에 대해 ndjson/ 및 pb64/ 하위 디렉토리를 생성
• dataConfig는 금지 (deprecated, 존재 시 빌드 FAIL)
• domains[*].dataTargetDirs는 금지 (존재 시 빌드 실패)

DomainType = DATA

DATA 입력은 {buildInputJson}의 domains 섹션이 정의한다.

Common 필수 (Hard Rule)

Devian v10 프로젝트는 DATA DomainKey로 Common을 반드시 포함한다.

• {buildInputJson}에서 domains.Common은 필수 항목이다.
• 결과로 Common 모듈(C#/TS)은 항상 생성/유지된다:
  • C#: Devian.Domain.Common (프로젝트명)
  • TS: @devian/module-common (폴더명: devian-domain-common)

Common 모듈의 상세 정책은 skills/devian-common/02-module-policy를 참조한다.

필수 개념

• Contracts: JSON 기반 타입/enum 정의
• Tables: XLSX 기반 테이블 정의 + 데이터

입력 경로는 {buildInputJson}이 정본이다:

• domains[Common].contractDir = Domains/Common/contracts
• domains[Common].tableDir = Domains/Common/tables

키 변경 (레거시 호환):

• contractDir (새 키), contractsDir (레거시/금지)
• tableDir (새 키), tablesDir (레거시/금지)

Tables (XLSX) 헤더/데이터 규약

• 최소 4행 헤더를 가진다.
  • Row 1: 컬럼명
  • Row 2: 타입
  • Row 3: 옵션
  • Row 4: 코멘트(해석하지 않음)
• Row 5부터 데이터
• Header Stop Rule: Row1에서 빈 셀을 만나면 그 뒤 컬럼은 무시
• Data Stop Rule: PrimaryKey 컬럼이 비면 즉시 중단

옵션 해석 정책

• PrimaryKey: pk 옵션만 PrimaryKey로 해석한다.
• gen:<EnumName>: gen: 옵션이 선언된 컬럼은 반드시 pk여야 한다.
• group:true (Hard): 테이블당 최대 1개 컬럼만 허용.
• optional:true는 "nullable/optional column" 힌트로만 사용
• 그 외 parser:* 등은 Reserved (있어도 무시 / 의미 부여 금지)

상세 규칙: skills/devian-data/30-table-authoring-rules

DATA 산출물 경로 (정책)

staging:

• {tempDir}/{DomainKey}/cs/Generated/{DomainKey}.g.cs
• {tempDir}/{DomainKey}/ts/Generated/{DomainKey}.g.ts, index.ts
• {tempDir}/{DomainKey}/data/ndjson/{TableName}.json (내용은 NDJSON)
• {tempDir}/{DomainKey}/data/pb64/{TableName}.asset (pk 옵션 있는 테이블만)

final (csConfig/tsConfig/tableConfig 기반):

• {csConfig.generateDir}/Devian.Domain.{DomainKey}/Generated/{DomainKey}.g.cs
• {tsConfig.generateDir}/devian-domain-{domainkey}/Generated/{DomainKey}.g.ts, index.ts
• {tableDir}/ndjson/{TableName}.json (내용은 NDJSON)
• {tableDir}/pb64/{TableName}.asset (pk 옵션 있는 테이블만)

도메인 폴더 미사용 (Hard Rule):

• 최종 경로에 {DomainKey} 폴더를 생성하지 않는다.
• 모든 도메인의 테이블 파일이 동일 디렉토리에 병합된다.
• 동일 파일명 충돌 시 빌드 FAIL (조용한 덮어쓰기 금지).

금지 필드 (Hard Fail):

• domains[*].csTargetDir — 금지, csConfig.generateDir 사용
• domains[*].tsTargetDir — 금지, tsConfig.generateDir 사용
• domains[*].dataTargetDirs — 금지, tableConfig.*Dirs 사용

C# Namespace (Hard Rule)

DATA Domain 생성물의 C# 네임스페이스:

• namespace Devian.Domain.{DomainKey}

예: DomainKey Common → namespace Devian.Domain.Common

TS index.ts Marker 관리 (Hard Rule)

TS devian-domain-*/index.ts는 빌더가 관리하되, 통째 덮어쓰기를 금지한다.

• marker 구간:
  • // <devian:domain-exports> ~ // </devian:domain-exports> — Domain 생성물 export
  • // <devian:feature-exports> ~ // </devian:feature-exports> — features 폴더 export

NDJSON 스토리지 규약

파일 확장자는 .json이지만, ndjson/ 폴더의 파일 내용은 NDJSON(라인 단위 JSON)이다.

상세 규칙: skills/devian-data/34-ndjson-storage

pb64 export 규약 (Hard Rule)

pk 옵션이 있는 테이블만 Unity TextAsset .asset 파일로 export한다.

• 파일명: {TableName}.asset (테이블 단위 1개 파일)
• 저장 형식: Unity TextAsset YAML
• pk 옵션이 없는 테이블은 export 안함

상세 규칙: skills/devian-data/35-pb64-storage

DATA export PK 규칙 (Hard Rule)

DATA export는 PK 유효 row만 포함하며, 유효 row가 없으면 산출물을 생성하지 않는다.

• primaryKey(pk 옵션)가 정의되지 않은 테이블은 ndjson/pb64 파일을 생성하지 않는다.
• primaryKey 값이 비어있는 row는 export 대상에서 제외된다.
• 결과적으로 유효 row가 0개인 경우 파일을 생성하지 않고 [Skip] 로그를 남긴다.

See Also

• Root SSOT — 공통 용어/플레이스홀더/머지 규칙
• Data Policy
• Table Authoring Rules
• NDJSON Storage
• PB64 Storage