# Fresh Database Setup Guide

## 🎯 Overview

This guide walks you through setting up a **completely fresh database** for the Royal Enfield Workflow Management System.

**Use this when:**
- First-time installation
- Major schema changes require full rebuild
- Moving to production environment
- Resetting development database

---

## ⚡ Quick Start (Automated)

### Linux/Mac:

```bash
cd Re_Backend
chmod +x scripts/fresh-database-setup.sh
./scripts/fresh-database-setup.sh
```

### Windows:

```cmd
cd Re_Backend
scripts\fresh-database-setup.bat
```

**The automated script will:**
1. ✅ Drop existing database (with confirmation)
2. ✅ Create fresh database
3. ✅ Install PostgreSQL extensions
4. ✅ Run all migrations in order
5. ✅ Seed admin configuration
6. ✅ Verify database structure

---

## 📋 Manual Setup (Step-by-Step)

### Prerequisites

```bash
# Check PostgreSQL
psql --version
# Required: PostgreSQL 16.x

# Check Redis
redis-cli ping
# Expected: PONG

# Check Node.js
node --version
# Required: 18.x or higher

# Configure environment
cp env.example .env
# Edit .env with your settings
```

---

### Step 1: Drop Existing Database

```bash
# Connect to PostgreSQL
psql -U postgres

# Drop database if exists
DROP DATABASE IF EXISTS royal_enfield_workflow;

# Exit psql
\q
```

---

### Step 2: Create Fresh Database

```bash
# Create new database
psql -U postgres -c "CREATE DATABASE royal_enfield_workflow OWNER postgres;"

# Verify
psql -U postgres -l | grep royal_enfield
```

---

### Step 3: Install Extensions

```bash
psql -U postgres -d royal_enfield_workflow <<EOF
-- UUID extension
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

-- Text search
CREATE EXTENSION IF NOT EXISTS "pg_trgm";

-- JSONB operators
CREATE EXTENSION IF NOT EXISTS "btree_gin";
EOF
```

---

### Step 4: Run Migrations

```bash
cd Re_Backend
npm install  # If not already done
npm run migrate
```

**Expected Output:**
```
✅ Migration: 2025103000-create-users.ts
✅ Migration: 2025103001-create-workflow-requests.ts
✅ Migration: 2025103002-create-approval-levels.ts
✅ Migration: 2025103003-create-participants.ts
✅ Migration: 2025103004-create-documents.ts
✅ Migration: 20251031_01_create_subscriptions.ts
✅ Migration: 20251031_02_create_activities.ts
✅ Migration: 20251031_03_create_work_notes.ts
✅ Migration: 20251031_04_create_work_note_attachments.ts
✅ Migration: 20251104-create-tat-alerts.ts
✅ Migration: 20251104-create-holidays.ts
✅ Migration: 20251104-create-admin-config.ts
✅ Migration: 20251111-create-conclusion-remarks.ts
✅ Migration: 20251111-create-notifications.ts
```

---

### Step 5: Seed Admin Configuration

```bash
npm run seed:config
```

**This creates default settings for:**
- Email notifications
- TAT thresholds
- Business hours
- Holiday calendar
- AI provider settings

---

### Step 6: Assign Admin User

**Option A: Via SQL Script (Replace YOUR_EMAIL first)**

```bash
# Edit the script
nano scripts/assign-admin-user.sql
# Change: YOUR_EMAIL@royalenfield.com

# Run it
psql -d royal_enfield_workflow -f scripts/assign-admin-user.sql
```

**Option B: Via Direct SQL**

```sql
psql -d royal_enfield_workflow

UPDATE users 
SET role = 'ADMIN'
WHERE email = 'your-email@royalenfield.com';

-- Verify
SELECT email, role FROM users WHERE role = 'ADMIN';
```

---

### Step 7: Verify Setup

```bash
# Check all tables created
psql -d royal_enfield_workflow -c "\dt"

# Check user role enum
psql -d royal_enfield_workflow -c "\dT+ user_role_enum"

# Check your user
psql -d royal_enfield_workflow -c "SELECT email, role FROM users WHERE email = 'your-email@royalenfield.com';"
```

---

### Step 8: Start Backend

```bash
npm run dev
```

Expected output:
```
🚀 Server started on port 5000
🗄️  Database connected
🔴 Redis connected
📡 WebSocket server ready
```

---

## 📊 Database Schema (Fresh Setup)

### Tables Created (in order):

1. ✅ **users** - User accounts with RBAC (role field)
2. ✅ **workflow_requests** - Workflow requests
3. ✅ **approval_levels** - Approval workflow steps
4. ✅ **participants** - Request participants
5. ✅ **documents** - Document attachments
6. ✅ **subscriptions** - User notification preferences  
7. ✅ **activities** - Audit trail
8. ✅ **work_notes** - Collaboration messages
9. ✅ **work_note_attachments** - Work note files
10. ✅ **tat_alerts** - TAT/SLA alerts
11. ✅ **holidays** - Holiday calendar
12. ✅ **admin_config** - System configuration
13. ✅ **conclusion_remarks** - AI-generated conclusions
14. ✅ **notifications** - Notification queue

---

## 🔑 User Roles (RBAC)

### Default Role: USER

**All new users automatically get `USER` role on first login.**

### Assign MANAGEMENT Role

```sql
-- Single user
UPDATE users SET role = 'MANAGEMENT' 
WHERE email = 'manager@royalenfield.com';

-- Multiple users
UPDATE users SET role = 'MANAGEMENT'
WHERE email IN (
  'manager1@royalenfield.com',
  'manager2@royalenfield.com'
);

-- By department
UPDATE users SET role = 'MANAGEMENT'
WHERE department = 'Management' AND is_active = true;
```

### Assign ADMIN Role

```sql
-- Single user
UPDATE users SET role = 'ADMIN'
WHERE email = 'admin@royalenfield.com';

-- Multiple admins
UPDATE users SET role = 'ADMIN'
WHERE email IN (
  'admin1@royalenfield.com',
  'admin2@royalenfield.com'
);

-- By department
UPDATE users SET role = 'ADMIN'
WHERE department = 'IT' AND is_active = true;
```

---

## 🔍 Verification Queries

### Check All Tables

```sql
SELECT tablename 
FROM pg_tables 
WHERE schemaname = 'public' 
ORDER BY tablename;
```

### Check Role Distribution

```sql
SELECT 
  role,
  COUNT(*) as user_count,
  COUNT(CASE WHEN is_active = true THEN 1 END) as active_users
FROM users 
GROUP BY role
ORDER BY 
  CASE role
    WHEN 'ADMIN' THEN 1
    WHEN 'MANAGEMENT' THEN 2
    WHEN 'USER' THEN 3
  END;
```

### Check Admin Users

```sql
SELECT 
  email,
  display_name,
  department,
  role,
  created_at,
  last_login
FROM users 
WHERE role = 'ADMIN' AND is_active = true
ORDER BY email;
```

### Check Extended SSO Fields

```sql
SELECT 
  email,
  display_name,
  manager,
  job_title,
  postal_address,
  mobile_phone,
  array_length(ad_groups, 1) as ad_group_count
FROM users 
WHERE email = 'your-email@royalenfield.com';
```

---

## 🧪 Test Your Setup

### 1. Create Test User (via API)

```bash
curl -X POST http://localhost:5000/api/v1/auth/okta/callback \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@royalenfield.com",
    "displayName": "Test User",
    "oktaSub": "test-sub-123"
  }'
```

### 2. Check User Created with Default Role

```sql
SELECT email, role FROM users WHERE email = 'test@royalenfield.com';
-- Expected: role = 'USER'
```

### 3. Update to ADMIN

```sql
UPDATE users SET role = 'ADMIN' WHERE email = 'test@royalenfield.com';
```

### 4. Verify API Access

```bash
# Login and get token
curl -X POST http://localhost:5000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "test@royalenfield.com", ...}'

# Try admin endpoint (should work if ADMIN role)
curl http://localhost:5000/api/v1/admin/configurations \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

## 📦 Migration Files (Execution Order)

| Order | Migration File | Purpose |
|-------|---------------|---------|
| 1 | `2025103000-create-users.ts` | Users table with role + SSO fields |
| 2 | `2025103001-create-workflow-requests.ts` | Workflow requests |
| 3 | `2025103002-create-approval-levels.ts` | Approval levels |
| 4 | `2025103003-create-participants.ts` | Participants |
| 5 | `2025103004-create-documents.ts` | Documents |
| 6 | `20251031_01_create_subscriptions.ts` | Subscriptions |
| 7 | `20251031_02_create_activities.ts` | Activities/Audit trail |
| 8 | `20251031_03_create_work_notes.ts` | Work notes |
| 9 | `20251031_04_create_work_note_attachments.ts` | Work note attachments |
| 10 | `20251104-create-tat-alerts.ts` | TAT alerts |
| 11 | `20251104-create-holidays.ts` | Holidays |
| 12 | `20251104-create-admin-config.ts` | Admin configuration |
| 13 | `20251111-create-conclusion-remarks.ts` | Conclusion remarks |
| 14 | `20251111-create-notifications.ts` | Notifications |

---

## ⚠️ Important Notes

### is_admin Field REMOVED

❌ **OLD (Don't use):**
```typescript
if (user.is_admin) { ... }
```

✅ **NEW (Use this):**
```typescript
if (user.role === 'ADMIN') { ... }
```

### Default Values

| Field | Default Value | Notes |
|-------|---------------|-------|
| `role` | `USER` | Everyone starts as USER |
| `is_active` | `true` | Accounts active by default |
| All SSO fields | `null` | Optional, populated from Okta |

### Automatic Behaviors

- 🔄 **First Login**: User created with role=USER
- 🔒 **Admin Assignment**: Manual via SQL or API
- 📧 **Email**: Required and unique
- 🆔 **oktaSub**: Required and unique from SSO

---

## 🚨 Troubleshooting

### Migration Fails

```bash
# Check which migrations ran
psql -d royal_enfield_workflow -c "SELECT * FROM SequelizeMeta ORDER BY name;"

# Rollback if needed
npm run migrate:undo

# Re-run
npm run migrate
```

### User Not Created on Login

```sql
-- Check if user exists
SELECT * FROM users WHERE email = 'your-email@royalenfield.com';

-- Check Okta sub
SELECT * FROM users WHERE okta_sub = 'your-okta-sub';
```

### Role Not Working

```sql
-- Verify role
SELECT email, role, is_active FROM users WHERE email = 'your-email@royalenfield.com';

-- Check role enum
\dT+ user_role_enum
```

---

## 📞 Quick Commands Reference

```bash
# Fresh setup (automated)
./scripts/fresh-database-setup.sh

# Make yourself admin
psql -d royal_enfield_workflow -c "UPDATE users SET role = 'ADMIN' WHERE email = 'your@email.com';"

# Check your role
psql -d royal_enfield_workflow -c "SELECT email, role FROM users WHERE email = 'your@email.com';"

# Start server
npm run dev

# Check logs
tail -f logs/application.log
```

---

## ✅ Success Checklist

- [ ] PostgreSQL 16.x installed
- [ ] Redis running
- [ ] .env configured
- [ ] Database created
- [ ] All migrations completed (14 tables)
- [ ] Admin config seeded
- [ ] At least one ADMIN user assigned
- [ ] Backend server starts without errors
- [ ] Can login and access admin endpoints

---

**Your fresh database is now production-ready!** 🎉