# Box NestJS Monorepo - Initialization Guide

> **Complete setup guide for Box Management API monorepo from scratch**

## 📋 Prerequisites

Before starting, ensure you have:

- **Node.js**: v20+ installed
- **pnpm**: v8+ installed (`npm install -g pnpm`)
- **MySQL**: v8.0+ running
- **MongoDB**: v6.0+ running
- **Git**: For version control

---

## 🚀 Step 1: Initial PNPM Installation

### 1.1 Clone and Install Dependencies

```bash
# Navigate to monorepo root
cd box-nestjs-monorepo

# Install all dependencies for monorepo
# This will install dependencies for:
# - Root workspace
# - apps/box-mgnt-api
# - libs/common
# - libs/core
# - libs/db
pnpm install
```

**What this does:**

- Installs all dependencies defined in `package.json`
- Creates symlinks between workspace packages (`@box/common`, `@box/core`, `@box/db`)
- Generates `node_modules/` and `pnpm-lock.yaml`
- Sets up Prisma client generators

**Expected output:**

```
Packages: +XXX
Progress: resolved XXX, reused XXX, downloaded 0, added XXX
Done in Xs
```

### 1.2 Verify Installation

```bash
# Check if NestJS CLI is available
pnpm nest --version

# Verify workspace structure
pnpm list --depth=0
```

---

## 🗄️ Step 2: Database Setup

### 2.1 Configure Environment Variables

Create `.env.mgnt.dev` in the monorepo root:

```bash
# Copy from template (if exists) or create new
touch .env.mgnt.dev
```

**Minimum required configuration:**

```dotenv
# Application Environment
APP_ENV=development

# MySQL Database Connection
MYSQL_URL="mysql://root:your_password@localhost:3306/box_admin"
# Optional: For migrations in development
# MYSQL_SHADOW_URL="mysql://root:your_password@localhost:3306/box_admin_shadow"

# MongoDB Connection
MONGO_URL="mongodb://admin:your_password@localhost:27017/box_admin?authSource=admin"

# Application Server
APP_HOST=0.0.0.0
APP_PORT=3300
APP_CORS_ORIGIN=*

# JWT Configuration
JWT_SECRET=047df8aaa3d17dc1173c5a9a3052ba66c2b0bd96937147eb643319a0c90d132f
JWT_ACCESS_TOKEN_TTL=43200

# 2FA Encryption
TWOFA_ENC_KEY=2q89JPacSKDmuU3hJCfKQhDg3sq74QScy0ShYBoQPgM=
APP_ISSUER=BOX-MGNT

# External APIs (optional for initial setup)
MGNT_API_URL=http://47.76.151.238:83
MGNT_API_TOKEN=
IMCHAT_API_URL=http://47.76.151.238:88
IMCHAT_API_TOKEN=
GAME_SERVER_ADMIN_API_URL=http://119.28.182.132:83
GAME_SERVER_TOKEN=

# Partner Integration (optional)
B_BASE_URL=https://wwapi.hxc1t.com
B_SIGN_SECRET=Z3VhbmNpbmV3ZWl4aWFvMTIzNDU2
PARTNER_MD5_KEY=160360904be3dd23bf4f1278a74196efdbf3f9b834ce883ef6ae09eb05c5c652
PARTNER_ITEMS_LIMIT=100
B_BASE_ORDER_ADD=/open/open/order/add
B_BASE_ORDER_UPDATE_STATUS=/open/open/order/updateStatus
B_BASE_CHAT_ADD=/open/order/chat/send
```

**Generate secure secrets:**

```bash
# Generate JWT_SECRET
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

# Generate TWOFA_ENC_KEY
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
```

### 2.2 Create Databases

**MySQL:**

```bash
# Connect to MySQL
mysql -u root -p

# Create database
CREATE DATABASE box_admin CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

# Optional: Create shadow database for migrations
CREATE DATABASE box_admin_shadow CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

# Verify
SHOW DATABASES LIKE 'box_%';
exit;
```

**MongoDB:**

```bash
# Connect to MongoDB
mongosh -u admin -p

# Switch to box_admin database (auto-created on first use)
use box_admin

# Verify connection
db.stats()
exit
```

---

## 🔧 Step 3: Initial Database Migrations

### 3.1 Generate Prisma Clients

```bash
# Generate both MySQL and MongoDB Prisma clients
pnpm prisma:generate

# Or generate separately:
pnpm prisma:generate:mysql
pnpm prisma:generate:mongo
```

**What this does:**

- Reads schema files from `prisma/mysql/schema/*.prisma`
- Reads schema files from `prisma/mongo/schema/*.prisma`
- Generates TypeScript client at `node_modules/@prisma/mysql/client`
- Generates TypeScript client at `node_modules/@prisma/mongo/client`

**Expected output:**

```
✔ Generated Prisma Client (MySQL) to ./node_modules/@prisma/mysql/client
✔ Generated Prisma Client (MongoDB) to ./node_modules/@prisma/mongo/client
```

### 3.2 Run MySQL Migrations

```bash
# Run all migrations and create database schema
pnpm prisma:migrate:dev:mysql
```

**What this does:**

- Creates all tables defined in `prisma/mysql/schema/*.prisma`
- Applies migration from `prisma/mysql/migrations/20251121082348_init_db/`
- Creates migration history in `_prisma_migrations` table

**Tables created:**

- `sys_user` - User accounts
- `sys_role` - User roles
- `sys_menu` - Menu/permission structure
- `sys_api_permission` - API endpoint permissions
- `sys_user_role` - User-role relationships
- `sys_role_menu` - Role-menu relationships
- `sys_role_api_permission` - Role-API permission relationships
- `sys_login_log` - Login activity logs
- `sys_operation_log` - Operation audit logs
- `sys_quota_log` - User quota tracking

**Verify migration:**

```bash
# Check tables were created
mysql -u root -p box_admin -e "SHOW TABLES;"

# Check migration history
mysql -u root -p box_admin -e "SELECT * FROM _prisma_migrations;"
```

### 3.3 MongoDB Collections

MongoDB collections are created dynamically when first used. Schema is defined in:

- `prisma/mongo/schema/*.prisma`

**Collections:**

- `adsModule` - Advertisement module types
- `ads` - Advertisement content
- `category` - Content categories
- `channel` - Distribution channels
- `home` - Homepage configurations
- `systemParam` - System parameters
- `tag` - Content tags
- `videoMedia` - Video media metadata

---

## 🌱 Step 4: Initial MySQL Seeding

### 4.1 Run Seed Script

```bash
# Seed MySQL database with initial data
pnpm prisma:seed:mysql
```

**What this seeds:**

1. **Admin User** (`sys_user`)

   - Username: `admin`
   - Password: `a123456` (hashed)
   - Email: `admin@box.com`
   - With 2FA disabled by default

2. **Roles** (`sys_role`)

   - Super Admin
   - Marketing Manager
   - Content Manager
   - Customer Support
   - Finance Manager
   - Operations Manager

3. **Menus** (`sys_menu`)

   - Complete menu hierarchy (~120+ menu items)
   - Marketing Center, Content Management, User Management, etc.
   - Directory, Menu, and Button types

4. **API Permissions** (`sys_api_permission`)

   - ~250+ API endpoints
   - Mapped to modules and methods

5. **Role Associations**
   - Admin assigned Super Admin role
   - Role-menu relationships
   - Role-API permission relationships

**Expected output:**

```
🌱 Seeding database...
✓ Created 1 users
✓ Created 6 roles
✓ Created 120+ menus
✓ Created 250+ API permissions
✓ Created user-role associations
✓ Created role-menu associations
✓ Created role-API permission associations
✅ Database seeded successfully!
```

### 4.2 Verify Seeded Data

```bash
# Check user was created
mysql -u root -p box_admin -e "SELECT id, username, nickname, email FROM sys_user;"

# Check roles
mysql -u root -p box_admin -e "SELECT id, name, code FROM sys_role;"

# Check menus (top-level)
mysql -u root -p box_admin -e "SELECT id, title, name, path FROM sys_menu WHERE parent_id IS NULL;"

# Verify admin has roles
mysql -u root -p box_admin -e "
  SELECT u.username, r.name
  FROM sys_user u
  JOIN sys_user_role ur ON u.id = ur.user_id
  JOIN sys_role r ON ur.role_id = r.id
  WHERE u.username = 'admin';
"
```

### 4.3 Seed MongoDB (Manual)

For MongoDB collections, refer to `mongo-db-seeds.md` for sample data:

```bash
# Connect to MongoDB
mongosh -u admin -p box_admin

# Example: Seed adsModule collection
db.adsModule.insertMany([
  { adsModule: "启动页(10:21)" },
  { adsModule: "轮播(2:1)" },
  { adsModule: "弹窗-图标(1:1)" },
  { adsModule: "弹窗-图片(2:3)" },
  { adsModule: "弹窗-官方(2:3)" },
  { adsModule: "瀑布流-图标(1:1)" },
  { adsModule: "瀑布流-文字" },
  { adsModule: "布流-视频(8:5)" },
  { adsModule: "悬浮-底部(1:1)" },
  { adsModule: "悬浮-边缘(1:1)" },
  { adsModule: "banner(4:1)" },
  { adsModule: "片头(8:5)" },
  { adsModule: "暂停(2:1)" }
])

# Verify
db.adsModule.find()
```

**Note:** Full MongoDB seeding scripts are in `mongo-db-seeds.md`. Implement as needed for your environment.

---

## 🔄 Step 5: Quick Setup (All-in-One)

For convenience, run all MySQL setup steps at once:

```bash
# Generate clients + Run migrations + Seed data
pnpm prisma:setup:mysql
```

This is equivalent to:

```bash
pnpm prisma:migrate:dev:mysql && pnpm prisma:seed:mysql
```

---

## ✅ Step 6: Verify Installation

### 6.1 Start Development Server

```bash
# Start Box Management API in watch mode
pnpm dev:mgnt
```

**Expected output:**

```
[Nest] INFO [NestFactory] Starting Nest application...
[Nest] INFO [InstanceLoader] AppModule dependencies initialized
[Nest] INFO [RoutesResolver] AuthController {/mgnt/auth}
[Nest] INFO [RoutesResolver] UserController {/mgnt/user}
...
[Nest] INFO [NestApplication] Nest application successfully started
🚀 Server running on http://0.0.0.0:3300
📚 API Documentation: http://0.0.0.0:3300/api-docs
```

### 6.2 Test API Endpoints

**Health Check:**

```bash
curl http://localhost:3300/health
```

**Login with seeded admin:**

```bash
curl -X POST http://localhost:3300/mgnt/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "a123456"
  }'
```

**Expected response:**

```json
{
  "success": true,
  "code": "OK",
  "message": "success",
  "data": {
    "account": "admin",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "avatar": null,
    "nickname": "Administrator",
    "email": "admin@box.com",
    ...
  },
  "timestamp": "2025-11-23T12:34:56.789Z"
}
```

### 6.3 Access Swagger Documentation

Open browser: `http://localhost:3300/api-docs`

---

## 🔄 Future: Adding New MySQL Migrations

### When to Create a Migration

- Adding new tables
- Modifying existing table columns
- Adding/removing indexes
- Changing relationships
- Any schema changes

### Migration Workflow

#### 1. Modify Prisma Schema

Edit files in `prisma/mysql/schema/`:

```prisma
// Example: Add new field to user.prisma
model SysUser {
  id              Int       @id @default(autoincrement())
  username        String    @unique @db.VarChar(50)
  // ... existing fields ...

  // NEW: Add phone number field
  phone           String?   @db.VarChar(20)

  @@map("sys_user")
}
```

#### 2. Create Migration

```bash
# Generate migration with descriptive name
pnpm prisma:migrate:dev:mysql
# When prompted, enter migration name: add_user_phone_field
```

**What happens:**

- Prisma detects schema changes
- Creates new migration file in `prisma/mysql/migrations/XXXXXXXXXXXXXX_add_user_phone_field/`
- Contains SQL DDL statements
- Applies migration to database
- Updates `_prisma_migrations` table
- Regenerates Prisma Client

#### 3. Review Generated Migration

```bash
# Check the generated SQL
cat prisma/mysql/migrations/XXXXXXXXXXXXXX_add_user_phone_field/migration.sql
```

**Example output:**

```sql
-- AlterTable
ALTER TABLE `sys_user` ADD COLUMN `phone` VARCHAR(20) NULL;
```

#### 4. Update Seed Data (if needed)

If your migration requires seed data updates:

```typescript
// prisma/mysql/seed.ts
const adminUser = {
  username: 'admin',
  password: await bcrypt.hash('a123456', 10),
  phone: '+1234567890', // Add new field
  // ... other fields
};
```

#### 5. Verify Migration

```bash
# Check database schema
mysql -u root -p box_admin -e "DESCRIBE sys_user;"

# Check migration history
mysql -u root -p box_admin -e "
  SELECT migration_name, finished_at, applied_steps_count
  FROM _prisma_migrations
  ORDER BY finished_at DESC
  LIMIT 5;
"
```

### Migration Best Practices

**✅ DO:**

- Use descriptive migration names
- Test migrations in development first
- Back up production database before migrating
- Review generated SQL before applying
- Keep migrations atomic (one logical change)
- Commit migration files to version control

**❌ DON'T:**

- Edit migration files after they're applied
- Delete migration files
- Skip migrations
- Apply migrations manually without Prisma
- Mix MySQL and MongoDB changes in same migration

### Common Migration Commands

```bash
# Create new migration without applying
pnpm exec dotenv -e .env.mgnt.dev -- prisma migrate dev --create-only --schema=prisma/mysql/schema

# Apply pending migrations
pnpm prisma:migrate:dev:mysql

# Reset database (⚠️ DESTRUCTIVE - deletes all data)
pnpm prisma:migrate:reset:mysql

# Check migration status
pnpm exec dotenv -e .env.mgnt.dev -- prisma migrate status --schema=prisma/mysql/schema

# Generate client only (after schema changes)
pnpm prisma:generate:mysql
```

### Handling Migration Conflicts

If multiple developers create migrations:

```bash
# 1. Pull latest changes
git pull origin main

# 2. Check for migration conflicts
pnpm exec dotenv -e .env.mgnt.dev -- prisma migrate status --schema=prisma/mysql/schema

# 3. If conflicts exist, reset and re-migrate
pnpm prisma:migrate:reset:mysql
pnpm prisma:migrate:dev:mysql
```

### Production Migration Strategy

```bash
# 1. Test migration in staging
pnpm exec dotenv -e .env.staging -- prisma migrate deploy --schema=prisma/mysql/schema

# 2. Backup production database
mysqldump -u root -p box_admin > backup_$(date +%Y%m%d_%H%M%S).sql

# 3. Apply to production
pnpm exec dotenv -e .env.production -- prisma migrate deploy --schema=prisma/mysql/schema

# 4. Verify
pnpm exec dotenv -e .env.production -- prisma migrate status --schema=prisma/mysql/schema
```

---

## 🛠️ Troubleshooting

### Issue: pnpm install fails

```bash
# Clear cache and retry
pnpm store prune
rm -rf node_modules pnpm-lock.yaml
pnpm install
```

### Issue: Prisma Client not found

```bash
# Regenerate clients
pnpm prisma:generate
```

### Issue: Migration fails

```bash
# Check database connection
mysql -u root -p -e "SELECT 1"

# Reset and retry (development only)
pnpm prisma:migrate:reset:mysql
pnpm prisma:setup:mysql
```

### Issue: Port 3300 already in use

```bash
# Change port in .env.mgnt.dev
APP_PORT=3301

# Or kill existing process
lsof -ti:3300 | xargs kill -9
```

### Issue: MongoDB connection fails

```bash
# Check MongoDB is running
systemctl status mongod

# Test connection
mongosh -u admin -p --authenticationDatabase admin
```

---

## 📚 Additional Resources

- **Architecture**: See `ARCHITECTURE_FLOW.md`
- **Developer Guide**: See `DEVELOPER_GUIDE.md`
- **Deployment**: See `DEPLOYMENT_CHECKLIST.md`
- **Refactor Summary**: See `REFACTOR_SUMMARY.md`
- **MongoDB Seeds**: See `mongo-db-seeds.md`

---

## 🎯 Quick Reference

| Task                    | Command                         |
| ----------------------- | ------------------------------- |
| Install dependencies    | `pnpm install`                  |
| Generate Prisma clients | `pnpm prisma:generate`          |
| Run migrations          | `pnpm prisma:migrate:dev:mysql` |
| Seed database           | `pnpm prisma:seed:mysql`        |
| Full setup              | `pnpm prisma:setup:mysql`       |
| Start dev server        | `pnpm dev:mgnt`                 |
| Build production        | `pnpm build:mgnt`               |
| Start production        | `pnpm start:mgnt`               |
| Type check              | `pnpm typecheck`                |
| Lint code               | `pnpm lint`                     |
| Run all tests           | `pnpm test`                     |

---

## ✨ Default Credentials

After seeding, login with:

- **Username**: `admin`
- **Password**: `a123456`
- **Email**: `admin@box.com`

**⚠️ IMPORTANT**: Change the default password in production!

---

**Last Updated**: November 23, 2025  
**Prisma Version**: 5.15.0  
**NestJS Version**: 10.3.8  
**Node Version**: 20+