800GB 온디바이스 AI 카탈로그의 API 계약과 직렬화 거버넌스: ZeliDesk.Server의 DTO 불변성 설계, 순환 참조 방어([JsonIgnore]), 및 경로 조작(Path Traversal) 0초 차단 아키텍처

// 자식 엔티티: 부모로의 역참조를 무조건 직렬화에서 제외
public class ModelFile
{
    public int Id { get; set; }
    public string ModelId { get; set; } = string.Empty;
    public string FileName { get; set; } = string.Empty;
    public long SizeBytes { get; set; }
    public string Sha256 { get; set; } = string.Empty;

    // Navigation: 부모 ModelInfo로 향하는 순환 참조 원천 봉쇄
    [JsonIgnore]
    public ModelInfo? Model { get; set; }
}

// 부모 엔티티: null인 경우 필드 자체를 JSON에서 완전히 생략
public class ModelInfo
{
    [Key]
    public string Id { get; set; } = string.Empty;
    public string DisplayName { get; set; } = string.Empty;
    public long TotalSizeBytes { get; set; }

    // 목록 조회(GetModels)에서는 Files가 로드되지 않거나 명시적으로 배제될 수 있음
    // null일 경우 "files": null 키 자체를 생성하지 않아 JSON 전송량 30% 절감
    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
    public List<ModelFile>? Files { get; set; }
}

/// <summary>
/// {id}/{relativeName} 경로가 모델 저장 디렉터리 안에 있는지 엄격히 검증한다.
/// ".." 등으로 디렉터리를 벗어나는 경로 탐색(path traversal)을 0초 차단한다.
/// </summary>
private bool TryResolveSafePath(string id, string relativeName, out string fullPath)
{
    fullPath = string.Empty;
    if (string.IsNullOrEmpty(relativeName)) return false;

    // 1. 모델의 합법적인 루트 디렉터리를 절대 경로로 정규화
    string root = Path.GetFullPath(Path.Combine(_storagePath, id));

    // 2. 요청된 상대 경로를 결합한 대상 경로를 절대 경로로 정규화 ('..' 등이 모두 해석됨)
    string candidate = Path.GetFullPath(Path.Combine(_storagePath, id, relativeName));

    // 3. 후보 경로가 모델 루트(root)와 정확히 일치하거나, 루트 바로 하위 디렉터리여야 한다.
    if (!candidate.Equals(root, StringComparison.Ordinal) &&
        !candidate.StartsWith(root + Path.DirectorySeparatorChar, StringComparison.Ordinal))
    {
        return false; // 경계를 벗어난 모든 시도를 즉시 차단
    }

    fullPath = candidate;
    return true;
}

[HttpPost]
[EnableRateLimiting("general")]
public async Task<ActionResult<ModelInfo>> CreateModel([FromBody] CreateModelRequest req)
{
    if (string.IsNullOrWhiteSpace(req.Id))
        return BadRequest(new { error = "모델 ID는 필수입니다." });

    // 저장 시 정규화(lowercase)하므로 중복 검사도 정규화된 ID로 통일
    string newId = req.Id.Trim().ToLowerInvariant();
    if (await _db.Models.AnyAsync(m => m.Id == newId))
        return Conflict(new { error = $"모델 '{newId}'이(가) 이미 존재합니다." });

    var model = new ModelInfo
    {
        Id = newId,
        DisplayName = req.DisplayName,
        Description = req.Description,
        Author = req.Author,
        Format = req.Format,
        QuantType = req.QuantType,
        ParamSize = req.ParamSize,
        Icon = req.Icon,
        CreatedAt = DateTime.UtcNow,
        UpdatedAt = DateTime.UtcNow,
        Files = new List<ModelFile>()
    };

    // 파일 저장소 격리 디렉터리 자동 생성
    string modelDir = Path.Combine(_storagePath, model.Id);
    Directory.CreateDirectory(modelDir);

    _db.Models.Add(model);
    await _db.SaveChangesAsync();

    _logger.LogInformation("모델 등록: {Id} ({DisplayName})", model.Id, model.DisplayName);
    return CreatedAtAction(nameof(GetModel), new { id = model.Id }, model);
}

[HttpPut("{id}")]
[EnableRateLimiting("general")]
public async Task<ActionResult<ModelInfo>> UpdateModel(string id, [FromBody] UpdateModelRequest req)
{
    var model = await _db.Models.FindAsync(id);
    if (model == null)
        return NotFound(new { error = $"모델 '{id}'을 찾을 수 없습니다." });

    // Nullable DTO 패턴: 전송된 필드만 선별적으로 패치
    if (req.DisplayName != null) model.DisplayName = req.DisplayName;
    if (req.Description != null) model.Description = req.Description;
    if (req.Author != null) model.Author = req.Author;
    if (req.Format != null) model.Format = req.Format;
    if (req.QuantType != null) model.QuantType = req.QuantType;
    if (req.ParamSize != null) model.ParamSize = req.ParamSize;
    if (req.Icon != null) model.Icon = req.Icon;
    if (req.Tier != null) model.Tier = req.Tier;
    model.UpdatedAt = DateTime.UtcNow;

    await _db.SaveChangesAsync();
    _logger.LogInformation("모델 수정: {Id}", id);
    return Ok(model);
}