uiframe — Next.js 后台模板

SHA-256: c99b48eb19f8affa233174e0566c6b288ec366871c6af85bc018e4ed09054f0d

2026-10-14T23:05:49.028Z

![The Blueprint Engine](public/assets/banner.png)

# The Blueprint Engine - UI Frame (Frontend)

Welcome to the **uiframe** of The Blueprint Engine! This frontend is built using Next.js 16 (App Router), React, and Shadcn UI. It is designed to connect seamlessly to the NestJS engine backend.

This README focuses strictly on setting up and configuring the frontend dashboard environment.

## 🚀 Getting Started

### Prerequisites
- [Bun](https://bun.sh/) (Recommended) or Node.js (v20+)
- The `engine` backend should be running on `http://localhost:5201` for the API calls to succeed.

### 1. Installation

Clone the repository and install the dependencies using Bun:

```bash
cd uiframe
bun install
```

### 2. Environment Configuration

Create a `.env.local` file in the root of the `uiframe` directory. The primary configuration needed is pointing the dashboard to the backend engine.

```env
# Point to your local NestJS Engine instance
NEXT_PUBLIC_API_BASE_URL=http://localhost:5201/api/v1
```

### 3. Running the Development Server

Start the development server. By default, we have configured it to run on port `5200` to avoid conflicts with the backend.

```bash
bun run dev
```

Open [http://localhost:5200](http://localhost:5200) in your browser. You should see the dashboard!

## 🏢 Multi-Tenancy Architecture

This frontend supports a multi-tenant architecture out-of-the-box, matching the backend engine's tenant capabilities.

- **Login Flow**: When users log in, they must provide an `accountId` (or `__root__` for platform admins).
- **Session Management**: Once authenticated, the JWT token provided by the backend contains the tenant scope. All subsequent API calls automatically inherit this scope.
- **Tenant Context**: The UI conditionally renders tenant-specific actions versus platform-wide actions depending on the user's role and account scope.

## 🛠️ Built-In Generators

We have created specialized CLI tools to speed up your frontend development.

### Dynamic Form Generator
Generate full Zod validation schemas and `react-hook-form` UI components instantly using JSON metadata.

1. Create a `schema.json`:
```json
{
  "entityName": "Product",
  "fields": [
    { "name": "title", "type": "string", "required": true, "ui": "input" },
    { "name": "price", "type": "number", "ui": "number-input" }
  ]
}
```
2. Run the generator:
```bash
bun run generate:form --schema=schema.json
```
This automatically outputs a wired-up React component and Schema into `src/components/forms/`.

## 📁 Project Structure

- `src/app/(main)`: The primary dashboard pages (Users, Roles, Auth, Settings, CRM, etc.).
- `src/lib/api-client.ts`: The core Fetch wrapper configuring JWT tokens, interceptors, and error handling for the backend engine.
- `src/components/ui`: The Shadcn UI primitive components.
- `scripts/`: Custom CLI tools for code generation.

## 🤝 Need Help?
Ensure your backend engine is running. For any UI-specific component modifications, refer to the [Shadcn UI documentation](https://ui.shadcn.com/).