22-generated-integration

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

Purpose

generated 산출물을 프로젝트에 통합할 때의 소유권/폴더/수정 금지 규칙을 정의한다.

이 문서는 "generated를 어떻게 취급할지"만 말한다. 실제 생성 파일 목록은 런타임/제너레이터 코드를 정답으로 본다.

런타임 참조 정책 (Hard Rule)

생성물이 런타임을 참조할 때는 using Devian;만 사용한다.

금지 패턴: 생성물에서 분리된 런타임 하위 네임스페이스 참조 금지. 빌더/제너레이터가 런타임 참조를 생성할 때 using Devian;만 사용해야 한다.

Ownership

• •framework-cs/module/**/*.g.cs, framework-ts/module/**/*.g.ts 는 기계 소유다.
• •사람은 이 파일을 수정하지 않는다.
• •수정이 필요하면 입력(contracts/tables/protocols) 또는 generator 코드 변경으로 해결한다.

Commit Policy

• •generated는 커밋 대상이다.
  • •빌드 없이도 소비자가 타입/codec을 사용할 수 있어야 한다.

Directory Expectations

정확한 출력 루트는 {buildInputJson}의 csConfig/tsConfig가 정본이다.

출력 경로 규칙

생성물 namespace 고정 (Hard Rule): C# 생성물 namespace는 Devian.Protocol.{ProtocolGroup}으로 고정이며, 런타임 모듈 단일화와 무관하게 변경하지 않는다.

도메인 폴더 미사용 (Hard Rule): 최종 경로에 {Domain} 폴더를 생성하지 않는다. 동일 파일명 충돌 시 빌드 FAIL.

권장 구조

framework-cs/
├── module/
│   ├── Devian/                             # 수동 관리 (런타임 모듈)
│   │   └── Devian.csproj
│   ├── Devian.Domain.{DomainKey}/          # 생성 산출물 (기계 소유)
│   │   └── Generated/
│   │       └── {DomainKey}.g.cs
│   └── Devian.Protocol.{ProtocolGroup}/    # 생성 산출물 (기계 소유)
│       ├── Devian.Protocol.{ProtocolGroup}.csproj
│       └── {ProtocolName}.g.cs

framework-ts/
├── module/
│   ├── devian/                             # 수동 관리 (런타임 패키지, @devian/core)
│   ├── devian-domain-{domain}/             # 생성 산출물 (기계 소유)
│   │   ├── Generated/
│   │   │   └── {Domain}.g.ts
│   │   └── index.ts
│   └── devian-protocol-{group}/            # 생성 산출물 (기계 소유)
│       ├── {ProtocolName}.g.ts
│       └── index.ts

{tableDir}/
├── ndjson/
│   └── *.json
└── pb64/
    └── *.asset  # pk 옵션 테이블만

{stringDir}/
├── ndjson/
│   └── {Language}/
│       └── *.json
└── pb64/
    └── {Language}/
        └── *.asset

실제 폴더명/레이아웃은 프로젝트 구성에 따라 달라질 수 있으며, 코드가 정답이다.

TypeScript Module Configuration

generated TS 코드가 @devian/core 모듈을 import하기 위해 paths alias 설정이 필요하다.

framework-ts/tsconfig.json (루트)

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@devian/core": ["./module/devian/src"]
    }
  }
}

번들러 설정

번들러(webpack, vite, esbuild 등) 사용 시 동일한 alias 설정이 필요하다.

Vite 예시 (vite.config.ts):

export default {
  resolve: {
    alias: {
      '@devian/core': path.resolve(__dirname, 'framework-ts/module/devian/src')
    }
  }
}

C# NuGet Dependencies

generated C# 코드는 netstandard2.1을 타겟으로 하며, 일부 NuGet 패키지에 대한 명시적 참조가 필요하다.

필수 패키지

이유

Unity는 System.Text.Json을 기본 제공하지 않으므로, Unity 호환성을 위해 Newtonsoft.Json을 사용한다. Unity는 com.unity.nuget.newtonsoft-json 패키지로 Newtonsoft.Json을 기본 제공한다.

자동 생성 csproj 예시

빌드 도구가 생성하는 Protocol 모듈의 csproj:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.1</TargetFramework>
    <LangVersion>9.0</LangVersion>
    <Nullable>enable</Nullable>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
  </ItemGroup>

  <ItemGroup>
    <ProjectReference Include="..\Devian\Devian.csproj" />
    <ProjectReference Include="..\Devian.Domain.Common\Devian.Domain.Common.csproj" />
  </ItemGroup>
</Project>

Must / Must Not

MUST

• •generated를 import하는 "수동 코드(manual)"는 generated와 분리된 폴더에서 관리한다.
• •{buildInputJson}의 csConfig/tsConfig + config.json의 tableConfig 설계로 산출 충돌을 방지한다.
• •TypeScript 프로젝트는 paths alias를 설정하여 @devian/core 등을 import한다.

MUST NOT

• •generated 파일을 직접 패치해서 '임시로' 문제를 해결하지 않는다.
• •generated 누락/빌드 실패를 숨기기 위해 "임시 stub 코드(Temp.cs 등)"를 추가하지 않는다.
  • •해결은 항상 입력/제너레이터/빌드 체인(예: lock 동기화)에서 해야 한다.

Reference

• •Policy SSOT: skills/devian-core/03-ssot/SKILL.md
• •동작 정본: 런타임/제너레이터 코드