ERP-node/.cursor/rules/ai-developer-collaboration-rules.mdc

# AI-개발자 협업 작업 수칙

## 핵심 원칙: "추측 금지, 확인 필수"

AI는 코드 작성 전에 반드시 실제 상황을 확인해야 합니다.

---

## 1. 데이터베이스 관련 작업

### 필수 확인 사항

- ✅ **항상 MCP Postgres로 실제 테이블 구조를 먼저 확인**
- ✅ 컬럼명, 데이터 타입, 제약조건을 추측하지 말고 쿼리로 확인
- ✅ 변경 후 실제로 데이터가 어떻게 보이는지 SELECT로 검증

### 확인 방법

```sql
-- 테이블 구조 확인
SELECT
  column_name,
  data_type,
  is_nullable,
  column_default
FROM information_schema.columns
WHERE table_name = '테이블명'
ORDER BY ordinal_position;

-- 실제 데이터 확인
SELECT * FROM 테이블명 LIMIT 5;
```

### 금지 사항

- ❌ "아마도 `created_at` 컬럼일 것입니다" → 확인 필수!
- ❌ "보통 이렇게 되어있습니다" → 이 프로젝트에서 확인!
- ❌ 다른 테이블 구조를 보고 추측 → 각 테이블마다 확인!

---

## 2. 코드 수정 작업

### 작업 전

1. **관련 파일 읽기**: 수정할 파일의 현재 상태 확인
2. **의존성 파악**: 다른 파일에 영향이 있는지 검색
3. **기존 패턴 확인**: 프로젝트의 코딩 스타일 준수

### 작업 중

1. **한 번에 하나씩**: 하나의 명확한 작업만 수행
2. **로그 추가**: 디버깅이 필요하면 명확한 로그 추가
3. **점진적 수정**: 큰 변경은 여러 단계로 나눔

### 작업 후

1. **로그 제거**: 디버깅 로그는 반드시 제거
2. **테스트 제안**: 브라우저로 테스트할 것을 제안
3. **변경사항 요약**: 무엇을 어떻게 바꿨는지 명확히 설명

---

## 3. 확인 및 검증

### 확인 도구 사용

- **MCP Postgres**: 데이터베이스 구조 및 데이터 확인
- **MCP Browser**: 실제 화면에서 동작 확인
- **codebase_search**: 관련 코드 패턴 검색
- **grep**: 특정 문자열 사용처 찾기

### 검증 프로세스

1. **변경 전 상태 확인** → 문제 파악
2. **변경 적용**
3. **변경 후 상태 확인** → 해결 검증
4. **부작용 확인** → 다른 기능에 영향 없는지

### 사용자 피드백 대응

- 사용자가 "확인 안하지?"라고 하면:
  1. 즉시 사과
  2. MCP/브라우저로 실제 확인
  3. 정확한 정보를 바탕으로 재작업

---

## 4. 커뮤니케이션

### 작업 시작 시

```
✅ 좋은 예:
"MCP로 item_info 테이블 구조를 먼저 확인하겠습니다."

❌ 나쁜 예:
"보통 created_at 컬럼이 있을 것이므로 수정하겠습니다."
```

### 작업 완료 시

```
✅ 좋은 예:
"완료! 두 가지를 수정했습니다:
1. 기본 높이를 40px → 30px로 변경 (ScreenDesigner.tsx:2174)
2. 숨김 컬럼을 created_date, updated_date, writer, company_code로 수정 (TablesPanel.tsx:57)

테스트해보세요!"

❌ 나쁜 예:
"수정했습니다!"
```

### 불확실할 때

```
✅ 좋은 예:
"컬럼명이 created_at인지 created_date인지 확실하지 않습니다.
MCP로 확인해도 될까요?"

❌ 나쁜 예:
"created_at일 것 같으니 일단 이렇게 하겠습니다."
```

---

## 5. 금지 사항

### 절대 금지

1. ❌ **확인 없이 "완료했습니다" 말하기**
   - 반드시 실제로 확인하고 보고
2. ❌ **이전에 실패한 방법 반복하기**
   - 같은 실수를 두 번 하지 않기
3. ❌ **디버깅 로그를 남겨둔 채 작업 종료**
   - 모든 console.log 제거 확인
4. ❌ **추측으로 답변하기**

   - "아마도", "보통", "일반적으로" 금지
   - 확실하지 않으면 먼저 확인

5. ❌ **여러 문제를 한 번에 수정하려고 시도**
   - 한 번에 하나씩 해결

---

## 6. 프로젝트 특별 규칙

### 백엔드 관련

- 🔥 **백엔드 재시작 절대 금지** (사용자 명시 규칙)
- 🔥 Node.js 프로세스를 건드리지 않음

### 데이터베이스 관련

- 🔥 **멀티테넌시 규칙 준수**
  - 모든 쿼리에 `company_code` 필터링 필수
  - `company_code = "*"`는 최고 관리자 전용
  - 자세한 내용: `.cursor/rules/multi-tenancy-guide.mdc`

### API 관련

- 🔥 **API 클라이언트 사용 필수**
  - `fetch()` 직접 사용 금지
  - `lib/api/` 의 클라이언트 함수 사용
  - 환경별 URL 자동 처리

### UI 관련

- 🔥 **shadcn/ui 스타일 가이드 준수**
  - CSS 변수 사용 (하드코딩 금지)
  - 중첩 박스 금지 (명시 요청 전까지)
  - 이모지 사용 금지 (명시 요청 전까지)

---

## 7. 에러 처리

### 에러 발생 시 프로세스

1. **에러 로그 전체 읽기**

   - 스택 트레이스 확인
   - 에러 메시지 정확히 파악

2. **근본 원인 파악**

   - 증상이 아닌 원인 찾기
   - 왜 이 에러가 발생했는지 이해

3. **해결책 적용**

   - 임시방편이 아닌 근본적 해결
   - 같은 에러가 재발하지 않도록

4. **검증**
   - 실제로 에러가 해결되었는지 확인
   - 다른 부작용은 없는지 확인

### 에러 로깅

```typescript
// ✅ 좋은 로그 (디버깅 시)
console.log("🔍 [컴포넌트명] 작업명:", {
  관련변수1,
  관련변수2,
  예상결과,
});

// ❌ 나쁜 로그
console.log("here");
console.log(data); // 무슨 데이터인지 알 수 없음
```

---

## 8. 작업 완료 체크리스트

모든 작업 완료 전에 다음을 확인:

- [ ] 실제 데이터베이스/파일을 확인했는가?
- [ ] 변경사항이 의도대로 작동하는가?
- [ ] 디버깅 로그를 모두 제거했는가?
- [ ] 다른 기능에 부작용이 없는가?
- [ ] 멀티테넌시 규칙을 준수했는가?
- [ ] 사용자에게 명확히 설명했는가?

---

## 9. 모범 사례

### 데이터베이스 확인 예시

```typescript
// 1. MCP로 테이블 구조 확인
mcp_postgres_query: SELECT column_name FROM information_schema.columns
WHERE table_name = 'item_info';

// 2. 실제 컬럼명 확인 후 코드 작성
const hiddenColumns = new Set([
  'id',
  'created_date',  // ✅ 실제 확인한 컬럼명
  'updated_date',  // ✅ 실제 확인한 컬럼명
  'writer',        // ✅ 실제 확인한 컬럼명
  'company_code'
]);
```

### 브라우저 테스트 제안 예시

```
"수정이 완료되었습니다!

다음을 테스트해주세요:
1. 화면관리 > 테이블 탭 열기
2. item_info 테이블 확인
3. 기본 5개 컬럼(id, created_date 등)이 안 보이는지 확인
4. 새 컬럼 드래그앤드롭 시 높이가 30px인지 확인

브라우저 테스트를 원하시면 말씀해주세요!"
```

---

## 10. 요약: 핵심 3원칙

1. **확인 우선** 🔍

   - 추측하지 말고, 항상 확인하고 작업

2. **한 번에 하나** 🎯

   - 여러 문제를 동시에 해결하려 하지 말기

3. **철저한 마무리** ✨
   - 로그 제거, 테스트, 명확한 설명

---

## 11. 화면관리 시스템 위젯 개발 가이드

### 위젯 크기 설정의 핵심 원칙

화면관리 시스템에서 위젯을 개발할 때, **크기 제어는 상위 컨테이너(`RealtimePreviewDynamic`)가 담당**합니다.

#### ✅ 올바른 크기 설정 패턴

```tsx
// 위젯 컴포넌트 내부
export function YourWidget({ component }: YourWidgetProps) {
  return (
    <div
      className="flex h-full w-full items-center justify-between gap-2"
      style={{
        padding: component.style?.padding || "0.75rem",
        backgroundColor: component.style?.backgroundColor,
        // ❌ width, height, minHeight 등 크기 관련 속성은 제거!
      }}
    >
      {/* 위젯 내용 */}
    </div>
  );
}
```

#### ❌ 잘못된 크기 설정 패턴

```tsx
// 이렇게 하면 안 됩니다!
<div
  style={{
    width: component.style?.width || "100%",    // ❌ 상위에서 이미 제어함
    height: component.style?.height || "80px",  // ❌ 상위에서 이미 제어함
    minHeight: "80px",                           // ❌ 내부 컨텐츠가 줄어듦
  }}
>
```

### 이유

1. **`RealtimePreviewDynamic`**이 `baseStyle`로 이미 크기를 제어:

   ```tsx
   const baseStyle = {
     left: `${position.x}px`,
     top: `${position.y}px`,
     width: getWidth(), // size.width 사용
     height: getHeight(), // size.height 사용
   };
   ```

2. 위젯 내부에서 크기를 다시 설정하면:
   - 중복 설정으로 인한 충돌
   - 내부 컨텐츠가 설정한 크기보다 작게 표시됨
   - 편집기에서 설정한 크기와 실제 렌더링 크기 불일치

### 위젯이 관리해야 할 스타일

위젯 컴포넌트는 **위젯 고유의 스타일**만 관리합니다:

- ✅ `padding`: 내부 여백
- ✅ `backgroundColor`: 배경색
- ✅ `border`, `borderRadius`: 테두리
- ✅ `gap`: 자식 요소 간격
- ✅ `flexDirection`, `alignItems`: 레이아웃 방향

### 위젯 등록 시 defaultSize

```tsx
ComponentRegistry.registerComponent({
  id: "your-widget",
  name: "위젯 이름",
  category: "utility",
  defaultSize: { width: 1200, height: 80 }, // 픽셀 단위 (필수)
  component: YourWidget,
  defaultProps: {
    style: {
      padding: "0.75rem",
      // width, height는 defaultSize로 제어되므로 여기 불필요
    },
  },
});
```

### 레이아웃 구조

```tsx
// 전체 높이를 차지하고 내부 요소를 정렬
<div className="flex h-full w-full items-center justify-between gap-2">
  {/* 왼쪽 컨텐츠 */}
  <div className="flex items-center gap-3">{/* ... */}</div>

  {/* 오른쪽 버튼들 */}
  <div className="flex items-center gap-2 flex-shrink-0">
    {/* flex-shrink-0으로 버튼이 줄어들지 않도록 보장 */}
  </div>
</div>
```

### 체크리스트

위젯 개발 시 다음을 확인하세요:

- [ ] 위젯 루트 요소에 `h-full w-full` 클래스 사용
- [ ] `width`, `height`, `minHeight` 인라인 스타일 **제거**
- [ ] `padding`, `backgroundColor` 등 위젯 고유 스타일만 관리
- [ ] `defaultSize`에 적절한 기본 크기 설정
- [ ] 양끝 정렬이 필요하면 `justify-between` 사용
- [ ] 줄어들면 안 되는 요소에 `flex-shrink-0` 적용

---

**이 규칙을 지키지 않으면 사용자에게 "확인 안하지?"라는 말을 듣게 됩니다!**