Shadmin Dev

Step 5: Wire Permissions

Shadmin uses a dual-layer permission model:

Backend (API access):    Casbin checks (userID, path, method)
Frontend (UI visibility): Permission strings like "system:project:add"

These are linked through the Role → Menu → API Resources binding:

1. Backend auto-scans routes into API resources on startup (bootstrap.InitApiResources)
2. API resource IDs are deterministic: METHOD:/api/v1/path (e.g., GET:/api/v1/system/project)
3. Admin assigns menus to roles, each menu binds to API resources
4. Frontend fetches permissions from /api/v1/resources and stores in Zustand

To add permissions for a new feature:

1. Backend: routes are scanned into API resources by bootstrap.InitApiResources; route inventory changes advance the authorization generation.
2. Frontend: add permission constants in frontend/src/constants/permissions.ts.
3. Admin panel: create menu entries, bind API resources, assign to roles.
4. For any new write path that changes users, roles, menus, API resources, or their authorization edges, use the repository authorization transaction helper so the DB change and authz_state.generation update commit together. Do not mutate the live Casbin Enforcer directly.

Casbin snapshot lifecycle: Ent authorization relations are the source of truth. Each process builds a complete in-memory Enforcer snapshot and publishes it atomically; a committed authz_states.generation update triggers local synchronization, while AUTHZ_SYNC_POLL_INTERVAL_SECONDS provides low-frequency recovery polling (default one hour) for missed triggers, restarts, and cross-instance changes. Snapshots are not persisted through Casbin AutoSave. If a generation change is detected or cannot be checked, protected Casbin requests fail closed until a fresh snapshot is published. Keep the existing g/p semantics (active users/roles, public resources excluded, admin wildcard) unless a separately reviewed change intentionally changes them.

Step 6: Generate & Verify

# Backend
go generate ./ent           # If schema changed
go fmt ./... && go vet ./... # Format + static analysis
go test ./...                # Run tests
swag init -g main.go --output ./docs  # If Swagger annotations changed

# Frontend (from frontend/)
pnpm lint                   # ESLint
pnpm format:check           # Prettier
pnpm build                  # Recommended if routes/build config changed

Key Response Format

// Success (HTTP 200/201)
type Response struct {
    Code int         `json:"code"`    // 0 = success
    Msg  string      `json:"msg"`     // "OK"
    Data interface{} `json:"data"`    // payload
}

// Error (HTTP 400/404/500)
// Code = 1, Msg = error description, Data = nil

// Paginated response (in Data field)
type PagedResult[T any] struct {
    List       []T `json:"list"`
    Total      int `json:"total"`
    Page       int `json:"page"`
    PageSize   int `json:"page_size"`
    TotalPages int `json:"total_pages"`
}

Boundaries

Things to never do:

• No business logic in controllers — controllers parse HTTP, call usecase, return response
• No HTTP/permission logic in repositories — repositories do data access only
• No bypassing Casbin on protected APIs
• No new globals — use factory's f.db, f.app, f.timeout
• No inline API calls in React — all API access goes through services/ wrappers
• No direct localStorage for auth — use useAuthStore
• No editing components/ui/ — shadcn-generated primitives
• No hardcoded menus — menus come from backend /api/v1/resources
• No unnecessary dependencies — frontend or backend
• Minimal changes — only touch files relevant to the feature

Reference Files

For detailed code templates and implementation patterns, read these as needed:

• references/backend.md — Complete Go/Gin/Ent code templates for domain, schema, repository, usecase, controller, routes, and factory. Read when implementing backend features.
• references/frontend.md — Complete React/TypeScript code templates for types, API services, feature modules, hooks, tables, forms, dialogs, routes, and permissions. Read when implementing frontend features.

Further Documentation

The docs/getting-started/ directory contains comprehensive guides:

• quickstart.zh.md / quickstart.en.md — Quick start guide
• architecture.zh.md / architecture.en.md — Architecture deep-dive
• development.zh.md / development.en.md — Full CRUD walkthrough with example
• deployment.zh.md / deployment.en.md — Production deployment guide