353 lines
10 KiB
Markdown
353 lines
10 KiB
Markdown
# Genex Web 管理前端开发指南
|
||
|
||
> 平台管理后台（Admin Dashboard） — React + TypeScript + Next.js
|
||
|
||
---
|
||
|
||
## 1. 技术栈
|
||
|
||
| 技术 | 版本 | 用途 |
|
||
|------|------|------|
|
||
| **React** | 18.x | UI框架 |
|
||
| **TypeScript** | 5.x | 类型安全 |
|
||
| **Next.js** | 14.x | SSR/SSG + App Router |
|
||
| **Zustand** | 4.x | 轻量状态管理（UI状态） |
|
||
| **Redux Toolkit** | 2.x | 复杂业务状态（交易、审核流程） |
|
||
| **RTK Query** | 内置 | API数据获取与缓存 |
|
||
| **Ant Design** | 5.x | 企业级UI组件库 |
|
||
| **ECharts / Recharts** | 最新 | 数据可视化 |
|
||
| **TanStack Table** | 8.x | 高性能数据表格 |
|
||
| **React Hook Form** | 7.x | 表单管理 |
|
||
| **Zod** | 3.x | 运行时类型校验 |
|
||
|
||
---
|
||
|
||
## 2. 项目结构
|
||
|
||
```
|
||
genex-admin/
|
||
├── src/
|
||
│ ├── app/ # Next.js App Router
|
||
│ │ ├── layout.tsx # 根布局
|
||
│ │ ├── page.tsx # Dashboard首页
|
||
│ │ ├── (auth)/ # 认证路由组
|
||
│ │ │ ├── login/page.tsx
|
||
│ │ │ └── layout.tsx
|
||
│ │ ├── (dashboard)/ # 管理面板路由组
|
||
│ │ │ ├── layout.tsx # 侧边栏+顶栏布局
|
||
│ │ │ ├── users/ # 用户管理
|
||
│ │ │ ├── issuers/ # 发行方管理
|
||
│ │ │ ├── coupons/ # 券管理
|
||
│ │ │ ├── trading/ # 交易监控
|
||
│ │ │ ├── compliance/ # 合规管理
|
||
│ │ │ ├── risk/ # 风控中心
|
||
│ │ │ ├── finance/ # 财务管理
|
||
│ │ │ ├── chain/ # 链上监控
|
||
│ │ │ └── system/ # 系统管理
|
||
│ ├── components/
|
||
│ │ ├── ui/ # 基础UI组件
|
||
│ │ ├── business/ # 业务组件
|
||
│ │ └── ai-agent/ # AI Agent组件
|
||
│ ├── features/ # 功能模块（Redux slices）
|
||
│ │ ├── auth/
|
||
│ │ ├── users/
|
||
│ │ ├── issuers/
|
||
│ │ ├── coupons/
|
||
│ │ ├── trading/
|
||
│ │ ├── compliance/
|
||
│ │ └── risk/
|
||
│ ├── services/ # API服务层
|
||
│ │ ├── api.ts # RTK Query base API
|
||
│ │ └── endpoints/ # 按模块分的API端点
|
||
│ ├── stores/ # Zustand stores
|
||
│ │ ├── ui-store.ts # UI状态（侧边栏、主题）
|
||
│ │ └── ai-agent-store.ts # AI Agent状态
|
||
│ ├── hooks/ # 自定义Hooks
|
||
│ ├── lib/ # 工具函数
|
||
│ │ ├── constants.ts
|
||
│ │ ├── utils.ts
|
||
│ │ └── types.ts
|
||
│ └── styles/ # 全局样式
|
||
├── public/
|
||
├── tests/
|
||
├── next.config.js
|
||
├── tailwind.config.ts
|
||
└── package.json
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 状态管理策略
|
||
|
||
### Zustand vs Redux Toolkit 分工
|
||
|
||
| 类型 | 工具 | 场景 |
|
||
|------|------|------|
|
||
| **UI状态** | Zustand | 侧边栏折叠、主题切换、弹窗控制 |
|
||
| **服务端数据** | RTK Query | API数据获取、缓存、自动刷新 |
|
||
| **复杂业务流** | Redux Toolkit | 审核流程、交易状态机、多步骤表单 |
|
||
| **AI Agent** | Zustand | 对话历史、Agent面板状态 |
|
||
|
||
### 3.1 RTK Query API定义
|
||
|
||
```typescript
|
||
// src/services/api.ts
|
||
import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query/react';
|
||
|
||
export const api = createApi({
|
||
baseQuery: fetchBaseQuery({
|
||
baseUrl: '/api/v1',
|
||
prepareHeaders: (headers) => {
|
||
const token = getToken();
|
||
if (token) headers.set('Authorization', `Bearer ${token}`);
|
||
return headers;
|
||
},
|
||
}),
|
||
tagTypes: ['Users', 'Issuers', 'Coupons', 'Orders', 'Compliance'],
|
||
endpoints: () => ({}),
|
||
});
|
||
```
|
||
|
||
```typescript
|
||
// src/services/endpoints/issuers.ts
|
||
export const issuerApi = api.injectEndpoints({
|
||
endpoints: (builder) => ({
|
||
getIssuers: builder.query<PaginatedResult<Issuer>, IssuerQuery>({
|
||
query: (params) => ({ url: '/issuers', params }),
|
||
providesTags: ['Issuers'],
|
||
}),
|
||
approveIssuer: builder.mutation<void, { id: string; decision: 'approve' | 'reject' }>({
|
||
query: ({ id, ...body }) => ({
|
||
url: `/issuers/${id}/review`,
|
||
method: 'POST',
|
||
body,
|
||
}),
|
||
invalidatesTags: ['Issuers'],
|
||
}),
|
||
}),
|
||
});
|
||
```
|
||
|
||
### 3.2 Zustand UI Store
|
||
|
||
```typescript
|
||
// src/stores/ui-store.ts
|
||
import { create } from 'zustand';
|
||
|
||
interface UiState {
|
||
sidebarCollapsed: boolean;
|
||
theme: 'light' | 'dark';
|
||
toggleSidebar: () => void;
|
||
setTheme: (theme: 'light' | 'dark') => void;
|
||
}
|
||
|
||
export const useUiStore = create<UiState>((set) => ({
|
||
sidebarCollapsed: false,
|
||
theme: 'light',
|
||
toggleSidebar: () => set((s) => ({ sidebarCollapsed: !s.sidebarCollapsed })),
|
||
setTheme: (theme) => set({ theme }),
|
||
}));
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 核心页面模块
|
||
|
||
### 4.1 Dashboard 首页
|
||
|
||
- 关键指标卡片：日交易量、活跃用户、新发行方、待审核数
|
||
- 交易量趋势图（ECharts线图）
|
||
- 异常交易告警列表
|
||
- AI洞察面板
|
||
|
||
### 4.2 用户管理
|
||
|
||
- 用户列表（TanStack Table，支持搜索/排序/分页）
|
||
- KYC审核详情
|
||
- 用户资产查看（我的券、余额、交易记录）
|
||
- 风控标记用户处理
|
||
|
||
### 4.3 发行方管理
|
||
|
||
```typescript
|
||
// 发行方审核流程
|
||
interface IssuerReview {
|
||
issuerId: string;
|
||
companyName: string;
|
||
businessLicense: string;
|
||
documents: Document[];
|
||
creditRating: CreditRating;
|
||
aiRiskScore: number; // AI预审风险分
|
||
aiRiskFlags: string[]; // AI标记的风险点
|
||
reviewStatus: 'pending' | 'approved' | 'rejected';
|
||
}
|
||
```
|
||
|
||
| 功能 | 说明 |
|
||
|------|------|
|
||
| 入驻审核 | AI预审+人工复核，标记风险点 |
|
||
| 信用管理 | 查看/调整信用评级，额度管理 |
|
||
| 发行监控 | 发行量、兑付率、Breakage率监控 |
|
||
| 违约处理 | 降级、冻结发行、账户冻结 |
|
||
|
||
### 4.4 交易监控
|
||
|
||
- 实时交易流（WebSocket推送）
|
||
- 订单簿深度图
|
||
- 异常交易检测告警
|
||
- 做市商活动监控
|
||
|
||
### 4.5 合规管理
|
||
|
||
```typescript
|
||
interface ComplianceCase {
|
||
id: string;
|
||
type: 'KYC' | 'AML' | 'OFAC' | 'TravelRule';
|
||
severity: 'low' | 'medium' | 'high' | 'critical';
|
||
status: 'open' | 'investigating' | 'resolved' | 'escalated';
|
||
aiAnalysis: string; // AI合规分析
|
||
suggestedAction: string; // AI建议操作
|
||
}
|
||
```
|
||
|
||
### 4.6 风控中心
|
||
|
||
- 风控仪表盘（实时风险指标）
|
||
- 异常交易图谱（关联分析可视化）
|
||
- 自动冻结记录
|
||
- SAR（可疑交易报告）管理
|
||
|
||
### 4.7 系统管理
|
||
|
||
| 页面 | 功能 |
|
||
|------|------|
|
||
| 管理员账号 | 管理员列表、RBAC角色权限、操作日志 |
|
||
| 系统配置 | 手续费率、KYC阈值、交易限额 |
|
||
| 合约管理 | 合约部署状态、升级提案、升级日志 |
|
||
| 系统监控 | 服务健康、API响应时间、Genex Chain节点状态 |
|
||
|
||
---
|
||
|
||
## 5. AI Agent 集成
|
||
|
||
### 5.1 管理端AI Agent功能
|
||
|
||
| 场景 | AI能力 | UI实现 |
|
||
|------|--------|--------|
|
||
| 风险预警 | 实时检测异常交易模式 | 仪表盘AI警告卡片+处理建议 |
|
||
| 审核辅助 | AI预审发行方资料，标记风险点 | 审核页面AI评分+风险标签 |
|
||
| 合规报告 | 自动生成SAR/CTR/监管报表草稿 | 合规报表页AI生成按钮 |
|
||
| 运营洞察 | 分析运营数据，提出优化建议 | Dashboard AI洞察面板 |
|
||
| 智能搜索 | 自然语言查询用户/订单/交易 | 全局搜索框支持NL查询 |
|
||
| 决策支持 | 手续费率调整建议、额度配置建议 | 系统配置页AI建议标签 |
|
||
|
||
### 5.2 AI Agent侧边面板
|
||
|
||
```tsx
|
||
// src/components/ai-agent/AgentPanel.tsx
|
||
export function AgentPanel() {
|
||
const { messages, sendMessage, isStreaming } = useAgentChat();
|
||
|
||
return (
|
||
<Drawer title="AI助手" placement="right" width={400}>
|
||
<ChatMessageList messages={messages} />
|
||
{isStreaming && <StreamingIndicator />}
|
||
<ChatInput onSend={sendMessage} placeholder="描述你要查询或分析的内容..." />
|
||
</Drawer>
|
||
);
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 权限管理（RBAC）
|
||
|
||
```typescript
|
||
// 角色定义
|
||
enum AdminRole {
|
||
SuperAdmin = 'super_admin', // 超级管理员：全部权限
|
||
OperationAdmin = 'ops_admin', // 运营管理员：用户+发行方+券管理
|
||
ComplianceOfficer = 'compliance', // 合规官：合规+风控
|
||
FinanceAdmin = 'finance_admin', // 财务管理员：财务+结算
|
||
Viewer = 'viewer', // 只读：仅查看Dashboard
|
||
}
|
||
|
||
// 路由守卫
|
||
function AuthGuard({ children, requiredRole }: GuardProps) {
|
||
const { user } = useAuth();
|
||
if (!hasPermission(user.role, requiredRole)) {
|
||
return <ForbiddenPage />;
|
||
}
|
||
return children;
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 实时数据
|
||
|
||
```typescript
|
||
// WebSocket连接管理
|
||
class AdminWebSocket {
|
||
private ws: WebSocket;
|
||
|
||
connect() {
|
||
this.ws = new WebSocket('wss://api.gogenex.com/admin/ws');
|
||
this.ws.onmessage = (event) => {
|
||
const data = JSON.parse(event.data);
|
||
switch (data.type) {
|
||
case 'trade_alert':
|
||
store.dispatch(addTradeAlert(data.payload));
|
||
break;
|
||
case 'risk_warning':
|
||
store.dispatch(addRiskWarning(data.payload));
|
||
break;
|
||
case 'chain_event':
|
||
store.dispatch(updateChainStatus(data.payload));
|
||
break;
|
||
}
|
||
};
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 测试策略
|
||
|
||
| 类型 | 工具 | 覆盖 |
|
||
|------|------|------|
|
||
| 单元测试 | Vitest | Redux slices、工具函数、Hooks |
|
||
| 组件测试 | React Testing Library | 关键表单、表格、弹窗 |
|
||
| E2E测试 | Playwright | 审核流程、配置变更、报表导出 |
|
||
|
||
---
|
||
|
||
## 9. 部署
|
||
|
||
```yaml
|
||
# Next.js部署配置
|
||
# Docker + Kubernetes
|
||
FROM node:20-alpine AS builder
|
||
WORKDIR /app
|
||
COPY package*.json ./
|
||
RUN npm ci
|
||
COPY . .
|
||
RUN npm run build
|
||
|
||
FROM node:20-alpine
|
||
WORKDIR /app
|
||
COPY --from=builder /app/.next ./.next
|
||
COPY --from=builder /app/public ./public
|
||
COPY --from=builder /app/package.json ./
|
||
RUN npm ci --production
|
||
EXPOSE 3000
|
||
CMD ["npm", "start"]
|
||
```
|
||
|
||
---
|
||
|
||
*文档版本: v1.0*
|
||
*基于: Genex 券交易平台 - 软件需求规格说明书 v4.1*
|
||
*技术栈: React 18 + TypeScript 5 + Next.js 14 + Zustand + Redux Toolkit*
|