# System Scripts Execution Guide

## 📋 Overview

This guide tells you **exactly which scripts to run, in what order, and when** from the System Scripts page.

**Page Location:** http://localhost:8080/admin/system-scripts

---

## 🎯 Quick Reference - What Should I Run?

### If You Need To...

| **Goal** | **Run This Script** | **How Often** |
|----------|-------------------|---------------|
| Fix permission security issues | See "Permission Security Workflow" below | Once, then as needed |
| Keep system running smoothly | "System Health Check" | Weekly |
| Free up disk space | "Cleanup Old Logs" | Monthly |
| Speed up database | "Optimize Database Tables" | Monthly |
| Backup before major changes | "Database Backup" | Before changes |
| Check if controllers have docs | "Documentation Coverage Check" | After adding features |

---

## 🔐 PRIORITY 1: Permission Security Workflow

**Run these NOW if you haven't already:**

### Step 1: Understand the Problem
📍 **Script:** `Analyze Unprotected Methods`  
📂 **Category:** Security  
⚙️ **Parameters:** None  
⏱️ **Time:** 3-5 seconds

**What to expect:**
```
✓ Intentionally Public: 9 (OK)
⚠ Test/Dev Controllers: 10 (Remove/Protect)  
? Needs Review: 11 (Evaluate)
⏳ Auth Only: 107 (Medium Priority)
🚨 Needs Protection: 165 (HIGH PRIORITY!)
```

**Action:** Read the output. Note the 165 methods that need immediate protection.

---

### Step 2: Preview the Fix (SAFE - No Changes)
📍 **Script:** `Auto-Fix Permission Checks`  
📂 **Category:** Security  
⚙️ **Parameters:**
- Mode: **Dry Run (Preview Only)**
- Scope: **Only Fix Completely Unprotected Methods**

⏱️ **Time:** 5-10 seconds

**What to expect:**
```
📄 Processing ProjectsController...
  ✓ Would fix dashboard() - add: projects.view
  ✓ Would fix create() - add: projects.create
  [... 165 methods total ...]
  
Files modified: 0 (DRY RUN)
Methods fixed: 165
```

**Action:** Review what will be changed. Make sure it looks reasonable.

---

### Step 3: Apply the Fix (MODIFIES FILES!)
📍 **Script:** `Auto-Fix Permission Checks`  
📂 **Category:** Security  
⚙️ **Parameters:**
- Mode: **Apply Changes (Modifies Files!)**  
- Scope: **Only Fix Completely Unprotected Methods**

⏱️ **Time:** 5-15 seconds

**What to expect:**
```
Files modified: 42
Methods fixed: 165
```

**Action:** Files are now modified. Continue to next step.

---

### Step 4: Add Permissions to Database
📍 **Script:** `Generate Missing Permissions SQL`  
📂 **Category:** Security  
⚙️ **Parameters:** None  
⏱️ **Time:** 2-3 seconds

**What to expect:**
```sql
-- Missing Permissions SQL
INSERT INTO permissions (name, module, description) VALUES
('projects.view', 'projects', 'View Projects'),
('projects.create', 'projects', 'Create Projects'),
...
```

**Action:** 
1. Copy all the SQL from the output
2. Open terminal:
   ```bash
   mysql -u rpmbbu brickwal_m1_ds
   ```
3. Paste the SQL and hit enter
4. Type `exit` to close MySQL

---

### Step 5: Scan Existing Permissions
📍 **Script:** `Permission Scanner`  
📂 **Category:** Permissions  
⚙️ **Parameters:**
- Mode: **Live (Apply Changes)**

⏱️ **Time:** 5-10 seconds

**What to expect:**
```
Synced permissions with database
Added: 42 new permissions
```

**Action:** Ensures all permissions from code are in the database.

---

### Step 6: Assign Permissions to Roles
📍 **Not a script - Use the Web UI**

1. Go to: http://localhost:8080/roles/111/edit
2. Expand each section in the permissions list
3. Check ALL the permissions for your admin role
4. Click "Update Role" at the bottom

**Time:** 5-10 minutes (one time only)

---

### Step 7: Verify Success
📍 **Script:** `Permission Coverage Audit`  
📂 **Category:** Security  
⚙️ **Parameters:** None  
⏱️ **Time:** 5-10 seconds

**What to expect:**
```
Controllers scanned: 147
Total methods: 1,275
Methods with permission checks: 1,138 (89%)  ← Much better!
HIGH severity: ~10 (down from 195)
```

**Action:** Celebrate! You've secured your application. 🎉

---

## 🛠️ PRIORITY 2: Regular Maintenance (Run Monthly)

### Workflow: Monthly Cleanup

**Run these in order once per month:**

#### 1. System Health Check
📍 **Script:** `System Health Check`  
⏱️ **Time:** 10-15 seconds  
**Why:** Checks database, disk space, directories, PHP settings

#### 2. Cleanup Old Logs
📍 **Script:** `Cleanup Old Logs`  
⚙️ **Parameters:**
- Keep logs from last: **90 days** (default)

⏱️ **Time:** 5-15 seconds  
**Why:** Removes old audit logs to free space

#### 3. Optimize Database Tables
📍 **Script:** `Optimize Database Tables`  
⏱️ **Time:** 30-60 seconds  
**Why:** Keeps database fast and efficient

#### 4. Clear Expired Sessions
📍 **Script:** `Clear Expired Sessions`  
⏱️ **Time:** 2-5 seconds  
**Why:** Removes old session data

---

## 💾 PRIORITY 3: Before Making Major Changes

**Run these BEFORE:**
- Deploying to production
- Major database changes
- Testing new features

### Backup Workflow

#### 1. Database Backup
📍 **Script:** `Database Backup`  
⏱️ **Time:** 10-30 seconds  
**Output:** Creates `backup_YYYY-MM-DD_HHMMSS.sql` in `/backups`

#### 2. (Optional) Clear Application Cache
📍 **Script:** `Clear Application Cache`  
⏱️ **Time:** 1 second  
**Why:** Fresh start after changes

---

## 🔍 PRIORITY 4: Audits and Reports (As Needed)

### When to Run:

#### After Adding New Features
📍 **Script:** `Documentation Coverage Check`  
**Why:** Make sure new features are documented

#### If Data Looks Wrong
📍 **Script:** `Data Integrity Check`  
**Why:** Finds orphaned records and broken relationships

#### Before Financial Period Close
📍 **Script:** `Recalculate Customer Balances`  
⚙️ **Mode:** Dry Run (Report Only) first, then Fix if needed

---

## ❌ DON'T RUN (Unless You Know What You're Doing)

### Development/Dangerous Scripts:

⚠️ **Anonymize Test Data** - Irreversibly replaces real data  
⚠️ **Generate Test Records** - Adds dummy data (dev/staging only)  
⚠️ **Close Stale Opportunities** - Auto-closes inactive opportunities

**When to use these:** Only in development/staging environments

---

## 📅 Recommended Schedule

### One-Time Setup (Do Now)
- [ ] Run Permission Security Workflow (Steps 1-7 above)
- [ ] Create initial database backup

### Weekly
- [ ] System Health Check

### Monthly  
- [ ] Cleanup Old Logs (90 days)
- [ ] Optimize Database Tables
- [ ] Clear Expired Sessions
- [ ] System Health Check

### Before Production Deployment
- [ ] Database Backup
- [ ] Permission Coverage Audit
- [ ] System Health Check

### After Adding New Controllers
- [ ] Analyze Unprotected Methods
- [ ] Auto-Fix Permission Checks (if needed)
- [ ] Documentation Coverage Check

---

## 🎓 Understanding the Categories

The scripts are organized into these categories:

### 🔐 **Security** (Most Important)
- Permission audits and fixes
- CSRF token checks
- Access control

### 🔧 **Maintenance** (Regular)
- Cache clearing
- Database optimization  
- Log cleanup

### 📊 **Audit** (As Needed)
- Data integrity checks
- Documentation coverage
- Orphaned file detection

### 👥 **Permissions** (Setup)
- Permission scanning
- Menu sync

### 💾 **Backup** (Before Changes)
- Database backups

### 📈 **Reporting** (Informational)
- System statistics
- Usage reports

### 🔢 **Data Operations** (Careful)
- Inventory recalculation
- Balance updates

### 🛠️ **Development** (Dev/Staging Only)
- Test data generation
- Data anonymization

---

## 💡 Pro Tips

### Tip 1: Always Dry Run First
For scripts that modify data, run in "Dry Run" or "Preview" mode first to see what will happen.

### Tip 2: Check Execution History
Scroll down on the System Scripts page to see "Execution History" - know what was run and when.

### Tip 3: Copy SQL Before Running
For SQL generation scripts, copy the output to a file before running it in the database.

### Tip 4: Read the Output
The output tells you exactly what happened. Don't skip reading it!

### Tip 5: Run Health Check First
If something seems wrong, start with "System Health Check" to diagnose.

---

## 🆘 Quick Troubleshooting

### "Permission denied" after running Auto-Fix
**Fix:** Go to http://localhost:8080/roles/111/edit and assign the new permissions to your role.

### "Script execution failed"
**Check:**
1. Read the error message in the output
2. Check the Execution History for details
3. Try running the script again
4. Check system logs if needed

### "Missing permissions in database"
**Fix:** Run "Generate Missing Permissions SQL" and apply the SQL to your database.

### "Nothing seems to be working"
**Do this:**
1. Run "System Health Check"
2. Run "Permission Coverage Audit"  
3. Check Execution History for errors

---

## 📞 Need More Help?

- **Permission Security:** See `PERMISSION_AUDIT_GUIDE.md`
- **Automation Details:** See `AUTOMATION_GUIDE.md`
- **Quick Fix:** See `QUICK_FIX.md`

---

## ✅ Your First Time Checklist

Use this checklist for your first run:

- [ ] 1. Run "Analyze Unprotected Methods" - See the problem
- [ ] 2. Run "Auto-Fix" in Dry Run mode - Preview solution
- [ ] 3. Run "Auto-Fix" in Apply mode - Fix the issue
- [ ] 4. Run "Generate Missing Permissions SQL" - Get SQL
- [ ] 5. Apply SQL to database via MySQL
- [ ] 6. Run "Permission Scanner" in Live mode - Sync
- [ ] 7. Assign permissions at http://localhost:8080/roles/111/edit
- [ ] 8. Run "Permission Coverage Audit" - Verify success
- [ ] 9. Run "System Health Check" - Ensure everything is good
- [ ] 10. Create a "Database Backup" - Save your work

**Estimated Total Time:** 30-45 minutes (mostly clicking and waiting)

---

**Ready to start?** Go to http://localhost:8080/admin/system-scripts and begin with **"Analyze Unprotected Methods"** in the Security category!