# Samity360 User Manual

## Developer

The Developer account is global and has no company restriction. It can view all companies, edit global database settings, control feature availability for each company, configure provider records, review global activity, and manage platform security and backup policy.

The Developer panel is available at `/developer`. Each company row includes **Edit**, **Settings**, and **Open Workspace** actions. The company Settings page controls that tenant's features, company-scoped values, Admin visibility/editability, and Activity access independently. Company users never receive the `developer.access`, `settings.developer`, or notification provider configuration permissions in the demo policy.

### Feature visibility

Every company feature is stored in `company_features`. This includes Fines, which can be enabled for one company and disabled for another. A disabled feature fails both checks:

1. Its menu item is not rendered.
2. Its route/API middleware returns HTTP 403.

This prevents users from bypassing hidden menus by typing a URL.

### Branding and footer

Software name, Developer name, website, hotline, theme, and company receipt title come from the `settings` table. The application footer reads these records on every request. The Developer website is displayed only as the hyperlink behind the Developer name; the raw URL is not printed separately. Do not move these values into PHP templates.

## Admin / Company Owner

The Admin controls the company workspace, staff accounts permitted by RBAC, members, products, loans, collections, accounting, reports, and only those settings whose database rows have both `is_admin_visible=1` and `is_admin_editable=1`.

Hidden or locked settings are not rendered as editable controls and are rejected again by the API.

## Manager

The Manager handles daily operations: member registration, savings, loan applications, collection, collector assignments, reports, notifications, and activity review according to assigned permissions.

## Collector / Field Officer

The Collector sees a restricted menu. The central workflow is **Collection**:

1. Search a member by member number, name, Bangla name, or mobile.
2. Select the member.
3. Enter one or more savings amounts.
4. Enter a loan installment amount. The server allocates fine, interest, principal, and any remaining advance.
5. Select payment method and enter an optional reference.
6. Post the collection.
7. Print the generated receipt.

The transaction records collector attribution, location fields when supplied by a mobile client, collector collection totals, and cash handover support.

## Accountant

The Accountant posts income and expenses, manages cash/bank/MFS balances, reviews collection-generated financial entries, closes the cashbook, and exports financial reports.

### Daily closing

1. Open Accounting.
2. Select **Daily Closing**.
3. Choose the date.
4. Enter physically counted cash.
5. The system calculates expected cash and variance.

## Member management

The member form supports name, Bangla name, mobile, NID, address, occupation, income, nominee, guarantor, joining date, photo, and NID files. Member numbers and QR tokens are generated automatically.

Use the QR Card action to print a member identity card. Admin and Developer users also see an Edit action. Other roles cannot open the Member Edit route even by typing its URL. Composer's QR dependency must be installed for SVG rendering.

## Savings

Saving products support daily, weekly, monthly, DPS, and flexible frequencies. An account is unique per member and saving type. Deposits are normally posted from the Collection page. Current Balance is calculated from the latest savings transaction and synchronized automatically to the account record by database triggers. Admin and Developer users always see Savings Edit and Active/Inactive controls. The Developer can enable `savings_edit_all_users` for a company to expose Savings Edit to other roles; account status remains restricted to Admin and Developer. Withdrawals should use the savings permission and a deployment-approved authorization workflow.

## Loans

The workflow is:

1. Application submitted.
2. Authorized user approves or rejects.
3. Accountant or authorized user disburses.
4. The system generates flat or declining installment schedules.
5. Collections update principal, interest, fines, partial payments, advances, dues, and outstanding totals.
6. Admin and Developer can edit a loan only before the first installment payment is received. After any installment payment, the edit route is locked server-side.
7. Closing or rescheduling can be built on the parent-loan and status fields included in the schema.

## 10. Reports

Open **Reports** from the sidebar to enter the Reporting Center. The page includes separate tabs for Overview, Member, Savings, Loan, Collection, and Financial reports. Every report uses the same company context, permission checks, date filters, export controls, responsive table, summary cards, chart, and performance insights.

### Generate a member report

1. Open **Reports**.
2. Select **Member Report**.
3. Choose a preset period or Custom Range.
4. Click **Apply**.
5. Review new members, active-member rate, current savings balances, loan exposure, member-status distribution, and the member directory table.
6. Use the report search box to find a member number, name, mobile number, occupation, or status.

The Member Report includes members whose **joining date** falls within the selected period. Savings and outstanding-loan columns show their current balances so management can review the financial position of newly enrolled members.

### Generate a savings report

1. Open **Reports**.
2. Select **Savings Report**.
3. Select the required date range and click **Apply**.
4. Review deposits, withdrawals, net savings movement, transaction count, active accounts, largest deposit, withdrawal ratio, product breakdown, and transaction records.

The Savings Report uses the `savings_transactions.transaction_date` field. Deposit, withdrawal, profit, opening, and adjustment entries are shown according to the available records.

### Generate a loan report

1. Open **Reports**.
2. Select **Loan Report**.
3. Choose the reporting period and click **Apply**.
4. Review loan applications, approved amounts, disbursement, installment collection, current outstanding balance, approval ratio, overdue-loan count, loan-status breakdown, and loan records.

A loan appears when its application date or disbursement date falls within the selected range. Current outstanding amounts are displayed from the latest loan record.

### Filter by the last 7, 30, or 90 days

1. Open any report tab.
2. Open the **Date Range** selector.
3. Select **Last 7 Days**, **Last 30 Days**, or **Last 90 Days**.
4. Click **Apply**.

The system also supports 15, 45, and 60 days. The ending date is the current Bangladesh date, and the starting date is calculated automatically.

### Use a custom date range

1. Select **Custom Range**.
2. Enter the **From Date**.
3. Enter the **To Date**.
4. Click **Apply**.

If the dates are entered in reverse order, the date-range service automatically corrects them. The selected report type remains active after filtering.

### Export a report to Excel

1. Generate the required report.
2. Click **Excel/CSV**.
3. Open the downloaded UTF-8 CSV file in Microsoft Excel, LibreOffice Calc, or Google Sheets.

The export contains the report title, period, summary metrics, column headings, and all matching records. The on-screen table may be limited to 500 preview rows for performance, but the export includes all matching records.

### Export a report to PDF

1. Generate the required report.
2. Click **PDF**.
3. Samity360 generates an A4 landscape PDF containing company information, report summary, insights, report table, signatures, and the database-controlled Developer footer.

The PDF feature uses Dompdf. Run `composer install` and ensure the `vendor` directory is present. If Dompdf is unavailable, Samity360 opens the print-ready report, where the browser can use **Save as PDF**.

### Print any report

1. Generate and filter the report.
2. Click **Print**.
3. A dedicated print page opens in a new tab.
4. Click **Print** on that page.
5. Select a printer, or select **Save as PDF** in the browser print dialog.

The print page includes company details, selected period, summary values, insights, all matching rows, Prepared/Checked/Authorized signature lines, and the database-controlled footer. Use landscape orientation for wide reports.

### Report permissions

- `reports.view` allows a user to open and print reports.
- `reports.export` allows Excel/CSV and PDF downloads.
- Company feature control `reports` must also be enabled by the Developer.
- Every query is restricted to the currently selected company.

## Notifications

Templates support placeholders such as `{{member_name}}`, `{{amount}}`, `{{receipt_no}}`, `{{due_date}}`, and `{{message}}`. The Notifications page supports member selection, recipient autofill, channel/template filtering, preview, custom JSON variables, and delivery logs. SMS and WhatsApp delivery is allowed only when the Developer enables the corresponding feature for that company and configures an active provider. The built-in in-app notice template can be tested without an external provider. All delivery attempts are logged with status and provider response identifiers.

### Activity and Notification permissions

The Developer controls both pages through one company-wise permission:

1. Open **Developer → Companies**.
2. Open the required company's **Settings** page.
3. Find **Activity & Notification Access**.
4. Enable **Page Access** for the roles that may see and open both Activity and Notification pages.
5. Enable **Notification Sending** only for roles that may use the message composer and protected send API.
6. Click **Apply** for each role change.

Enabling **Notification Sending** automatically enables combined page access. Disabling combined access automatically removes sending permission. Users without combined access cannot open either page by typing its URL. Users with combined access but without sending permission can review notification logs in read-only mode.

Tenant Activity pages and Activity printouts contain only that company's non-Developer records. Developer actions remain private and are visible only through `/developer/activity`.

## User profile and logout

Every authenticated user can open **My Profile** from the top-right account menu or the bottom of the sidebar. The profile page supports a JPG, PNG, or WebP picture up to 2 MB, name, Bangla name, email, Bangladesh mobile number, preferred active language, and password change. A Logout action is always available at the bottom of the sidebar and in the top-right account menu.

## Password and session safety

- Never share user accounts.
- Change demo passwords immediately.
- Use HTTPS.
- Log out on shared devices.
- Enable OTP only after a reliable SMS provider is configured and tested.


## Loan application workflow update

1. Open **Loans** to view the Loan Records register.
2. Click **New Loan Application** to open the dedicated application page.
3. Search by member ID, member name, Bangla name, or mobile number.
4. Select the member from the search results.
5. Choose the category and enter the single **Amount** value, interest method, frequency, installment count, and purpose.
6. Submit the application. The internal approval and disbursement workflow remains protected even though the interface uses one Amount field.

Admin and Developer can edit the loan before its first installment payment. Once a payment is received, Samity360 locks the record to protect financial history.

## Reactivate an inactive Savings account

1. Open **Savings**.
2. Find the inactive account.
3. Click **Reactivate**, or open **Edit** and select **Active**.
4. Confirm the action.

Reactivation clears any stale closing timestamp, restores the account to Collection, and synchronizes its Current Balance from the latest savings transaction. Only Admin and Developer can change Active/Inactive status.

## Company attachment isolation

Each company has its own attachment tree under `public/storage/uploads/companies/company-{id}/`. Member photos and NID files, company-user profile pictures, future loan attachments, and general documents are therefore organized separately for every company. The global Developer profile is stored under `public/storage/uploads/global/users/` because it is not owned by a tenant.

When upgrading an older installation, an authorized server administrator should back up the database and upload directory and run `php bin/migrate_company_attachments_v117.php` once.