# KiyoHR — User Guide

This guide is for **company admins**, **HR**, and **employees** using the web application (e.g. `http://hrms.saas.laravel/`).

For developers, see [README.md](../README.md), [API.md](API.md), and [LOGIN.md](LOGIN.md).

---
#IncomeTax Settings Data
#php artisan db:seed --class=IndianIncomeTaxSeeder

#reset permissions
php artisan hrms:reset-permissions

## Roles at a glance

| Role | Typical access |
|------|----------------|
| **Company admin / HR** | Employees, attendance, leave approvals, payroll run, offboarding, reports |
| **Employee** | My attendance, my leave, my payslips, income tax declaration |
| **Super admin** | All companies, subscription plans, global income tax plans (platform level) |

---

## 1. Leave balances (Track A)

### What it does

- Maintains a **leave ledger** per employee, per leave type, per year
- Supports **monthly accrual**, **pro-rata on joining**, and **year-end carry-forward**
- Shows **available**, **used**, **pending**, and **encashed** balances

### HR — opening balances

1. Go to **Leave** → **Opening balances import** (if enabled for your tenant)
2. Upload CSV with employee, leave type, and opening balance
3. Run sync command (scheduled on server): `php artisan leaves:sync-balances`

### HR — leave rules

1. **Leave** → **Leave types / rules**
2. On the **Advanced** tab, set:
   - **Accrual mode:** yearly or monthly
   - **Pro-rata on joining:** yes/no

### Scheduled jobs (server)

| Command | When | Purpose |
|---------|------|---------|
| `leaves:accrue-monthly` | 1st of month, 01:00 | Monthly accrual |
| `leaves:carry-forward` | 1 Jan, 02:00 | Carry unused balance to new year |
| `leaves:sync-balances` | Manual / one-time | Backfill balances |

### Employee — check balance

1. **Leave** → **Dashboard** — see your balances and team summary
2. When applying for leave, the create form shows **live available balance**

### Manager / HR — approve leave

1. **Leave** → pending requests
2. **Approve** debits the ledger; **Reject** releases the pending hold

---

## 2. Module CRUD & reports (Track B)

### Shifts

- **Settings / Shifts** — create, **edit**, **delete** (delete blocked if employees are assigned)

### Assets

- **Assets** — create, **edit**, **return**, **dispose**
- Use **Return** when an employee hands back equipment (important for offboarding)

### Finance (by role)

Finance navigation adapts to your role. After a permission upgrade, admins run:

```bash
php artisan hrms:finance-migrate-permissions
# alias: php artisan hrms:reset-tenant-permissions
```

| Role | What you see |
|------|----------------|
| **Employee** | **My Finance** — submit claims, view own advance repayment schedule (read-only) |
| **Manager** | **Team Finance** — approve team expense claims only; cannot record salary advances |
| **HR** | **HR Finance** — company expenses, advances, F&F; no cash accounts or deposits |
| **Finance / Admin** | **Company Finance** — full treasury: accounts, deposits, balances, setup masters |

**Employees**
- **Finance → My Finance** — pending claims, MTD totals, outstanding advance
- **Submit claim** — Finance → Expenses (scope: My claims)
- **My Advances** — read-only payroll deduction schedule

**Managers**
- **Finance → Team Finance** — pending team approvals
- **Expenses** (scope: Team) — review and approve direct reports' claims

**HR**
- **Finance → HR Finance** — pending expenses, active advances, F&F queue
- **Advances** — record installment-based salary advances for employees
- Cannot access Accounts, Deposits, or company cash dashboard

**Finance team**
- **Finance → Dashboard** — cash balance, MTD flow, accounts
- **Accounts / Deposits / Setup** — treasury masters (vendors, payees, payers)

Mobile API: see [API.md](API.md) — `GET /api/finance/home`, `/self`, `/team`, `/operational`, `/my-advances`.

### Finance (legacy summary)
- **Finance** → Accounts, Expenses, Deposits — full create, edit, delete (treasury roles)
- **Advances** → record salary pre-payments; deducted on payroll recalculate
- Deposits update the linked account **current balance**

### Complaints

- **HR** → **Complaints** — edit, update status
- **Resolution notes** are required when status is **Resolved**

### Reports hub

- **Reports** — links to attendance reports, payroll export, employee export, leave dashboard

### Auto-inactivate after last working day

- Employees with `last_working_date` in the past are set to **inactive** daily (`employees:deactivate-past-lwd` at 00:30)
- HR can preview: `php artisan employees:deactivate-past-lwd --dry-run`

### Salary components

- **Settings** → **Salary Components** tile is enabled for component catalog management

---

## 3. Income tax & TDS (Track C)

### HR — setup (once per company)

1. **Super admin** must configure **Income tax plans** and **tax slabs** (old/new regime)
2. **Payroll** → **Advanced** → **Declaration settings**:
   - Select **Old regime** and **New regime** plans
   - Enable **monthly TDS deduction in payroll run**
   - Set declaration window and **mandatory proof** if needed

### Employee — declare investments

1. **Payroll** → **My** → **Income tax**
2. Choose **New regime** (no 80C) or **Old regime** (80C, 80D, HRA, etc.)
3. Enter amounts → **Save draft** → **Submit for verification**
4. Upload **proof** documents (PDF/JPG/PNG) per line item

### HR — verify declarations

1. **Payroll** → **Declaration** tab
2. Filter by financial year and status
3. Review line items, set **verified amount** and proof status
4. **Verify** or **Reject** (employee can revise if rejected)

### Payroll — TDS deduction

- When TDS is enabled and the employee has a **submitted** or **verified** declaration, payroll run adds an **Income Tax (TDS)** deduction line
- Monthly amount is projected from annual tax ÷ remaining months in the FY (Apr–Mar)

### Form 16

- After **verified** declaration: employee or HR can download Form 16
- URL pattern: `payroll/income-tax/form16/{financialYear}?download=1`  
  Example FY: `2025-26`

---

## 4. Offboarding & F&F settlement (Track D)

### Start offboarding

1. **HR** → **Offboarding** → **Start offboarding**
2. Select employee, **offboarding date**, **last working day (LWD)**, **notice period** (days)
3. System automatically:
   - Updates employee **LWD**
   - Creates **clearance checklist** (IT, assets, HR, finance, docs, manager)
   - Adds tasks for each **assigned asset**
   - Creates a **draft F&F worksheet**

### Clearance checklist

1. Open offboarding from the list → **Open**
2. Mark each task: **pending** → **completed** / **waived** / **na**
3. When all items are done, status becomes **Cleared** and F&F moves to **Pending approval**

### F&F worksheet

1. From offboarding detail → **F&F Worksheet** (or `/fnf/{id}`)
2. Review calculated fields:

   | Field | Typical source |
   |-------|------------------|
   | Daily rate | CTC ÷ 365 |
   | Notice recovery | Shortfall in notice period × daily rate |
   | Leave encashment | Paid leave balance × daily rate |
   | Recoveries | Loan, asset, other (manual) |

3. Edit amounts → **Recalculate** or **Refresh from leave balances**
4. **Approve settlement** → **Mark as paid**

### On “Mark as paid”

- Leave balances are **encashed** in the leave ledger
- Employee status set to **inactive**
- Offboarding marked **completed**
- Download PDF: **Download PDF** on the F&F page

---

## 5. Payroll (quick reference)

| Task | Where |
|------|--------|
| Run monthly payroll | **Payroll** → **Run Payroll** (`/payroll?tab=run`) |
| Employee payslips | **Payroll** → **My** → **Payslips** |
| Statutory PF/ESI/PT | **Payroll** → **Setup** / Advanced settings |
| Payroll | **Payroll** → **Run Payroll** tab (`/payroll?tab=run`) |

---

## 6. Common URLs (tenant web)

Replace host with your installation (e.g. `http://hrms.saas.laravel`).

| Area | URL |
|------|-----|
| Dashboard | `/dashboard` |
| Employees | `/employees` |
| Leave dashboard | `/leaves/dashboard` |
| Payroll home | `/payroll` |
| Income tax (employee) | `/payroll?tab=my&my_sub=income-tax` |
| Declaration (HR) | `/payroll?tab=declaration` |
| Offboarding | `/offboardings` |
| Reports | `/reports` |
| Documents | `/documents` |

---

## 7. India-specific notes

- **Financial year** for tax: **1 April – 31 March** (e.g. FY `2025-26`)
- **Leave year** in the ledger follows calendar year unless your policy differs
- F&F and Form 16 PDFs are **system summaries**; consult your CA for statutory filing formats

---

## 8. Troubleshooting

| Issue | What to check |
|-------|----------------|
| Leave balance shows zero | Run `leaves:sync-balances`; confirm leave type rules and accrual |
| TDS not deducted in payroll | Declaration settings → TDS enabled; employee declaration submitted/verified |
| Cannot submit declaration | Declaration window dates in Declaration settings |
| F&F leave encash fails | Paid leave types only; available balance must cover encashment days |
| Employee still active after LWD | Formal offboarding **Mark as paid**, or wait for nightly `deactivate-past-lwd` job |

---

## 9. Demo logins

See [LOGIN.md](LOGIN.md) for seeded accounts (`admin@demo.local` / `password`).

---

*Last updated: June 2026 — covers Tracks A–D (leave ledger, module CRUD, income tax, offboarding/F&F).*

---

## 10. Documents, forms & letters (Phases 4–6)

### Company policies
- **HR:** `Company policies` — create/edit policies
- **Employees:** Profile → **View company policies** or `/policies`
- **Acknowledgment:** Open a policy → **I have read and acknowledge**
- **HR audit:** Policy → **View acknowledgments**

### Forms
- **HR:** Documents → **Forms** (builder), **Form submissions** (review + CSV export)
- **Employees:** Documents → **Fill forms** or Profile → **Open forms portal**
- HR can **approve/reject** submissions from the submission detail page

### Generated letters
- Documents → **Letters** — relieving, experience, warning, offer
- Uses letterhead templates; placeholders: employee name, LWD, designation, etc.
- From **Offboarding** detail: quick links for relieving / experience letters

### Reports
- **Reports hub** — CSV exports (attendance, payroll, expenses, audit, forms, performance)
- **Saved reports** — save filters and optional daily/weekly/monthly schedule

---

## 11. Security & privacy

### Two-factor authentication
- **Settings → Profile → Security** — enable **email OTP** or **authenticator app (TOTP)** when company policy is **Optional** or **Required**
- **Settings** (admin) — company policy: **Off** (hidden from profiles; clears existing employee 2FA), **Optional** (default), or **Required** for all employees
- When **Required**, employees must enroll on first login (email auto-enroll or authenticator setup page); they cannot disable 2FA while the policy is required

### GDPR export
- **Settings → Profile → Export my data** — JSON download of profile fields

### Session management
- Profile shows recent login sessions; revoke old sessions

### Scheduled jobs (server)
| Command | When | Purpose |
|---------|------|---------|
| `hrms:send-proactive-alerts` | Weekly Mon 08:00 | Low leave balance, due performance reviews |
| `hrms:run-scheduled-reports` | Daily 06:00 | Mark scheduled saved reports due |
| `employees:deactivate-past-lwd` | Daily 00:30 | Deactivate past LWD + HR digest notification |