sonamu 0.7.53 → 0.8.0

package/src/skills/sonamu/scaffolding.md

@@ -143,6 +143,7 @@ export const PostSaveParams = PostBaseSchema
 | "존재하지 않는 모듈 패스 요청 {Type}" | types.ts 미생성 또는 미컴파일 | 대기/수동생성 → build → dev 재시작 |
 | exhaustive() 타입 에러 | OrderBy 첫 번째 값만 자동 처리 | 위 "4. OrderBy 케이스 추가" 참조 |
 | i18n 키 없음 (relation) | `author_id` vs `author` | 위 "3. Relation이 있는 경우" 참조 |
+| IdAsyncSelect API 불일치 | 구버전 scaffolding 템플릿 사용 | 아래 "IdAsyncSelect API 마이그레이션" 참조 |
 
 ## 상세 설명
 
@@ -283,3 +284,114 @@ export default {
 ```
 
 **권장**: 첫 번째 방법 - ko.ts에 `_id` 키 추가. sync 시 유지되며 여러 form에서 재사용 가능.
+
+### IdAsyncSelect API 마이그레이션
+
+#### 발생 배경
+
+Sonamu의 `@sonamu-kit/react-components` 패키지가 업데이트되면서 IdAsyncSelect API가 변경되었으나, scaffolding 생성 코드(`scaffolding/react-components.ts`)는 구 API 기준으로 코드를 생성합니다.
+
+따라서 `pnpm sonamu scaffold` 실행 시 구 API 기반 래퍼 컴포넌트가 생성되며, 최신 패키지를 사용하는 프로젝트에서는 빌드 오류가 발생합니다.
+
+#### 구체적인 API 변경 사항
+
+**구 API (scaffolding이 생성하는 코드):**
+```typescript
+export function UserIdAsyncSelect<T extends UserSubsetKey>({
+  subset,
+  value,
+  onValueChange,
+  listParams,      // ← 구 API
+  textField = "name",  // ← 구 API
+  pageField,       // ← 구 API
+  ...
+}: UserIdAsyncSelectProps<T>) {
+  // 수동 상태 관리
+  const [searchText, setSearchText] = useState("");
+
+  const handleSearch = useCallback((text: string) => {
+    setSearchText(text);
+  }, []);
+
+  return (
+    <AsyncSelect  // ← 구 컴포넌트
+      config={UserAsyncIdConfig}
+      subset={subset}
+      listParams={{ ...listParams, [textField]: searchText }}
+      textField={textField}
+      pageField={pageField}
+      onSearch={handleSearch}
+      ...
+    />
+  );
+}
+```
+
+**신 API (실제 패키지 API):**
+```typescript
+export function UserIdAsyncSelect<T extends UserSubsetKey>({
+  subset,
+  value,
+  onValueChange,
+  baseListParams,    // ← 신 API
+  displayField = "name",  // ← 신 API
+  // pageField 없음  // ← 제거됨
+  ...
+}: UserIdAsyncSelectProps<T>) {
+  // 상태 관리 없음 (내부에서 처리)
+
+  return (
+    <IdAsyncSelect<number>  // ← 신 컴포넌트 + 제네릭
+      config={UserAsyncIdConfig}
+      subset={subset}
+      baseListParams={baseListParams}
+      displayField={displayField}
+      // 내부에서 검색 처리
+      ...
+    />
+  );
+}
+```
+
+#### 주요 변경점
+
+1. **컴포넌트명**: `AsyncSelect` → `IdAsyncSelect<T>` (제네릭 추가)
+2. **Props 이름**:
+   - `listParams` → `baseListParams`
+   - `textField` → `displayField`
+   - `pageField` 삭제
+3. **검색 로직**: 외부 상태관리 → 내부 처리 (useState, useCallback, onSearch 불필요)
+4. **제네릭 타입**: PK 타입 명시 필요 (`<number>` 또는 `<string>`)
+
+#### 수정이 필요한 파일들
+
+```
+src/components/
+  ├── user/UserIdAsyncSelect.tsx
+  ├── account/AccountIdAsyncSelect.tsx
+  ├── announcement/AnnouncementIdAsyncSelect.tsx
+  └── ... (모든 *IdAsyncSelect.tsx 파일)
+```
+
+#### 마이그레이션 체크리스트
+
+- [ ] 컴포넌트 import 변경: `AsyncSelect` → `IdAsyncSelect`
+- [ ] 제네릭 타입 파라미터 추가: `<number>` 또는 `<string>` (PK 타입에 따라)
+- [ ] Props 타입 정의 업데이트:
+  - [ ] `listParams` → `baseListParams`
+  - [ ] `textField` → `displayField`
+  - [ ] `pageField` 제거
+- [ ] 수동 상태 관리 제거:
+  - [ ] `useState`, `useCallback` 제거
+  - [ ] `onSearch` 핸들러 제거
+- [ ] JSX 내 props 이름 변경:
+  - [ ] `listParams={...}` → `baseListParams={...}`
+  - [ ] `textField={...}` → `displayField={...}`
+  - [ ] `pageField` 제거
+  - [ ] `onSearch` 제거
+
+#### 왜 이런 일이 발생하나?
+
+Sonamu의 scaffolding 생성 코드가 최신 패키지 API를 반영하지 못한 상태에서, 사용자가 로컬의 Sonamu 소스를 수정하면서 패키지는 업데이트되었지만 scaffolding 템플릿은 그대로인 상황에서 발생합니다.
+
+**해결책**: 생성된 컴포넌트를 위 체크리스트에 따라 수동으로 수정하거나, Sonamu 코어의 scaffolding 템플릿을 최신 API로 업데이트해야 합니다.

package/src/skills/sonamu/subset.md

@@ -134,9 +134,15 @@ const user = await UserModel.findById("P", 1);
 // findMany
 const { rows } = await UserModel.findMany("P", { num: 20, page: 1 });
 
-// getPuri + Subset (Puri는 Thenable이므로 직접 await)
-const users = await UserModel.getPuri("r", ["P"])
-  .where("employee__department.name", "Engineering");
+// getSubsetQueries + executeSubsetQuery
+const { qb } = UserModel.getSubsetQueries("P");
+qb.where("users.role", "admin");
+
+const result = await UserModel.executeSubsetQuery({
+  subset: "P",
+  qb,
+  params: { num: 20, page: 1 },
+});
 ```
 
 ## 주의사항

package/src/skills/sonamu/testing.md

@@ -11,6 +11,10 @@ Sonamu는 Vitest 기반 테스트 환경을 제공한다. 각 테스트는 트
 
 **WARNING: 엔티티 10개 이상 프로젝트는 반드시 배치 전략 사용** (아래 "대규모 프로젝트 전략" 참고)
 
+**참고 문서**:
+- **Fixture CLI 명령어**: `fixture-cli.md` - fixture gen/fetch/explore 사용법, 3-Tier DB 구조
+- **Fixture 생성 팁**: 이 문서 하단 "Fixture 데이터 생성 팁" 섹션 또는 `fixture-cli.md` "실전 팁" 섹션
+
 ---
 
 ## Quick Start - 테스트 작성 빠른 시작
@@ -638,7 +642,7 @@ status: "completed"    // entity.json의 정확한 값
 
 단순 우선순위가 아닌, **업무 흐름 단위**로 엔티티를 묶는다.
 
-**VOC 시스템 예시:**
+**고객 상담 시스템 예시:**
 
 ```
 그룹 1: 기반 인프라
@@ -2051,7 +2055,7 @@ await expect(UserModel.findById("A", 99999))
 // packages/api/package.json
 {
   "dependencies": {
-    "sonamu": "0.7.50"  // link 대신 버전 명시
+    "sonamu": "0.8.0"  // link 대신 버전 명시
   }
 }
 ```
@@ -2324,3 +2328,284 @@ describe("TaskModel", () => {
   });
 });
 ```
+
+---
+
+## 흔한 실수와 해결 방법
+
+### ubUpsert는 unique constraint 에러를 던지지 않습니다
+
+ubUpsert는 INSERT 실패 시 UPDATE를 수행하므로 unique constraint 위반 시에도 에러를 던지지 않습니다.
+
+```typescript
+// BAD: 이 테스트는 항상 실패
+test("코드 중복 방지 (unique 제약)", async () => {
+  await createTestDepartment({ code: "IT" });
+
+  // ubUpsert는 에러를 던지지 않고 UPDATE를 수행
+  await expect(
+    createTestDepartment({ code: "IT" })
+  ).rejects.toThrow();
+});
+
+// GOOD: skip 처리하고 이유를 명시
+test.skip("코드 중복 방지 - ubUpsert는 중복 시 업데이트 수행", async () => {
+  const code = "IT";
+  await createTestDepartment({ code });
+
+  // 같은 코드로 두 번째 생성 시도
+  await expect(
+    createTestDepartment({ code })
+  ).rejects.toThrow();
+});
+```
+
+**이유:** Sonamu의 ubUpsert 패턴은 INSERT ... ON DUPLICATE KEY UPDATE를 사용하므로 중복 키가 있어도 에러 대신 업데이트를 수행합니다.
+
+**대안:** unique constraint 검증이 필요한 경우 직접 Knex 쿼리로 테스트하거나, 비즈니스 로직에서 중복 체크를 구현합니다.
+
+### Transaction isolation과 테스트 격리
+
+각 테스트는 독립된 트랜잭션에서 실행되므로 데이터가 격리됩니다. 같은 테스트 내에서도 생성한 데이터가 쿼리에 즉시 보이지 않을 수 있습니다.
+
+```typescript
+// BAD: 정확한 개수를 기대하면 실패할 수 있음
+test("역할명 검색", async () => {
+  await createTestRole({ name: "관리자A" });
+  await createTestRole({ name: "관리자B" });
+
+  const { rows } = await RoleModel.findMany("A", {
+    keyword: "관리자"
+  });
+
+  // Transaction isolation으로 인해 2개가 보이지 않을 수 있음
+  expect(rows.length).toBe(2);
+});
+
+// GOOD: 고유 식별자와 유연한 assertion 사용
+test("역할명 검색", async () => {
+  // 고유한 식별자로 충돌 방지
+  const testName = `검색테스트_${Date.now()}`;
+  await createTestRole({ name: `${testName}A` });
+  await createTestRole({ name: `${testName}B` });
+
+  const { rows } = await RoleModel.findMany("A", {
+    keyword: testName
+  });
+
+  // 최소 1개 이상 확인
+  expect(rows.length).toBeGreaterThanOrEqual(1);
+  // 내용 검증
+  expect(rows.some(r => r.name.includes(testName))).toBe(true);
+});
+```
+
+**패턴:**
+- 고유 식별자 사용: `Date.now()`, `uuid()` 등으로 충돌 방지
+- 유연한 assertion: `toBeGreaterThanOrEqual(1)` 대신 `toBe(2)` 사용
+- 내용 검증: 개수보다 실제 데이터가 맞는지 확인
+
+### 정렬 테스트의 조건부 검증
+
+정렬 테스트에서 모든 데이터가 조회되지 않을 수 있으므로 조건부 검증을 사용합니다:
+
+```typescript
+// BAD: 항상 두 항목이 조회된다고 가정
+test("정렬 - ID 최신순", async () => {
+  const id1 = await createTestRole({ name: "역할1" });
+  const id2 = await createTestRole({ name: "역할2" });
+
+  const { rows } = await RoleModel.findMany("A", {
+    orderBy: "id-desc",
+  });
+
+  const id2Index = rows.findIndex(r => r.id === id2);
+  const id1Index = rows.findIndex(r => r.id === id1);
+
+  // 둘 중 하나라도 없으면 실패
+  expect(id2Index).toBeLessThan(id1Index);
+});
+
+// GOOD: 조건부 검증
+test("정렬 - ID 최신순", async () => {
+  const id1 = await createTestRole({ name: "역할1" });
+  const id2 = await createTestRole({ name: "역할2" });
+
+  const { rows } = await RoleModel.findMany("A", {
+    orderBy: "id-desc",
+  });
+
+  const testRoles = rows.filter(r => [id1, id2].includes(r.id));
+  expect(testRoles.length).toBeGreaterThanOrEqual(1);
+
+  // 두 역할이 모두 조회된 경우에만 순서 검증
+  if (testRoles.length === 2) {
+    const id2Index = rows.findIndex(r => r.id === id2);
+    const id1Index = rows.findIndex(r => r.id === id1);
+    expect(id2Index).toBeLessThan(id1Index);
+  }
+});
+```
+
+**핵심:** Transaction isolation으로 인한 불확실성을 받아들이고, 검증 가능한 경우에만 assertion을 수행합니다.
+
+---
+
+## Fixture 데이터 생성 팁
+
+Sonamu의 `pnpm sonamu fixture gen` 명령어로 테스트용 fixture 데이터를 생성할 때 유용한 패턴들입니다.
+
+### Unique Constraint 고려
+
+unique constraint가 있는 필드는 랜덤 데이터 생성 시 중복을 피해야 합니다.
+
+**문제 상황:**
+```typescript
+// BAD - 같은 값 반복 생성 → unique constraint 위반
+const dept = faker.helpers.arrayElement(["개발팀", "기획팀", "마케팅팀"]);
+// 같은 company_id에 "개발팀"이 여러 번 생성되면 오류 발생
+```
+
+**해결 방법: Suffix/Prefix 추가로 중복 방지**
+```typescript
+// GOOD - 70% 확률로 suffix/prefix 추가하여 변형
+const depts = ["개발팀", "기획팀", "마케팅팀", "영업팀", "인사팀"];
+const prefixes = ["신규", "통합", "전략", "글로벌", "디지털", "핵심"];
+const suffixes = ["1팀", "2팀", "3팀", "A팀", "B팀", "본부", "센터", "그룹"];
+
+const dept = faker.helpers.arrayElement(depts);
+const random = Math.random();
+
+if (random > 0.7) {
+  return `${faker.helpers.arrayElement(prefixes)} ${dept}`;
+}
+if (random > 0.4) {
+  return `${dept} ${faker.helpers.arrayElement(suffixes)}`;
+}
+return dept;
+
+// 결과 예시: "개발팀", "개발팀 1팀", "글로벌 개발팀", "개발팀 본부" 등
+```
+
+**핵심:**
+- 기본 값(30% 확률) + 변형 값(70% 확률)으로 중복 최소화
+- unique constraint가 있는 필드는 반드시 변형 로직 추가
+- 여러 조합으로 다양성 확보 (prefix × dept, dept × suffix)
+
+### 한국어 데이터 생성
+
+테스트 데이터의 가독성을 높이기 위해 한국어 데이터를 생성합니다.
+
+**설치:**
+```bash
+pnpm add -D @faker-js/faker
+```
+
+**사용 예시:**
+```typescript
+import { faker } from "@faker-js/faker";
+import { fakerKO } from "@faker-js/faker";
+
+// 한국 이름 (성+이름)
+const name = fakerKO.person.fullName();
+// 예: "김민준", "이서연", "박지호"
+
+// 한국 성만
+const lastName = fakerKO.person.lastName();
+// 예: "김", "이", "박"
+
+// 한국 이름만
+const firstName = fakerKO.person.firstName();
+// 예: "민준", "서연", "지호"
+
+// 한국 부서명 (커스텀 리스트)
+const departments = [
+  "개발팀", "기획팀", "마케팅팀", "영업팀", "인사팀",
+  "재무팀", "법무팀", "품질관리팀", "IT팀", "디자인팀"
+];
+const dept = faker.helpers.arrayElement(departments);
+
+// 한국 회사명 (커스텀 리스트 + suffix)
+const companies = ["테크놀로지", "솔루션즈", "디지털", "이노베이션"];
+const suffixes = ["주식회사", "㈜", "코퍼레이션", "그룹"];
+const company = `${faker.helpers.arrayElement(companies)} ${faker.helpers.arrayElement(suffixes)}`;
+// 예: "테크놀로지 주식회사", "디지털 ㈜"
+```
+
+**FixtureGenerator에서 활용:**
+```typescript
+// fixture-generator.ts 내부
+if (entity?.id === "Department" && prop.name === "name") {
+  const departments = ["개발팀", "기획팀", "마케팅팀", "영업팀"];
+  const prefixes = ["신규", "통합", "전략", "글로벌"];
+  const suffixes = ["1팀", "2팀", "본부", "센터"];
+
+  const dept = faker.helpers.arrayElement(departments);
+  const random = Math.random();
+
+  if (random > 0.7) {
+    return `${faker.helpers.arrayElement(prefixes)} ${dept}`;
+  }
+  if (random > 0.4) {
+    return `${dept} ${faker.helpers.arrayElement(suffixes)}`;
+  }
+  return dept;
+}
+
+if (prop.name === "name" || prop.name === "username") {
+  return fakerKO.person.fullName();
+}
+```
+
+### Fixture Gen vs Fetch 선택 기준
+
+| 상황 | 명령어 | 이유 |
+|------|--------|------|
+| 운영 DB에 데이터가 없음 | `fixture gen` | faker로 더미 데이터 생성 |
+| 실제 데이터로 테스트 필요 | `fixture fetch` | 운영 DB에서 가져오기 |
+| 특정 패턴 데이터 필요 | `fixture gen` + custom logic | FixtureGenerator 수정 |
+| 관련 데이터 함께 필요 | `fixture fetch` | FK 따라 자동으로 가져옴 |
+
+**예시:**
+```bash
+# 더미 데이터 생성 (한국어)
+pnpm sonamu fixture gen --include Department --count 10
+
+# 실제 데이터 가져오기 (최근 10개 + 관련 데이터)
+pnpm sonamu fixture fetch --include User --limit 10 --strategy recent
+```
+
+### DB 시퀀스 리셋
+
+Fixture 데이터 생성 후 ID 시퀀스가 실제 데이터와 맞지 않을 수 있습니다.
+
+**확인:**
+```bash
+PGPASSWORD=1234 psql -h 0.0.0.0 -U postgres -d project_fixture -c "
+SELECT
+  schemaname,
+  sequencename,
+  last_value
+FROM pg_sequences
+WHERE schemaname = 'public'
+ORDER BY sequencename;
+"
+```
+
+**리셋:**
+```sql
+-- 각 테이블마다 실행
+SELECT setval('departments_id_seq', (SELECT MAX(id) FROM departments), true);
+SELECT setval('companies_id_seq', (SELECT MAX(id) FROM companies), true);
+```
+
+**자동화 스크립트:**
+```bash
+# 모든 시퀀스 리셋
+PGPASSWORD=1234 psql -h 0.0.0.0 -U postgres -d project_fixture -c "
+SELECT 'SELECT setval(''' || sequencename || ''', (SELECT COALESCE(MAX(id), 1) FROM ' ||
+  replace(sequencename, '_id_seq', '') || '), true);'
+FROM pg_sequences
+WHERE schemaname = 'public' AND sequencename LIKE '%_id_seq';
+" | grep SELECT | PGPASSWORD=1234 psql -h 0.0.0.0 -U postgres -d project_fixture
+```

package/src/skills/sonamu/workflow.md

@@ -16,21 +16,86 @@ description: Sonamu 전체 개발 워크플로우. 엔티티 설계부터 Fronte
 **참조 스킬:** entity-basic.md, entity-relations.md
 
 **절차:**
-1. 요구사항 분석 (누락된 Entity 확인)
+
+1. **비즈니스 플로우 작성**
+   - 업무 프로세스를 단계별로 작성
+   - 각 단계의 입력/출력 데이터 명시
+   - 데이터 흐름 다이어그램 작성 (선택)
+   - 예: "공고 발행 → 과제 신청 → 평가 생성 → 평가위원 배정 → 평가표 작성 → 확정"
+
+2. **Entity 식별 및 역할 정의**
+   - 비즈니스 플로우 기반으로 필요한 모든 Entity 나열
+   - 각 Entity의 역할 명확히 정의
    - "사용자(User) Entity가 필요한가요?"
    - "추가로 필요한 Entity가 있나요?"
-2. Entity 간 관계 확인 (한 번에 하나씩 질문)
+   - **중요**: 매핑 테이블(N:M 관계)도 Entity로 식별
+
+3. **Entity 간 관계 정의**
+   - ERD 작성 (시각화 권장)
+   - 관계 유형 결정 (BelongsToOne, HasMany, ManyToMany)
+   - FK 관계 명시
    - "챕터는 강좌의 자식으로 함께 관리할까요?"
    - "강좌와 수강생은 어떤 관계인가요?"
-3. parentId 사용 여부 결정
-4. 사용자 최종 확인
+   - **중요**: N:M 관계는 중간 매핑 Entity 필요
+
+4. **필드 목록 상세화**
+   - 각 Entity별로 필요한 필드 전부 나열
+   - 필드명, 타입, nullable 여부 결정
+   - 시간 추적 필드 확인 (created_at, updated_at, started_at 등)
+   - 상태 관리 필드 확인 (status, confirmed_date 등)
+   - **체크리스트**: "이 Entity에 누락된 필드는 없는가?"
+
+5. **parentId 사용 여부 결정**
+   - 계층 구조가 필요한 Entity 확인
+   - parentId 또는 별도 관계 테이블 선택
+
+6. **사용자 최종 확인**
+   - 전체 설계 리뷰
+   - 누락 사항 확인
+   - 승인
 
 **완료 기준:**
+- [ ] 비즈니스 플로우 문서 작성 완료
 - [ ] 모든 필수 Entity 식별 완료
-- [ ] Entity 간 관계 정의 완료 (BelongsToOne, HasMany, ManyToMany)
+- [ ] 각 Entity의 역할 정의 완료
+- [ ] Entity 간 관계 정의 완료 (ERD 포함)
+- [ ] **각 Entity별 필드 목록 작성 완료**
 - [ ] parentId 사용 여부 결정
 - [ ] 사용자 승인
 
+**CRITICAL - API 개발 전 필수 단계:**
+
+Entity 설계 후 API 개발로 넘어가기 전에 **반드시** 다음을 수행하세요:
+
+**"추측하지 말고, 확인하라"**
+
+- DON'T: 필드명 추측 금지 → Entity JSON 확인 필수
+- DON'T: 관계 타입 추측 금지 → BelongsToOne은 자동으로 _id FK 생성
+- DON'T: Subset 접근 추측 금지 → nested 접근 방식 확인 (예: committee.id, evaluator.id)
+
+**API 개발 시작 전 체크리스트:**
+```
+□ 1. 모든 Entity JSON 파일 읽기 완료
+   - 필드명 정확히 파악
+   - 타입 확인
+   - nullable 여부 확인
+
+□ 2. 관계 확인
+   - BelongsToOne → _id FK 자동 생성 확인
+   - HasMany 방향 확인
+   - ManyToMany 매핑 테이블 확인
+
+□ 3. Subset 구조 확인
+   - Subset A에서 관계 필드 접근 방식 확인
+   - nested object로 접근 (예: sheet.committee.id)
+   - FK 직접 접근 불가 (예: sheet.committee_id ❌)
+
+□ 4. 기존 필드 활용 확인
+   - 시작/종료 시점: start_date, end_date 있는지 확인
+   - 상태 관리: status enum으로 충분한지 확인
+   - 불필요한 필드 추가 방지
+```
+
 **다음 단계:** PHASE 2 엔티티 생성
 
 ---

package/src/ssr/renderer.ts

@@ -64,8 +64,8 @@ export async function renderSSR(
   } else {
     // Prod: 빌드된 파일
     const fs = await import("node:fs");
-    const webDistPath = path.join(Sonamu.apiRootPath, "public", "web");
-    const ssrPath = path.join(Sonamu.apiRootPath, "dist", "ssr");
+    const webDistPath = path.join(Sonamu.apiRootPath, "web-dist", "client");
+    const ssrPath = path.join(Sonamu.apiRootPath, "web-dist", "server");
 
     // 빌드된 index.html에서 스크립트 추출
     const builtHtml = fs.readFileSync(path.join(webDistPath, "index.html"), "utf-8");

package/src/syncer/api-parser.ts

@@ -234,6 +234,18 @@ function resolveTypeNode(typeNode: ts.TypeNode): ApiParamType {
       // 괄호로 묶인 타입 (예: (A & B)[] 에서 (A & B))
       // 내부 타입을 재귀적으로 resolve
       return resolveTypeNode((typeNode as ts.ParenthesizedTypeNode).type);
+
+    case ts.SyntaxKind.FunctionType:
+      return {
+        t: "function",
+        parameters: (typeNode as ts.FunctionTypeNode).parameters.map((param) => ({
+          name: param.name.getText(),
+          type: param.type ? resolveTypeNode(param.type) : "unknown",
+          optional: param.questionToken !== undefined,
+          defaultDef: undefined,
+        })),
+        returnType: resolveTypeNode((typeNode as ts.FunctionTypeNode).type),
+      };
     case undefined:
       throw new Error(`typeNode undefined`);
   }

package/src/syncer/checksum.ts

@@ -48,38 +48,6 @@ export async function renewChecksums(): Promise<void> {
   await saveChecksums(calculatedChecksums);
 }
 
-export type FileOrData =
-  | {
-      path: PathLike;
-    }
-  | {
-      data: string;
-    };
-
-/**
- * 두 파일의 내용이 같은지 체크섬으로 비교합니다.
- * 만약 파일이 둘 중 하나라도 없다면 비교 불가로 false 반환합니다.
- * @param one 파일 경로 혹은 데이터
- * @param two 파일 경로 혹은 데이터
- * @returns boolean
- */
-export async function areFilesSame(...files: FileOrData[]): Promise<boolean> {
-  const checksums: string[] = [];
-
-  for (const file of files) {
-    if ("path" in file && !(await exists(file.path))) {
-      return false;
-    }
-
-    checksums.push(
-      "path" in file ? await getChecksumOfFile(file.path) : getChecksumOfData(file.data),
-    );
-  }
-
-  // 모든 체크섬이 첫 번째 체크섬과 같은지 확인
-  return checksums.every((checksum) => checksum === checksums[0]);
-}
-
 async function getCurrentChecksums(): Promise<PathAndChecksum[]> {
   const filePaths = (
     await Promise.all(
@@ -147,12 +115,6 @@ async function saveChecksums(checksums: PathAndChecksum[]): Promise<void> {
   );
 }
 
-function getChecksumOfData(data: string): string {
-  const hash = crypto.createHash("sha1");
-  hash.update(data);
-  return hash.digest("hex");
-}
-
 async function getChecksumOfFile(filePath: PathLike): Promise<string> {
   return new Promise<string>((resolve, reject) => {
     const hash = crypto.createHash("sha1");

package/src/syncer/syncer-actions.ts

@@ -113,7 +113,13 @@ export async function actionSyncFilesToTargets(tsPaths: AbsolutePath[]): Promise
               console.log(
                 chalk.bold("Copied: ") + chalk.blue(dst.replace(`${Sonamu.appRootPath}/`, "")),
               );
-            await copyFileWithReplaceCoreToShared(realSrc, dst);
+            const syncHeader = [
+              "/**",
+              " * @generated",
+              " * API에서 동기화된 파일입니다. 직접 수정하지 마세요.",
+              " */",
+            ].join("\n");
+            await copyFileWithReplaceCoreToShared(realSrc, dst, syncHeader);
             return dst;
           }),
         ),