@tailor-platform/erp-kit 0.6.0 → 0.8.0

package/templates/scaffold/app/docs/business-flow/user-lifecycle/README.md

@@ -0,0 +1,48 @@
+# user-lifecycle
+
+## Overview
+
+Manages the lifecycle of user accounts. Users with appropriate roles can create accounts, browse and view other users, edit profile information, and control the active/inactive status. Any user can view and update their own profile.
+
+## Actors Involved
+
+- [user](../../actors/user.md)
+
+## Flow Diagram
+
+```mermaid
+sequenceDiagram
+    actor User as user
+    participant System
+
+    User->>System: Create User Account
+    System-->>User: User created (ACTIVE)
+    User->>System: Browse User List
+    System-->>User: Paginated user list
+    User->>System: View User Detail
+    System-->>User: User profile details
+    User->>System: Update User Profile
+    System-->>User: Profile updated
+    User->>System: View Own Profile
+    System-->>User: Own profile details
+    User->>System: Update Own Profile
+    System-->>User: Own profile updated
+    alt Deactivate
+        User->>System: Deactivate User
+        System-->>User: User set to INACTIVE
+    end
+    alt Reactivate
+        User->>System: Reactivate User
+        System-->>User: User set to ACTIVE
+    end
+```
+
+## Stories
+
+- [Create User Account](./story/user--create-user-account.md)
+- [Browse User List](./story/user--browse-user-list.md)
+- [View User Detail](./story/user--view-user-detail.md)
+- [Update User Profile](./story/user--update-user-profile.md)
+- [View Own Profile](./story/user--view-own-profile.md)
+- [Update Own Profile](./story/user--update-own-profile.md)
+- [Toggle User Status](./story/user--toggle-user-status.md)

package/templates/scaffold/app/docs/business-flow/user-lifecycle/story/user--browse-user-list.md

@@ -0,0 +1,38 @@
+# Browse User List
+
+## User Story
+
+As a user with the appropriate role, I want to browse a list of all users, so that I can find and manage user accounts.
+
+## Story Diagram
+
+```mermaid
+flowchart TD
+    A[Open User List] --> B[View paginated user list]
+    B --> C{Filter or search?}
+    C -- Yes --> D[Apply name/email/status filter]
+    D --> B
+    C -- No --> E[Select a user to view detail]
+```
+
+## Scenario Patterns
+
+- View the full list of users with name, email, role, and status columns
+- Filter users by status (ACTIVE / INACTIVE)
+- Search users by name or email
+- Empty list when no users match the filter criteria
+
+## Test Cases
+
+- Open the user list page; verify all users are displayed with name, email, role, and status
+- Filter by INACTIVE status; verify only inactive users are shown
+- Search by a partial name; verify matching users are displayed
+- Apply a filter that matches no users; verify an empty state message is shown
+
+## Screens
+
+- [user-list](../../../screen/user-list.md)
+
+## Resolvers
+
+- None

package/templates/scaffold/app/docs/business-flow/user-lifecycle/story/user--create-user-account.md

@@ -0,0 +1,45 @@
+# Create User Account
+
+## User Story
+
+As a user with the appropriate role, I want to create a new user account with name, email, and optionally one or more roles, so that new employees can access the system.
+
+## Story Diagram
+
+```mermaid
+flowchart TD
+    A[Open User List] --> B[Click Create]
+    B --> C[Enter name and email]
+    C --> D[Select roles - optional, multiple allowed]
+    D --> E[Submit]
+    E --> F{Validation}
+    F -- Email already exists --> G[Show duplicate email error]
+    F -- Required field missing --> H[Show validation error]
+    F -- Valid --> I[User created with ACTIVE status]
+    I --> J[Display initial password dialog]
+    J --> K[Admin copies password and confirms]
+    K --> L[Navigate to user list]
+```
+
+## Scenario Patterns
+
+- Create user with all required fields and one or more roles; initial password is displayed in a dialog
+- Create user with no roles assigned; user is created and roles can be assigned later
+- Duplicate email address is rejected with an error
+- Submission with missing required fields is blocked by validation
+
+## Test Cases
+
+- Submit the form with valid name, email, and one or more roles; verify the user appears in the list with ACTIVE status and an initial password is returned
+- Submit the form with valid name and email but no roles; verify the user is created with ACTIVE status
+- Submit the form with an email address already assigned to another user; verify an error is shown and no user is created
+- Submit the form with the name field empty; verify a validation error is shown and submission is blocked
+
+## Screens
+
+- [user-list](../../../screen/user-list.md)
+- [user-create-form](../../../screen/user-create-form.md)
+
+## Resolvers
+
+- [createUser](../../../resolver/createUser.md)

package/templates/scaffold/app/docs/business-flow/user-lifecycle/story/user--toggle-user-status.md

@@ -0,0 +1,38 @@
+# Toggle User Status
+
+## User Story
+
+As a user with the appropriate role, I want to activate or deactivate a user account, so that I can control system access.
+
+## Story Diagram
+
+```mermaid
+flowchart TD
+    A[Open User Detail] --> B{Current status}
+    B -- ACTIVE --> C[Click Deactivate]
+    B -- INACTIVE --> D[Click Reactivate]
+    C --> E[Confirm]
+    D --> E
+    E --> F[Status changed]
+```
+
+## Scenario Patterns
+
+- Deactivate an ACTIVE user account
+- Reactivate an INACTIVE user account
+- Cannot deactivate own account
+
+## Test Cases
+
+- Open the detail page for an ACTIVE user and click Deactivate; verify the user's status changes to INACTIVE
+- Open the detail page for an INACTIVE user and click Reactivate; verify the user's status changes to ACTIVE
+- Open the detail page for the currently authenticated user; verify the Deactivate action is not available
+
+## Screens
+
+- [user-detail](../../../screen/user-detail.md)
+
+## Resolvers
+
+- [deactivateUser](../../../resolver/deactivateUser.md)
+- [reactivateUser](../../../resolver/reactivateUser.md)

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

@@ -0,0 +1,36 @@
+# Update Own Profile
+
+## User Story
+
+As a user, I want to update my personal information, so that my profile stays accurate.
+
+## Story Diagram
+
+```mermaid
+flowchart TD
+    A[Open Profile Page] --> B[Click Edit]
+    B --> C[Update fields]
+    C --> D[Submit]
+    D --> E{Validation}
+    E -- Invalid input --> F[Show validation error]
+    E -- Valid --> G[Profile updated]
+```
+
+## Scenario Patterns
+
+- Update name or email with valid values
+- Submission with invalid values is blocked by validation
+
+## Test Cases
+
+- Edit the name field with a new valid value and submit; verify the profile page reflects the updated name
+- Clear a required field and submit; verify a validation error is shown and the profile is not updated
+
+## Screens
+
+- [my-profile](../../../screen/my-profile.md)
+- [my-profile-edit-form](../../../screen/my-profile-edit-form.md)
+
+## Resolvers
+
+- [updateOwnProfile](../../../resolver/updateOwnProfile.md)

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)