Tenant Administration
Table of Contents
- Introduction
- Project Structure
- Core Components
- Architecture Overview
- Detailed Component Analysis
- Dependency Analysis
- Performance Considerations
- Troubleshooting Guide
- Conclusion
- Appendices
Introduction
This document describes the Tenant Administration functionality in the Admin Panel. It covers the multi-tenant management interface, including tenant creation, configuration, lifecycle management, subscription management, and resource allocation. It also documents the tenant hierarchy, onboarding workflows, billing integration, usage monitoring, settings management, custom branding, service configuration controls, isolation mechanisms, data partitioning, security boundaries, analytics and reporting, and capacity planning. Examples of provisioning, subscription upgrades/downgrades, and deactivation are included.
Project Structure
The Tenant Administration feature spans the bi-tenant service (backend), Protobuf API definitions, and the Admin Web UI client.
Diagram sources
- [Tenant API proto]
- [Tenant HTTP handlers]
- [Tenant usecase]
- [Tenant repository]
- [Admin UI tenant API client]
- [bi-tenant architecture]
- [Database schema]
Section sources
Core Components
- Tenant management: creation, updates, status toggling, deletion, batch deletion, statistics.
- Subscription management: package assignment, status transitions, pricing/time tracking.
- Organization management: hierarchical departments and employees.
- User management: employee accounts, roles, delegates, stores, password reset.
- Analytics and reporting: tenant stats aggregation.
- Security and isolation: tenant-scoped queries, RBAC, and dynamic table management triggers.
Section sources
Architecture Overview
The bi-tenant service enforces tenant isolation via explicit tenant ID filtering and supports dynamic table creation for shops. The Admin Panel interacts with the TenantService via HTTP endpoints generated from Protobuf definitions.
Diagram sources
Section sources
Detailed Component Analysis
Tenant Management
- Creation: Generates tenant code, creates tenant record, optionally attaches a subscription, creates default organization, and creates the default admin user.
- Updates: Modifies tenant metadata and branding.
- Status: Enables/disables tenants.
- Deletion: Soft deletes tenants; batch deletion supported.
- Password reset: Resets tenant admin password.
- Statistics: Aggregates tenant counts by status and package.
Diagram sources
Section sources
Subscription Management
- Package assignment: Sets or changes a tenant’s active package; marks previous subscription as inactive and creates a new subscription record.
- Package lifecycle: Create/update/delete/list/options/status; menu permissions per package.
- Pricing/time: Price stored on subscription; start/end time tracked; expiration derived from current active subscription.
Diagram sources
Section sources
Organization and Employee Management
- Hierarchical organization: Parent-child relationships with ancestor lists; supports department/team/company types.
- Employee lifecycle: Create/update/delete/list; supports status and role assignments.
- Delegation and store scoping: Users can be granted access to specific stores or act as delegates for other users.
Diagram sources
Section sources
User and Access Control
- User lifecycle: Create/update/delete/batch delete; protected default/admin accounts; password hashing.
- Roles and permissions: Assign roles to users; integrate with menu permissions via packages.
- Delegation and store scoping: Grant access to specific stores or delegate access to another user.
Diagram sources
Section sources
Tenant Settings, Branding, and Configuration
- Branding: Logo URL stored per tenant.
- Configuration: Contact info, remarks, and tenant code generation.
- Menu permissions: Packages define menu sets; roles inherit menus via package-menu relations.
Section sources
Tenant Analytics and Reporting
- Tenant statistics: Total, active, disabled, expired tenants; active packages; total accounts.
- Logs: Login and operation logs support dynamic partitioning for time-series analytics.
Diagram sources
Section sources
Tenant Isolation, Data Partitioning, and Security Boundaries
- Isolation: All queries filter by tenant ID; repositories enforce tenant scoping.
- Dynamic tables: On shop addition, dynamic tables are created (e.g., order goods tables) to isolate data per tenant and shop.
- RBAC: Roles and menus define granular permissions; delegation and store scoping further refine access.
Diagram sources
Section sources
Dependency Analysis
The Admin UI calls HTTP endpoints backed by the TenantService. The service orchestrates usecases that interact with repositories and the database.
Diagram sources
- [Admin UI tenant API client]
- [Tenant API proto]
- [Tenant HTTP handlers]
- [Tenant usecase]
- [Tenant repository]
- [Database schema]
Section sources
Performance Considerations
- Indexing: Bitmap indexes on status and deleted_at fields improve filtering performance.
- Distribution: Tables are distributed by primary keys; consider distribution keys aligned with tenant filters.
- Partitioning: Login and operation logs use dynamic monthly partitions to manage time-series growth.
- Queries: Prefer tenant-scoped queries and avoid scanning entire tables; leverage paginated lists and indexed filters.
[No sources needed since this section provides general guidance]
Troubleshooting Guide
Common issues and resolutions:
- Tenant code conflicts: Ensure uniqueness; the system validates and generates new codes when collisions occur.
- Subscription transitions: Previous subscriptions are marked inactive before creating new ones; verify package existence and pricing.
- Deletion protections: Default and admin accounts cannot be deleted; check account flags before attempting removal.
- Password resets: Both tenant admin and user passwords can be reset; ensure the target account exists and is not protected.
Section sources
Conclusion
The Tenant Administration feature provides a robust, tenant-isolated platform for managing tenants, subscriptions, organizations, users, and permissions. It integrates with the Admin Panel via HTTP endpoints and supports analytics, dynamic table creation, and strong security boundaries enforced by tenant scoping and RBAC.
[No sources needed since this section summarizes without analyzing specific files]
Appendices
API Reference: Tenant Management Endpoints
- List tenants: GET /api/v1/tenant-m/tenants
- Get tenant: GET /api/v1/tenant-m/tenants/
- Create tenant: POST /api/v1/tenant-m/tenants
- Update tenant: PUT /api/v1/tenant-m/tenants/
- Update tenant status: PUT /api/v1/tenant-m/tenants/{id}/status
- Set tenant package: PUT /api/v1/tenant-m/tenants/{id}/package
- Delete tenant: DELETE /api/v1/tenant-m/tenants/
- Reset tenant admin password: POST /api/v1/tenant-m/tenants/{id}/reset-password
- Batch delete tenants: POST /api/v1/tenant-m/tenants/batch-delete
- List tenant options: GET /api/v1/tenant-m/tenants/options
- Get tenant stats: GET /api/v1/tenant-m/stats
Section sources
Example Workflows
Tenant provisioning
- Steps: Create tenant (with optional package), create default organization, create default admin user, optionally set subscription.
- Endpoints: POST /api/v1/tenant-m/tenants, PUT /api/v1/tenant-m/tenants/{id}/package.
Subscription upgrade/downgrade
- Steps: PUT /api/v1/tenant-m/tenants/{id}/package with new package ID; system deactivates old subscription and activates new one.
Tenant deactivation/reactivation
- Steps: PUT /api/v1/tenant-m/tenants/{id}/status with status 0 or 1.
Admin password reset
- Steps: POST /api/v1/tenant-m/tenants/{id}/reset-password; receive new temporary password.
Section sources