136 lines
3.7 KiB
Markdown
136 lines
3.7 KiB
Markdown
# MamadApp
|
|
|
|
Emergency tracker web app with role-based admin management and hierarchical user organization.
|
|
|
|
## Overview
|
|
MamadApp tracks user status (shelter and activity) and provides an admin console to manage users across a hierarchy:
|
|
Field > Department > Team > Person. Admins can manage only the scope they are assigned to.
|
|
|
|
## Requirements
|
|
- Node.js 18+
|
|
- MySQL 8+
|
|
- npm (or pnpm)
|
|
|
|
## Repository Layout
|
|
- `app/` Next.js app routes (UI + API)
|
|
- `components/` shared UI components
|
|
- `hooks/` client hooks (real-time polling)
|
|
- `lib/` database and auth utilities
|
|
- `scripts/` database setup, migration, and maintenance
|
|
- `types/` shared TypeScript types
|
|
|
|
## Configuration
|
|
1) Copy `config.json.template` to `config.json`
|
|
2) Update database settings:
|
|
- `database.host`
|
|
- `database.user`
|
|
- `database.password`
|
|
- `database.database`
|
|
|
|
## Database Setup
|
|
|
|
Fresh install:
|
|
1) (Optional) Create database user:
|
|
- Run `scripts/setup-database-user.sql` as MySQL root.
|
|
2) Create schema:
|
|
- Run `scripts/schema.sql`
|
|
|
|
Existing database:
|
|
1) Run `scripts/migrate-managed-types.sql`
|
|
- Adds `managed_types` table
|
|
- Converts `users.field/department/team` to `VARCHAR`
|
|
- Seeds managed types and hierarchy from existing user data
|
|
|
|
See `scripts/README.md` for details and archived migrations.
|
|
|
|
## Running the App
|
|
Local development:
|
|
- `npm install`
|
|
- `npm run dev`
|
|
|
|
Production build:
|
|
- `npm run build`
|
|
- `npm run start`
|
|
|
|
## Admin Roles and Permissions
|
|
|
|
Global admin:
|
|
- Full access to all fields/departments/teams
|
|
- Can create, rename, and delete managed types
|
|
- Can move any user
|
|
|
|
Field admin (Field A):
|
|
- Can manage users in Field A only
|
|
- Can create/rename/delete departments and teams under Field A
|
|
- Can move users within Field A (including across departments/teams)
|
|
|
|
Department admin (Dept X in Field A):
|
|
- Can manage users in Dept X only
|
|
- Can create/rename/delete teams under Dept X
|
|
- Can move users within Dept X
|
|
|
|
Team admin (Team Y in Dept X):
|
|
- Can manage users in Team Y only
|
|
- Cannot create/rename/delete managed types
|
|
- Can only move users within Team Y
|
|
|
|
## Managed Types (Fields, Departments, Teams)
|
|
Managed types are stored in `managed_types` with hierarchy:
|
|
- `field` has no parent
|
|
- `department` parent = field
|
|
- `team` parent = department
|
|
|
|
UI behavior:
|
|
- Managed types list is filtered based on the admin scope.
|
|
- Department and team creation requires selecting a parent.
|
|
- Rename updates both `managed_types` and existing user rows.
|
|
- Deleting is blocked if users or child types still reference the value.
|
|
|
|
## Database Tables
|
|
|
|
`users` (core):
|
|
- identity: `national_id`, `name`
|
|
- auth: `password`, `must_change_password`, `password_changed_at`
|
|
- scope: `field`, `department`, `team`
|
|
- role: `role`, `is_admin`
|
|
- status: `in_shelter`, `last_updated`
|
|
- safety: `lock_status`
|
|
|
|
`managed_types`:
|
|
- `type`: `field | department | team`
|
|
- `name`
|
|
- `parent_id` for hierarchy
|
|
|
|
`admin_actions`:
|
|
- Tracks resets, password resets, and role changes
|
|
|
|
## Common Tasks
|
|
|
|
Add a new field/department/team:
|
|
- Use the Admin UI (global/field/department admins only).
|
|
- Department/team creation requires selecting a parent.
|
|
|
|
Move a user:
|
|
- Use the Admin UI and the edit (pencil) button in user tables.
|
|
- User movement is restricted by admin scope.
|
|
|
|
Rename a type:
|
|
- Use the managed types UI. Rename cascades to users.
|
|
|
|
## Troubleshooting
|
|
|
|
Managed types not appearing:
|
|
- Ensure `managed_types` table exists.
|
|
- Run `scripts/migrate-managed-types.sql`.
|
|
|
|
Cannot delete a type:
|
|
- Users or child types still reference it.
|
|
- Reassign users and delete children first.
|
|
|
|
Permissions denied:
|
|
- Verify the admin role and assigned scope (field/department/team values).
|
|
|
|
## Notes
|
|
- Admin actions are logged in `admin_actions`.
|
|
- Managed types are hierarchical and validated in API routes.
|