Platform Settings — Requirements

Overview

A single business module (@libs-modules/platform-settings) that provides administrative CRUD pages for platform-level configuration entities: tax classes (fiscal), brands (brand-registry), and categories + tags (taxonomy). These entities are managed by existing core libraries that already provide services, models, mock APIs, and embeddable selectors. This module adds the missing management UI.

Location: libs/modules/platform-settings/ Import path: @libs-modules/platform-settings Base path: /settings Module ID: platform-settings

Functional Requirements

FR-1: Navigation

• Single top-level menu item: Settings (icon: cog)
• Sub-items:
  • Tax Classes → /settings/fiscal
  • Brands → /settings/brands
  • Categories → /settings/taxonomy/categories
  • Tags → /settings/taxonomy/tags

FR-2: Tax Classes (Basic CRUD)

List page (/settings/fiscal):

• Table displaying: name, code, rate (%), isDefault badge, isActive badge, actions
• Inline "Add" button opens a dialog/inline form
• Edit action opens same dialog/form pre-filled
• Delete action with confirmation
• No separate detail page needed

Form (dialog or inline):

• Fields: name (required), code (required, unique), description, rate (required, number with %), isDefault (toggle), isActive (toggle), sortOrder
• Validation: code format, rate 0–100 range
• Uses FiscalService from @libs-core/fiscal

FR-3: Brands (Basic CRUD)

List page (/settings/brands):

• Table displaying: logo thumbnail, name, slug, website (link), isActive badge, actions
• Search by name
• Inline "Add" button opens a dialog/inline form
• Edit/Delete actions

Form (dialog or inline):

• Fields: name (required), slug (auto-generated from name), description, website, isActive (toggle), sortOrder
• Logo upload via GgsEntityMediaSectionComponent (edit mode only)
• Uses BrandService from @libs-core/brand-registry

FR-4: Categories (Full CRUD)

List/Tree page (/settings/taxonomy/categories):

• Category tree view using GgsCategoryTreeComponent with scope selector at top
• Default scope: product (should support switching between available scopes)
• Actions per node: Edit, Add child, Move, Delete
• "Add Root Category" button

Detail page (/settings/taxonomy/categories/:id):

• Category info: name, slug, description, path, level, parent
• Children list
• Media (image)
• Metadata (key-value)

Form (/settings/taxonomy/categories/create, /settings/taxonomy/categories/:id/edit):

• Fields: scope (required), name (required), slug (auto-gen), description, parentId (category selector), isActive (toggle), sortOrder
• Image upload via media component (edit mode only)
• Metadata editor (key-value pairs)
• Uses TaxonomyCategoryService from @libs-core/taxonomy

FR-5: Tags (Basic CRUD)

List page (/settings/taxonomy/tags):

• Table displaying: name, slug, color swatch, scope, usageCount, isActive badge, actions
• Scope filter dropdown
• Search by name
• "Add" button opens dialog/inline form
• Edit/Delete actions

Form (dialog or inline):

• Fields: scope (required), name (required), slug (auto-gen), color (color picker), isActive (toggle)
• Uses TaxonomyTagService from @libs-core/taxonomy

Non-Functional Requirements

NFR-1: Architecture Compliance

• Follow @ModuleDecorator pattern (same as user-management, product-catalog)
• Standalone components with OnPush change detection
• Uses existing core library services — no new API services needed
• All CRUD operations go through existing FiscalService, BrandService, TaxonomyCategoryService, TaxonomyTagService

NFR-2: Permissions

NFR-3: Events

• Publish domain events through existing core library event classes (TaxClassCreatedEvent, BrandUpdatedEvent, CategoryMovedEvent, etc.)
• No new event classes needed — the core services already publish events

NFR-4: Mock Integration

• No new mock APIs needed — fiscal, brand-registry, and taxonomy mock APIs are already registered in MOCK_DEFINITIONS

NFR-5: Reuse

• Maximize use of existing components:
  • GgsCategoryTreeComponent for category navigation
  • GgsCategorySelectorComponent for parent category selection in form
  • GgsEntityMediaSectionComponent for brand logos and category images
  • GgsTagCloudComponent could be used for visual tag overview on list page
• Use useCrudList and useCrudForm composables from module-base where applicable

User Stories

Tax Classes

• US-1.1: As an admin, I can view all tax classes in a table to understand the tax configuration.
• US-1.2: As an admin, I can create a new tax class with name, code, and rate.
• US-1.3: As an admin, I can edit an existing tax class.
• US-1.4: As an admin, I can delete a tax class (with confirmation).
• US-1.5: As an admin, I can mark a tax class as default.

Brands

• US-2.1: As an admin, I can view all brands in a searchable table.
• US-2.2: As an admin, I can create a new brand with name, description, and website.
• US-2.3: As an admin, I can edit a brand and upload/change its logo.
• US-2.4: As an admin, I can delete a brand (with confirmation).

Categories

• US-3.1: As an admin, I can view the category tree for a specific scope.
• US-3.2: As an admin, I can switch between scopes (product, document, etc.) to view different trees.
• US-3.3: As an admin, I can create a new root category or child category.
• US-3.4: As an admin, I can edit a category's properties (name, description, image).
• US-3.5: As an admin, I can move a category to a different parent.
• US-3.6: As an admin, I can view category details including its children and ancestors.
• US-3.7: As an admin, I can delete a category (with confirmation and warning about children).

Tags

• US-4.1: As an admin, I can view all tags filterable by scope.
• US-4.2: As an admin, I can create a new tag with name, scope, and color.
• US-4.3: As an admin, I can edit a tag's properties.
• US-4.4: As an admin, I can delete a tag (with confirmation).

Open Questions

1. Scopes: Should the category scope list be dynamic (discovered from data) or hardcoded (product, document)?
2. Category move: Should moving a category be drag-and-drop in the tree or a "Move to..." action with a selector?
3. Brand logo: Since brands use logoId (string reference), should the logo upload work like product media (entity media section)?
4. Tag color: Simple hex input or a predefined palette picker?

Dependencies

Consumes (already exist):

• @libs-core/fiscal — FiscalService, FiscalApiService, TaxClass model, events
• @libs-core/brand-registry — BrandService, BrandApiService, Brand model, events, GgsBrandCardComponent
• @libs-core/taxonomy — TaxonomyCategoryService, TaxonomyTagService, Category/Tag models, events, GgsCategoryTreeComponent, GgsCategorySelectorComponent, GgsTagInputComponent, GgsTagCloudComponent
• @libs-core/media — GgsEntityMediaSectionComponent (for brand logos, category images)
• @libs-core/module-base — @ModuleDecorator, BrowserModuleContract, useCrudList, useCrudForm
• @libs-core/ui-framework — UI components (tables, dialogs, forms, buttons)
• @libs-core/security — permission guards