docs: update initialization guide with setup instructions and database configurations

box-mgnt-note.md

@@ -1,4 +1,4 @@
-## dave note for any changes here
+# dave note for any changes here
 
 ```bash
 pnpm install
@@ -30,7 +30,7 @@ sudo systemctl start mongod
 
 ```
 
-# 重置 mysql 数据库并添加测试数据x
+## 重置 mysql 数据库并添加测试数据x
 
 pnpm run prisma:seed:mysql
 pnpm run prisma:migrate:mysql
@@ -54,18 +54,23 @@ git remote add origin git@47.238.201.61:fct/box-nestjs-monorepo.git
 
 ```
 
+```code
 +-----------+-------------------------------------------------------------------------------------------------------------------------------------+
 | Database | Create Database |
 +-----------+-------------------------------------------------------------------------------------------------------------------------------------+
-| box*admin | CREATE DATABASE `box_admin` /*!40100 DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4*0900_ai_ci */ /_!80016 DEFAULT ENCRYPTION='N' _/ |
+| box*admin | CREATE DATABASE `box_admin` /*!40100 DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4*0900_ai_ci*/ /_!80016 DEFAULT ENCRYPTION='N'_/ |
 +-----------+-------------------------------------------------------------------------------------------------------------------------------------+
+```
 
+```code
 mongosh mongodb://admin:ZXcv%21%21996@localhost:27017/box?authSource=admin
 
-curl -X POST http://47.76.151.238:3200/external-sync/fullsync/tea-copy \
+curl -X POST <http://47.76.151.238:3200/external-sync/fullsync/tea-copy> \
  -H "Content-Type: application/json" \
  -d '{"size": 20}'
+```
 
+```code
 Future<Uint8List> decryptImage(Map<String, dynamic> params) async {
 Uint8List imgBytes = params['imgBytes'];
 String path = params['path'];
@@ -102,3 +107,4 @@ List<int> fileNameList = utf8.encode(path);
 }
 return imgBytes;
 }
+```

box-nestjs-monorepo-init.md

@@ -0,0 +1,697 @@
+# 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+
+