@tailor-platform/erp-kit 0.7.0 → 0.8.0

package/templates/scaffold/app/docs/business-flow/user-lifecycle/story/user--update-user-profile.md

@@ -0,0 +1,41 @@
+# Update User Profile
+
+## User Story
+
+As a user with the appropriate role, I want to update another user's profile information, so that I can keep user records accurate and up to date.
+
+## Story Diagram
+
+```mermaid
+flowchart TD
+    A[Open User Detail] --> B[Click Edit]
+    B --> C[Modify name or email]
+    C --> D[Submit]
+    D --> E{Validation}
+    E -- Email already exists --> F[Show duplicate email error]
+    E -- Required field missing --> G[Show validation error]
+    E -- Valid --> H[Profile updated]
+```
+
+## Scenario Patterns
+
+- Update another user's name
+- Update another user's email address
+- Duplicate email address is rejected with an error
+- Submission with missing required fields is blocked by validation
+
+## Test Cases
+
+- Change a user's name and submit; verify the updated name is reflected on the detail page
+- Change a user's email to a valid unique address and submit; verify the updated email is shown
+- Change a user's email to one already assigned to another user; verify an error is shown and no change is saved
+- Clear the name field and submit; verify a validation error is shown
+
+## Screens
+
+- [user-detail](../../../screen/user-detail.md)
+- [user-edit-form](../../../screen/user-edit-form.md)
+
+## Resolvers
+
+- [updateUserProfile](../../../resolver/updateUserProfile.md)

package/templates/scaffold/app/docs/business-flow/user-lifecycle/story/user--view-own-profile.md

@@ -0,0 +1,30 @@
+# View Own Profile
+
+## User Story
+
+As a user, I want to view my profile details, so that I can verify my information and assigned roles.
+
+## Story Diagram
+
+```mermaid
+flowchart TD
+    A[Open Profile Page] --> B[View name and email]
+    B --> C[View assigned roles]
+```
+
+## Scenario Patterns
+
+- View profile showing name, email, and assigned roles
+- Profile reflects the currently authenticated user's data
+
+## Test Cases
+
+- Navigate to the profile page; verify name, email, and assigned roles are displayed correctly
+
+## Screens
+
+- [my-profile](../../../screen/my-profile.md)
+
+## Resolvers
+
+- None

package/templates/scaffold/app/docs/business-flow/user-lifecycle/story/user--view-user-detail.md

@@ -0,0 +1,33 @@
+# View User Detail
+
+## User Story
+
+As a user with the appropriate role, I want to view another user's profile details, so that I can review their information and assigned roles.
+
+## Story Diagram
+
+```mermaid
+flowchart TD
+    A[Open User List] --> B[Click on a user]
+    B --> C[View name, email, status]
+    C --> D[View assigned roles]
+```
+
+## Scenario Patterns
+
+- View full profile details of another user including name, email, status, and assigned roles
+- View profile of an INACTIVE user
+
+## Test Cases
+
+- Click on a user in the list; verify name, email, status, and assigned roles are displayed
+- Click on an INACTIVE user; verify the profile is displayed with INACTIVE status clearly indicated
+
+## Screens
+
+- [user-list](../../../screen/user-list.md)
+- [user-detail](../../../screen/user-detail.md)
+
+## Resolvers
+
+- None

package/templates/scaffold/app/docs/resolver/assignPermissionToRole.md

@@ -0,0 +1,16 @@
+# assignPermissionToRole
+
+## Overview
+
+Assigns a permission to a role, granting that permission to all users with the role.
+
+## Modules Commands Used
+
+- `user-management.assignPermissionToRole` — Creates a role-permission association
+
+## Exception Handling
+
+| Error Code           | Description                                    |
+| -------------------- | ---------------------------------------------- |
+| ROLE_NOT_FOUND       | The specified role does not exist       |
+| PERMISSION_NOT_FOUND | The specified permission does not exist |

package/templates/scaffold/app/docs/resolver/assignRoleToUser.md

@@ -0,0 +1,17 @@
+# assignRoleToUser
+
+## Overview
+
+Assigns a role to a user, granting the role's permissions.
+
+## Modules Commands Used
+
+- `user-management.assignRoleToUser` — Creates a user-role association
+
+## Exception Handling
+
+| Error Code           | Description                              |
+| -------------------- | ---------------------------------------- |
+| USER_NOT_FOUND  | The specified user does not exist |
+| ROLE_NOT_FOUND  | The specified role does not exist |
+| USER_NOT_ACTIVE | The user is not in ACTIVE status  |

package/templates/scaffold/app/docs/resolver/createRole.md

@@ -0,0 +1,17 @@
+# createRole
+
+## Overview
+
+Creates a new role with a unique name and optional description. Automatically assigns the `audit:logAuditEvent` and `user-management:updateOwnProfile` permissions so that all operations performed under this role are audited and users can update their own profile. The role can then have additional permissions assigned to it.
+
+## Modules Commands Used
+
+- `user-management.createRole` — Creates a new role record
+- `user-management.assignPermissionToRole` — Auto-assigns the `audit:logAuditEvent` and `user-management:updateOwnProfile` permissions to the new role
+
+## Exception Handling
+
+| Error Code             | Source               | Description                              |
+| ---------------------- | -------------------- | ---------------------------------------- |
+| DUPLICATE_ROLE_NAME    | createRole           | A role with the same name already exists |
+| MISSING_REQUIRED_FIELD | createRole           | The role name was not provided           |

package/templates/scaffold/app/docs/resolver/createUser.md

@@ -0,0 +1,23 @@
+# createUser
+
+## Overview
+
+Creates a new user account with ACTIVE status, optionally assigns one or more roles, and provisions an IDP user with an auto-generated password. The initial password is returned in the response for the admin to communicate to the user.
+
+## Modules Commands Used
+
+- `user-management.createUser` — Creates a new user record in PENDING status
+- `user-management.activateUser` — Transitions user to ACTIVE status
+- `user-management.assignRoleToUser` — Assigns each selected role to the new user (called once per role)
+
+## Exception Handling
+
+| Error Code                | Source               | Description                                                              |
+| ------------------------- | -------------------- | ------------------------------------------------------------------------ |
+| USER_ALREADY_EXISTS       | createUser           | A user with the same email exists                                        |
+| MISSING_REQUIRED_FIELD    | createUser           | Name or email is missing                                                 |
+| INVALID_EMAIL             | createUser           | Email format is invalid                                                  |
+| ROLE_NOT_FOUND            | assignRoleToUser     | One of the selected roles does not exist                                 |
+| USER_NOT_FOUND            | assignRoleToUser     | The created user was not found (should not occur in normal flow)         |
+| USER_NOT_ACTIVE           | assignRoleToUser     | The user is not in ACTIVE status (should not occur in normal flow)       |
+| IDP provisioning failure  | idp.Client.createUser | IDP user creation failed. DB transaction is rolled back — no user record is created |

package/templates/scaffold/app/docs/resolver/deactivateUser.md

@@ -0,0 +1,17 @@
+# deactivateUser
+
+## Overview
+
+Deactivates a user account, preventing system access. Only ACTIVE users can be deactivated. Users cannot deactivate their own account.
+
+## Modules Commands Used
+
+- `user-management.deactivateUser` — Changes user status from ACTIVE to INACTIVE
+
+## Exception Handling
+
+| Error Code                | Description                                |
+| ------------------------- | ------------------------------------------ |
+| USER_NOT_FOUND            | The specified user does not exist          |
+| INVALID_STATUS_TRANSITION | The user is not in ACTIVE status           |
+| SELF_DEACTIVATION         | A user cannot deactivate their own account |

package/templates/scaffold/app/docs/resolver/reactivateUser.md

@@ -0,0 +1,16 @@
+# reactivateUser
+
+## Overview
+
+Reactivates a previously deactivated user account. Only INACTIVE users can be reactivated.
+
+## Modules Commands Used
+
+- `user-management.reactivateUser` — Changes user status from INACTIVE to ACTIVE
+
+## Exception Handling
+
+| Error Code                | Description                        |
+| ------------------------- | ---------------------------------- |
+| USER_NOT_FOUND            | The specified user does not exist  |
+| INVALID_STATUS_TRANSITION | The user is not in INACTIVE status |

package/templates/scaffold/app/docs/resolver/revokePermissionFromRole.md

@@ -0,0 +1,17 @@
+# revokePermissionFromRole
+
+## Overview
+
+Removes a permission from a role, revoking that permission from all users with the role.
+
+## Modules Commands Used
+
+- `user-management.revokePermissionFromRole` — Removes a role-permission association
+
+## Exception Handling
+
+| Error Code           | Description                                |
+| -------------------- | ------------------------------------------ |
+| ROLE_NOT_FOUND       | The specified role does not exist          |
+| PERMISSION_NOT_FOUND | The specified permission does not exist    |
+| ASSIGNMENT_NOT_FOUND | The permission is not assigned to the role |

package/templates/scaffold/app/docs/resolver/revokeRoleFromUser.md

@@ -0,0 +1,17 @@
+# revokeRoleFromUser
+
+## Overview
+
+Removes a role from a user, revoking the role's permissions.
+
+## Modules Commands Used
+
+- `user-management.revokeRoleFromUser` — Removes a user-role association
+
+## Exception Handling
+
+| Error Code           | Description                          |
+| -------------------- | ------------------------------------ |
+| USER_NOT_FOUND       | The specified user does not exist    |
+| ROLE_NOT_FOUND       | The specified role does not exist    |
+| ASSIGNMENT_NOT_FOUND | The role is not assigned to the user |

package/templates/scaffold/app/docs/resolver/updateOwnProfile.md

@@ -0,0 +1,20 @@
+# updateOwnProfile
+
+## Overview
+
+Updates the authenticated user's own profile information. Uses the session context to identify the user. Only ACTIVE users can update their own profile.
+
+## Modules Commands Used
+
+- `user-management.updateOwnProfile` — Updates caller's own name and email (ACTIVE only, targets caller via ctx.actorId)
+
+## Exception Handling
+
+| Error Code                | Description                                    |
+| ------------------------- | ---------------------------------------------- |
+| USER_NOT_FOUND            | The authenticated user does not exist          |
+| INVALID_STATUS_TRANSITION | Caller is not ACTIVE (PENDING or INACTIVE)     |
+| USER_ALREADY_EXISTS       | A user with the same email exists              |
+| MISSING_REQUIRED_FIELD    | A required field was cleared or missing        |
+| INVALID_NAME              | Name is empty or whitespace only               |
+| INVALID_EMAIL             | Email does not follow valid email format        |

package/templates/scaffold/app/docs/resolver/updateUserProfile.md

@@ -0,0 +1,19 @@
+# updateUserProfile
+
+## Overview
+
+Updates another user's profile information (name and email). Admin-only operation that works on users in any status.
+
+## Modules Commands Used
+
+- `user-management.updateUser` — Updates user name and email (any status)
+
+## Exception Handling
+
+| Error Code             | Description                              |
+| ---------------------- | ---------------------------------------- |
+| USER_NOT_FOUND         | The specified user does not exist        |
+| USER_ALREADY_EXISTS    | A user with the same email exists        |
+| MISSING_REQUIRED_FIELD | Neither name nor email was provided      |
+| INVALID_NAME           | Name is empty or whitespace only         |
+| INVALID_EMAIL          | Email does not follow valid email format |

package/templates/scaffold/app/docs/screen/audit-entry-detail.md

@@ -0,0 +1,30 @@
+# audit-entry-detail
+
+## Overview
+
+Displays the full details of an audit log entry including actor, timestamp, and field-level change details (old and new values).
+
+## Screen Type
+
+DetailView
+
+### DetailView Details
+
+#### Displayed Fields
+
+- Event ID
+- Timestamp
+- Operation Type
+- Entity Type
+- Entity ID
+- Actor Type
+- Actor ID
+- Change Details (field name, old value, new value)
+
+#### Available Actions
+
+- Back to Audit Log List
+
+## Access Control
+
+- [user](../actors/user.md)

package/templates/scaffold/app/docs/screen/audit-entry-list.md

@@ -0,0 +1,25 @@
+# audit-entry-list
+
+## Overview
+
+Displays a paginated list of audit log entries with filtering by entity type and date range.
+
+## Screen Type
+
+ListView
+
+### ListView Details
+
+#### Required Columns
+
+| Column Name    | Hideable (Yes/No) | Sort-able (Yes/No) | Filter-able (Yes/No) | Searchable (Yes/No) |
+| -------------- | ----------------- | ------------------ | -------------------- | ------------------- |
+| Timestamp      | No                | Yes                | Yes                  | No                  |
+| Entity Type    | No                | Yes                | Yes                  | No                  |
+| Entity ID      | Yes               | No                 | No                   | Yes                 |
+| Operation Type | No                | Yes                | Yes                  | No                  |
+| Actor          | Yes               | Yes                | No                   | Yes                 |
+
+## Access Control
+
+- [user](../actors/user.md)

package/templates/scaffold/app/docs/screen/my-profile-edit-form.md

@@ -0,0 +1,22 @@
+# my-profile-edit-form
+
+## Overview
+
+Form to update the authenticated user's own profile information.
+
+## Screen Type
+
+Form
+
+### Form Details
+
+#### Input Fields
+
+| Field Name | Field Type | Required (Yes/No) |
+| ---------- | ---------- | ----------------- |
+| Name       | String     | Yes               |
+| Email      | String     | Yes               |
+
+## Access Control
+
+- [user](../actors/user.md)

package/templates/scaffold/app/docs/screen/my-profile.md

@@ -0,0 +1,27 @@
+# my-profile
+
+## Overview
+
+Displays the authenticated user's own profile details and assigned roles.
+
+## Screen Type
+
+DetailView
+
+### DetailView Details
+
+#### Displayed Fields
+
+- Name
+- Email
+- Status (ACTIVE / INACTIVE)
+- Assigned Roles
+
+#### Available Actions
+
+- Edit Profile
+- Sign out
+
+## Access Control
+
+- [user](../actors/user.md)

package/templates/scaffold/app/docs/screen/role-create-form.md

@@ -0,0 +1,23 @@
+# role-create-form
+
+## Overview
+
+Form to create a new role with name and permission selection.
+
+## Screen Type
+
+Form
+
+### Form Details
+
+#### Input Fields
+
+| Field Name  | Field Type   | Required (Yes/No) |
+| ----------- | ------------ | ----------------- |
+| Name        | String       | Yes               |
+| Description | String       | No                |
+| Permissions | Multi-select | Yes               |
+
+## Access Control
+
+- [user](../actors/user.md)

package/templates/scaffold/app/docs/screen/role-detail.md

@@ -0,0 +1,27 @@
+# role-detail
+
+## Overview
+
+Displays role details including assigned permissions.
+
+## Screen Type
+
+DetailView
+
+### DetailView Details
+
+#### Displayed Fields
+
+- Name
+- Description
+- Created At
+- Assigned Permissions
+
+#### Available Actions
+
+- Edit Role
+- Back to Role List
+
+## Access Control
+
+- [user](../actors/user.md)

package/templates/scaffold/app/docs/screen/role-edit-form.md

@@ -0,0 +1,21 @@
+# role-edit-form
+
+## Overview
+
+Form to modify a role's permission assignments.
+
+## Screen Type
+
+Form
+
+### Form Details
+
+#### Input Fields
+
+| Field Name  | Field Type   | Required (Yes/No) |
+| ----------- | ------------ | ----------------- |
+| Permissions | Multi-select | Yes               |
+
+## Access Control
+
+- [user](../actors/user.md)

package/templates/scaffold/app/docs/screen/role-list.md

@@ -0,0 +1,23 @@
+# role-list
+
+## Overview
+
+Displays a list of all roles. Provides navigation to role detail and role creation.
+
+## Screen Type
+
+ListView
+
+### ListView Details
+
+#### Required Columns
+
+| Column Name | Hideable (Yes/No) | Sort-able (Yes/No) | Filter-able (Yes/No) | Searchable (Yes/No) |
+| ----------- | ----------------- | ------------------ | -------------------- | ------------------- |
+| Name        | No                | Yes                | No                   | Yes                 |
+| Description | Yes               | No                 | No                   | No                  |
+| Created At  | Yes               | Yes                | No                   | No                  |
+
+## Access Control
+
+- [user](../actors/user.md)

package/templates/scaffold/app/docs/screen/user-create-form.md

@@ -0,0 +1,23 @@
+# user-create-form
+
+## Overview
+
+Form to create a new user account with name, email, and optional role assignments.
+
+## Screen Type
+
+Form
+
+### Form Details
+
+#### Input Fields
+
+| Field Name | Field Type   | Required (Yes/No) |
+| ---------- | ------------ | ----------------- |
+| Name       | String       | Yes               |
+| Email      | String       | Yes               |
+| Roles      | MultiSelect  | No                |
+
+## Access Control
+
+- [user](../actors/user.md)

package/templates/scaffold/app/docs/screen/user-detail.md

@@ -0,0 +1,33 @@
+# user-detail
+
+## Overview
+
+Displays user profile details including assigned roles. Provides actions for editing, status toggling, and role management.
+
+## Screen Type
+
+DetailView
+
+### DetailView Details
+
+#### Displayed Fields
+
+- Name
+- Email
+- Status (ACTIVE / INACTIVE)
+- Assigned Roles
+- Created At
+- Updated At
+
+#### Available Actions
+
+- Edit User
+- Deactivate User (when ACTIVE and not self)
+- Reactivate User (when INACTIVE)
+- Assign Roles (multiple selection)
+- Remove Role
+- Back to User List
+
+## Access Control
+
+- [user](../actors/user.md)

package/templates/scaffold/app/docs/screen/user-edit-form.md

@@ -0,0 +1,22 @@
+# user-edit-form
+
+## Overview
+
+Form to update another user's profile information including name and email.
+
+## Screen Type
+
+Form
+
+### Form Details
+
+#### Input Fields
+
+| Field Name | Field Type | Required (Yes/No) |
+| ---------- | ---------- | ----------------- |
+| Name       | String     | Yes               |
+| Email      | String     | Yes               |
+
+## Access Control
+
+- [user](../actors/user.md)

package/templates/scaffold/app/docs/screen/user-list.md

@@ -0,0 +1,24 @@
+# user-list
+
+## Overview
+
+Displays a paginated list of all users. Supports filtering by status and searching by name or email.
+
+## Screen Type
+
+ListView
+
+### ListView Details
+
+#### Required Columns
+
+| Column Name | Hideable (Yes/No) | Sort-able (Yes/No) | Filter-able (Yes/No) | Searchable (Yes/No) |
+| ----------- | ----------------- | ------------------ | -------------------- | ------------------- |
+| Name        | No                | Yes                | No                   | Yes                 |
+| Email       | No                | Yes                | No                   | Yes                 |
+| Status      | No                | Yes                | Yes                  | No                  |
+| Roles       | Yes               | No                 | No                   | No                  |
+
+## Access Control
+
+- [user](../actors/user.md)

package/templates/scaffold/app/frontend/package.json

@@ -16,7 +16,7 @@
     "@hookform/resolvers": "5.2.2",
     "@radix-ui/react-label": "2.1.8",
     "@radix-ui/react-slot": "1.2.4",
-    "@tailor-platform/app-shell": "0.28.0",
+    "@tailor-platform/app-shell": "0.31.0",
     "class-variance-authority": "0.7.1",
     "clsx": "2.1.1",
     "gql.tada": "1.9.0",

package/templates/scaffold/app/frontend/src/App.tsx

@@ -44,8 +44,12 @@ const App = () => {
               <DefaultSidebar>
                 <SidebarGroup title="User Management">
                   <SidebarItem to="/user-management/user" />
+                  <SidebarItem to="/user-management/role" />
                   <SidebarItem to="/user-management/profile" />
                 </SidebarGroup>
+                <SidebarGroup title="Audit">
+                  <SidebarItem to="/user-management/audit" />
+                </SidebarGroup>
               </DefaultSidebar>
             }
           />

package/templates/scaffold/app/frontend/src/components/composed/error-fallback.tsx

@@ -1,4 +1,4 @@
-import { Button } from "../ui/button";
+import { Button } from "@tailor-platform/app-shell";
 
 interface ErrorFallbackProps {
   title?: string;