# Task 8: Prospect Follow-up Audit

## বর্তমান DB check কোথায় হয়

Follow-up eligibility-এর প্রধান table হলো `prospects`।

| Table | ব্যবহৃত column | কাজ |
| --- | --- | --- |
| `prospects` | `status` | শুধু `prospect` অথবা `initial_interview` status follow-up-এর জন্য valid। |
| `prospects` | `follow_up` | ইতোমধ্যে কতবার follow-up হয়েছে তার count। |
| `prospects` | `last_follow_up_date` | সর্বশেষ follow-up time; next 24-hour interval এর reference। |
| `prospects` | `reactivated_at` | Silent থেকে reactivate হলে নতুন waiting period-এর reference। |
| `prospects` | `created_at` | প্রথম follow-up-এর waiting period-এর reference। |
| `upwork_settings` | `follow_up_limit` | সর্বোচ্চ follow-up count; default 3। |
| `upwork_settings` | `follow_up_interval_hours` | দুই follow-up-এর minimum interval; default 24 hours। |

Follow-up history-এর জন্য আলাদা `prospect_follow_ups` table নেই। বর্তমান implementation `activity_logs` table-এ `action = prospects.follow_up`, subject type/id, user id, count এবং time log করে। `prospect_lead_histories` table follow-up history নয়; এটি lead assignment, accepted/rejected response history রাখে।

## Follow-up permission audit

বর্তমান system-এ follow-up-এর জন্য dedicated permission আছে:

| Permission | বর্তমানে কোথায় ব্যবহার হয় | Result |
| --- | --- | --- |
| `prospects.follow_up` | Permission seeder-এ create করা হয়েছে; frontend এই permission থাকলে Follow-up button দেখায়। | Dedicated follow-up permission। |
| `prospects.edit` | Frontend follow-up button দেখায়; backend follow-up route access দেয়। | বর্তমানে follow-up করতে পারে। |
| `prospects.create` | Frontend follow-up button দেখায়; backend follow-up route access দেয়। | বর্তমানে follow-up করতে পারে। |
| `prospects.set_interview` | Backend follow-up route access দেয়, কিন্তু frontend button দেখায় না যদি user-এর শুধু এই permission থাকে। | Route/UI mismatch। |
| `prospects.edit_interview` | শুধু interview update route-এ ব্যবহৃত; follow-up button বা follow-up route-এ ব্যবহৃত নয়। | Follow-up permission নয়। |
| `prospects.reactivate` | Reactivate action-এর জন্য। | Follow-up permission নয়। |

বর্তমান seeded role assignment:

- **admin:** সব permission পায়, তাই follow-up করতে পারে।
- **sales_person:** `prospects.create`, `prospects.edit`, `prospects.set_interview`, `prospects.follow_up` পায়; তাই UI ও route দুই দিকেই access আছে।
- **prospect_lead:** `prospects.follow_up` এবং `prospects.set_interview` পায়, কিন্তু `prospects.edit/create` পায় না। UI button দেখাবে, কিন্তু backend route-এর permission list-এ `prospects.follow_up` নেই—ফলে follow-up API 403 দিতে পারে।
- **writer:** seeded role অনুযায়ী prospect follow-up permission পায় না।

**Root mismatch:** backend `POST /prospects/{id}/follow-up` route এখন `prospects.edit | prospects.create | prospects.set_interview` check করে। Dedicated `prospects.follow_up` permission এই route-এ include করা হয়নি। Approval-এর পরে route-এ `prospects.follow_up` add করে এটিকেই authoritative permission করতে হবে।

## বর্তমান eligibility rule

Backend resource `follow_up_eligible` true করে যখন:

1. status `prospect` বা `initial_interview`;
2. `follow_up < follow_up_limit`;
3. reference time + `follow_up_interval_hours` পার হয়েছে।

Reference time priority: `last_follow_up_date` → `reactivated_at` → `created_at`।
Frontend এই boolean, count ও permission দেখে Follow-up Due button দেখায়।

## Test server-এ কেন কাজ নাও করতে পারে

1. **Permission mismatch:** frontend `prospects.follow_up` থাকলে button দেখায়। কিন্তু backend route বর্তমানে `prospects.edit | prospects.create | prospects.set_interview` permission চায়; `prospects.follow_up` একা route access দেয় না। ফলে follow-up-only user button দেখেও 403 পেতে পারে।
2. **Migration/schema missing:** `follow_up`, `last_follow_up_date` এবং `upwork_settings` 2026_09_15 migration-এ আসে। Migration test server-এ pending হলে service runtime-এ ALTER করার চেষ্টা করে, কিন্তু exception silently ignore করে। DB user-এর ALTER permission না থাকলে পরে unknown-column 500 error হতে পারে।
3. **Expected disabled state:** নতুন prospect-এর ক্ষেত্রে creation time থেকে 24 hours না পার হলে button disabled থাকা business rule অনুযায়ী সঠিক। একইভাবে count 3 হলে বা status Silent/Client/Reject হলে disabled থাকা সঠিক।
4. **Wrong server validation:** follow-up API শুধু status check করে। Count limit ও 24-hour interval server-side validate করে না। তাই direct/repeated request UI rule bypass করতে পারে।
5. **Wrong error status:** business-rule exception controller থেকে 500 হয়ে যায়; actual invalid follow-up-এর জন্য 422 হওয়া উচিত। Test server response দেখে root cause বোঝা কঠিন হয়।
6. **Timezone clarity নেই:** app timezone Asia/Dhaka। Eligibility backend-এ calculate হয়, যা browser timezone issue এড়ায়; কিন্তু timestamp storage/parse-এর UTC policy explicit নয়।

## Approval-এর পরে implementation plan

1. Backend route ও frontend permission একই করা: `prospects.follow_up` permission follow-up API-এর authoritative permission হবে।
2. একটি reusable backend eligibility method তৈরি করা হবে, যা status, limit এবং interval এক জায়গায় evaluate করবে।
3. Follow-up write transaction/row lock-এর মধ্যে করা হবে; double-click বা parallel request duplicate follow-up করতে পারবে না।
4. API level-এ 24-hour wait, count limit এবং invalid status enforce করে clear 422 message ফেরত দেওয়া হবে।
5. Required migration deployment check যোগ করা হবে; request-time ALTER এবং silent catch remove করা হবে।
6. Business approval অনুযায়ী follow-up limit পূরণ হলে Silent immediately হবে, নাকি configured inactivity period শেষে হবে—বর্তমান UI text এবং auto-silent service এই জায়গায় conflict করে।
7. প্রতিটি follow-up-এর immutable audit প্রয়োজন হলে নতুন `prospect_follow_ups` table যোগ করা হবে; না হলে `activity_logs`-কেই official history হিসেবে রাখা হবে।
8. Datetime comparison explicit `Asia/Dhaka`/UTC policy দিয়ে standardize করা হবে।
9. Feature tests যোগ হবে: eligible, too early, limit reached, invalid status, permission denied, duplicate request, migration schema এবং history preservation।

## Test server verification checklist

- `php artisan migrate:status`-এ Upwork follow-up migration executed কি না।
- `prospects` table-এ `follow_up` এবং `last_follow_up_date` আছে কি না।
- `upwork_settings`-এ follow-up limit ও interval value কী।
- Test user-এর permissions-এ `prospects.follow_up` এবং route-required permission আছে কি না।
- Failed request-এর HTTP code এবং response body: 403 permission, 422 eligibility, অথবা 500 schema error।