# PMS Commission Business Logic ## Commission, Fixed Team Allocation, Office Expense ও Provident Fund **Document Type:** Business Logic / Implementation Reference **Status:** Updated and Corrected > **Source of Truth:** এই document-এ confirmed business rules-ই implement করতে হবে। কোনো unresolved বিষয় developer নিজের assumption দিয়ে implement করতে পারবে না। ## ১. উদ্দেশ্য PMS-এর মাধ্যমে project-based employee commission, fixed team allocation, office expense এবং provident fund (PF) পরিচালনা করা হবে। Calculation-এর সময় employee eligibility, project contributor assignment, Act As Role, allocation method, client payment, commission configuration, office expense, PF rules এবং Company EPS বিবেচনা করা হবে। ## ২. Official Role এবং Act As Role Employee-এর একটি **Official Role / Designation** থাকবে। কোনো নির্দিষ্ট project-এ employee contributor হিসেবে assigned হলে তার জন্য একটি **Act As Role** থাকবে। দুটি বিষয় আলাদা। **Act As Role অবশ্যই existing Designation List থেকে আসবে। আলাদা hard-coded Act As Role list থাকবে না।** উদাহরণ: ```text Employee Official Role = PM Project Act As Role = Salesperson ``` Employee-এর official designation PM-ই থাকবে, কিন্তু project commission/allocation-এর জন্য project-specific Act As Role ব্যবহার হবে। ## ৩. Multiple Contributors একটি project-এ একাধিক contributor থাকতে পারবে। একই Act As Role-এও একাধিক employee থাকতে পারবে। উদাহরণ: ```text Project A - PM 1 - PM 2 - Manager 1 - Manager 2 - Closer 1 - Closer 2 - Writer 1 - Writer 2 ``` একটি Act As Role-এর জন্য বর্তমানে কোনো confirmed maximum employee limit নেই। প্রতিটি eligible contributor-কে আলাদাভাবে evaluate করতে হবে। ## ৪. একজন Employee একাধিক Project-এ থাকতে পারবে একজন employee একই সময়ে একাধিক project-এ assigned থাকতে পারবে। উদাহরণ: ```text Employee = Rahim Project A -> Manager Project B -> PM Project C -> Closer ``` প্রতিটি project assignment independently evaluate হবে। ## ৫. Cross-Team Contribution Employee নিজের Home Team-এর বাইরের project-এও contributor হিসেবে কাজ করতে পারবে। Commission/allocation-এর জন্য employee-এর Official Role নয়, project-এর Act As Role ব্যবহার হবে। ## ৬. Allocation Method PMS-এ দুই ধরনের allocation method থাকবে: ১. Percentage Commission ২. Fixed Team Allocation একটি project/team calculation-এর ক্ষেত্রে configured method অনুযায়ী calculation হবে। একই calculation-এ দুটো method একসাথে apply হবে না, যতক্ষণ না Management নতুন rule confirm করে। ## ৭. Commission Configuration Commission rate এবং duration configurable হবে। ### Current / Default Values | Role / Designation | Commission Rate | Duration | |---|---:|---| | PM | 3% | Lifetime | | Manager | 1% | Lifetime | | Closer | 2.75% | 3 Months | | Proposal Writer | 2.75% | 3 Months | | Applier / Salesperson | 0.5% | 3 Months | এগুলো current/default values; code-এর মধ্যে hard-code করা যাবে না। Management configure করতে পারবে: - Commission Percentage - Commission Duration - Active / Inactive ## ৮. Project Start Date এবং End Date প্রতিটি project-এর থাকবে: ```text Project Start Date Project End Date ``` এই দুইটি project lifecycle define করবে। **Commission duration calculation-এর reference point Project Start Date নয়।** ## ৯. Client Payment Trigger শুধু project create, project start অথবা invoice তৈরি হওয়ার কারণে commission calculate হবে না। Client payment **received / cleared** হওয়ার পর commission calculation শুরু হবে। Commission duration-এর reference date হবে: ```text Client Payment Received / Cleared Date ``` উদাহরণ: ```text Project Start Date = January 1 Client Payment Cleared = January 15 Commission reference date = January 15 ``` ## ১০. Commission Duration যে role-এর finite duration আছে, যেমন `3 Months`, সেই commission period client payment date থেকে গণনা হবে। Configured duration শেষ হলে ওই finite-duration role-এর normal commission বন্ধ হবে। Lifetime role configuration অনুযায়ী commission চলতে থাকবে। তিন মাসের exact date boundary কীভাবে গণনা হবে সেটি Management আলাদাভাবে confirm না করা পর্যন্ত unresolved থাকবে। ## ১১. Employee Probation Rule Probation চলাকালীন employee commission eligible হবে না। Probation শেষ হলে project, contributor, role এবং configuration অনুযায়ী employee commission eligible হতে পারবে। ## ১২. Commission Base Amount Financial flow হবে: ```text Client Gross Payment -> Applicable Platform / Payment Charges -> Net Amount -> Dynamic Office Expense -> Final Commission Base Amount ``` Platform/payment charge-এর exact source বা integration mechanism Commission module-এর business rule হিসেবে define করা হচ্ছে না। Appropriate financial/payment flow থেকে applicable cleared payment এবং charge values পাওয়া যাবে। ## ১৩. Office Expense Office Expense dynamic percentage-based হবে। Management Office Expense percentage configure করবে। এটি hard-code করা যাবে না। Formula: ```text Office Expense Amount = Platform/Payment Charges বাদ দেওয়ার পর Net Amount x Configured Office Expense % Final Commission Base = Platform/Payment Charges বাদ দেওয়ার পর Net Amount - Office Expense Amount ``` ## ১৪. Percentage Commission Formula ```text Commission Amount = Final Commission Base Amount x Configured Commission Percentage ``` উদাহরণ: ```text Gross Payment = $1,000 Platform/Payment Charges = $120 Net Amount = $880 Office Expense = 10% Office Expense Amount = $88 Final Commission Base = $792 Closer Rate = 2.75% Commission = $792 x 2.75% = $21.78 ``` ## ১৫. Fixed Team Allocation Fixed Team Allocation Percentage Commission থেকে আলাদা। Fixed Team Allocation-এর role budget **Team Budget-এর percentage হিসেবে configure হবে**, fixed dollar amount হিসেবে নয়। উদাহরণ: ```text Team Budget = $100 Manager = 50% PM = 20% Writer = 15% Closer = 15% ``` তাহলে: ```text Manager Pool = $50 PM Pool = $20 Writer Pool = $15 Closer Pool = $15 ``` Formula: ```text Role Allocation Amount = Team Budget x Configured Role Allocation % ``` ## ১৬. একই Fixed Team Role-এর Multiple Employee একই fixed allocation role-এ একাধিক employee থাকতে পারবে। সেই role-এর allocation amount ঐ role-এর eligible employees-এর মধ্যে equally distribute হবে। উদাহরণ: ```text Manager Pool = $50 Managers = Manager 1, Manager 2 Manager 1 = $25 Manager 2 = $25 ``` Formula: ```text Per Employee Allocation = Role Allocation Amount / ঐ Role-এর Eligible Employee সংখ্যা ``` একই rule PM, Writer, Closer বা অন্য configured designation-এর ক্ষেত্রেও প্রযোজ্য হবে। ## ১৭. Fixed Allocation Example ```text Team Budget = $100 PM = 20% Manager = 50% Writer = 15% Closer = 15% ``` যদি থাকে: ```text 2 PM 2 Manager 1 Writer 2 Closer ``` তাহলে: ```text PM Pool = $20 PM 1 = $10 PM 2 = $10 Manager Pool = $50 Manager 1 = $25 Manager 2 = $25 Writer Pool = $15 Writer 1 = $15 Closer Pool = $15 Closer 1 = $7.50 Closer 2 = $7.50 ``` ## ১৮. Percentage Commission বনাম Fixed Allocation একটি project/team calculation-এর allocation method হবে: ```text Percentage Commission ``` অথবা: ```text Fixed Team Allocation ``` Management নতুন rule confirm না করা পর্যন্ত দুই method mix করা যাবে না। ## ১৯. PF Objective PF commission lifecycle-এর সাথে connected থাকবে। Writer, Sales/Approval এবং Closer-এর মতো finite-duration role-এর ক্ষেত্রে configured 3-month commission period শেষ হলে commission stop হবে। যে stopped commission amount থাকবে, সেটি PF calculation-এর source amount হবে। ## ২০. PF Role-Based Dynamic Percentage PF percentage role/designation অনুযায়ী dynamic এবং configurable হবে। উদাহরণ values শুধু বোঝানোর জন্য: | Role | PF Percentage | |---|---:| | PM | 2.75% | | Manager | Management Configured | | Writer | Management Configured | | Closer | Management Configured | | Sales / Approval | Management Configured | **PF role percentages-এর total 100% হওয়া বাধ্যতামূলক নয়।** প্রতিটি applicable role-এর PF percentage Management independently configure করবে। ## ২১. PF Calculation প্রতিটি applicable role-এর জন্য: ```text Role PF Amount = Stopped Commission Amount x Configured PF Percentage ``` উদাহরণ: ```text Stopped Commission Amount = $1,000 Writer PF = 2% Writer PF = $1,000 x 2% = $20 ``` একই role-এর একাধিক eligible fixed-team member থাকলে applicable role amount fixed-team member distribution rule অনুযায়ী equally distribute হবে। ## ২২. PF Maturity / Eligibility Period PF একটি configurable number of years পর mature হবে। উদাহরণ: ```text PF Maturity Period = 4 Years ``` Management future-এ threshold change করতে পারবে। Maturity period hard-code করা যাবে না। ## ২৩. Employee PF Maturity-এর আগে চলে গেলে Employee configured PF maturity period complete করার আগে চলে গেলে full PF amount automatically পাওয়ার entitlement থাকবে না। Management decide করবে employee-কে কত টাকা দেওয়া হবে। উদাহরণ: ```text PF Fund = $10,000 Employee maturity-এর আগে চলে গেল Management payout decide করল = $6,000 ``` ## ২৪. PF Disbursement PF disbursement Management manually control করবে। System-এ Management actual disbursement amount manually enter করতে পারবে এবং disbursement history সংরক্ষণ করতে হবে। ```text PF Accrued -> Maturity / Eligibility Check -> Management Review -> Manual Disbursement Amount -> Disbursement History ``` ## ২৫. Company EPS PF calculation-এর পরে যে balance থাকবে সেটি **Company EPS** হিসেবে save হবে। Formula: ```text Company EPS = PF Source Amount - Total PF Amount Allocated ``` উদাহরণ: ```text PF Source Amount = $1,000 Total PF Allocation = $102.50 Company EPS = $897.50 ``` ## ২৬. Company EPS Project-wise এবং Team-wise Storage Company EPS database-এ project এবং team association সহ save করতে হবে। Logical structure: ```text Company -> Project -> Team -> Company EPS ``` Management যেন project/team অনুযায়ী EPS কত generated হয়েছে তা দেখতে পারে। ## ২৭. End-to-End Financial Flow ```text Client Gross Payment -> Platform / Payment Charges -> Net Payment -> Dynamic Office Expense -> Final Commission Base -> Allocation Method -> Percentage Commission OR -> Fixed Team Allocation -> Commission Paid -> Finite Commission Duration Ends -> Commission Stops -> Stopped Commission Amount -> Role-based PF Percentage -> PF Amount -> Remaining Balance -> Company EPS (Project + Team wise) -> PF Maturity Period -> Management Disbursement Decision -> PF Disbursement ``` ## ২৮. Historical Configuration Rule Management পরে configuration পরিবর্তন করলেও historical commission, fixed allocation, PF এবং EPS calculation automaticভাবে change হবে না। এটি প্রযোজ্য: - Commission Rate - Commission Duration - Office Expense Percentage - Fixed Team Allocation Percentage - PF Percentage - Historical record-এর জন্য প্রযোজ্য PF Maturity Period Calculation-এর সময় ব্যবহৃত configuration values relevant transaction/history-এর সাথে preserve করতে হবে। ## ২৯. Required Transaction History Commission history-তে applicable information preserve করতে হবে, যেমন: ```text Employee Project Team Project Contributor Act As Role / Designation Client Payment Reference Payment Cleared Date Allocation Method Commission Base Amount Commission Rate Used Commission Duration Commission Amount Calculation Date ``` Fixed allocation history-তে applicable team budget, role allocation percentage, role allocation amount, eligible employee count এবং per-employee allocation preserve করতে হবে। PF history-তে applicable employee, project, team, role, PF source amount, PF percentage, PF amount, maturity date, disbursement information এবং Company EPS amount preserve করতে হবে। Exact database structure existing PMS architecture follow করবে এবং equivalent structure থাকলে duplicate table/model/migration তৈরি করা যাবে না। ## ৩০. Backend Responsibility Backend financial calculation-এর source of truth হবে। Backend-এর দায়িত্ব: - Employee eligibility এবং probation - Project contributor validation - Designation-based Act As Role - Multiple project assignment - Commission configuration - Payment-triggered duration calculation - Office Expense - Percentage Commission - Fixed Team Allocation - Same-role fixed-team member equal distribution - PF calculation - PF maturity/eligibility - Management-controlled PF disbursement - Company EPS - Historical transaction preservation ## ৩১. Frontend Responsibility Frontend-এ থাকবে: - Commission configuration UI - Office Expense configuration UI - Fixed Team Allocation configuration UI - PF configuration UI - Project contributor management - Designation List থেকে Act As Role selection - Commission history - Fixed allocation history - PF history এবং maturity status - PF disbursement information - Company EPS reporting Frontend final financial calculation-এর source of truth হবে না। ## ৩২. Architecture Principle Implementation-এর আগে existing PMS architecture inspect করতে হবে। Preferred flow: ```text Controller -> Form Request / Validation -> Service -> Repository -> Model ``` Business logic Service layer-এ থাকবে এবং Controller thin হবে। Equivalent existing repository, service, model, configuration এবং permission থাকলে সেগুলো reuse করতে হবে। ## ৩৩. Permissions Existing PMS permission convention আগে inspect করতে হবে। যেখানে possible existing permission reuse করতে হবে। প্রয়োজন হলে minimum permission তৈরি করতে হবে: - Commission Configuration - Commission Management - Fixed Team Allocation Configuration - PF Configuration - PF Management - PF Disbursement - Company EPS Management Exact permission slug existing project convention অনুযায়ী হবে। ## ৩৪. Unresolved / Not Confirmed Management confirm না করা পর্যন্ত নিচের বিষয়গুলো unresolved থাকবে: ১. Platform/payment charge-এর exact technical source/API। ২. Refund/chargeback হলে exact workflow। ৩. Exact rounding/decimal precision rule। ৪. Duplicate payment prevention rule। ৫. 3-month commission-এর exact date-boundary convention। ৬. Existing finite commission period চলার সময় configuration change হলে exact historical/current-period treatment। Developer এসব বিষয়ে নিজের assumption দিয়ে implementation করতে পারবে না। ## ৩৫. Final Business Rule Summary | Area | Confirmed Rule | |---|---| | Official Role | Employee-এর existing Designation | | Act As Role | একই Designation List থেকে | | Separate Act As Role List | No | | Multiple Contributors | Allowed | | Same Role Multiple Employees | Allowed | | One Employee Multiple Projects | Allowed | | Cross-Team Contribution | Allowed | | Allocation Method | Percentage Commission OR Fixed Team Allocation | | Commission Rate | Configurable | | Commission Duration | Configurable | | Commission Duration Reference | Client Payment Received / Cleared Date | | Probation Employee | Commission eligible নয় | | Office Expense | Dynamic percentage | | Fixed Team Allocation | Team Budget-এর percentage হিসেবে role budget | | Same Fixed Role | Eligible members-এর মধ্যে equal distribution | | PF Source | Applicable finite-duration role-এর stopped commission amount | | PF Percentage | Role অনুযায়ী dynamic | | PF Percentage Total = 100% | Required নয় | | PF Maturity | Dynamic/configurable years | | Early Exit Before Maturity | Management payout decide করবে | | PF Disbursement | Manual Management decision | | Remaining PF Balance | Company EPS | | EPS Storage | Project-wise + Team-wise | | Historical Records | Unchanged রাখতে হবে | | Backend | Financial source of truth | ## ৩৬. Core Principle ```text Employee Eligibility + Project Assignment + Designation List থেকে Act As Role + Allocation Method + Client Payment Received/Cleared + Applicable Charges + Dynamic Office Expense + Configured Commission / Allocation = Commission / Fixed Team Allocation ``` Finite-duration role-এর ক্ষেত্রে: ```text Commission Stops -> Stopped Commission Amount -> Role-based PF Percentage -> PF Amount -> Remaining Balance -> Company EPS ``` PF lifecycle: ```text PF Accrued -> Configured Maturity Period -> Eligible / Mature -> Management Review -> Manual Disbursement ``` **Role percentage, commission duration, office expense percentage, fixed team allocation percentage এবং PF maturity year hard-code করা যাবে না। এগুলো configuration-driven হতে হবে এবং historical calculation values preserve করতে হবে।**