FLW Gamification: ASHA-level enable/disable via dedicated access API (GET /gamification/access + admin bulk APIs)

XMLWordPrintable

    • 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)

      1. Default when nothing is configured: recommended OFF. Rollout = add DISTRICT / BLOCK rows; go-live = one GLOBAL ALL true row.
      2. 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".
      3. Who may change flags (list of roles), and whether block / district officers may manage only their own area.
      4. Whether badge_config.feature_enabled is kept or retired.
      5. 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.

              Assignee:
              Unassigned
              Reporter:
              Nikhil Ananda Fegade
              Votes:
              0 Vote for this issue
              Watchers:
              1 Start watching this issue

                Created:
                Updated: