-
Type:
Task
-
Resolution: Unresolved
-
Priority:
Low
-
None
-
Affects Version/s: None
-
None
-
FLW Mobile App
-
UAT
Goal
Turn the FLW Gamification module (Badges, Monthly Recap, Evening Notifications (21:00), My Impact card / Badge Shelf, Journey screen) ON or OFF from the server:
- for selected ASHAs (pilot / individual), and
- in bulk (a whole block, district or state, or a list of userIds),
through one dedicated API, with no app release and no Firebase Remote Config change.
This replaces the getUserDetail approach in AMM-2556. A separate API keeps login and facility data safe if the gamification lookup fails, has its own contract, and can be called often.
Current backend state (PSMRI/FLW-API main)
- GET /user/getUserDetail (UserServiceImpl.getUserDetail) already resolves the ASHA's state, district, block and villages from the JWT user. The new resolver can reuse these lookups (UserServiceRoleRepo).
- The badges APIs already exist (/badges/config, /badges/freezes, /badges/earned), but badge_config.feature_enabled is global, so it can't target one ASHA.
- badge_streak_freeze already uses the pattern "userId NULL = everyone, set = one ASHA". This task generalises that pattern.
- FLW-API has no per-user feature flag today, so a new table is needed.
—
1. DB: new table (through the AMRIT DB scripts, not Hibernate auto-create)
CREATE TABLE db_iemr.gamification_access ( id BIGINT AUTO_INCREMENT PRIMARY KEY, scope_type VARCHAR(20) NOT NULL, -- GLOBAL | STATE | DISTRICT | BLOCK | USER scope_id INT NULL, -- NULL only for GLOBAL mechanic VARCHAR(50) NOT NULL DEFAULT 'ALL', -- ALL | BADGES | MONTHLY_RECAP | EVENING_NOTIF | CONSISTENCY_DASHBOARD enabled BIT(1) NOT NULL, deleted BIT(1) NOT NULL DEFAULT 0, created_by VARCHAR(50) NOT NULL, created_date DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, modified_by VARCHAR(50) NULL, last_mod_date DATETIME NULL ON UPDATE CURRENT_TIMESTAMP, UNIQUE KEY uk_scope_mech (scope_type, scope_id, mechanic), KEY idx_scope (scope_type, scope_id) );
2. Read API (called by the mobile app)
GET flw-api/gamification/access Headers: Authorization, JwtToken -- userId taken from the JWT, never from the request
{
"statusCode": 200,
"status": "Success",
"data": {
"enabled": true,
"mechanics": {
"badges": true,
"monthlyRecap": true,
"eveningNotifications": true,
"consistencyDashboard": false
},
"source": "BLOCK",
"updatedAt": 1762156800000
}
}
- enabled: master switch for this ASHA. Mechanics apply only when enabled is true.
- mechanics: one switch per mechanic. A missing key means false.
- source: the scope that matched (USER | BLOCK | DISTRICT | STATE | GLOBAL | DEFAULT), for support and debugging.
- updatedAt: latest modification time (epoch ms) of the matching rows.
- Non-ASHA roles (ASHA Supervisor, ANM, CHO, …) always get enabled: false.
3. Resolution rule: the most specific scope wins
USER > BLOCK > DISTRICT > STATE > GLOBAL > default (OFF)
- For each mechanic, take the most specific non-deleted row. At the same scope level, a mechanic-specific row beats an ALL row. Otherwise fall through to the next level.
- enabled (master) is the resolution of mechanic ALL.
- Stop TB users: their BlockId holds a Nikshay TU id, not an AMRIT block, so apply USER scope only (getUserDetail already treats them as a special case).
- Users with several role-mapping rows or blocks: use the same primary row that UserServiceImpl.primaryRole picks.
| Rows | Result |
|---|---|
| none | OFF (default) |
| DISTRICT=12, ALL, true | every ASHA in district 12 ON |
| DISTRICT=12, ALL, true + USER=4501, ALL, false | district 12 ON except ASHA 4501 |
| BLOCK=88, ALL, true + BLOCK=88, EVENING_NOTIF, false | block 88 ON, but no 21:00 notification |
| GLOBAL, ALL, true | full go-live |
4. Admin (write) APIs
| Method | Path | Body / params | Purpose |
|---|---|---|---|
| POST | /gamification/access/bulk | {{
{ "scopeType": "USER", "ids": [4501, 4502], "mechanic": "ALL", "enabled": true }
}} |
Upsert for one ASHA, a list of ASHAs, or a list of blocks / districts / states |
| GET | /gamification/access | ?scopeType=&scopeId= | List configured rows |
| DELETE | {{/gamification/access/
{id}
}} (soft delete) |
— | Remove an override, so the next level applies |
| GET | {{/gamification/access/resolve/
{userId}
}} (optional) |
— | Support tool: what ASHA X currently gets, and from which scope |
- Authorization: limit the write APIs to an admin / programme-manager role. This is new: most FLW-API endpoints only validate the JWT today.
- Audit: take created_by / modified_by from the JWT user. A history table is optional.
- Phase 1: Swagger / Postman or a SQL script is enough. Later: an Admin UI screen and CSV upload (userId, enabled, mechanic).
5. Optional server-side enforcement
- /badges/* for a disabled ASHA should return empty results and ignore pushes. The app won't call them when disabled anyway, so this is only an extra safeguard.
- Decide whether to keep the global badge_config.feature_enabled as an extra kill switch or retire it.
6. Performance
- One indexed lookup across at most 5 scope levels per call. The result can be cached (Redis / in-memory) per userId with a short TTL, cleared on any admin write.
- Load is roughly the number of ASHAs × Home opens per day, which is trivial next to the sync APIs.
—
Open decisions (product / backend)
- Default when nothing is configured: recommended OFF. Rollout = add DISTRICT / BLOCK rows; go-live = one GLOBAL ALL true row.
- Release order: deploy this API (with the rollout rows in place) before the FLW-1251 app build reaches ASHAs. Otherwise the mobile side has to treat 404 as "no server decision".
- Who may change flags (list of roles), and whether block / district officers may manage only their own area.
- Whether badge_config.feature_enabled is kept or retired.
- Admin UI in Phase 1, or Swagger / SQL only.
Acceptance criteria
- [ ] DB script for gamification_access added to the AMRIT DB scripts.
- [ ] GET /gamification/access returns the resolved flags for the JWT user according to the rule in §3, including the Stop TB and non-ASHA cases.
- [ ] Admin can enable / disable for one ASHA, a list of ASHAs, and a whole block / district / state. The next GET /gamification/access reflects the change.
- [ ] Soft delete of an override falls back to the next scope level.
- [ ] Write APIs are restricted to admin roles, and changes are audited (who / when).
- [ ] Unit tests cover the resolution rules (examples in §3).
- [ ] Swagger and the API contract are shared with the FLW mobile team.
Related
- Mobile counterpart: FLW-1251. The app calls this API at login and on Home open, caches the result, and gates badges, recap, the 21:00 notification, the My Impact card and Journey. Firebase Remote Config stays as the global kill switch only.
- Supersedes the getUserDetail approach in AMM-2556.
- Mobile branch: naf_feature_gamification. Full analysis: docs/GAMIFICATION_ASHA_ACCESS_ANALYSIS.md.