erp/docs/superpowers/specs/2026-04-10-erp-platform-base-design.md

ERP Platform Base - Design Specification

Date: 2026-04-10 Status: Draft (Review Round 2) Author: Claude + User

---

Context

Build a commercial SaaS ERP product from scratch using a "platform base + industry plugins" architecture. The base provides core infrastructure (auth, workflow, messaging, configuration), enabling rapid deployment of industry-specific modules (inventory, manufacturing, finance, HR, etc.) on top.

The system targets progressive scaling: start with small businesses, expand to mid and large enterprises. Multi-tenant SaaS deployment is the default, with private deployment as an option.

---

Architecture

Overall: Modular Monolith (Progressive)

Start as a single Rust backend service with well-defined module boundaries. Modules communicate through an internal event bus and shared traits. When a module needs independent scaling, it can be extracted into a standalone service without changing interfaces.

System Layers

Web Frontend (Vite + React 18 + Ant Design 5)
  ├── Shell / Layout / Navigation
  └── Module UI (dynamically loaded per tenant config)
        │
API Layer (REST + WebSocket)
        │
Rust Backend Service (Axum + Tokio)
  ├── Auth Module      (identity, roles, permissions, tenants)
  ├── Workflow Engine   (BPMN processes, tasks, approvals)
  ├── Message Center    (notifications, templates, channels)
  └── Config Module     (menus, dictionaries, settings, numbering)
        │
Core Shared Layer (tenant context, audit, events, caching)
        │
PostgreSQL (primary)  +  Redis (cache + session + pub/sub)

Note: Tauri 桌面端为可选方案，未来行业模块（如工厂仓库）需要硬件集成时启用。主力前端为 Web SPA。

Design Principles

1. Module isolation: Each business module is an independent Rust crate, interfaces defined via traits
2. Multi-tenant built-in: All data tables include tenant_id, middleware auto-injects tenant context
3. Event-driven: Modules communicate via event bus, no direct coupling
4. Plugin extensibility: Industry modules register through standard interfaces, support dynamic enable/disable

Error Handling Strategy

// erp-core defines the unified error hierarchy
// Uses thiserror for typed errors across crate boundaries

#[derive(Debug, thiserror::Error)]
pub enum AppError {
    #[error("Not found: {0}")]
    NotFound(String),

    #[error("Validation error: {0}")]
    Validation(String),

    #[error("Unauthorized")]
    Unauthorized,

    #[error("Forbidden: {0}")]
    Forbidden(String),

    #[error("Conflict: {0}")]
    Conflict(String),

    #[error("Internal error: {0}")]
    Internal(String),
}

// Axum IntoResponse impl maps to HTTP status codes
// Validation errors include field-level detail for UI rendering

Decision: thiserror for crate boundaries (typed, catchable), anyhow never crosses crate boundaries (internal use only for prototyping). Each module defines its own error variants that wrap AppError.

Event Bus Specification

EventBus (tokio::sync::broadcast based, in-process)

Event {
  id: UUID v7
  event_type: String (e.g., "user.created", "workflow.task.completed")
  tenant_id: UUID
  payload: serde_json::Value
  timestamp: DateTime<Utc>
  correlation_id: UUID (for tracing)
}

Delivery Guarantees:
- At-least-once delivery within the process
- Events persisted to `domain_events` table before dispatch (outbox pattern)
- Failed handlers log to dead-letter storage, trigger alert
- No cross-process delivery in Phase 1 (single binary)

Plugin / Module Registration Interface

// erp-core defines the plugin trait
pub trait ErpModule: Send + Sync {
    fn name(&self) -> &str;
    fn version(&self) -> &str;
    fn dependencies(&self) -> Vec<&str>;  // required modules

    fn register_routes(&self, router: Router) -> Router;
    fn register_event_handlers(&self, bus: &EventBus);
    fn on_tenant_created(&self, tenant_id: Uuid) -> Result<()>;
    fn on_tenant_deleted(&self, tenant_id: Uuid) -> Result<()>;
}

// erp-server assembles modules at startup
fn build_app(modules: Vec<Box<dyn ErpModule>>) -> Router { ... }

Industry modules implement ErpModule and are discovered via configuration, not compile-time.

API Versioning & Contract Governance

• Code-first with utoipa: derive OpenAPI from Rust types
• Auto-generated Swagger UI at /docs in development
• /api/v1/ prefix for all endpoints; v2 only when breaking changes needed
• Client sends X-API-Version: 1 header; server rejects unsupported versions
• Tauri client version and server version must be compatible (checked on connect)

Concurrency & Transaction Strategy

• Optimistic locking: All mutable entities carry version column; updates fail on mismatch
• Idempotency: Write endpoints accept optional Idempotency-Key header
• Cross-module transactions: Avoided by design; event bus + saga pattern for consistency
• Numbering sequences: PostgreSQL sequences with advisory_lock per tenant per rule

Audit Logging

AuditLog {
  id: UUID v7
  tenant_id: UUID
  user_id: UUID
  action: String (e.g., "user.update", "role.create")
  resource_type: String
  resource_id: UUID
  changes: JSONB { before: {}, after: {} }
  ip_address: String
  user_agent: String
  timestamp: DateTime<Utc>
}

Retention: 90 days hot, archive to cold storage after
Query API: GET /api/v1/audit-logs?resource_type=user&from=...

Frontend-Backend Communication

Aspect	Decision
Auth flow	Login via REST → JWT stored in httpOnly cookie (web) → sent as Bearer header
REST calls	Standard fetch/axios from browser to backend
WebSocket	Connect on page load, auth via first message with JWT, auto-reconnect with exponential backoff
File upload/download	Standard HTTP multipart + blob download
CORS	Whitelist per tenant, deny by default

Security Measures

• CORS: Whitelist per tenant, deny by default
• Rate limiting: Per-IP + per-user via Redis token bucket
• Secret management: Environment variables + vault (HashiCorp Vault for production)
• Data encryption: TLS in transit, AES-256 at rest for PII fields (optional per tenant config)
• Input validation: Schema-based (JSON Schema for complex inputs, types for simple)
• SQL injection: Prevented by SeaORM parameterized queries

---

Tech Stack

Backend (Rust)

Component	Choice	Rationale
Web framework	Axum 0.8	Tokio-team maintained, best ecosystem
Async runtime	Tokio	Rust async standard
ORM	SeaORM	Async, type-safe, migration support
DB migration	SeaORM Migration	Versioned schema management
Cache	redis-rs	Official Redis client
JWT	jsonwebtoken	Lightweight, reliable
Serialization	serde + serde_json	Rust standard
Logging	tracing + tracing-subscriber	Structured logging
Config	config-rs	Multi-format support
API docs	utoipa (OpenAPI 3)	Auto-generate Swagger
Testing	Built-in + tokio-test	Unit + integration

Web Frontend

Layer	Technology
Build tool	Vite 6
UI framework	React 18 + TypeScript
Component library	Ant Design 5
State management	Zustand
Routing	React Router 7
Styling	TailwindCSS + CSS Variables

Infrastructure

Component	Technology
Primary database	PostgreSQL 16+
Cache / Session / PubSub	Redis 7+
Containerization	Docker + Docker Compose (dev)

---

Crate Structure

erp/
├── crates/
│   ├── erp-core/          # Shared: error handling, types, traits, events
│   ├── erp-auth/          # Identity & permissions module
│   ├── erp-workflow/      # Workflow engine module
│   ├── erp-message/       # Message center module
│   ├── erp-config/        # System configuration module
│   ├── erp-server/        # Axum server entry, assembles all modules
│   └── erp-common/        # Shared utilities, macros
├── apps/
│   └── web/               # Vite + React SPA (primary frontend)
├── desktop/               # (Optional) Tauri desktop, enabled per industry need
├── packages/
│   └── ui-components/     # React shared component library
├── migrations/            # Database migrations
├── docs/                  # Documentation
└── docker/                # Docker configurations

---

Module 1: Identity & Permissions (Auth)

Data Model

Tenant
 ├── Organization
 │    └── Department
 │         └── Position
 ├── User
 │    ├── UserCredential (password / OAuth / SSO)
 │    ├── UserProfile
 │    └── UserToken (session)
 ├── Role
 │    └── Permission
 └── Policy (ABAC rules)

Permission Model: RBAC + ABAC Hybrid

• RBAC: User -> Role -> Permission, for standard scenarios
• ABAC: Attribute-based rules (e.g., "department manager can only approve own department's requests")
• Data-level: Row filtering (e.g., "only see own department's data")

Authentication Methods

Method	Description
Username/Password	Basic auth, Argon2 hash
OAuth 2.0	Third-party login (WeChat, DingTalk, WeCom)
SSO (SAML/OIDC)	Enterprise SSO, required for private deployment
TOTP	Two-factor authentication

Key APIs

POST   /api/v1/auth/login
POST   /api/v1/auth/logout
POST   /api/v1/auth/refresh
POST   /api/v1/auth/revoke                    # Revoke a specific token
GET    /api/v1/users
POST   /api/v1/users
PUT    /api/v1/users/:id
DELETE /api/v1/users/:id (soft delete)
GET    /api/v1/roles
POST   /api/v1/roles
PUT    /api/v1/roles/:id
DELETE /api/v1/roles/:id
POST   /api/v1/roles/:id/permissions
GET    /api/v1/permissions                     # List all available permissions
GET    /api/v1/tenants/:id/users
GET    /api/v1/organizations
POST   /api/v1/organizations
PUT    /api/v1/organizations/:id
DELETE /api/v1/organizations/:id
GET    /api/v1/organizations/:id/departments
POST   /api/v1/organizations/:id/departments
GET    /api/v1/positions
POST   /api/v1/positions
GET    /api/v1/policies
POST   /api/v1/policies
PUT    /api/v1/policies/:id
DELETE /api/v1/policies/:id

Multi-tenant Isolation

• Default: Shared database + tenant_id column isolation (cost-optimal)
• Switchable: Independent schema per tenant (for private deployment)
• Middleware auto-injects tenant_id, application code is tenant-agnostic

Multi-tenant Migration Strategy

• Schema migrations run once globally, affect all tenants' rows
• New tenant provisioning: seed data script (default roles, admin user, org structure, menus)
• Migrations are versioned and idempotent; failed migrations halt startup
• Per-tenant data migrations (e.g., adding default config) trigger on on_tenant_created hook

---

Module 2: Workflow Engine

Design Goals

• BPMN 2.0 subset compatible visual process designer
• Low latency, high throughput (Rust advantage)
• Support conditional branches, parallel gateways, sub-processes
• Embeddable into any business module

BPMN Subset Scope (Phase 4)

Included in Phase 4:

• Start/End events
• User Tasks (with assignee, candidate groups)
• Service Tasks (HTTP call, script execution)
• Exclusive Gateways (conditional branching)
• Parallel Gateways (fork/join)
• Sequence Flows with conditions
• Process variables (basic types: string, number, boolean, date)

Deferred to later phases:

• Inclusive Gateways
• Sub-Processes (call activity)
• Timer events (intermediate, boundary)
• Signal/Message events
• Error boundary events
• Multi-instance (loop) activities
• Data objects and stores

Core Concepts

ProcessDefinition
 ├── Node Types
 │    ├── StartNode
 │    ├── EndNode
 │    ├── UserTask (human task)
 │    ├── ServiceTask (system task)
 │    ├── Gateway (exclusive / parallel / inclusive)
 │    └── SubProcess
 ├── Flow (connections)
 │    └── Condition (expressions)
 └── ProcessInstance
      ├── Token (tracks execution position)
      ├── Task (pending tasks)
      └── Variable (process variables)

Key Features

Feature	Description
Visual designer	React flowchart editor, drag-and-drop
Condition expressions	EL expressions: amount > 10000 && dept == "finance"
Countersign / Or-sign	Multi-person approval: all approve / any approve
Delegate / Transfer	Tasks can be delegated to others
Reminder / Timeout	Auto-remind, auto-handle on timeout
Version management	Process definitions versioned, running instances use old version

Key APIs

POST   /api/v1/workflow/definitions
GET    /api/v1/workflow/definitions/:id
PUT    /api/v1/workflow/definitions/:id
POST   /api/v1/workflow/instances
GET    /api/v1/workflow/instances/:id
GET    /api/v1/workflow/tasks (my pending)
POST   /api/v1/workflow/tasks/:id/approve
POST   /api/v1/workflow/tasks/:id/reject
POST   /api/v1/workflow/tasks/:id/delegate
GET    /api/v1/workflow/instances/:id/diagram (highlighted)

Integration Points

• Auth: Task assignment based on roles/org structure
• Message: Pending task notifications, reminders, approval results
• Config: Process categories, numbering rules

---

Module 3: Message Center

Message Channels

Channel	Use Case
In-app notifications	Foundation for all messages
WebSocket	Real-time push, instant desktop alerts
Email	Important approvals, scheduled reports
SMS	Verification codes, urgent alerts
WeCom / DingTalk	Enterprise messaging integration

Data Model

MessageTemplate
 ├── Channel type
 ├── Template content (variable interpolation: {{user_name}})
 └── Multi-language versions

Message
 ├── Sender (system / user)
 ├── Recipient (user / role / department / all)
 ├── Priority (normal / important / urgent)
 ├── Read status
 └── Business reference (deep link to specific page)

MessageSubscription
 ├── User notification preferences
 ├── Do-not-disturb periods
 └── Channel preferences (e.g., approvals via in-app + WeCom, reports via email)

Key Features

• Message aggregation: Group similar messages (e.g., "You have 5 pending approvals")
• Read/unread: Read receipts, unread count query
• Message recall: Sender can recall unread messages
• Scheduled sending: Set delivery time
• Message archive: Auto-archive history, searchable

Key APIs

GET    /api/v1/messages (list with pagination)
GET    /api/v1/messages/unread-count
PUT    /api/v1/messages/:id/read
PUT    /api/v1/messages/read-all
DELETE /api/v1/messages/:id
POST   /api/v1/messages/send
GET    /api/v1/message-templates
POST   /api/v1/message-templates
PUT    /api/v1/message-subscriptions (update preferences)
WS     /ws/v1/messages (real-time push)

---

Module 4: System Configuration

Configuration Hierarchy

Platform (global)
 └── Tenant
      └── Organization
           └── User

Lower-level overrides higher-level. Priority: User > Organization > Tenant > Platform.

Capabilities

Capability	Description
Dynamic menus	Tenants customize menu structure, display by role
Data dictionaries	System-level and tenant-level enum management
Numbering rules	Document number generation with concurrency-safe sequences
Multi-language	i18n resource management, runtime switching
System parameters	Key-value general configuration
Theme customization	Tenant-level UI theme (colors, logo)

Key APIs

GET    /api/v1/config/menus                    # Tenant from middleware
PUT    /api/v1/config/menus
GET    /api/v1/config/dictionaries
POST   /api/v1/config/dictionaries
PUT    /api/v1/config/dictionaries/:id
GET    /api/v1/config/settings/:key
PUT    /api/v1/config/settings/:key
GET    /api/v1/config/numbering-rules
POST   /api/v1/config/numbering-rules
PUT    /api/v1/config/numbering-rules/:id
GET    /api/v1/config/languages
PUT    /api/v1/config/languages/:code
GET    /api/v1/config/themes                   # Tenant theme
PUT    /api/v1/config/themes

---

Database Design Principles

• All tables include: tenant_id, created_at, updated_at, created_by, updated_by
• Soft delete via deleted_at (no hard deletes)
• UUID v7 as primary keys (time-sortable + unique)
• JSONB columns for flexible extension data
• Indexes on tenant_id + business keys for multi-tenant queries

---

Web UI Design

Layout

Classic SaaS admin panel layout (responsive, mobile-friendly):

+----------------------------------------------+
|  LOGO   Search...       🔔 5  👤 Admin  ▾   |  ← Top nav bar
+--------+-------------------------------------+
| Home   |                                     |
| Users  |      Main Content Area              |
| Roles  |      (Dynamic per menu selection)   |
| Flows  |      Multi-tab support              |
| Messages|                                    |
| Settings|                                    |
|--------|                                     |
| Inv.   |                                     |
| Mfg.   |                                     |
| Finance|                                     |
|--------|                                     |
| More > |                                     |
+--------+-------------------------------------+

Key UI Features

• Collapsible sidebar: Multi-level menus, grouped (base modules / industry modules)
• Multi-tab content: Switch between open pages like browser tabs
• Global search: Search menus, users, documents
• Notification panel: Click bell icon to expand message list
• Dark/Light theme: Toggle support, follow system preference
• Responsive: Mobile/tablet adaptive layout
• Browser notifications: Web Notification API for real-time alerts

---

Development Roadmap

Phase 1 - Foundation (2-3 weeks)

• Rust workspace scaffolding + Vite + React setup
• erp-core: error types, shared types, trait definitions, event bus
• ErpModule trait + module registration system
• Database migration framework (SeaORM) with tenant provisioning
• Docker dev environment (PostgreSQL + Redis)
• CI/CD pipeline setup

Phase 2 - Identity & Permissions (2-3 weeks)

• User, Role, Organization, Department, Position CRUD
• RBAC + ABAC permission model
• JWT auth (access + refresh tokens, token revocation)
• httpOnly cookie for web JWT storage
• Multi-tenant middleware
• Login page UI + user management pages

Phase 3 - System Configuration (1-2 weeks)

• Data dictionaries
• Dynamic menus
• System parameters (hierarchical override)
• Numbering rules (concurrency-safe PostgreSQL sequences)
• i18n framework
• Settings pages UI

Phase 4 - Workflow Engine (4-6 weeks)

• Process definition storage and versioning
• BPMN subset parser (start/end, user/service tasks, exclusive/parallel gateways)
• Execution engine with token tracking
• Task assignment, countersign, delegation
• Condition expression evaluator
• React visual flowchart designer
• Process diagram viewer (highlighted current node)
• Reminder and timeout handling

Phase 5 - Message Center (2 weeks)

• Message templates with variable interpolation
• In-app notification CRUD
• WebSocket real-time push (auth, reconnect)
• Notification panel UI
• Message aggregation and read tracking

Phase 6 - Integration & Polish (2-3 weeks)

• Cross-module integration testing
• Audit logging verification
• Web app deployment and optimization
• Performance optimization
• Documentation

---

Verification Plan

1. Unit tests: Each module has comprehensive unit tests (80%+ coverage target)
2. Integration tests: API endpoint tests against real PostgreSQL/Redis
3. E2E tests: Desktop client test automation via Tauri WebDriver
4. Multi-tenant tests: Verify data isolation between tenants
5. Workflow tests: Full process lifecycle (define -> start -> approve -> complete)
6. Performance benchmarks: API response time < 100ms (p99), WebSocket push < 50ms
7. Security audit: OWASP top 10 check before release