vitepress-template

Appearance

Menu and Navigation Management ​

**Referenced Files in This Document** - [[menu.proto]](file/bi-sys/api/sys/v1/menu.proto) - [[menu.go]](file/bi-sys/internal/biz/menu.go) - [[menu.go]](file/bi-sys/internal/data/menu.go) - [[menu.go]](file/bi-sys/internal/service/menu.go) - [[role.proto]](file/bi-sys/api/sys/v1/role.proto) - [[role.go]](file/bi-sys/internal/biz/role.go) - [[role.go]](file/bi-sys/internal/data/role.go) - [[role.go]](file/bi-sys/internal/service/role.go) - [[schema.sql]](file/bi-sys/docs/database/schema.sql)

Table of Contents ​

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Troubleshooting Guide
  9. Conclusion

Introduction ​

This document describes the menu and navigation management system within the bi-sys module. It covers menu structure definition, hierarchical organization, and navigation tree construction. It also documents menu item properties (URLs, icons, permissions, visibility), CRUD operations, role-based menu assignment, and dynamic menu generation for current users. Finally, it outlines integration points with frontend navigation components and breadcrumb generation.

Project Structure ​

The menu and navigation system is implemented as a gRPC/HTTP service with a layered architecture:

  • API layer: Protocol Buffers define the service contract and messages.
  • Service layer: Implements HTTP/gRPC handlers that translate requests to use cases.
  • Business logic layer: Encapsulates domain logic and orchestrates repositories.
  • Data layer: Persists and retrieves data from StarRocks via ORM and query builders.

Diagram sources

Section sources

Core Components ​

  • MenuService: Provides endpoints for listing, retrieving, creating, updating, deleting menus, building trees, fetching role-specific trees, and retrieving current user menus.
  • RoleService: Manages roles and assigns menus to roles, enabling role-based menu visibility.
  • MenuUsecase: Orchestrates menu operations (CRUD, tree building, role queries).
  • RoleUsecase: Manages role operations and menu assignments.
  • MenuRepo and RoleRepo: Data access layer implementing persistence and queries against StarRocks.

Key capabilities:

  • Hierarchical menu storage with parent-child relationships.
  • Menu types: directory, page route, and button.
  • Permission identifiers per menu for fine-grained access control.
  • Role-based menu visibility via sys_role_menu association.
  • Dynamic menu generation for current user based on role membership.

Section sources

Architecture Overview ​

The system follows a clean architecture pattern with clear separation of concerns:

  • API layer defines contracts and HTTP/gRPC mappings.
  • Service layer handles transport-specific logic and delegates to use cases.
  • Business logic layer encapsulates domain rules and orchestration.
  • Data layer abstracts persistence and query composition.

Diagram sources

Detailed Component Analysis ​

  • Table: sys_menu
  • Primary key: menu_id
  • Parent relationship: parent_id references another menu_id (self-reference)
  • Types: menu_type supports directory, page route, and button
  • Routing: path and component fields for frontend route mapping
  • Permissions: perms field for permission-based visibility
  • Visibility and state: visible and status flags
  • Behavior flags: cache and external for SPA caching and external links
  • Ordering: sort column for presentation order

Diagram sources

Section sources

  • CreateMenu: Validates and persists a new menu with generated ID, default flags, and timestamps.
  • UpdateMenu: Updates all menu attributes atomically.
  • DeleteMenu: Prevents deletion if child menus exist; otherwise deletes the record.
  • GetMenu: Retrieves a single menu by ID.
  • ListMenu: Filters by name and status, ordered by sort and menu_id.

Diagram sources

Section sources

  • GetMenuTree: Returns a flattened tree node list suitable for frontend tree controls.
  • GetRoleMenuTree: Returns the full menu tree and marks checked keys for a given role.
  • GetCurrentUserMenus: Returns a route tree for the current user (requires RBAC middleware and user context).

Diagram sources

Section sources

Role-Based Menu Assignment and Visibility ​

  • AssignRoleMenus: Replaces a role’s menu permissions with the provided set.
  • GetMenuIDs: Retrieves a role’s assigned menu IDs.
  • GetPermissions: Aggregates permission identifiers from a role’s menus for authorization checks.

Diagram sources

Section sources

Current User Menu Generation ​

  • GetCurrentUserMenus: Returns a route tree for the currently authenticated user. This requires:
    • RBAC middleware to populate user identity.
    • Role-based retrieval of enabled menus (status = 1).
    • Tree construction from flat menu records.

Diagram sources

Section sources

  • MenuInfo and MenuTreeNode include:
    • Identity: id, parent_id
    • Presentation: menu_name, icon
    • Routing: path, component
    • Permissions: perms
    • Behavior: visible, status, cache, external
    • Ordering: sort
    • Metadata: remark, created_at, updated_at
  • Validation constraints ensure safe defaults and limits (e.g., menu_type in [1,2,3], status in [0,1], length limits).

Section sources

API Endpoints Summary ​

  • ListMenu: GET /api/v1/sys/menus
  • GetMenuTree: GET /api/v1/sys/menus/tree
  • GetMenu: GET /api/v1/sys/menus/
  • CreateMenu: POST /api/v1/sys/menus
  • UpdateMenu: PUT /api/v1/sys/menus/
  • DeleteMenu: DELETE /api/v1/sys/menus/
  • GetRoleMenuTree: GET /api/v1/sys/menus/role-tree/
  • GetCurrentUserMenus: GET /api/v1/sys/menus/current
  • GetMenuOptions: GET /api/v1/sys/menus/options

Section sources

Dependency Analysis ​

  • MenuService depends on MenuUsecase for business logic.
  • MenuUsecase depends on MenuRepo for persistence.
  • RoleService depends on RoleUsecase for role operations.
  • RoleUsecase depends on RoleRepo for role and menu assignment persistence.
  • MenuRepo and RoleRepo depend on StarRocks via ORM and query builder utilities.

Diagram sources

Section sources

Performance Considerations ​

  • Indexes: sys_menu includes indexes on parent_id, status, and menu_type to optimize tree queries and filtering.
  • Pagination: Role listing uses pagination to limit payload sizes.
  • Sorting: Queries order by sort and menu_id to maintain consistent presentation order.
  • Caching: cache flag in menu indicates SPA-level caching behavior; consider integrating with frontend route-level caching strategies.

Recommendations:

  • Add composite indexes for frequent filter combinations (e.g., status + menu_type).
  • Consider materialized hierarchies or adjacency lists for deep trees if traversal becomes expensive.
  • Cache frequently accessed role-menu sets at the application level to reduce database load.

Section sources

Troubleshooting Guide ​

Common issues and resolutions:

  • Deleting a menu with children: The system prevents deletion if child records exist. Remove or reassign children first.
  • Role menu assignment: AssignRoleMenus replaces existing permissions; ensure the provided menu set is complete.
  • Permission visibility: perms must be populated on menus for role-based permission checks; verify role-to-menu associations in sys_role_menu.
  • Tree construction: Ensure status = 1 for visible menus; sorting by sort ensures consistent ordering.

Operational tips:

  • Use ListMenu with status filters to debug visibility issues.
  • Verify sys_role_menu entries for a role to confirm assigned menus.
  • Confirm indexes exist and are effective for large datasets.

Section sources

Conclusion ​

The menu and navigation management system provides a robust, role-aware menu framework with clear CRUD operations, hierarchical modeling, and dynamic menu generation for users. Its layered architecture enables scalability, maintainability, and straightforward integration with frontend navigation components. By leveraging role-based menu assignments and permission identifiers, it supports fine-grained access control and consistent user experiences across applications.