@tailor-platform/erp-kit 0.7.0 → 0.9.0

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

@@ -0,0 +1,35 @@
+# View Audit Log Detail
+
+## User Story
+
+As a user with the appropriate role, I want to view the full details of an audit log entry, so that I can see what changed (before/after values).
+
+## Story Diagram
+
+```mermaid
+flowchart TD
+    A[Open Audit Log List] --> B[Click entry]
+    B --> C[Open Audit Log Detail]
+    C --> D[Display actor and timestamp]
+    D --> E[Display old values]
+    D --> F[Display new values]
+```
+
+## Scenario Patterns
+
+- View detail of an update entry that includes both old and new values
+- View detail of a creation entry where no old values exist
+
+## Test Cases
+
+- Click an update entry in the audit log list; verify the detail screen shows the actor, timestamp, and both old and new field values
+- Click a creation entry; verify old values are empty and new values reflect the created record
+
+## Screens
+
+- [audit-entry-list](../../../screen/audit-entry-list.md)
+- [audit-entry-detail](../../../screen/audit-entry-detail.md)
+
+## Resolvers
+
+- None

package/templates/scaffold/app/docs/business-flow/audit-log/story/user--view-audit-log.md

@@ -0,0 +1,44 @@
+# View Audit Log
+
+## User Story
+
+As a user with the appropriate role, I want to view and filter the audit log, so that I can track all entity operations for compliance.
+
+## Story Diagram
+
+```mermaid
+flowchart TD
+    A[Open Audit Log List] --> B[Apply filters]
+    B --> C{Filter type}
+    C -- Entity type selected --> D[Show entries for that entity type]
+    C -- Date range selected --> E[Show entries within date range]
+    C -- No filter --> F[Show all entries]
+    D --> G[View paginated results]
+    E --> G
+    F --> G
+    G --> H{Results}
+    H -- Entries found --> I[Display audit log entries]
+    H -- No entries --> J[Show empty state]
+```
+
+## Scenario Patterns
+
+- View all audit log entries without any filter applied
+- Filter entries by a specific entity type
+- Filter entries by a date range
+- Combined filter returns no results and an empty state is shown
+
+## Test Cases
+
+- Open the audit log list with no filters; verify all entries are displayed with pagination
+- Select an entity type filter; verify only entries for that entity type are shown
+- Set a date range filter; verify only entries within the specified range are shown
+- Set a date range with no matching entries; verify an empty state is displayed
+
+## Screens
+
+- [audit-entry-list](../../../screen/audit-entry-list.md)
+
+## Resolvers
+
+- None

package/templates/scaffold/app/docs/business-flow/role-management/README.md

@@ -0,0 +1,33 @@
+# role-management
+
+## Overview
+
+Manages roles within the organization. Users with appropriate roles can define roles with specific permissions, and assign or remove roles from users to control access.
+
+## Actors Involved
+
+- [user](../../actors/user.md)
+
+## Flow Diagram
+
+```mermaid
+sequenceDiagram
+    actor User as user
+    participant System
+
+    User->>System: Create Role
+    System-->>User: Role created
+    User->>System: Update Role Permissions
+    System-->>User: Role updated
+    User->>System: Assign Role to User
+    System-->>User: Role assigned
+    User->>System: Remove Role from User
+    System-->>User: Role removed
+```
+
+## Stories
+
+- [Create Role](./story/user--create-role.md)
+- [Update Role Permissions](./story/user--update-role-permissions.md)
+- [Assign Role to User](./story/user--assign-role-to-user.md)
+- [Remove Role from User](./story/user--remove-role-from-user.md)

package/templates/scaffold/app/docs/business-flow/role-management/story/user--assign-role-to-user.md

@@ -0,0 +1,35 @@
+# Assign Role To User
+
+## User Story
+
+As a user with the appropriate role, I want to assign a role to a user, so that they gain the role's permissions.
+
+## Story Diagram
+
+```mermaid
+flowchart TD
+    A[Open User Detail] --> B[Click Assign Role]
+    B --> C[Select role from list]
+    C --> D[Confirm]
+    D --> E{Validation}
+    E -- Role already assigned --> F[Show duplicate assignment error]
+    E -- Valid --> G[Role assigned to user]
+```
+
+## Scenario Patterns
+
+- Assign a role that is not yet assigned to the user
+- Assigning a role the user already holds is rejected with an error
+
+## Test Cases
+
+- Select a role not yet assigned to the user and confirm; verify the role appears in the user's role list
+- Attempt to assign a role the user already holds; verify an error is shown and no duplicate assignment is created
+
+## Screens
+
+- [user-detail](../../../screen/user-detail.md)
+
+## Resolvers
+
+- [assignRoleToUser](../../../resolver/assignRoleToUser.md)

package/templates/scaffold/app/docs/business-flow/role-management/story/user--create-role.md

@@ -0,0 +1,41 @@
+# Create Role
+
+## User Story
+
+As a user with the appropriate role, I want to create a new role with permissions, so that I can define access levels.
+
+## Story Diagram
+
+```mermaid
+flowchart TD
+    A[Open Role List] --> B[Click Create]
+    B --> C[Enter role name]
+    C --> D[Select permissions]
+    D --> E[Submit]
+    E --> F{Validation}
+    F -- Role name already exists --> G[Show duplicate name error]
+    F -- Required field missing --> H[Show validation error]
+    F -- Valid --> I[Role created and available for assignment]
+```
+
+## Scenario Patterns
+
+- Create a role with a unique name and one or more permissions
+- Duplicate role name is rejected with an error
+- Submission with a missing role name is blocked by validation
+
+## Test Cases
+
+- Submit the form with a unique name and selected permissions; verify the role appears in the role list
+- Submit the form with a name already used by an existing role; verify an error is shown and no role is created
+- Submit the form with the name field empty; verify a validation error is shown and submission is blocked
+
+## Screens
+
+- [role-list](../../../screen/role-list.md)
+- [role-create-form](../../../screen/role-create-form.md)
+
+## Resolvers
+
+- [createRole](../../../resolver/createRole.md)
+- [assignPermissionToRole](../../../resolver/assignPermissionToRole.md)

package/templates/scaffold/app/docs/business-flow/role-management/story/user--remove-role-from-user.md

@@ -0,0 +1,33 @@
+# Remove Role From User
+
+## User Story
+
+As a user with the appropriate role, I want to remove a role from a user, so that their permissions are revoked.
+
+## Story Diagram
+
+```mermaid
+flowchart TD
+    A[Open User Detail] --> B[Select role to remove]
+    B --> C[Click Remove]
+    C --> D[Confirm removal]
+    D --> E[Role removed from user]
+```
+
+## Scenario Patterns
+
+- Remove an assigned role from a user
+- Cancelling the confirmation leaves the role assignment unchanged
+
+## Test Cases
+
+- Select an assigned role on a user, click Remove, and confirm; verify the role no longer appears in the user's role list
+- Select an assigned role on a user, click Remove, and cancel; verify the role still appears in the user's role list
+
+## Screens
+
+- [user-detail](../../../screen/user-detail.md)
+
+## Resolvers
+
+- [revokeRoleFromUser](../../../resolver/revokeRoleFromUser.md)

package/templates/scaffold/app/docs/business-flow/role-management/story/user--update-role-permissions.md

@@ -0,0 +1,41 @@
+# Update Role Permissions
+
+## User Story
+
+As a user with the appropriate role, I want to modify a role's permissions, so that access levels stay current.
+
+## Story Diagram
+
+```mermaid
+flowchart TD
+    A[Open Role List] --> B[Select role]
+    B --> C[Click Edit]
+    C --> D[Modify permission selection]
+    D --> E[Submit]
+    E --> F{Validation}
+    F -- No permissions selected --> G[Show validation error]
+    F -- Valid --> H[Role permissions updated]
+```
+
+## Scenario Patterns
+
+- Add one or more permissions to an existing role
+- Remove one or more permissions from an existing role
+- Submission with no permissions selected is blocked by validation
+
+## Test Cases
+
+- Add a permission to a role and submit; verify the updated permissions are reflected on the role detail
+- Remove all permissions from a role and submit; verify a validation error is shown and the role is not updated
+- Remove one permission while keeping others and submit; verify the permission is no longer listed on the role
+
+## Screens
+
+- [role-list](../../../screen/role-list.md)
+- [role-detail](../../../screen/role-detail.md)
+- [role-edit-form](../../../screen/role-edit-form.md)
+
+## Resolvers
+
+- [assignPermissionToRole](../../../resolver/assignPermissionToRole.md)
+- [revokePermissionFromRole](../../../resolver/revokePermissionFromRole.md)

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 |