# 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*