@kms545487/contracts 0.1.0

package/README.md

@@ -0,0 +1,83 @@
+# @kms545487/contracts
+
+프론트엔드(Next.js)와 백엔드(NestJS)가 공유하는 **도메인 계약** 단일 소스. 도메인 타입·enum·요청 DTO 형상을 담습니다.
+
+빌드 시 `dist/`에 `.d.ts`(+빈 `.js`)를 emit합니다. 소비측은 `import type`으로만 가져가 런타임 의존이 없습니다.
+
+## 빌드
+
+```bash
+npm install
+npm run build      # → dist/index.d.ts, dist/index.js
+```
+
+## 배포 (npm 레지스트리)
+
+repo가 분리되어 있어 **원격/CI 빌드에서는 `file:../contracts`가 동작하지 않습니다** (옆에 contracts 폴더가 없음).
+따라서 이 패키지를 배포하고, 소비측은 **버전**으로 의존해야 합니다.
+
+> ⚠️ `@taco` 스코프: 공개 npm에 올리려면 `@taco` 조직을 소유해야 합니다.
+> 소유하지 않으면 (a) 본인 스코프(`@yourorg/contracts`)로 이름을 바꾸거나,
+> (b) **GitHub Packages**(조직 스코프) 사용을 권장합니다.
+
+### 1) 배포
+
+```bash
+cd contracts
+npm version patch               # 0.1.0 → 0.1.1 (변경 시마다)
+npm publish --access public     # prepublishOnly가 자동 build
+```
+
+#### 2FA 오류(E403) 해결
+npm은 publish에 2단계 인증을 요구합니다. 둘 중 하나:
+
+- **일회성(OTP)**: 인증앱 6자리 코드로 즉시 publish
+  ```bash
+  npm publish --access public --otp=123456
+  ```
+- **토큰(반복·CI 권장)**: npmjs.com → Access Tokens → **Granular/Automation token**
+  (publish 시 2FA bypass 가능)를 발급 → 환경변수로 주입 (이 폴더의 `.npmrc`가 `${NPM_TOKEN}` 사용)
+  ```bash
+  export NPM_TOKEN=npm_xxxxx
+  npm publish --access public
+  ```
+  CI에서는 `NPM_TOKEN`을 시크릿으로 등록하면 됩니다.
+
+> 비공개로 두려면 `--access public` 대신 `publishConfig.access: "restricted"`(유료 플랜 필요).
+
+### 2) 소비측(frontend·backend) 의존 전환
+
+```jsonc
+// package.json
+{ "dependencies": { "@kms545487/contracts": "^0.1.0" } }   // file:../contracts → 버전
+```
+
+```bash
+npm install        # 레지스트리에서 설치 → CI 빌드 통과
+```
+
+### 로컬 개발 (미배포 변경분 사용)
+
+배포 전 로컬에서 최신 계약을 쓰려면 `npm link` 사용:
+
+```bash
+cd contracts && npm run build && npm link
+cd ../frontend && npm link @kms545487/contracts
+cd ../backend  && npm link @kms545487/contracts
+```
+
+## 구성
+
+```
+src/
+├─ common.ts      # ID, ISODate, Audited
+├─ account.ts     # Account, AccountRole, WebIdCheckResult
+├─ people.ts      # Student, Parent, ParentStudent, Instructor
+├─ catalog.ts     # Subject, Course(hourlyRate)
+├─ enrollment.ts  # Enrollment
+├─ session.ts     # ClassSession, Attendance, SessionReport
+├─ finance.ts     # Payment, Transaction, Expense(ApprovalStatus), InstructorPayout
+├─ counsel.ts     # CounselForm, CounselRound
+├─ event.ts       # AcademyEvent, EventType, EventPriority
+└─ inputs.ts      # Create*Input (요청 DTO 형상)
+```

package/dist/account.d.ts

@@ -0,0 +1,14 @@
+import type { ID } from './common';
+export type AccountRole = 'student' | 'parent' | 'instructor' | 'manager' | 'admin' | 'super_admin';
+export type Account = {
+    id: ID;
+    webId: string;
+    name: string;
+    role: AccountRole;
+};
+export type WebIdCheckResult = {
+    webId: string;
+    exists: boolean;
+    name?: string;
+    role?: AccountRole;
+};

package/dist/account.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/catalog.d.ts

@@ -0,0 +1,14 @@
+import type { ID } from './common';
+export type Subject = {
+    id: ID;
+    code: string;
+    name: string;
+};
+export type Course = {
+    id: ID;
+    name: string;
+    subjectId: ID;
+    instructorId: ID;
+    price: number;
+    hourlyRate: number;
+};

package/dist/catalog.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/common.d.ts

@@ -0,0 +1,6 @@
+export type ID = number;
+export type ISODate = string;
+export type Audited = {
+    createdAt?: ISODate;
+    updatedAt?: ISODate;
+};

package/dist/common.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/counsel.d.ts

@@ -0,0 +1,40 @@
+import type { ID, ISODate } from './common';
+export type CounselStatus = 'requested' | 'pending' | 'registered' | 'dropped';
+export type CounselSource = 'internal_form' | 'naver_form' | 'google_form' | 'manual' | 'etc';
+export type DesiredStartTime = 'immediately' | 'within_1_month' | 'within_2_3_months' | 'undecided';
+export type LearningAtmosphere = 'self_directed' | 'normal' | 'needs_management';
+export type StudentIntention = 'student_wants' | 'parent_only' | 'unknown';
+export type CounselResult = 'positive' | 'neutral' | 'negative' | 'no_response' | 'registered';
+export type CounselForm = {
+    id: ID;
+    applicantName: string;
+    applicantPhone?: string;
+    parentId?: ID;
+    studentId?: ID;
+    assignedStaffId?: ID;
+    status: CounselStatus;
+    source: CounselSource;
+    interestSubjectId?: ID;
+    interestCourseId?: ID;
+    academyExpectation?: string;
+    desiredStartTime?: DesiredStartTime;
+    learningAtmosphere?: LearningAtmosphere;
+    studentIntention?: StudentIntention;
+    weakness?: string;
+    nextContactAt?: ISODate;
+    createdAt: ISODate;
+};
+export type CounselRound = {
+    id: ID;
+    counselFormId: ID;
+    roundNo: number;
+    counselorId?: ID;
+    scheduledAt?: ISODate;
+    completedAt?: ISODate;
+    isCompleted: boolean;
+    summary?: string;
+    detail?: string;
+    result?: CounselResult;
+    nextAction?: string;
+    nextContactAt?: ISODate;
+};

package/dist/counsel.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/enrollment.d.ts

@@ -0,0 +1,13 @@
+import type { ID, ISODate, Audited } from './common';
+export type EnrollmentStatus = 'active' | 'paused' | 'completed' | 'canceled';
+export type Enrollment = {
+    id: ID;
+    studentId: ID;
+    courseId: ID;
+    roadmapId?: ID;
+    status: EnrollmentStatus;
+    totalSessions?: number;
+    completedSessions?: number;
+    memo?: string;
+    enrolledAt: ISODate;
+} & Audited;

package/dist/enrollment.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/event.d.ts

@@ -0,0 +1,13 @@
+import type { ID, ISODate, Audited } from './common';
+export type EventType = 'notice' | 'exam' | 'holiday' | 'closure' | 'event';
+export type EventPriority = 'low' | 'normal' | 'high';
+export type AcademyEvent = {
+    id: ID;
+    title: string;
+    type: EventType;
+    priority: EventPriority;
+    startDate: ISODate;
+    endDate: ISODate;
+    allDay?: boolean;
+    memo?: string;
+} & Audited;

package/dist/event.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/finance.d.ts

@@ -0,0 +1,51 @@
+import type { ID, ISODate, Audited } from './common';
+export type PaymentStatus = 'pending' | 'paid' | 'overdue' | 'refunded' | 'partial_refund';
+export type PaymentMethod = 'card' | 'transfer' | 'cash' | 'point' | 'etc';
+export type Payment = {
+    id: ID;
+    enrollmentId?: ID;
+    studentId: ID;
+    payerParentId?: ID;
+    amount: number;
+    paidAmount?: number;
+    status: PaymentStatus;
+    paymentMethod?: PaymentMethod;
+    dueAt?: ISODate;
+    paidAt?: ISODate;
+    memo?: string;
+} & Audited;
+export type TxDirection = 'in' | 'out';
+export type Transaction = {
+    id: ID;
+    direction: TxDirection;
+    category: string;
+    label: string;
+    amount: number;
+    method?: string;
+    occurredAt: ISODate;
+};
+export type ApprovalStatus = 'requested' | 'approved' | 'rejected';
+export type ExpenseCategory = 'supplies' | 'equipment' | 'books' | 'rent' | 'utility' | 'marketing' | 'meal' | 'etc';
+export type Expense = {
+    id: ID;
+    category: ExpenseCategory;
+    title: string;
+    amount: number;
+    spentAt: ISODate;
+    vendor?: string;
+    memo?: string;
+    receiptUrl?: string;
+    status: ApprovalStatus;
+} & Audited;
+export type PayoutStatus = 'pending' | 'confirmed' | 'paid';
+export type InstructorPayout = {
+    id: ID;
+    instructorId: ID;
+    periodStart: ISODate;
+    periodEnd: ISODate;
+    sessionCount?: number;
+    totalMinutes?: number;
+    amount: number;
+    status: PayoutStatus;
+    paidAt?: ISODate;
+};

package/dist/finance.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export * from './common';
+export * from './account';
+export * from './people';
+export * from './catalog';
+export * from './enrollment';
+export * from './session';
+export * from './finance';
+export * from './counsel';
+export * from './event';
+export * from './inputs';

package/dist/index.js

@@ -0,0 +1,26 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./common"), exports);
+__exportStar(require("./account"), exports);
+__exportStar(require("./people"), exports);
+__exportStar(require("./catalog"), exports);
+__exportStar(require("./enrollment"), exports);
+__exportStar(require("./session"), exports);
+__exportStar(require("./finance"), exports);
+__exportStar(require("./counsel"), exports);
+__exportStar(require("./event"), exports);
+__exportStar(require("./inputs"), exports);

package/dist/inputs.d.ts

@@ -0,0 +1,58 @@
+import type { ID, ISODate } from './common';
+import type { StudentStatus, ResidenceType } from './people';
+import type { PaymentMethod, ExpenseCategory } from './finance';
+import type { EventType, EventPriority } from './event';
+export type CreateStudentInput = {
+    name: string;
+    englishName?: string;
+    phone?: string;
+    grade?: number;
+    schoolName?: string;
+    residenceType?: ResidenceType;
+    status?: StudentStatus;
+    memo?: string;
+    webId?: string;
+};
+export type CreateEnrollmentInput = {
+    studentId: ID;
+    courseId: ID;
+    roadmapId?: ID;
+    totalSessions?: number;
+    memo?: string;
+};
+export type CreatePaymentInput = {
+    studentId: ID;
+    enrollmentId?: ID;
+    payerParentId?: ID;
+    amount: number;
+    paymentMethod?: PaymentMethod;
+};
+export type CreateExpenseInput = {
+    category: ExpenseCategory;
+    title: string;
+    amount: number;
+    spentAt: ISODate;
+    vendor?: string;
+    memo?: string;
+    receiptUrl?: string;
+};
+export type CreateSubjectInput = {
+    code: string;
+    name: string;
+};
+export type CreateCourseInput = {
+    name: string;
+    subjectId: ID;
+    instructorId: ID;
+    price: number;
+    hourlyRate: number;
+};
+export type CreateEventInput = {
+    title: string;
+    type: EventType;
+    priority?: EventPriority;
+    startDate: ISODate;
+    endDate: ISODate;
+    allDay?: boolean;
+    memo?: string;
+};

package/dist/inputs.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/people.d.ts

@@ -0,0 +1,35 @@
+import type { ID, Audited } from './common';
+export type StudentStatus = 'lead' | 'active' | 'paused' | 'completed' | 'canceled';
+export type ResidenceType = 'domestic' | 'overseas';
+export type Student = {
+    id: ID;
+    name: string;
+    englishName?: string;
+    grade?: number;
+    phone?: string;
+    status: StudentStatus;
+    schoolName?: string;
+    residenceType?: ResidenceType;
+    memo?: string;
+    webId?: string;
+} & Audited;
+export type Parent = {
+    id: ID;
+    name: string;
+    phone: string;
+    kakaoAvailable: boolean;
+    webId?: string;
+} & Audited;
+export type ParentStudent = {
+    id: ID;
+    parentId: ID;
+    studentId: ID;
+    relation?: string;
+    isPayer: boolean;
+    isPrimary: boolean;
+};
+export type Instructor = {
+    id: ID;
+    name: string;
+    subjectName?: string;
+};

package/dist/people.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/session.d.ts

@@ -0,0 +1,28 @@
+import type { ID, ISODate } from './common';
+export type SessionStatus = 'scheduled' | 'held' | 'canceled' | 'no_show' | 'makeup';
+export type ClassSession = {
+    id: ID;
+    courseId: ID;
+    instructorId: ID;
+    sessionDate: ISODate;
+    durationMinutes: number;
+    status: SessionStatus;
+    topic?: string;
+};
+export type AttendanceStatus = 'present' | 'late' | 'absent' | 'excused';
+export type Attendance = {
+    id: ID;
+    sessionId: ID;
+    studentId: ID;
+    status: AttendanceStatus;
+};
+export type ReportStatus = 'draft' | 'submitted' | 'sent';
+export type SessionReport = {
+    id: ID;
+    sessionId: ID;
+    studentId: ID;
+    instructorId: ID;
+    content: string;
+    homework?: string;
+    status: ReportStatus;
+};

package/dist/session.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@kms545487/contracts",
+  "version": "0.1.0",
+  "description": "TACO 공유 도메인 계약(타입·enum·DTO). 프론트/백 단일 소스.",
+  "license": "UNLICENSED",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}