# Security Model Consolidation

## Overview

The M1 ERP system security model has been refactored from a role-based system with duplicate and redundant roles/positions into a clean, consolidated **Position-Role Hierarchy** model.

**Final State:**
- **50 positions** (job titles) - down from 112
- **30 roles** (permission sets) - down from 41
- **Clean mapping** - every position links to exactly one role

---

## Architecture: Position → Role → Permissions

```
User
  ↓
Position (job title)
  ↓
Role (permission set)
  ↓
Permissions (what you can do)
```

### How It Works

1. **User logs in** with their email/password
2. **Auth system fetches user's position** from `users.position_id`
3. **Auth system fetches position's role** from `positions.role_id`
4. **Auth system loads all permissions** for that role from `role_permissions` table
5. **User session is granted those permissions** for the current session

**Result:** When you change a user's position, their permissions automatically change (no need to manually assign roles).

---

## Consolidation Summary

### Positions Reduction: 112 → 50

**Deleted 62 duplicate position records:**

1. **Exact Duplicates (50 deleted)**
   - Removed 50 positions where the title exactly matched a role name
   - Example: "Accountant" position IDs 85, 102 deleted (kept role 120)
   - These were redundant since roles define permissions

2. **Duplicate Position Sets (4 merged)**
   - Deleted Customer Support Manager position 109 (kept 92)
   - Deleted Customer Support Specialist position 108 (kept 91)
   - Deleted Senior Product Manager position 97 (kept 80)
   - Deleted Senior Software Engineer position 94 (kept 77)

3. **Specialty Positions (9 deleted)**
   - Deleted regional sales managers (East, West, Central) - kept generic "Sales Manager"
   - Deleted warehouse specialty roles (Forklift Operator, Machine Operator, Shipping Clerk, Receiving Clerk) - use generic "Warehouse Associate"
   - Deleted junior positions (Junior Accountant, Junior Sales Rep) - use senior role equivalents

### Roles Reduction: 41 → 30

**Deleted 11 completely unused roles (no positions, no users):**
- Manager (generic base role)
- Senior Accountant, Staff Accountant, Accountant, Accounts Payable Clerk, Accounts Receivable Clerk
- Warehouse Associate, Warehouse Supervisor
- Purchasing Agent
- Production Manager, Production Supervisor, Production Worker
- HR Manager, HR Specialist
- Recruiter, IT Support Specialist
- Project Manager
- Operations Analyst, Director of Operations, Operations Manager
- Engineering Manager
- Marketing Manager, Marketing Specialist

---

## Core Roles (30 Total)

Organized by department:

### Executive (5 roles)
- **Admin** (id 1) - System administrator, full access
- **CEO** (id 108) - Chief Executive Officer, C-suite
- **COO** (id 112) - Chief Operating Officer
- **CFO** (id 110) - Chief Financial Officer
- **CTO** (id 111) - Chief Technology Officer

### Finance & Accounting (5 roles)
- **Controller** (id 121) - Finance director, accounting oversight
- **Accounts Payable Manager** (id 70) - AP operations
- **Accounts Receivable Manager** (id 72) - AR operations
- **Payroll Manager** (id 99) - Payroll processing

### Sales & Customer Service (5 roles)
- **Sales Director** (id 76) - Sales leadership
- **Sales Manager** (id 77) - Sales team management
- **Sales Representative** (id 78) - Individual contributor sales
- **Customer Service Manager** (id 79) - Support leadership
- **Customer Service Representative** (id 80) - Support staff

### Operations & Warehouse (4 roles)
- **Operations Director** (id 81) - Operations leadership
- **Warehouse Manager** (id 82) - Warehouse operations
- **Inventory Controller** (id 87) - Inventory management
- **Purchasing Manager** (id 85) - Purchasing oversight

### Manufacturing (3 roles)
- **Manufacturing Director** (id 88) - Manufacturing leadership
- **Quality Manager** (id 92) - Quality oversight
- **Quality Inspector** (id 93) - Quality control

### Human Resources (3 roles)
- **Director of HR** (id 116) - HR leadership
- **HR Coordinator** (id 96) - HR operations
- **Recruiting Manager** (id 97) - Recruitment leadership

### Information Technology (3 roles)
- **IT Manager** (id 101) - IT leadership
- **System Administrator** (id 100) - System administration
- **Software Engineer** (id 126) - Development

### Product & Special (2 roles)
- **Product Manager** (id 127) - Product management
- **President, Batteries & Tech** (id 130) - Division president (reports to CTO)

---

## Positions (50 Total)

Organized by role, showing key examples:

### Executive Positions (5)
- Chief Executive Officer → CEO role
- Chief Financial Officer → CFO role
- Chief Operating Officer → COO role
- Chief Technology Officer → CTO role
- Administrator → Admin role

### Finance Positions (9)
- VP of Finance → CFO role
- Director of Accounting → Controller role
- Accounting Manager → Controller role
- Accounting Supervisor → Controller role
- AP Supervisor, AP Clerk → Accounts Payable Manager role
- AR Supervisor, AR Clerk → Accounts Receivable Manager role
- Payroll Specialist → Payroll Manager role

### Sales Positions (10)
- VP of Sales → Sales Director role
- Sales Manager (3) → Sales Manager role
- Sales Team Lead (3) → Sales Representative role
- Senior Sales Representative → Sales Manager role
- Customer Service Lead → Customer Service Manager role
- Customer Support Manager → Customer Service Manager role
- Customer Support Specialist → Customer Service Representative role

### Operations Positions (8)
- Director of Operations → Operations Director role
- Director of Supply Chain → Inventory Controller role
- Receiving Supervisor → Warehouse Manager role
- Shipping Supervisor → Warehouse Manager role
- Warehouse Associate (2) → Warehouse Associate role
- Receiving Clerk, Shipping Clerk → Warehouse Associate role
- Inventory Control Manager → Inventory Controller role

### Manufacturing Positions (6)
- Director of Manufacturing → Operations Director role
- Quality Control Manager → Quality Manager role
- Quality Inspector Lead → Quality Inspector role

### HR Positions (5)
- Director of HR Operations → Director of HR role
- Director of Talent Acquisition → Recruiting Manager role
- HR Coordinator Lead → HR Coordinator role
- HR Assistant → HR Coordinator role
- Recruiting Manager → Recruiting Manager role
- Recruiter Lead → Recruiting Manager role

### IT Positions (4)
- Director of IT → IT Manager role
- Database Administrator → System Administrator role
- Systems Administrator → System Administrator role
- IT Support Lead → IT Manager role

### Product & Other Positions (3)
- Senior Product Manager → Product Manager role
- Senior Software Engineer → Software Engineer role
- President → President, Batteries & Tech role

---

## User Assignment Flow

### When creating a new employee:

1. **Create Position** (if needed) via HR > Positions
   - Example: "Senior Accountant" position
   - Set Department, Level, Reports To
   - **Select Role**: "Controller" (this determines permissions)

2. **Create User** via User Management
   - Set email, password
   - **Assign Position**: "Senior Accountant"
   - (role permissions are inherited from position)

3. **User logs in**
   - Auth system gets position "Senior Accountant"
   - Auth system gets role "Controller" from position
   - Auth system loads all Controller permissions
   - User session is granted those permissions

### Changing a user's role:

- **Change their position** (e.g., "Senior Accountant" → "AP Supervisor")
- Position already links to role (AP Supervisor → Accounts Payable Manager)
- **Permissions automatically update** on next login
- No need to manually reassign roles

---

## Permission Assignment

Permissions are configured in the database via:

1. **roles** table - list of all roles
2. **permissions** table - list of all permissions (e.g., "users.view", "crm.create")
3. **role_permissions** table - junction table linking roles to permissions

### To add a permission to a role:

```sql
INSERT INTO role_permissions (role_id, permission_id)
VALUES (121, 5);  -- Add permission 5 to Controller role (121)
```

### To remove a permission from a role:

```sql
DELETE FROM role_permissions WHERE role_id = 121 AND permission_id = 5;
```

**Effects:** All users with that role lose that permission on next login.

---

## Common Tasks

### Add a new position without changing permissions

1. Create position in HR > Positions
2. Select existing role (e.g., "Sales Representative")
3. Assign users to this position
4. Done - they inherit that role's permissions

### Create a new role with custom permissions

1. Insert into `roles` table:
   ```sql
   INSERT INTO roles (name, description) VALUES ('Warehouse Supervisor', 'Supervises warehouse operations');
   ```

2. Add permissions to this role:
   ```sql
   INSERT INTO role_permissions (role_id, permission_id) SELECT 'NEW_ROLE_ID', id FROM permissions WHERE name LIKE 'warehouse%';
   ```

3. Create positions that link to this role
4. Assign users to those positions

### Consolidate two similar positions

1. Move all employees from Position A to Position B (both link to same role)
2. Delete Position A
3. Done - employees still have same permissions

---

## Why This Architecture?

**Before (messy):**
- 112 positions, 41 roles
- Many duplicate positions with same name as roles
- Hard to manage who has what permission
- Regional position variants created redundancy

**After (clean):**
- 50 focused positions (job titles)
- 30 core roles (permission sets)
- Clear separation: positions are titles, roles are permissions
- Easy to add new positions (just pick existing role)
- Easy to change permissions (modify role, all users with that role update on next login)

---

## Files Modified

- `/core/Auth.php` - Updated to load permissions from position → role → permissions chain
- `/models/Position.php` - Added `role_id` column support
- `/controllers/PositionController.php` - Added role selection to forms
- `/views/hr/positions/create.php` - Added role dropdown
- `/views/hr/positions/edit.php` - Added role dropdown

---

## Data Dictionary

### positions table
- `id` - Position ID
- `title` - Position job title (e.g., "Sales Manager")
- `department` - Department name
- `level` - Hierarchy level (Entry, Junior, Mid, Senior, Lead, Manager, Director, Executive)
- `role_id` - **FK to roles.id** - Links position to permission set
- `reports_to_position_id` - FK to positions.id - Reporting structure
- `is_active` - 1 = active, 0 = inactive
- `created_at`, `updated_at` - Timestamps

### roles table
- `id` - Role ID
- `name` - Role name (e.g., "Sales Manager")
- `description` - Role description
- `is_system` - 1 = system role (Admin, Manager)

### role_permissions table
- `role_id` - FK to roles.id
- `permission_id` - FK to permissions.id
- Links roles to their permissions

---

## Testing the System

1. **Log in as a user with a position:**
   - Verify their sidebar shows appropriate menu items
   - Verify they can see permitted resources

2. **Change a user's position:**
   - Reassign to different position (linked to different role)
   - Log out and back in
   - Verify permissions changed

3. **Add/remove permission from a role:**
   - Insert/delete row in role_permissions
   - Users with that role see change on next login

---

## Support

For questions about:
- **Permission structure**: See `WARP.md` - Security Requirements section
- **User management**: See User Management controller
- **Adding new features**: See `WARP.md` - New Module Checklist (step 8 for permissions)