Kyaw_Min_Khant/e_receipt_mobile
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

reset-cashier-password

Browse Source
This commit is contained in:
moon 2026-05-11 21:05:11 +06:30
parent dd6a1aa425
commit b3494d71dd
12 changed files with 933 additions and 266 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
lib/core/config/app_config.dart
View File

@ -1,7 +1,7 @@
class AppConfig { class AppConfig {
const AppConfig._(); const AppConfig._();
static const String apiBaseUrl = 'https://api-tms.kbzbank.com/receipt'; // static const String apiBaseUrl = 'https://api-tms.kbzbank.com/receipt';
// static const String apiBaseUrl = 'https://receipt-nest.utsmyanmar.com'; static const String apiBaseUrl = 'https://receipt-nest.utsmyanmar.com';
static const String apiSecret = 'y812J21lhha11OS'; static const String apiSecret = 'y812J21lhha11OS';
} }

81
lib/data/repositories/api_auth_repository.dart
View File

@ -29,10 +29,7 @@ class ApiAuthRepository implements AuthRepository {
final response = await _client.post( final response = await _client.post(
uri, uri,
headers: { headers: {'Content-Type': 'application/json', 'x-api-key': apiSecret},
'Content-Type': 'application/json',
'x-api-key': apiSecret,
},
body: requestBody, body: requestBody,
); );
@ -68,16 +65,11 @@ class ApiAuthRepository implements AuthRepository {
required String role, required String role,
}) async { }) async {
final uri = Uri.parse('$baseUrl/auth/refresh-token'); final uri = Uri.parse('$baseUrl/auth/refresh-token');
final requestBody = jsonEncode({ final requestBody = jsonEncode({'refreshToken': refreshToken});
'refreshToken': refreshToken,
});
final response = await _client.post( final response = await _client.post(
uri, uri,
headers: { headers: {'Content-Type': 'application/json', 'x-api-key': apiSecret},
'Content-Type': 'application/json',
'x-api-key': apiSecret,
},
body: requestBody, body: requestBody,
); );
@ -99,17 +91,11 @@ class ApiAuthRepository implements AuthRepository {
required String password, required String password,
}) async { }) async {
final uri = Uri.parse('$baseUrl/auth/reset-password'); final uri = Uri.parse('$baseUrl/auth/reset-password');
final requestBody = jsonEncode({ final requestBody = jsonEncode({'userId': userId, 'password': password});
'userId': userId,
'password': password,
});
final response = await _client.put( final response = await _client.put(
uri, uri,
headers: { headers: {'Content-Type': 'application/json', 'x-api-key': apiSecret},
'Content-Type': 'application/json',
'x-api-key': apiSecret,
},
body: requestBody, body: requestBody,
); );
@ -121,18 +107,36 @@ class ApiAuthRepository implements AuthRepository {
} }
@override @override
Future<void> logout({required String refreshToken}) async { Future<String> resetCashierPassword({required String username}) async {
final uri = Uri.parse('$baseUrl/auth/logout'); final trimmedUsername = username.trim();
final requestBody = jsonEncode({ final encodedUsername = Uri.encodeComponent(trimmedUsername);
'refreshToken': refreshToken, final uri = Uri.parse(
}); '$baseUrl/user/$encodedUsername/cashier-reset-password',
);
final response = await _client.post( final response = await _client.post(
uri, uri,
headers: { headers: {'Content-Type': 'application/json', 'x-api-key': apiSecret},
'Content-Type': 'application/json', );
'x-api-key': apiSecret,
}, if (response.statusCode >= 200 && response.statusCode < 300) {
return _extractSuccessMessage(
response.body,
fallback: 'Password reset successfully',
);
}
throw Exception(_extractErrorMessage(response.body));
}
@override
Future<void> logout({required String refreshToken}) async {
final uri = Uri.parse('$baseUrl/auth/logout');
final requestBody = jsonEncode({'refreshToken': refreshToken});
final response = await _client.post(
uri,
headers: {'Content-Type': 'application/json', 'x-api-key': apiSecret},
body: requestBody, body: requestBody,
); );
@ -164,6 +168,19 @@ class ApiAuthRepository implements AuthRepository {
return message.toString(); return message.toString();
} }
String _extractSuccessMessage(String body, {required String fallback}) {
final data = _asMap(body);
final message =
data['message'] ??
data['success'] ??
data['detail'] ??
_extractPayload(data)['message'];
if (message == null || message.toString().trim().isEmpty) {
return fallback;
}
return message.toString().trim();
}
String? _extractUserId(Map<String, dynamic> data) { String? _extractUserId(Map<String, dynamic> data) {
final rootUser = data['user']; final rootUser = data['user'];
if (rootUser is Map<String, dynamic>) { if (rootUser is Map<String, dynamic>) {
@ -192,10 +209,10 @@ class ApiAuthRepository implements AuthRepository {
final payload = _extractPayload(data); final payload = _extractPayload(data);
final apiUsername = _pickString(payload, const ['username', 'email']); final apiUsername = _pickString(payload, const ['username', 'email']);
final token = _pickString(payload, const ['token', 'accessToken']); final token = _pickString(payload, const ['token', 'accessToken']);
final refreshToken = _pickString( final refreshToken = _pickString(payload, const [
payload, 'refreshToken',
const ['refreshToken', 'refresh_token'], 'refresh_token',
); ]);
final role = _pickString(payload, const ['role']); final role = _pickString(payload, const ['role']);
if (token == null) { if (token == null) {

11
lib/data/repositories/mock_auth_repository.dart
View File

@ -60,6 +60,17 @@ class MockAuthRepository implements AuthRepository {
} }
} }
@override
Future<String> resetCashierPassword({required String username}) async {
await Future<void>.delayed(const Duration(milliseconds: 500));
if (username.trim().isEmpty) {
throw Exception('Username is required.');
}
return 'Password reset successfully';
}
@override @override
Future<void> logout({required String refreshToken}) async { Future<void> logout({required String refreshToken}) async {
await Future<void>.delayed(const Duration(milliseconds: 250)); await Future<void>.delayed(const Duration(milliseconds: 250));

7
lib/domain/repositories/auth_repository.dart
View File

@ -9,7 +9,12 @@ abstract class AuthRepository {
required String role, required String role,
}); });
Future<void> resetPassword({required String userId, required String password}); Future<void> resetPassword({
required String userId,
required String password,
});
Future<String> resetCashierPassword({required String username});
Future<void> logout({required String refreshToken}); Future<void> logout({required String refreshToken});
} }

26
lib/presentation/admin_reset_password/admin_reset_password_form_providers.dart Normal file
View File

@ -0,0 +1,26 @@
import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
final adminResetPasswordFormKeyProvider =
Provider.autoDispose<GlobalKey<FormState>>((ref) {
return GlobalKey<FormState>();
});
final adminResetUsernameControllerProvider =
Provider.autoDispose<TextEditingController>((ref) {
final controller = TextEditingController();
ref.onDispose(controller.dispose);
return controller;
});
final adminResetUsernameFocusNodeProvider = Provider.autoDispose<FocusNode>((
ref,
) {
final focusNode = FocusNode();
ref.onDispose(focusNode.dispose);
return focusNode;
});
final adminResetAttemptedSubmitProvider = StateProvider.autoDispose<bool>(
(ref) => false,
);

392
lib/presentation/admin_reset_password/admin_reset_password_page.dart Normal file
View File

@ -0,0 +1,392 @@
import 'package:e_receipt_mobile/domain/entities/login_user.dart';
import 'package:e_receipt_mobile/presentation/admin_reset_password/admin_reset_password_form_providers.dart';
import 'package:e_receipt_mobile/presentation/admin_reset_password/admin_reset_password_view_model.dart';
import 'package:e_receipt_mobile/presentation/auth/session_controller.dart';
import 'package:e_receipt_mobile/presentation/login/widgets/login_background.dart';
import 'package:flutter/material.dart';
import 'package:flutter/services.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
class AdminResetPasswordPage extends ConsumerWidget {
const AdminResetPasswordPage({super.key});
String? _buildDefaultPassword(String username) {
final trimmed = username.trim();
if (trimmed.length < 4) {
return null;
}
final firstThree = trimmed.substring(0, 3).toUpperCase();
final fourth = trimmed.substring(3, 4).toLowerCase();
final lastFour = trimmed.substring(trimmed.length - 4);
return '$firstThree$fourth@$lastFour';
}
void _submit({
required WidgetRef ref,
required GlobalKey<FormState> formKey,
required TextEditingController usernameController,
required bool isLoading,
}) {
if (isLoading) {
return;
}
ref.read(adminResetPasswordViewModelProvider.notifier).clearMessages();
FocusManager.instance.primaryFocus?.unfocus();
ref.read(adminResetAttemptedSubmitProvider.notifier).state = true;
if (!(formKey.currentState?.validate() ?? false)) {
return;
}
ref
.read(adminResetPasswordViewModelProvider.notifier)
.resetCashierPassword(username: usernameController.text);
}
@override
Widget build(BuildContext context, WidgetRef ref) {
final user = ref.watch(sessionControllerProvider);
if (!(user?.isAdmin ?? false)) {
return _AdminResetPasswordForbiddenPage(user: user);
}
final state = ref.watch(adminResetPasswordViewModelProvider);
final colorScheme = Theme.of(context).colorScheme;
ref.listen(adminResetPasswordViewModelProvider, (previous, next) {
final message = next.errorMessage;
if (message != null && message != previous?.errorMessage) {
ScaffoldMessenger.of(context).showSnackBar(
SnackBar(content: Text(message), behavior: SnackBarBehavior.floating),
);
}
final success = next.successMessage;
if (success != null && success != previous?.successMessage) {
final username = ref
.read(adminResetUsernameControllerProvider)
.text
.trim();
final generatedPassword = _buildDefaultPassword(username);
showDialog<void>(
context: context,
builder: (context) {
return AlertDialog(
title: const Text('Password reset'),
content: Column(
mainAxisSize: MainAxisSize.min,
crossAxisAlignment: CrossAxisAlignment.start,
children: [
const Text(
'The cashier password has been reset to the default temporary password.',
),
if (generatedPassword != null) ...[
const SizedBox(height: 12),
SelectableText(
generatedPassword,
style: Theme.of(context).textTheme.titleMedium?.copyWith(
fontWeight: FontWeight.w700,
),
),
const SizedBox(height: 8),
Text(
'The cashier will be required to change it on next login.',
style: Theme.of(context).textTheme.bodySmall?.copyWith(
color: colorScheme.onSurfaceVariant,
),
),
],
],
),
actions: [
TextButton(
onPressed: () {
final navigator = Navigator.of(context);
navigator.pop();
Navigator.of(
context,
rootNavigator: true,
).popUntil((route) => route.isFirst);
},
child: const Text('Back to home'),
),
],
);
},
);
}
});
final formKey = ref.watch(adminResetPasswordFormKeyProvider);
final usernameController = ref.watch(adminResetUsernameControllerProvider);
final usernameFocusNode = ref.watch(adminResetUsernameFocusNodeProvider);
final attemptedSubmit = ref.watch(adminResetAttemptedSubmitProvider);
return Scaffold(
appBar: AppBar(title: const Text('Reset cashier password')),
body: AnnotatedRegion<SystemUiOverlayStyle>(
value: Theme.of(context).brightness == Brightness.dark
? SystemUiOverlayStyle.light
: SystemUiOverlayStyle.dark,
child: LoginBackground(
child: SafeArea(
child: Center(
child: SingleChildScrollView(
padding: const EdgeInsets.symmetric(
horizontal: 20,
vertical: 24,
),
child: ConstrainedBox(
constraints: const BoxConstraints(maxWidth: 460),
child: Card(
elevation: 0,
color: colorScheme.surface.withValues(
alpha: Theme.of(context).brightness == Brightness.dark
? 0.75
: 0.92,
),
shape: RoundedRectangleBorder(
borderRadius: BorderRadius.circular(28),
side: BorderSide(
color: colorScheme.outlineVariant.withValues(
alpha: 0.35,
),
),
),
child: Padding(
padding: const EdgeInsets.fromLTRB(20, 22, 20, 18),
child: Form(
key: formKey,
autovalidateMode: attemptedSubmit
? AutovalidateMode.onUserInteraction
: AutovalidateMode.disabled,
child: Column(
crossAxisAlignment: CrossAxisAlignment.stretch,
children: [
Row(
children: [
Container(
height: 44,
width: 44,
decoration: BoxDecoration(
borderRadius: BorderRadius.circular(14),
gradient: LinearGradient(
begin: Alignment.topLeft,
end: Alignment.bottomRight,
colors: [
colorScheme.primary,
colorScheme.tertiary,
],
),
),
child: const Icon(
Icons.admin_panel_settings_outlined,
color: Colors.white,
),
),
const SizedBox(width: 12),
Expanded(
child: Column(
crossAxisAlignment:
CrossAxisAlignment.start,
children: [
Text(
'Reset cashier access',
style: Theme.of(context)
.textTheme
.titleLarge
?.copyWith(
fontWeight: FontWeight.w800,
),
),
Text(
'Reset a cashier account to its temporary default password.',
style: Theme.of(context)
.textTheme
.bodyMedium
?.copyWith(
color:
colorScheme.onSurfaceVariant,
),
),
],
),
),
],
),
const SizedBox(height: 18),
TextFormField(
controller: usernameController,
focusNode: usernameFocusNode,
enabled: !state.isLoading,
textInputAction: TextInputAction.done,
textCapitalization: TextCapitalization.characters,
onFieldSubmitted: (_) => _submit(
ref: ref,
formKey: formKey,
usernameController: usernameController,
isLoading: state.isLoading,
),
validator: (value) {
final text = (value ?? '').trim();
if (text.isEmpty) {
return 'Cashier username is required';
}
if (text.length < 4) {
return 'Username must be at least 4 characters';
}
return null;
},
decoration: InputDecoration(
labelText: 'Cashier username',
hintText: 'Enter terminal username',
prefixIcon: const Icon(Icons.badge_outlined),
filled: true,
fillColor: colorScheme.surfaceContainerHighest
.withValues(
alpha:
Theme.of(context).brightness ==
Brightness.dark
? 0.55
: 0.9,
),
border: OutlineInputBorder(
borderRadius: BorderRadius.circular(18),
),
),
),
const SizedBox(height: 14),
ValueListenableBuilder<TextEditingValue>(
valueListenable: usernameController,
builder: (context, value, _) {
final generatedPassword = _buildDefaultPassword(
value.text,
);
return Container(
padding: const EdgeInsets.all(14),
decoration: BoxDecoration(
color: colorScheme.surfaceContainerHigh
.withValues(alpha: 0.8),
borderRadius: BorderRadius.circular(18),
border: Border.all(
color: colorScheme.outlineVariant
.withValues(alpha: 0.45),
),
),
child: Column(
crossAxisAlignment:
CrossAxisAlignment.start,
children: [
Text(
'Default temporary password',
style: Theme.of(context)
.textTheme
.labelLarge
?.copyWith(
fontWeight: FontWeight.w700,
),
),
const SizedBox(height: 6),
SelectableText(
generatedPassword ??
'Enter at least 4 username characters to preview the generated password.',
style: Theme.of(context)
.textTheme
.bodyMedium
?.copyWith(
color: generatedPassword == null
? colorScheme.onSurfaceVariant
: colorScheme.onSurface,
fontWeight:
generatedPassword == null
? FontWeight.w400
: FontWeight.w700,
),
),
],
),
);
},
),
const SizedBox(height: 16),
FilledButton.icon(
onPressed: state.isLoading
? null
: () => _submit(
ref: ref,
formKey: formKey,
usernameController: usernameController,
isLoading: state.isLoading,
),
icon: state.isLoading
? const SizedBox(
height: 18,
width: 18,
child: CircularProgressIndicator(
strokeWidth: 2,
),
)
: const Icon(Icons.lock_reset_outlined),
label: Padding(
padding: const EdgeInsets.symmetric(
vertical: 12,
),
child: Text(
state.isLoading
? 'Resetting...'
: 'Reset password',
style: const TextStyle(
fontWeight: FontWeight.w600,
),
),
),
),
const SizedBox(height: 10),
Text(
'This will mark the password as temporary and force a password change on next login.',
textAlign: TextAlign.center,
style: Theme.of(context).textTheme.bodySmall
?.copyWith(
color: colorScheme.onSurfaceVariant,
),
),
],
),
),
),
),
),
),
),
),
),
),
);
}
}
class _AdminResetPasswordForbiddenPage extends StatelessWidget {
const _AdminResetPasswordForbiddenPage({required this.user});
final LoginUser? user;
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: const Text('Reset cashier password')),
body: Center(
child: Padding(
padding: const EdgeInsets.all(24),
child: Text(
user == null
? 'You must be logged in as admin to access this page.'
: 'Only admin users can reset cashier passwords.',
textAlign: TextAlign.center,
),
),
),
);
}
}

30
lib/presentation/admin_reset_password/admin_reset_password_state.dart Normal file
View File

@ -0,0 +1,30 @@
import 'package:flutter/foundation.dart';
@immutable
class AdminResetPasswordState {
const AdminResetPasswordState({
this.isLoading = false,
this.errorMessage,
this.successMessage,
});
final bool isLoading;
final String? errorMessage;
final String? successMessage;
AdminResetPasswordState copyWith({
bool? isLoading,
String? errorMessage,
String? successMessage,
bool clearError = false,
bool clearSuccess = false,
}) {
return AdminResetPasswordState(
isLoading: isLoading ?? this.isLoading,
errorMessage: clearError ? null : errorMessage ?? this.errorMessage,
successMessage: clearSuccess
? null
: successMessage ?? this.successMessage,
);
}
}

56
lib/presentation/admin_reset_password/admin_reset_password_view_model.dart Normal file
View File

@ -0,0 +1,56 @@
import 'package:e_receipt_mobile/domain/repositories/auth_repository.dart';
import 'package:e_receipt_mobile/presentation/admin_reset_password/admin_reset_password_state.dart';
import 'package:e_receipt_mobile/presentation/login/login_view_model.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
final adminResetPasswordViewModelProvider =
StateNotifierProvider.autoDispose<
AdminResetPasswordViewModel,
AdminResetPasswordState
>((ref) {
return AdminResetPasswordViewModel(
ref.watch(authenticatedAuthRepositoryProvider),
);
});
class AdminResetPasswordViewModel
extends StateNotifier<AdminResetPasswordState> {
AdminResetPasswordViewModel(this._authRepository)
: super(const AdminResetPasswordState());
final AuthRepository _authRepository;
Future<void> resetCashierPassword({required String username}) async {
final trimmedUsername = username.trim();
if (trimmedUsername.isEmpty) {
state = state.copyWith(
isLoading: false,
errorMessage: 'Cashier username is required',
clearSuccess: true,
);
return;
}
state = state.copyWith(
isLoading: true,
clearError: true,
clearSuccess: true,
);
try {
final responseMessage = await _authRepository.resetCashierPassword(
username: trimmedUsername,
);
state = state.copyWith(isLoading: false, successMessage: responseMessage);
} catch (error) {
state = state.copyWith(
isLoading: false,
errorMessage: error.toString().replaceFirst('Exception: ', ''),
);
}
}
void clearMessages() {
state = state.copyWith(clearError: true, clearSuccess: true);
}
}

13
lib/presentation/home/home_screen.dart
View File

@ -1,4 +1,5 @@
import 'package:e_receipt_mobile/domain/entities/login_user.dart'; import 'package:e_receipt_mobile/domain/entities/login_user.dart';
import 'package:e_receipt_mobile/presentation/admin_reset_password/admin_reset_password_page.dart';
import 'package:e_receipt_mobile/presentation/auth/logout_view_model.dart'; import 'package:e_receipt_mobile/presentation/auth/logout_view_model.dart';
import 'package:e_receipt_mobile/presentation/home/home_pagination_providers.dart'; import 'package:e_receipt_mobile/presentation/home/home_pagination_providers.dart';
import 'package:e_receipt_mobile/presentation/home/merchant_paging_view_model.dart'; import 'package:e_receipt_mobile/presentation/home/merchant_paging_view_model.dart';
@ -37,6 +38,16 @@ class HomeScreen extends ConsumerWidget {
), ),
drawer: HomeDrawer( drawer: HomeDrawer(
user: user, user: user,
onResetCashierPassword: user.isAdmin
? () {
Navigator.of(context).pop();
Navigator.of(context).push(
MaterialPageRoute<void>(
builder: (_) => const AdminResetPasswordPage(),
),
);
}
: null,
onLogout: () async { onLogout: () async {
if (logoutState.isLoading) { if (logoutState.isLoading) {
return; return;
@ -195,8 +206,6 @@ class HomeScreen extends ConsumerWidget {
); );
} }
void _openTerminalSelection( void _openTerminalSelection(
BuildContext context, BuildContext context,
String merchantId, String merchantId,

13
lib/presentation/home/widgets/home_drawer.dart
View File

@ -6,11 +6,13 @@ class HomeDrawer extends StatelessWidget {
const HomeDrawer({ const HomeDrawer({
required this.user, required this.user,
required this.onLogout, required this.onLogout,
this.onResetCashierPassword,
super.key, super.key,
}); });
final LoginUser user; final LoginUser user;
final VoidCallback onLogout; final VoidCallback onLogout;
final VoidCallback? onResetCashierPassword;
@override @override
Widget build(BuildContext context) { Widget build(BuildContext context) {
@ -21,11 +23,20 @@ class HomeDrawer extends StatelessWidget {
child: Column( child: Column(
children: [ children: [
_DrawerHeader(user: user), _DrawerHeader(user: user),
if (user.isAdmin)
Padding(
padding: const EdgeInsets.fromLTRB(8, 12, 8, 0),
child: _DrawerItem(
icon: Icons.lock_reset_outlined,
label: 'Reset cashier password',
onTap: onResetCashierPassword ?? () {},
),
),
const Spacer(), const Spacer(),
Divider( Divider(
height: 1, height: 1,
thickness: 1, thickness: 1,
color: colorScheme.outlineVariant.withOpacity(0.6), color: colorScheme.outlineVariant.withValues(alpha: 0.6),
), ),
Padding( Padding(
padding: const EdgeInsets.fromLTRB(8, 4, 8, 8), padding: const EdgeInsets.fromLTRB(8, 4, 8, 8),

8
lib/presentation/login/login_view_model.dart
View File

@ -67,6 +67,14 @@ final authRepositoryProvider = Provider<AuthRepository>((ref) {
); );
}); });
final authenticatedAuthRepositoryProvider = Provider<AuthRepository>((ref) {
return ApiAuthRepository(
baseUrl: AppConfig.apiBaseUrl,
apiSecret: AppConfig.apiSecret,
client: ref.watch(authenticatedHttpClientProvider),
);
});
final loginViewModelProvider = final loginViewModelProvider =
StateNotifierProvider<LoginViewModel, LoginState>((ref) { StateNotifierProvider<LoginViewModel, LoginState>((ref) {
return LoginViewModel( return LoginViewModel(

102
user.md Normal file
View File

@ -0,0 +1,102 @@
# User API Documentation
Base path: `/user` (mounted at `/user`)
All routes require `keycloak.protect()` — Bearer token authentication via Keycloak.
---
## POST /user/:username/cashier-reset-password
**Purpose:** Reset a cashier's password to an auto-generated default. The default password is generated as: first 3 chars uppercase + 4th char lowercase + `@` + last 4 chars of username. The password is set as **temporary** (user must change on next login).
### Path Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| username | string | Yes | Username of the cashier to reset |
### Responses
| Code | Body |
|------|------|
| 200 | `{ "message": "Password reset successfully" }` |
| 400 | `{ "message": "Username is required" }` |
| 404 | `{ "message": "No user found" }` |
| 500 | `{ "message": "<error>" }` |
---
## POST /user/change-password
**Purpose:** Authenticated user changes their own password. Verifies old password against Keycloak token endpoint, then sets the new password as **permanent**.
### Request Body
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| oldPassword | string | Yes | Current password |
| newPassword | string | Yes | New password |
| confirmPassword | string | Yes | Must match newPassword |
### Responses
| Code | Body |
|------|------|
| 200 | `{ "message": "Password changed successfully" }` |
| 400 | `{ "message": "All fields are required" }` or `"New passwords do not match"` or `"Invalid old password"` |
| 401 | `{ "message": "Unauthorized: User" }` |
| 404 | `{ "message": "No user found" }` |
| 500 | `{ "message": "<error>" }` |
---
## POST /user/
**Purpose:** Create a cashier user in Keycloak tied to a specific merchant. The username must correspond to an existing terminal serial in TMS for the given merchantId.
### Middleware
- `keycloak.protect()`
- `createUserValidationRules` (express-validator)
### Request Body
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| username | string | Yes | Alphanumeric, must exist as serial in TMS |
| password | string | Yes | Minimum 6 characters |
| role | string | Yes | One of: `"cashier"`, `"merchant"`, `"admin"` |
| merchantId | string | Yes | Merchant ID the user belongs to |
### Responses
| Code | Body |
|------|------|
| 201 | `{ "message": "User created successfully", "userId": "<keycloak-id>" }` |
| 400 | `{ "errors": [...] }` (validation) or `{ "message": "Serials did not exist in TMS" }` |
| 500 | `{ "message": "<error>" }` |
---
## GET /user/merchant
**Purpose:** Get all cashier/terminal users belonging to a merchant. Fetches terminal serials from TMS for the given merchantId, then returns the corresponding Keycloak user data for each serial.
### Query Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| merchantId | string | Yes | Merchant ID to retrieve cashier users for |
### Responses
| Code | Body |
|------|------|
| 200 | `[{ "id": "...", "username": "...", "email": null, "firstName": null, "lastName": null, "enabled": true }]` |
| 400 | `{ "message": "merchantId is required" }` |
| 500 | `{ "message": "<error>" }` |
---
## GET /user/admin
**Purpose:** Get all admin users from Keycloak. Requires the authenticated user to have the `"admin"` client role.
### Responses
| Code | Body |
|------|------|
| 200 | `[{ "id": "...", "username": "...", "email": "...", "firstName": "...", "lastName": "...", "enabled": true }]` |
| 400 | `{ "message": "permission is required" }` |
| 500 | `{ "message": "<error>" }` |