507 lines
10 KiB
Markdown
507 lines
10 KiB
Markdown
# 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!** 🎉
|
|
|