### SkillsFuture Grants

Package `soq-sg-grants-verify` - permissions 90110-90114 (90115-90119 reserved) - implementation guide: [SkillsFuture Grants Module](../engineering/modules/grants/MODULE.md)

#### What this module does

SkillsFuture Grants applies SSG course fee grants at checkout after checking residency and age. Eligibility comes from Singpass identity when linked, or from a staff-reviewed document declaration. There is no public government eligibility API in this implementation.

#### UI map: where to click

| UI area | Path | What operators do | Key buttons / controls |
|---|---|---|---|
| Eligibility queue | `/admin/grants` | Review pending learner declarations and documents. | **Approve**, **Reject**, **Revoke**, document link |
| Grant audit log | `/admin/grants/subsidies` | Review grants applied to orders and export for claim work. | **Export** |
| Grant settings | `/admin/grants/settings` | Enable grants, set rates, notify staff, add funded courses. | **Save settings**, add/remove course |
| Learner eligibility | `/grants/eligibility` | Learner declares residency/date of birth or uploads proof. | Submit eligibility form |
| Cart | `/cart` | Learner sees grant deduction for funded courses. | Grant block / continue checkout |

#### Permissions

| Permission | Purpose |
|---|---|
| `admin_sg_grants` | Parent access |
| `admin_sg_grants_eligibility` | Eligibility queue and document list |
| `admin_sg_grants_review` | Approve and reject eligibility |
| `admin_sg_grants_settings` | Settings and funded courses |
| `admin_sg_grants_audit` | Subsidy audit log/export |

Run `php artisan soq:seed-grants` to install sections, default settings and notifications.

#### Field guide

| Field / control | What to enter | Impact |
|---|---|---|
| Enable SkillsFuture grants | Turn on after rates and funded courses are configured. | Shows learner grant block and starts applying grants. |
| Baseline citizen / PR rate | Approved SSG percentage. | Default subsidy rate when course does not override. |
| MCES rate and minimum age | Usually 90% and age 40+. | Applies enhanced subsidy for eligible citizens. |
| Notify staff user IDs | Admin/staff IDs who review uploaded documents. | Empty falls back to main admin. |
| Funded courses | Courses approved for grant support. | Only these courses show grant eligibility. |
| Course grant cap | Optional SGD cap. | Prevents grant amount from exceeding approved cap. |
| Approve / Reject / Revoke | Use from eligibility queue. | Controls whether learner can use grants in future checkout. |

Settings bag: `soq_sg_grants_verify_settings`.

#### First-time setup

1. Run `php artisan migrate`.
2. Run `php artisan soq:seed-grants`.
3. Open `/admin/grants/settings`.
4. Set baseline/PR/MCES rates and MCES age.
5. Add funded courses and any course-specific rate/cap.
6. Add staff reviewers if needed.
7. Turn on **Enable SkillsFuture grants** and save.
8. Test one learner with Singpass linked and one learner using document upload.

#### UAT script

| Step | Action | Expected result |
|---|---|---|
| 1 | Add a paid course as funded. | Course appears in settings list. |
| 2 | Learner with Singpass identity checks eligibility. | Eligibility is approved immediately when residency/age qualifies. |
| 3 | Learner without Singpass uploads document. | Queue row appears in `/admin/grants`. |
| 4 | Staff clicks document link and **Approve**. | Learner can use grant at checkout. |
| 5 | Learner checks out funded course. | Grant deduction appears; GST remains based on full fee. |
| 6 | Admin opens `/admin/grants/subsidies`. | Audit row shows scheme, rate, fee and grant amount. |
| 7 | Admin clicks **Export**. | Export contains grant records for claim work. |
| 8 | Admin revokes eligibility. | Future grants stop; paid orders are not automatically reversed. |

#### Daily operations

- Review `/admin/grants` daily while document uploads are enabled.
- Export `/admin/grants/subsidies` for finance/claim reconciliation.
- Re-check rates when SSG funding approval changes.
- Revoke only after documenting the reason outside SOQ if compliance requires an audit note.

#### Troubleshooting

| Symptom | Check |
|---|---|
| Grant block missing in cart | Module disabled, course not funded, course is free, gift/installment/account-balance rules block grants. |
| Learner stuck pending | Staff has not approved uploaded residency proof. |
| Wrong grant amount | Course-specific rates/caps override defaults; GST is calculated on full fee. |
| FIN/foreign learner not eligible | Current implementation supports Singapore citizen/PR grant logic only. |
| Staff cannot approve | Role needs grants review permission. |

#### Policy notes

- Individual sponsorship only; no company/SME rates.
- Only courses bought for oneself are eligible.
- An order with a grant cannot be paid from account balance.
- Revoking eligibility stops future grants but does not recover grants already used on paid orders.