ExperionCrawler/.roo/rules-code/glm-code-rules.md

GLM-4.7-Flash 코드 작업 규칙 (ExperionCrawler)

필수 준수 사항

작업 전

• 반드시 task_state.md를 먼저 읽어 진행 상태 파악
• 파일 수정 전 반드시 read_file로 전체 내용 확인 후 수정

코드 수정 원칙

• 요청된 범위만 수정 — 관련 없는 코드 리팩토링 금지
• 빌드 검증: 각 파일 수정 후 dotnet build src/Web/ExperionCrawler.csproj --no-restore -v q 실행
• 빌드 실패 시 즉시 원인 수정 후 재빌드, 다음 항목으로 넘어가지 않음

issues.md 작성 형식

| # | 파일 | 심각도 | 분류 | 내용 | 상태 |
|---|------|--------|------|------|------|
| 1 | src/... | HIGH/MED/LOW | bug/perf/quality/security | 설명 | pending/fixed |

심각도 기준:

• HIGH: 런타임 예외, 데이터 손실, 보안 취약점
• MED: 성능 저하, 잘못된 동작, 예외 미처리
• LOW: 코드 품질, 불필요한 코드, 명명 불일치

클로드 검수를 위한 커밋 규칙

• 각 이슈 수정 완료 시: git add -p 후 이슈 번호 포함 커밋 예: fix(#3): ExperionDbContext null 참조 예외 방어 처리
• 전체 완료 후 REVIEW_REQUEST.md 생성하여 검수 요청

MCP 도구 활용

• search_codebase: 관련 코드 패턴 검색에 적극 활용
• ask_iiot_llm: IIoT/OPC UA 도메인 판단이 필요할 때 사용

---

[CRITICAL] ASP.NET Core 컨트롤러 JSON 직렬화 규칙

배경 (반드시 숙지)

src/Web/Program.cs에 다음 설정이 있다:

opt.JsonSerializerOptions.PropertyNamingPolicy = null;  // PascalCase 그대로 직렬화

이로 인해 C# 속성명이 그대로 JSON 키가 된다.
프론트엔드(app.js)는 모든 JSON 필드를 camelCase로 접근하므로,
PascalCase 키가 오면 모든 값이 undefined 가 된다.

금지 패턴 (절대 사용 금지)

// ❌ shorthand 익명 객체 — C# 속성명(PascalCase)이 JSON 키로 그대로 사용됨
return Ok(new { x.Id, x.TagName, x.NodeId, x.LiveValue });

// ❌ typed 객체를 Ok()에 직접 전달 — PascalCase 직렬화됨
return Ok(result);
return Ok(new MyDto { Id = 1, TagName = "abc" });

올바른 패턴 (항상 명시적 camelCase 매핑)

// ✅ 항상 명시적으로 소문자 키 지정
return Ok(new
{
    id        = x.Id,
    tagName   = x.TagName,
    nodeId    = x.NodeId,
    liveValue = x.LiveValue,
    timestamp = x.Timestamp
});

// ✅ 컬렉션 포함 응답
return Ok(new
{
    total = r.Total,
    items = r.Items.Select(x => new
    {
        id       = x.Id,
        tagName  = x.TagName,
        nodeId   = x.NodeId
    })
});

C# 예약어 처리

class는 C# 예약어이므로 @class를 사용한다. System.Text.Json이 "class"로 정상 직렬화한다:

// ✅ @class → JSON "class"
return Ok(new { id = x.Id, @class = x.Class, name = x.Name });

점검 체크리스트

컨트롤러에서 Ok(...) 또는 return 사용 시:

• 익명 객체의 모든 키가 소문자(camelCase)인가?
• new { x.SomeProp } 형태(shorthand)가 없는가?
• typed record/class를 그대로 반환하지 않는가?
• C# 예약어(class, string 등)에 @ 접두사를 붙였는가?