10 KiB

Raw Blame History

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定义

// 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: () => ({}),
});

// 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

// 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 发行方管理

// 发行方审核流程
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 合规管理

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侧边面板

// 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）

// 角色定义
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. 实时数据

// 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. 部署

# 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

10 KiB Raw Blame History Unescape Escape

Genex Web 管理前端开发指南

1. 技术栈

2. 项目结构

3. 状态管理策略

Zustand vs Redux Toolkit 分工

3.1 RTK Query API定义

3.2 Zustand UI Store

4. 核心页面模块

4.1 Dashboard 首页

4.2 用户管理

4.3 发行方管理

4.4 交易监控

4.5 合规管理

4.6 风控中心

4.7 系统管理

5. AI Agent 集成

5.1 管理端AI Agent功能

5.2 AI Agent侧边面板

6. 权限管理（RBAC）

7. 实时数据

8. 测试策略

9. 部署

10 KiB

Raw Blame History