@compfest-18/oppenheimer-schema 0.0.2-develop.abfb770

package/README.md

@@ -0,0 +1,540 @@
+# @compfest-18/oppenheimer-schema
+
+Private Drizzle ORM schema package for the Oppenheimer database. This package contains all database table definitions, enums, and relationships used by the Oppenheimer NestJS backend.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Consumer Setup](#consumer-setup)
+- [Usage](#usage)
+- [Schema Overview](#schema-overview)
+- [Available Tables](#available-tables)
+- [Enums](#enums)
+- [Type Safety](#type-safety)
+- [Versioning \& Branching](#versioning--branching)
+- [CI/CD Pipeline](#cicd-pipeline)
+- [Development](#development)
+- [Publishing](#publishing)
+- [License](#license)
+
+---
+
+## Installation
+
+### Prerequisites
+
+1. **GitHub Account** with access to the COMPFEST organization
+2. **GitHub Personal Access Token (PAT)** with `read:packages` scope
+3. **Node.js** v18+ and **pnpm** v9+
+
+### Quick Install
+
+```bash
+# Add GitHub Packages registry configuration
+echo "@compfest:registry=https://npm.pkg.github.com" >> .npmrc
+echo "//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}" >> .npmrc
+
+# Install the schema package
+pnpm add @compfest-18/oppenheimer-schema
+```
+
+### Manual Setup (Recommended for Production)
+
+Create a `.npmrc` file in your project root:
+
+```ini
+# .npmrc
+@compfest:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
+```
+
+Then install:
+
+```bash
+pnpm add @compfest-18/oppenheimer-schema
+```
+
+### Environment Variable Setup
+
+For CI/CD environments, set `GITHUB_TOKEN` as a secret. In GitHub Actions:
+
+```yaml
+- name: Install dependencies
+  run: pnpm install
+  env:
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+For local development, create a Classic PAT with `read:packages` scope:
+1. Go to GitHub → Settings → Developer settings → Personal access tokens
+2. Generate new token with `read:packages` permission
+3. Add to your shell profile or use `pnpm add` with `--auth-token` flag
+
+---
+
+## Consumer Setup
+
+### Full Example: Adding Schema to a New Service
+
+```bash
+# 1. Initialize your project
+pnpm init
+
+# 2. Add required dependencies
+pnpm add drizzle-orm @compfest-18/oppenheimer-schema
+pnpm add -D drizzle-kit @types/node typescript tsx
+
+# 3. Create drizzle.config.ts
+cat > drizzle.config.ts << 'EOF'
+import { defineConfig } from 'drizzle-kit';
+
+export default defineConfig({
+  schema: './node_modules/@compfest-18/oppenheimer-schema',
+  dialect: 'postgresql',
+  out: './drizzle',
+  dbCredentials: {
+    url: process.env.DATABASE_URL!,
+  },
+});
+EOF
+
+# 4. Generate migrations
+pnpm drizzle-kit generate
+
+# 5. Push schema to database (development only!)
+pnpm drizzle-kit push
+```
+
+### Using Schemas in Your Code
+
+```typescript
+// Import specific tables or enums
+import { users, eventEnum } from '@compfest-18/oppenheimer-schema';
+import { eq, and, desc } from 'drizzle-orm';
+
+// Use with your database instance
+const result = await db
+  .select()
+  .from(users)
+  .where(eq(users.id, '123'))
+  .orderBy(desc(users.createdAt));
+```
+
+---
+
+## Usage
+
+### Basic Query Examples
+
+```typescript
+import { db } from './your-db-instance'; // Your Drizzle db instance
+import { users, eventEnum } from '@compfest-18/oppenheimer-schema';
+import { eq, and, inArray } from 'drizzle-orm';
+
+// Select single user
+const user = await db.select().from(users).where(eq(users.id, '123'));
+
+// Insert new user
+const newUser = await db.insert(users).values({
+  id: 'user-456',
+  email: 'john@example.com',
+  name: 'John Doe',
+  referralCode: 'JOHN123',
+});
+
+// Update user
+await db.update(users)
+  .set({ name: 'Jane Doe' })
+  .where(eq(users.id, 'user-456'));
+
+// Delete user
+await db.delete(users).where(eq(users.id, 'user-456'));
+
+// Batch insert
+await db.insert(users).values([
+  { id: 'user-1', email: 'a@test.com', name: 'User A' },
+  { id: 'user-2', email: 'b@test.com', name: 'User B' },
+]);
+```
+
+### Using Enums
+
+```typescript
+import { eventEnum } from '@compfest-18/oppenheimer-schema';
+
+// Enum values are typed
+type EventType = typeof eventEnum.enumValues[number];
+
+const eventType: EventType = 'GRAND_LAUNCHING';
+```
+
+### Relations (if available)
+
+```typescript
+import { users, userProfiles } from '@compfest-18/oppenheimer-schema';
+
+const result = await db
+  .select()
+  .from(users)
+  .leftJoin(userProfiles, eq(users.id, userProfiles.userId))
+  .where(eq(users.email, 'john@example.com'));
+```
+
+---
+
+## Schema Overview
+
+The Oppenheimer schema covers a comprehensive event management system with the following domains:
+
+| Domain | Description |
+|--------|-------------|
+| **Auth** | User authentication and profiles |
+| **Events** | Event definitions and registrations |
+| **Programs** | Academy and competition programs |
+| **Tasks** | Program tasks and submissions |
+| **Games** | Game integrations and rules |
+| **Playground** | Virtual playground system |
+| **Tokens** | Token economy (rewards, expenses) |
+| **Quiz** | Quiz systems (main event and mini) |
+| **Feedback** | Event feedback collection |
+| **Exhibition** | Company exhibition booths |
+| **Job Fair** | Walk-in interview system |
+| **CV Clinic** | CV clinic voucher system |
+| **Voting** | Project voting system |
+| **Booth** | Event booth rewards |
+| **Supermarket** | Virtual supermarket |
+| **Notifications** | Dashboard notifications |
+| **Announcements** | Event announcements |
+| **Content** | Articles and fun facts |
+| **Ads** | Advertisement system |
+
+---
+
+## Available Tables
+
+### Auth Module
+
+| Table | Description |
+|-------|-------------|
+| `users` | User accounts synced from SSO (Feynman) |
+| `userProfiles` | Extended user profile information |
+
+### Events Module
+
+| Table | Description |
+|-------|-------------|
+| `event` | Event definitions |
+| `eventDate` | Event date/time information |
+| `eventRegistration` | User event registrations |
+| `grandLaunchingRegistration` | Grand launching event registrations |
+| `mainEventRegistration` | Main event registrations |
+| `xcelerateRegistration` | Xcelerate seminar/workshop registrations |
+
+### Programs Module
+
+| Table | Description |
+|-------|-------------|
+| `program` | Program definitions |
+| `team` | Team information |
+| `member` | Team members |
+| `programRegistration` | Program registrations |
+| `singleParticipant` | Single participant programs |
+
+### Tasks Module
+
+| Table | Description |
+|-------|-------------|
+| `programTask` | Tasks within programs |
+| `programTaskExtraDescription` | Additional task descriptions |
+| `programTaskSubmission` | Task submissions |
+| `xcelerateWorkshopTask` | Xcelerate workshop tasks |
+| `xcelerateWorkshopTaskSubmission` | Workshop task submissions |
+
+### Games Module
+
+| Table | Description |
+|-------|-------------|
+| `game` | Game definitions |
+| `gameDeveloper` | Game developers |
+| `gameRule` | Game rules |
+| `userPlayGameHistory` | User game play history |
+
+### Tokens Module
+
+| Table | Description |
+|-------|-------------|
+| `playgroundToken` | User token balances |
+| `playgroundExpenseHistory` | Token expense records |
+| `playgroundRewardHistory` | Token reward records |
+
+### Quiz Module
+
+| Table | Description |
+|-------|-------------|
+| `miniQuiz` | Mini quiz definitions |
+| `miniQuizQuestion` | Mini quiz questions |
+| `miniQuizAttempt` | Mini quiz attempts |
+| `mainEventMiniQuiz` | Main event mini quiz |
+| `mainEventMiniQuizQuestion` | Main event quiz questions |
+| `mainEventMiniQuizQuestionOption` | Question options |
+| `mainEventMiniQuizAttempt` | Main event quiz attempts |
+
+### And more...
+
+See the full list in [`index.ts`](./index.ts)
+
+---
+
+## Enums
+
+The package includes the following PostgreSQL enums:
+
+```typescript
+// Event types
+'GRAND_LAUNCHING', 'XCELERATE_SEMINAR', 'XCELERATE_WORKSHOP',
+'XCELERATE_FOUNDATION', 'COMPFEST_TALKS', 'MAIN_EVENT_PLAYGROUND',
+'MAIN_EVENT_SEMINAR', 'MAIN_EVENT_STAGE'
+
+// Program codes
+'LANDING', 'SEA', 'UXA', 'DSA', 'PMA', 'IGI', 'SCPC', 'JCPC',
+'AIC', 'BIZZIT', 'CTF', 'DAD', 'GAMEJAM', 'MINICASE'
+
+// Program types
+'ACADEMY', 'COMPETITION'
+
+// Task types
+'TEAM', 'PERSONAL'
+
+// Submission status
+'PENDING', 'REJECTED', 'ACCEPTED'
+
+// Team status
+'WAITING_FOR_VERIFICATION', 'VERIFIED', 'VERIFICATION_FAILED'
+
+// And many more...
+```
+
+Import enums:
+```typescript
+import {
+  eventEnum,
+  programCodeEnum,
+  submissionStatusEnum,
+  teamStatusEnum,
+} from '@compfest-18/oppenheimer-schema';
+```
+
+---
+
+## Type Safety
+
+This package provides full TypeScript type safety:
+
+### Table Types
+
+```typescript
+import type { InferSelectModel, InferInsertModel } from 'drizzle-orm';
+import { users } from '@compfest-18/oppenheimer-schema';
+
+// Extract row type from table
+type User = InferSelectModel<typeof users>;
+type NewUser = InferInsertModel<typeof users>;
+
+// Full type safety for queries
+const user: User = {
+  id: '123',
+  email: 'test@example.com',
+  name: 'Test User',
+  referralCode: 'TEST123',
+  createdAt: new Date(),
+  updatedAt: new Date(),
+};
+```
+
+### Query Builder Type Safety
+
+```typescript
+import { users } from '@compfest-18/oppenheimer-schema';
+import { eq } from 'drizzle-orm';
+
+// Drizzle automatically infers return types
+const result = await db
+  .select({
+    id: users.id,
+    email: users.email,
+    name: users.name,
+  })
+  .from(users)
+  .where(eq(users.email, 'test@example.com'));
+
+// result is typed as { id: string; email: string; name: string }[]
+```
+
+---
+
+## Versioning & Branching
+
+This package uses semantic versioning with branch-specific tags:
+
+| Branch | NPM Tag | Example Version |
+|--------|---------|-----------------|
+| `main` | `@latest` | `1.2.3` |
+| `staging` | `@staging` | `1.2.3-staging.a1b2c3d` |
+| `develop` | `@develop` | `1.2.3-develop.f4e5d6` |
+
+### Installing Specific Branch Versions
+
+```bash
+# Install latest stable (from main)
+pnpm add @compfest-18/oppenheimer-schema@latest
+
+# Install staging version
+pnpm add @compfest-18/oppenheimer-schema@staging
+
+# Install develop version
+pnpm add @compfest-18/oppenheimer-schema@develop
+
+# Install specific version
+pnpm add @compfest-18/oppenheimer-schema@1.2.3
+```
+
+### Version Format
+
+- **Production (`main`)**: `MAJOR.MINOR.PATCH` (e.g., `1.0.0`)
+- **Pre-release (`develop`/`staging`)**: `BASEVERSION-BRANCH.SHORT_SHA` (e.g., `1.0.0-develop.a1b2c3d`)
+
+---
+
+## CI/CD Pipeline
+
+The schema package is automatically published when:
+
+1. **Trigger**: Push to `develop`, `staging`, or `main` branch
+2. **Condition**: Schema files changed in `src/infrastructure/database/drizzle/schema/`
+3. **Action**:
+   - Install dependencies
+   - Build with tsup
+   - Bump version
+   - Publish to GitHub Packages with branch tag
+
+### Workflow File
+
+See [`.github/workflows/npm-publish.yml`](../../.github/workflows/npm-publish.yml)
+
+### Version Bump Logic
+
+```yaml
+# main branch: Increment patch version
+# Example: 1.0.0 → 1.0.1
+
+# develop/staging: Create prerelease version
+# Example: 1.0.0 → 1.0.0-develop.a1b2c3d
+```
+
+---
+
+## Development
+
+### Building Locally
+
+```bash
+cd src/infrastructure/database/drizzle/schema
+
+# Install dependencies
+pnpm install
+
+# Build the package
+pnpm build
+
+# Run typecheck
+pnpm typecheck
+```
+
+### Testing Changes Before Publishing
+
+1. Make schema changes
+2. Build locally: `pnpm build`
+3. Test in Oppenheimer by adding as local dependency:
+   ```bash
+   # In Oppenheimer project
+   pnpm add file:../oppenheimer/src/infrastructure/database/drizzle/schema
+   ```
+4. Verify types work correctly
+5. Commit and push to trigger CI/CD
+
+---
+
+## Publishing
+
+### Automatic Publishing
+
+The package is automatically published via GitHub Actions when schemas change.
+
+### Manual Publishing (if needed)
+
+```bash
+cd src/infrastructure/database/drizzle/schema
+
+# Login to GitHub Packages
+echo "//npm.pkg.github.com/:_authToken=YOUR_TOKEN" > .npmrc
+
+# Build and publish
+pnpm build
+pnpm publish --tag develop
+```
+
+### Pre-release vs Production
+
+| Action | Tag | Usage |
+|--------|-----|-------|
+| Merge to `develop` | `@develop` | Testing in development |
+| Merge to `staging` | `@staging` | Testing in staging |
+| Merge to `main` | `@latest` | Production release |
+
+---
+
+## Troubleshooting
+
+### "Cannot find module '@compfest-18/oppenheimer-schema'"
+
+1. Verify `.npmrc` is configured correctly
+2. Ensure `GITHUB_TOKEN` is set as environment variable
+3. Check you have access to COMPFEST GitHub Packages
+
+### "Package version not found"
+
+1. Check if the package was actually published
+2. Verify you're using the correct tag (`@latest`, `@develop`, `@staging`)
+3. Check GitHub Actions logs for publish status
+
+### Type Errors After Update
+
+1. Clear node_modules and reinstall:
+   ```bash
+   rm -rf node_modules
+   pnpm install
+   ```
+
+2. If types are outdated, you may need to wait for CI/CD to complete
+
+### Build Errors in Consumer Project
+
+Make sure you have the peer dependencies installed:
+
+```bash
+pnpm add drizzle-orm
+```
+
+---
+
+## License
+
+UNLICENSED - Private. All rights reserved, COMPFEST.
+
+---
+
+## Support
+
+For issues or questions:
+- Open an issue on GitHub: [COMPFEST/oppenheimer](https://github.com/COMPFEST/oppenheimer/issues)
+- Contact the backend team