# ERPFlow — nwidart Migration Implementation Phases

**লক্ষ্য:** Module code সম্পূর্ণ **nwidart/laravel-modules** দিয়ে organize করা; **Role/Permission, Approval, Onboarding, Activity Log** Platform layer-এ manually (Admin UI + code) রাখা; Frontend sidebar **core-এ central menu file** + `can()` check।

**সংস্করণ:** 1.1  
**সম্পর্কিত:** [docs/MODULE_DEVELOPMENT_GUIDE.md](./docs/MODULE_DEVELOPMENT_GUIDE.md), [docs/APPROVAL_FLOW_BN.md](./docs/APPROVAL_FLOW_BN.md)

---

## সারাংশ — শেষ অবস্থায় কী হবে

```
┌─────────────────────────────────────────────────────────────┐
│  nwidart Module (filesystem — code only)                    │
│    Routes · Controllers · Services · Repositories             │
└──────────────────────────┬──────────────────────────────────┘
                           │ API (JWT + X-Company-Id only)
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  Platform (manual admin + code wiring)                      │
│    Roles · Permissions · Approval · Onboarding · Activity   │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  Frontend                                                   │
│    core/config/navigation.ts  →  সব module-এর sidebar menu  │
│    modules/{slug}/index.tsx   →  শুধু routes                │
│    can() + RequirePermissionRoute + PermissionGuard         │
└─────────────────────────────────────────────────────────────┘
```

### যা বাদ যাবে

| বাদ | কারণ |
|-----|------|
| ERPFlow `PluginDiscovery` / `PluginSync` | nwidart + Admin UI যথেষ্ট |
| ERPFlow `module.json` (actions/menus/permissions) | Admin UI + frontend menu code |
| `platform:sync` (permission setup-এর জন্য) | Admin → Actions / Modules / Roles |
| `BaseModuleServiceProvider` | nwidart RouteServiceProvider |
| Backend-driven sidebar (`GET /me/navigation`) | `core/config/navigation.ts` |
| Menu Builder (sidebar-এর জন্য) | Optional — audit-only রাখতে পারো |
| Per-module `navigation` in `index.tsx` | Central core sidebar ব্যবহার করবে |

### যা রাখবে (কখনো সরাবে না)

| রাখবে | কেন |
|-------|-----|
| `PermissionEngine`, `RoleEngine` | API + UI permission check |
| `ApprovalEngine`, `ApprovalGateway` | Approval workflow (যখন লাগে) |
| Onboarding middleware | `auth:api`, `onboarding.access`, `onboarding.document` |
| `ActivityLogService` | Audit trail |
| DB: `modules`, `module_actions`, `permissions`, `roles` | Role Matrix — permission **grouping** (plugin registry নয়) |
| `GET /me/permissions` | Frontend `can()` check |

> **গুরুত্বপূর্ণ:** `modules` DB টেবিল = nwidart folder registry **নয়**। এটা Role Matrix-এ permission group (`configuration`, `hrms`)। Admin UI দিয়ে manually setup করা হয়; nwidart-এর সাথে auto-link নেই।

---

## `module.json` — কখন কী লিখতে হবে?

| ফাইল | লিখতে হবে? | কারণ |
|------|------------|------|
| **ERPFlow** `backend/Modules/.../module.json` | ❌ **না** | `platform:sync`, actions, menus — বাদ। Migration后 delete |
| **nwidart** `module.json` | ⚠️ প্রায় না | `module:make` auto তৈরি করে (providers, alias)। হাতে বড় কিছু লিখার দরকার নেই |

Permission, menu, role — **কোনোটাই ERPFlow `module.json`-এ manually লিখতে হবে না।**

---

## Frontend File Responsibilities

| ফাইল | দায়িত্ব |
|------|----------|
| `frontend/src/modules/core/config/navigation.ts` | **সব module-এর sidebar menu** (central, manually) |
| `frontend/src/modules/core/hooks/useNavigation.ts` | `appNavigation` + `can()` filter |
| `frontend/src/modules/core/components/layout/Sidebar.tsx` | Menu render (পরিবর্তন কম) |
| `frontend/src/modules/{slug}/index.tsx` | **শুধু routes** + `RequirePermissionRoute` |
| `frontend/src/app/registerModules.ts` | Module route registration |

`configuration/index.tsx` Configuration module-এর জন্য তৈরি — কিন্তু **menu সেখানে লেখা বাধ্যতামূলক নয়**। অনেক module হলে menu এক জায়গায় (`navigation.ts`) রাখা সহজ।

---

## Non-Negotiable Rules

1. **Permission key format:** `{group_slug}.{action_slug}` — যেমন `configuration.employee`
2. **Frontend `can(key)`** এবং **backend `permission:key`** — একই string
3. **API request-এ permission পাঠানো যাবে না** — শুধু `Authorization: Bearer {token}` + `X-Company-Id`
4. **Onboarding middleware** — সব business API route-এ
5. **Approval** — শুধু create/update/delete-এ **যখন Admin-এ approval ON**; তখন `ApprovalGateway::submit()` বাধ্য
6. **Activity log** — sensitive business action-এ `ActivityLogService::log()`

---

## Permission vs Approval (আলাদা জিনিস)

| | Permission | Approval |
|--|------------|----------|
| প্রশ্ন | কে action করতে **পারবে**? | Permission থাকলেও action **এখনই** হবে নাকি **approve পরে**? |
| Backend | `middleware('permission:...')` | `ApprovalGateway::submit()` |
| Frontend | `can()` + `RequirePermissionRoute` | Pending UI / approval status |
| সব API-তে লাগে? | হ্যাঁ (protected routes) | **না** — শুধু CUD যখন workflow ON |

Approval OFF থাকলে সরাসরি `repository->create()` যথেষ্ট — `ApprovalGateway` লাগে না।

---

## Phase 0 — Baseline & Regression Checklist

**সময়:** ১–২ দিন · **Risk:** কম

### কাজ

- [ ] Configuration module দিয়ে current flow document করো
- [ ] Postman collection: login, `/me/permissions`, `/configuration/health`, `/configuration/employee`
- [ ] Test users: `developer` (admin), `employee` role user
- [ ] Role Matrix-এ existing permission keys note করো

### Verify Matrix (প্রতি phase-এ repeat)

| Area | Test | Pass? |
|------|------|-------|
| Auth | Login → token | |
| Permission | Employee user without `configuration.employee` → 403 API, redirect UI | |
| Permission | Role assign后 → access granted | |
| Onboarding | Incomplete user blocked from business API | |
| Approval | OFF → immediate; ON → pending (if configured) | |
| Activity | Login → `auth.login` in activity log | |

### Rollback

N/A

---

## Phase 1 — nwidart Install (Parallel, Nothing Removed)

**সময়:** ১–২ দিন · **Risk:** কম

### কাজ

```bash
composer require nwidart/laravel-modules
php artisan vendor:publish --provider="Nwidart\Modules\LaravelModulesServiceProvider"
```

- [ ] nwidart config (`modules.php`) — path `Modules/`
- [ ] Shared route middleware group:
  ```
  auth:api, onboarding.access, onboarding.document
  ```
- [ ] **বর্তমান `Modules/Configuration/` সরাও না** — parallel রাখো

### Do NOT touch

- `PluginLoader`, `PluginSync`, `BaseModuleServiceProvider`
- Platform engines (Role, Permission, Approval, Activity, Onboarding)

### Verify

- [ ] Existing Configuration API still works
- [ ] `php artisan module:list` shows modules (after pilot in Phase 2)

### Rollback

Disable nwidart module; old provider remains

---

## Phase 2 — Pilot: Configuration via nwidart

**সময়:** ৩–৫ দিন · **Risk:** মাঝারি

### Backend

- [ ] `php artisan module:make Configuration` (nwidart structure)
- [ ] Controllers, Services, Repositories → nwidart module
- [ ] `Routes/api.php`:
  ```php
  Route::middleware(['auth:api', 'onboarding.access', 'onboarding.document'])
      ->group(function () {
          Route::middleware('permission:configuration.view')->get('/health', ...);
          Route::middleware('permission:configuration.employee')->get('/employee', ...);
      });
  ```
- [ ] Prefix: `api/v1/configuration`
- [ ] পুরানো `ConfigurationServiceProvider` disable — verify后

### Permission DB (Manual Admin — NO `platform:sync`)

- [ ] Admin → Actions → `employee` (যদি নেই)
- [ ] Admin → Modules → `Configuration` + actions: `view`, `create`, `update`, `delete`, `employee`
- [ ] Admin → Roles → assign `configuration.*` keys
- [ ] ERPFlow `module.json` edit **করো না**

### Frontend (routes only — menu Phase 3-এ)

- [ ] `configuration/index.tsx` — শুধু `routes` + `RequirePermissionRoute`
- [ ] API client unchanged

### Verify

- [ ] `GET /api/v1/configuration/employee` — 200 / 403
- [ ] `GET /me/permissions` — assigned keys
- [ ] Onboarding incomplete → 403
- [ ] No duplicate routes

### Rollback

Re-enable old `ConfigurationServiceProvider`

---

## Phase 3 — Central Sidebar Navigation (Core)

**সময়:** ২–৩ দিন · **Risk:** কম–মাঝারি

### কাজ

**নতুন ফাইল:** `frontend/src/modules/core/config/navigation.ts`

```tsx
import type { NavItem } from '../../../shared/types/module';

export const appNavigation: NavItem[] = [
  {
    id: 'dashboard',
    title: 'Dashboard',
    icon: 'bi-house',
    path: '/',
  },
  {
    id: 'configuration',
    title: 'Configuration',
    icon: 'bi-box',
    path: '#',
    permission: 'configuration.view',
    children: [
      {
        id: 'configuration-home',
        title: 'Home',
        path: '/configuration',
        permission: 'configuration.view',
      },
      {
        id: 'configuration-employee',
        title: 'Employee Configuration',
        path: '/configuration/employee',
        permission: 'configuration.employee',
      },
    ],
  },
  // HRMS, Inventory, ... — নতুন module এখানে যোগ
];
```

**`useNavigation.ts`** — backend API সরিয়ে central menu:

```tsx
// Before: menusApi.navigation()  (GET /me/navigation)
// After:  appNavigation + filterNavItems(can)
```

- [ ] `appNavigation` import + `can()` filter
- [ ] `GET /me/navigation` dependency remove (বা fallback সরাও)
- [ ] `configuration/index.tsx`-এ `navigation` field **যোগ করো না**

**Page-level buttons**

```tsx
<PermissionGuard permission="configuration.employee_create">
  <button>Create</button>
</PermissionGuard>
```

### Verify

- [ ] Sidebar `can()` অনুযায়ী show/hide
- [ ] Parent hidden যদি কোনো child permitted না
- [ ] Direct URL → `RequirePermissionRoute` block
- [ ] Menu Builder sidebar-এর উপর নির্ভর নেই

### Rollback

Revert `useNavigation` to API-driven

---

## Phase 4 — Approval Wiring (Optional — যখন দরকার)

**সময়:** ২–৩ দিন · **Risk:** মাঝারি  
**শর্ত:** Admin-এ approval workflow চালু করতে চাইলে only

### Admin (manual)

- [ ] Admin → Modules → `create`, `update`, `delete` actions linked
- [ ] Admin → Approval Settings → `configuration.create` ON
- [ ] Admin → Approval Workflows → `module_action_id` bind

### Module Service (শুধু approval ON থাকলে)

```php
return $this->approvalGateway->submit(new ApprovalSubmissionData(
    moduleSlug: 'configuration',
    actionSlug: 'create',
    companyId: $companyId,
    requesterId: $userId,
    operation: ApprovalOperation::Create,
    entityType: 'employee_config',
    title: 'Create employee configuration',
    payloadAfter: $data,
    onApproved: fn () => $this->repository->create($data),
));
```

Approval OFF → Gateway সাথে সাথে `onApproved()` চালায় (সরাসরি create-এর মতো)।

### Provider

```php
Platform::registerApprovalExecutor('employee_config', EmployeeConfigExecutor::class);
```

### Verify

| Setting | Expected |
|---------|----------|
| Approval OFF | Immediate DB write (Gateway বা direct create) |
| Approval ON | `approval_requests` pending |
| Approve | Executor runs |
| Reject | No DB change |

---

## Phase 5 — Activity Log Standard

**সময়:** ১–২ দিন · **Risk:** কম

```php
$this->activityLogService->log(LogActivityData::make('employee_config.created', [
    'moduleId' => $moduleId,       // optional: modules.id by slug
    'actionKey' => 'configuration.create',
    'subjectType' => 'employee_config',
    'subjectId' => (string) $model->id,
    'properties' => ['name' => $model->name],
]));
```

### Verify

- [ ] Admin → Activity Logs
- [ ] `auth.login` / `auth.logout` unchanged

---

## Phase 6 — New Module Playbook

```
□ php artisan module:make {Name}              (nwidart)
□ Routes + auth + onboarding + permission middleware
□ Admin → Actions (new slugs if needed)
□ Admin → Modules → link actions              (NO platform:sync)
□ Admin → Roles → assign permissions
□ core/config/navigation.ts → menu entry যোগ   (central sidebar)
□ frontend/src/modules/{slug}/index.tsx
    □ routes + RequirePermissionRoute only      (NO navigation here)
□ registerModules.ts import
□ ApprovalGateway (শুধু যদি approval workflow দরকার)
□ ActivityLogService in services
□ Postman requests
```

### Permission naming

```
{group_slug}.{action_slug}

configuration.view
configuration.employee
configuration.employee_create
```

---

## Phase 7 — Deprecate Old Plugin Layer

**সময়:** ২–৩ দিন · **Risk:** উচ্চ — Phase 2–6 stable后

### Remove

| Remove | Replace |
|--------|---------|
| `PluginDiscovery` / `PluginSync` / `PluginRegistrar` | Admin UI |
| `PluginLoader` | nwidart enable |
| ERPFlow `make:module` | `php artisan module:make` |
| `BaseModuleServiceProvider` | nwidart RouteServiceProvider |
| ERPFlow `module.json` per module | Delete |
| `GET /me/navigation` for sidebar | `core/config/navigation.ts` |

### Keep

- Platform engines + Admin UI (Roles, Approval, Activity, Actions, Modules)
- Onboarding
- `GET /me/permissions`

---

## Phase 8 — Documentation Update

- [ ] `docs/MODULE_DEVELOPMENT_GUIDE.md`
- [ ] `docs/MODULE_DEVELOPMENT_GUIDE.bn.md`
- [ ] Postman collection
- [ ] Remove plugin/sync/menu-builder-sidebar references

---

## Developer Quick Reference

### Permission (সব module-এ)

```
Admin → Actions
Admin → Modules (group) + link actions
Admin → Roles → assign

Frontend:
  GET /me/permissions
  can('configuration.employee')
  core/config/navigation.ts (menu)
  RequirePermissionRoute (routes)
  PermissionGuard (buttons)

Backend:
  middleware('permission:configuration.employee')
  Request-এ permission key পাঠাও না
```

### Postman

```http
GET /api/v1/configuration/employee
Authorization: Bearer {token}
X-Company-Id: {company_uuid}
Accept: application/json
```

### Approval (শুধু যখন দরকার)

```
Admin → Approval Settings ON
Admin → Workflow bind to module_action
Service → ApprovalGateway::submit()
Provider → registerApprovalExecutor()
```

### What NOT to do

- ❌ Permission in request body/header
- ❌ `platform:sync` for permissions
- ❌ ERPFlow `module.json` manually edit
- ❌ Menu in `configuration/index.tsx` (use `navigation.ts`)
- ❌ Menu Builder for sidebar
- ❌ `ApprovalGateway` on every endpoint (শুধু CUD + approval ON)
- ❌ Skip onboarding middleware

---

## Timeline Estimate

| Phase | Duration | Cumulative |
|-------|----------|------------|
| 0 | 1–2 days | ~2 days |
| 1 | 1–2 days | ~4 days |
| 2 | 3–5 days | ~9 days |
| 3 | 2–3 days | ~12 days |
| 4 | 2–3 days (optional) | ~15 days |
| 5 | 1–2 days | ~17 days |
| 6 | 1 day | ~18 days |
| 7 | 2–3 days | ~21 days |
| 8 | 1–2 days | ~23 days |

**Total:** ~3–4 weeks

---

## Success Criteria

1. Configuration module nwidart-এ চলে
2. Permission শুধু Admin UI + Role Matrix
3. Sidebar = `core/config/navigation.ts` + `can()`
4. `configuration/index.tsx` = routes only
5. ERPFlow `module.json` unused / removed
6. Approval কাজ করে (যদি configured)
7. Onboarding + Activity log intact
8. Plugin sync code removed
9. নতুন module playbook দিয়ে দ্বিতীয় module add যায়