1710 lines
46 KiB
Markdown
1710 lines
46 KiB
Markdown
# 榴莲认种管理后台 (RWADurian Admin Web) - 前端开发规范文档
|
||
|
||
> **项目名称**: RWADurian Admin Web
|
||
> **版本**: 1.0.0
|
||
> **目标路径**: `rwadurian/frontend/admin-web`
|
||
> **文档用途**: 供 Claude Code 阅读并指导完成项目开发
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
1. [项目概述](#1-项目概述)
|
||
2. [技术架构](#2-技术架构)
|
||
3. [目录结构](#3-目录结构)
|
||
4. [功能模块详解](#4-功能模块详解)
|
||
5. [UI/UX 设计规范](#5-uiux-设计规范)
|
||
6. [组件设计指南](#6-组件设计指南)
|
||
7. [状态管理方案](#7-状态管理方案)
|
||
8. [API 集成规范](#8-api-集成规范)
|
||
9. [开发规范与约定](#9-开发规范与约定)
|
||
10. [开发优先级与里程碑](#10-开发优先级与里程碑)
|
||
|
||
---
|
||
|
||
## 1. 项目概述
|
||
|
||
### 1.1 项目背景
|
||
|
||
榴莲认种管理后台是一个面向管理员的 Web 应用系统，用于管理榴莲树认种业务的全流程，包括用户管理、排名龙虎榜、省市公司授权、数据统计分析等核心功能。
|
||
|
||
### 1.2 核心功能模块
|
||
|
||
| 模块名称 | 路由路径 | 功能描述 |
|
||
|---------|---------|---------|
|
||
| 登录认证 | `/login` | 管理员登录、忘记密码、注册入口 |
|
||
| 仪表板 | `/dashboard` | 数据概览、趋势图表、最近活动 |
|
||
| 用户管理 | `/users` | 用户列表、搜索筛选、批量操作 |
|
||
| 龙虎榜管理 | `/leaderboard` | 日/周/月榜配置、虚拟排名设置 |
|
||
| 授权管理 | `/authorization` | 省/市公司授权、考核规则配置 |
|
||
| 数据统计 | `/statistics` | 多维度数据分析、报表导出 |
|
||
| 系统设置 | `/settings` | 结算参数、限额、安全配置 |
|
||
| 帮助中心 | `/help` | 文档、FAQ、联系支持 |
|
||
|
||
### 1.3 目标用户
|
||
|
||
- **超级管理员**: 拥有全部权限，可管理其他管理员账号
|
||
- **运营管理员**: 日常运营操作，无敏感设置权限
|
||
- **数据分析员**: 只读权限，专注数据查看和报表导出
|
||
|
||
---
|
||
|
||
## 2. 技术架构
|
||
|
||
### 2.1 技术栈
|
||
|
||
```yaml
|
||
核心框架:
|
||
- React: 18.x
|
||
- Next.js: 15.x (App Router)
|
||
- TypeScript: 5.x
|
||
|
||
状态管理:
|
||
- Redux Toolkit: 全局状态（用户认证、系统配置）
|
||
- Zustand: 局部状态（表单、UI临时状态）
|
||
|
||
样式方案:
|
||
- 纯 CSS/SCSS Modules (无第三方 UI 库)
|
||
- CSS Variables 主题系统
|
||
- Figma 导出的自定义设计
|
||
|
||
数据可视化:
|
||
- Recharts 或 ECharts (图表库)
|
||
- D3.js (复杂可视化需求)
|
||
|
||
网络请求:
|
||
- Axios + React Query (TanStack Query)
|
||
|
||
工具链:
|
||
- ESLint + Prettier
|
||
- Husky + lint-staged
|
||
- Jest + React Testing Library
|
||
```
|
||
|
||
### 2.2 Clean Architecture 分层
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ Presentation Layer │
|
||
│ (Pages, Components, Hooks) │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ Application Layer │
|
||
│ (Use Cases, Services, State Management) │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ Domain Layer │
|
||
│ (Entities, Value Objects, Domain Services) │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ Infrastructure Layer │
|
||
│ (API Clients, Storage, External Services) │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 目录结构
|
||
|
||
```
|
||
admin-web/
|
||
├── public/
|
||
│ ├── assets/
|
||
│ │ ├── images/
|
||
│ │ │ ├── logo.svg
|
||
│ │ │ └── icons/
|
||
│ │ └── fonts/
|
||
│ └── locales/
|
||
│ └── zh-CN.json
|
||
│
|
||
├── src/
|
||
│ ├── app/ # Next.js App Router
|
||
│ │ ├── (auth)/
|
||
│ │ │ ├── login/
|
||
│ │ │ │ └── page.tsx
|
||
│ │ │ ├── forgot-password/
|
||
│ │ │ │ └── page.tsx
|
||
│ │ │ └── layout.tsx
|
||
│ │ │
|
||
│ │ ├── (dashboard)/
|
||
│ │ │ ├── dashboard/
|
||
│ │ │ │ └── page.tsx
|
||
│ │ │ ├── users/
|
||
│ │ │ │ ├── page.tsx
|
||
│ │ │ │ └── [id]/
|
||
│ │ │ │ └── page.tsx
|
||
│ │ │ ├── leaderboard/
|
||
│ │ │ │ └── page.tsx
|
||
│ │ │ ├── authorization/
|
||
│ │ │ │ └── page.tsx
|
||
│ │ │ ├── statistics/
|
||
│ │ │ │ └── page.tsx
|
||
│ │ │ ├── settings/
|
||
│ │ │ │ └── page.tsx
|
||
│ │ │ ├── help/
|
||
│ │ │ │ └── page.tsx
|
||
│ │ │ └── layout.tsx
|
||
│ │ │
|
||
│ │ ├── layout.tsx
|
||
│ │ ├── page.tsx
|
||
│ │ └── globals.css
|
||
│ │
|
||
│ ├── components/ # UI 组件
|
||
│ │ ├── common/ # 通用基础组件
|
||
│ │ │ ├── Button/
|
||
│ │ │ │ ├── Button.tsx
|
||
│ │ │ │ ├── Button.module.scss
|
||
│ │ │ │ └── index.ts
|
||
│ │ │ ├── Input/
|
||
│ │ │ ├── Select/
|
||
│ │ │ ├── Table/
|
||
│ │ │ ├── Modal/
|
||
│ │ │ ├── Card/
|
||
│ │ │ ├── Badge/
|
||
│ │ │ ├── Avatar/
|
||
│ │ │ ├── Pagination/
|
||
│ │ │ ├── Toggle/
|
||
│ │ │ ├── Dropdown/
|
||
│ │ │ ├── Tabs/
|
||
│ │ │ ├── Tooltip/
|
||
│ │ │ ├── Loading/
|
||
│ │ │ └── Toast/
|
||
│ │ │
|
||
│ │ ├── layout/ # 布局组件
|
||
│ │ │ ├── Sidebar/
|
||
│ │ │ ├── Header/
|
||
│ │ │ ├── Breadcrumb/
|
||
│ │ │ └── PageContainer/
|
||
│ │ │
|
||
│ │ ├── charts/ # 图表组件
|
||
│ │ │ ├── LineChart/
|
||
│ │ │ ├── BarChart/
|
||
│ │ │ ├── PieChart/
|
||
│ │ │ └── DonutChart/
|
||
│ │ │
|
||
│ │ └── features/ # 业务组件
|
||
│ │ ├── dashboard/
|
||
│ │ │ ├── StatCard/
|
||
│ │ │ ├── TrendChart/
|
||
│ │ │ ├── RegionDistribution/
|
||
│ │ │ └── RecentActivity/
|
||
│ │ ├── users/
|
||
│ │ │ ├── UserTable/
|
||
│ │ │ ├── UserFilters/
|
||
│ │ │ └── UserDetailModal/
|
||
│ │ ├── leaderboard/
|
||
│ │ │ ├── RankingTable/
|
||
│ │ │ ├── BoardSettings/
|
||
│ │ │ └── VirtualRankPreview/
|
||
│ │ ├── authorization/
|
||
│ │ │ ├── CompanyTable/
|
||
│ │ │ ├── AssessmentRules/
|
||
│ │ │ └── LadderTargetTable/
|
||
│ │ ├── statistics/
|
||
│ │ │ ├── TrendAnalysis/
|
||
│ │ │ ├── RegionStats/
|
||
│ │ │ ├── CompanyOperations/
|
||
│ │ │ └── RevenueDetails/
|
||
│ │ ├── settings/
|
||
│ │ │ ├── SettlementConfig/
|
||
│ │ │ ├── LeaderboardConfig/
|
||
│ │ │ ├── QuotaConfig/
|
||
│ │ │ ├── AssessmentConfig/
|
||
│ │ │ ├── DisplayConfig/
|
||
│ │ │ └── SecurityConfig/
|
||
│ │ └── help/
|
||
│ │ ├── DocumentCard/
|
||
│ │ ├── DocumentList/
|
||
│ │ ├── FAQSection/
|
||
│ │ └── ContactSupport/
|
||
│ │
|
||
│ ├── domain/ # 领域层
|
||
│ │ ├── entities/
|
||
│ │ │ ├── User.ts
|
||
│ │ │ ├── Company.ts
|
||
│ │ │ ├── Ranking.ts
|
||
│ │ │ ├── Statistics.ts
|
||
│ │ │ └── Settings.ts
|
||
│ │ ├── value-objects/
|
||
│ │ │ ├── UserId.ts
|
||
│ │ │ ├── Province.ts
|
||
│ │ │ └── Currency.ts
|
||
│ │ └── interfaces/
|
||
│ │ ├── IUserRepository.ts
|
||
│ │ ├── ICompanyRepository.ts
|
||
│ │ └── IStatisticsRepository.ts
|
||
│ │
|
||
│ ├── application/ # 应用层
|
||
│ │ ├── use-cases/
|
||
│ │ │ ├── auth/
|
||
│ │ │ │ ├── LoginUseCase.ts
|
||
│ │ │ │ └── LogoutUseCase.ts
|
||
│ │ │ ├── users/
|
||
│ │ │ │ ├── GetUsersUseCase.ts
|
||
│ │ │ │ ├── UpdateUserUseCase.ts
|
||
│ │ │ │ └── ExportUsersUseCase.ts
|
||
│ │ │ ├── leaderboard/
|
||
│ │ │ │ ├── GetRankingsUseCase.ts
|
||
│ │ │ │ └── UpdateBoardSettingsUseCase.ts
|
||
│ │ │ └── ...
|
||
│ │ │
|
||
│ │ ├── services/
|
||
│ │ │ ├── AuthService.ts
|
||
│ │ │ ├── UserService.ts
|
||
│ │ │ ├── LeaderboardService.ts
|
||
│ │ │ ├── AuthorizationService.ts
|
||
│ │ │ ├── StatisticsService.ts
|
||
│ │ │ └── SettingsService.ts
|
||
│ │ │
|
||
│ │ └── dto/
|
||
│ │ ├── UserDTO.ts
|
||
│ │ ├── CompanyDTO.ts
|
||
│ │ └── StatisticsDTO.ts
|
||
│ │
|
||
│ ├── infrastructure/ # 基础设施层
|
||
│ │ ├── api/
|
||
│ │ │ ├── client.ts # Axios 实例配置
|
||
│ │ │ ├── endpoints.ts # API 端点定义
|
||
│ │ │ └── repositories/
|
||
│ │ │ ├── UserRepository.ts
|
||
│ │ │ ├── CompanyRepository.ts
|
||
│ │ │ └── StatisticsRepository.ts
|
||
│ │ │
|
||
│ │ ├── storage/
|
||
│ │ │ ├── localStorage.ts
|
||
│ │ │ └── sessionStorage.ts
|
||
│ │ │
|
||
│ │ └── external/
|
||
│ │ └── exportService.ts # Excel 导出等
|
||
│ │
|
||
│ ├── store/ # 状态管理
|
||
│ │ ├── redux/
|
||
│ │ │ ├── store.ts
|
||
│ │ │ ├── rootReducer.ts
|
||
│ │ │ └── slices/
|
||
│ │ │ ├── authSlice.ts
|
||
│ │ │ ├── settingsSlice.ts
|
||
│ │ │ └── notificationSlice.ts
|
||
│ │ │
|
||
│ │ └── zustand/
|
||
│ │ ├── useUserFiltersStore.ts
|
||
│ │ ├── useLeaderboardStore.ts
|
||
│ │ └── useModalStore.ts
|
||
│ │
|
||
│ ├── hooks/ # 自定义 Hooks
|
||
│ │ ├── useAuth.ts
|
||
│ │ ├── useUsers.ts
|
||
│ │ ├── useLeaderboard.ts
|
||
│ │ ├── useStatistics.ts
|
||
│ │ ├── usePagination.ts
|
||
│ │ ├── useDebounce.ts
|
||
│ │ └── useExport.ts
|
||
│ │
|
||
│ ├── utils/ # 工具函数
|
||
│ │ ├── formatters.ts # 数字、日期格式化
|
||
│ │ ├── validators.ts # 表单验证
|
||
│ │ ├── constants.ts # 常量定义
|
||
│ │ └── helpers.ts # 通用辅助函数
|
||
│ │
|
||
│ ├── styles/ # 全局样式
|
||
│ │ ├── variables.scss # CSS 变量
|
||
│ │ ├── mixins.scss # SCSS Mixins
|
||
│ │ ├── typography.scss # 字体样式
|
||
│ │ ├── animations.scss # 动画定义
|
||
│ │ └── reset.scss # 样式重置
|
||
│ │
|
||
│ └── types/ # TypeScript 类型
|
||
│ ├── api.types.ts
|
||
│ ├── user.types.ts
|
||
│ ├── company.types.ts
|
||
│ ├── statistics.types.ts
|
||
│ └── common.types.ts
|
||
│
|
||
├── .env.local
|
||
├── .env.development
|
||
├── .env.production
|
||
├── .eslintrc.json
|
||
├── .prettierrc
|
||
├── next.config.js
|
||
├── tsconfig.json
|
||
├── package.json
|
||
└── README.md
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 功能模块详解
|
||
|
||
### 4.1 登录认证模块 (`/login`)
|
||
|
||
#### 页面布局
|
||
- 居中卡片式设计，浅灰色背景 (`#F5F5F5`)
|
||
- Logo + 系统名称 "榴莲认种管理后台"
|
||
- 欢迎语 "欢迎回来"
|
||
|
||
#### 功能点
|
||
| 功能 | 描述 | 交互 |
|
||
|-----|------|------|
|
||
| 邮箱输入 | 邮箱格式验证 | 失焦验证 |
|
||
| 密码输入 | 密码强度提示 | 实时验证 |
|
||
| 忘记密码 | 跳转密码重置页 | 链接跳转 |
|
||
| 登录按钮 | 提交登录请求 | Loading 状态 |
|
||
| 注册入口 | 跳转注册页面 | 链接跳转 |
|
||
|
||
#### 表单验证规则
|
||
```typescript
|
||
interface LoginForm {
|
||
email: string; // 必填，邮箱格式
|
||
password: string; // 必填，6-20位
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 4.2 仪表板模块 (`/dashboard`)
|
||
|
||
#### 页面结构
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ [Sidebar] │ [Header: 面包屑 + 操作按钮 + 用户信息] │
|
||
│ ├─────────────────────────────────────────────────┤
|
||
│ │ [统计卡片区: 4个卡片横向排列] │
|
||
│ ├───────────────────────────┬─────────────────────┤
|
||
│ │ [认种趋势图] │ [最近活动] │
|
||
│ ├───────────────────────────┤ │
|
||
│ │ [月度增长图] │ │
|
||
│ ├───────────────────────────┤ │
|
||
│ │ [区域分布饼图] │ │
|
||
└───────────┴───────────────────────────┴─────────────────────┘
|
||
```
|
||
|
||
#### 统计卡片数据
|
||
| 卡片名称 | 数据字段 | 增长指标 |
|
||
|---------|---------|---------|
|
||
| 总认种量 | `totalAdoptions` | 百分比增长 |
|
||
| 活跃用户 | `activeUsers` | 百分比增长 |
|
||
| 省级公司 | `provincialCompanies` | 百分比增长 |
|
||
| 市级公司 | `cityCompanies` | 百分比增长 |
|
||
|
||
#### 图表组件
|
||
|
||
**认种趋势折线图**
|
||
```typescript
|
||
interface TrendChartData {
|
||
date: string;
|
||
value: number;
|
||
}
|
||
// 支持时间范围切换: 7天/30天/90天
|
||
```
|
||
|
||
**月度增长柱状图**
|
||
```typescript
|
||
interface MonthlyGrowthData {
|
||
month: string;
|
||
adoptions: number;
|
||
growth: number; // 环比增长
|
||
}
|
||
```
|
||
|
||
**区域分布环形图**
|
||
```typescript
|
||
interface RegionDistributionData {
|
||
region: string;
|
||
percentage: number;
|
||
color: string;
|
||
}
|
||
```
|
||
|
||
#### 最近活动列表
|
||
```typescript
|
||
interface ActivityItem {
|
||
id: string;
|
||
type: 'user_register' | 'company_activity' | 'system_update' | 'report_generated';
|
||
icon: string;
|
||
title: string;
|
||
description: string;
|
||
timestamp: string; // "5分钟前", "2小时前", "昨天"
|
||
}
|
||
```
|
||
|
||
#### 顶部操作按钮
|
||
- **添加用户**: 打开添加用户弹窗
|
||
- **授权管理**: 跳转授权管理页
|
||
- **查看报表**: 跳转数据统计页（主按钮样式）
|
||
|
||
---
|
||
|
||
### 4.3 用户管理模块 (`/users`)
|
||
|
||
#### 页面功能
|
||
|
||
**搜索与筛选**
|
||
```typescript
|
||
interface UserFilters {
|
||
keyword: string; // 账户ID、昵称搜索
|
||
advancedFilters: {
|
||
province?: string; // 省份筛选
|
||
city?: string; // 城市筛选
|
||
rankRange?: [number, number]; // 排名范围
|
||
adoptionRange?: [number, number]; // 认种量范围
|
||
status?: 'active' | 'inactive';
|
||
};
|
||
}
|
||
```
|
||
|
||
**用户表格列定义**
|
||
| 列名 | 字段 | 宽度 | 排序 | 说明 |
|
||
|-----|------|------|------|------|
|
||
| 复选框 | - | 48px | - | 批量选择 |
|
||
| 账户序号 | `accountId` | 100px | ✓ | 唯一标识 |
|
||
| 头像 | `avatar` | 60px | - | 圆形头像+在线状态指示 |
|
||
| 昵称 | `nickname` | 80px | ✓ | - |
|
||
| 账户认种量 | `personalAdoptions` | 100px | ✓ | - |
|
||
| 团队总注册地址量 | `teamAddresses` | 120px | ✓ | - |
|
||
| 团队总认种量 | `teamAdoptions` | 100px | ✓ | - |
|
||
| 团队本省认种量及占比 | `provincialAdoptions` | 140px | ✓ | 显示数量(占比%) |
|
||
| 团队本市认种量及占比 | `cityAdoptions` | 140px | ✓ | 显示数量(占比%) |
|
||
| 推荐人序列号 | `referrerId` | 100px | - | - |
|
||
| 龙虎榜排名 | `ranking` | 80px | ✓ | 显示"-"表示未上榜 |
|
||
| 操作 | - | 120px | - | 查看详情、编辑 |
|
||
|
||
**批量操作**
|
||
- 导出 Excel (选中项/全部)
|
||
- 批量编辑（修改状态等）
|
||
|
||
**分页配置**
|
||
```typescript
|
||
interface PaginationConfig {
|
||
pageSize: 10 | 20 | 50 | 100;
|
||
current: number;
|
||
total: number;
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 4.4 龙虎榜管理模块 (`/leaderboard`)
|
||
|
||
#### 页面布局
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ [页面标题] [导出排名数据按钮] │
|
||
├─────────────────────────────────┬───────────────────────────┤
|
||
│ │ │
|
||
│ ┌─────────────────────────┐ │ 榜单设置 │
|
||
│ │ 日榜 [开关] │ │ ┌───────────────────┐ │
|
||
│ │ 排名表格... │ │ │ 虚拟排名设置 │ │
|
||
│ └─────────────────────────┘ │ │ - 启用开关 │ │
|
||
│ │ │ - 虚拟账户数量 │ │
|
||
│ ┌─────────────────────────┐ │ │ - 规则说明 │ │
|
||
│ │ 周榜 [开关] │ │ │ - 实时预览 │ │
|
||
│ │ 榜单未开启/排名表格 │ │ └───────────────────┘ │
|
||
│ └─────────────────────────┘ │ ┌───────────────────┐ │
|
||
│ │ │ 显示设置 │ │
|
||
│ ┌─────────────────────────┐ │ │ - 前端显示数量 │ │
|
||
│ │ 月榜 [开关] │ │ └───────────────────┘ │
|
||
│ │ 榜单未开启/排名表格 │ │ │
|
||
│ └─────────────────────────┘ │ [保存设置按钮] │
|
||
│ │ │
|
||
└─────────────────────────────────┴───────────────────────────┘
|
||
```
|
||
|
||
#### 排名表格
|
||
```typescript
|
||
interface RankingItem {
|
||
rank: number; // 1, 2, 3 显示奖牌图标
|
||
avatar: string;
|
||
nickname: string;
|
||
isVirtual: boolean; // 虚拟用户标签
|
||
adoptionCount: number; // X 棵
|
||
teamData: string; // 团队标识 (A队, B队, C队)
|
||
}
|
||
```
|
||
|
||
#### 榜单设置
|
||
```typescript
|
||
interface BoardSettings {
|
||
virtualRanking: {
|
||
enabled: boolean;
|
||
virtualAccountCount: number; // 滑块 0-10
|
||
ruleDescription: string;
|
||
};
|
||
displaySettings: {
|
||
frontendDisplayCount: 10 | 20 | 50; // 下拉选择
|
||
};
|
||
}
|
||
```
|
||
|
||
#### 榜单开关状态
|
||
- **已开启**: 显示排名表格
|
||
- **未开启**: 显示空状态图标 + "榜单未开启" + "待激活"
|
||
|
||
---
|
||
|
||
### 4.5 授权管理模块 (`/authorization`)
|
||
|
||
#### 页面分区
|
||
|
||
**1. 授权省公司管理**
|
||
```typescript
|
||
interface ProvinceCompanyFilter {
|
||
province: string;
|
||
authStatus: 'authorized' | 'pending' | 'all';
|
||
keyword: string;
|
||
}
|
||
|
||
interface ProvinceCompanyItem {
|
||
avatar: string;
|
||
nickname: string;
|
||
accountId: string;
|
||
province: string;
|
||
teamAdoptions: number;
|
||
authStatus: 'authorized' | 'pending';
|
||
actions: ['authorize' | 'revoke'];
|
||
}
|
||
```
|
||
|
||
**2. 省公司团队权益考核规则**
|
||
```typescript
|
||
interface ProvinceAssessmentRules {
|
||
firstTriggerThreshold: number; // 首次考核触发门槛 (棵)
|
||
stageUnitBenefit: number; // 考核阶段单棵权益 (USDT)
|
||
incrementalBenefit: number; // 达标后每新增1棵获得 (USDT)
|
||
assessmentCycle: 'monthly' | 'quarterly';
|
||
failureResetEnabled: boolean; // 未达成目标时权益失效并重置
|
||
}
|
||
```
|
||
|
||
**3. 授权市公司管理**
|
||
- 结构同省公司，增加城市筛选
|
||
|
||
**4. 市公司团队权益考核规则**
|
||
- 结构同省公司规则，阈值和权益数值不同
|
||
|
||
**5. 正式省/市公司授权管理**
|
||
- 通过全部阶梯性考核后的正式公司列表
|
||
|
||
**6. 授权限制规则**
|
||
```typescript
|
||
interface AuthorizationLimits {
|
||
oneProvinceOneCompany: boolean; // 每省份仅授权1个
|
||
oneCityOneCompany: boolean; // 每城市仅授权1个
|
||
topRankingRequired: number; // 排名前N才具备资格
|
||
specialCityRules: {
|
||
beijing: boolean; // 北京特例
|
||
shanghai: boolean; // 上海特例
|
||
};
|
||
}
|
||
```
|
||
|
||
**7. 阶梯性考核目标表**
|
||
```typescript
|
||
interface LadderTarget {
|
||
assessmentMonth: number; // 考核月 (1-9)
|
||
provinceMonthlyTarget: number; // 省代当月目标
|
||
provinceCumulativeTarget: number; // 省代累计目标
|
||
cityMonthlyTarget: number; // 市代当月目标
|
||
cityCumulativeTarget: number; // 市代累计目标
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 4.6 数据统计模块 (`/statistics`)
|
||
|
||
#### 页面分区
|
||
|
||
**1. 顶部统计概览**
|
||
```typescript
|
||
interface StatisticsOverview {
|
||
totalAdoptions: number; // 榴莲树认种总量
|
||
todayAdoptions: number; // 今日认种数量
|
||
monthlyAdoptions: number; // 本月认种数量
|
||
}
|
||
```
|
||
|
||
**2. 认种数量趋势**
|
||
- 时间维度切换: 日 / 周 / 月 / 季度 / 年度
|
||
- 折线图展示
|
||
|
||
**3. 龙虎榜与排名统计**
|
||
```typescript
|
||
interface LeaderboardStats {
|
||
activeTab: 'daily' | 'weekly' | 'monthly';
|
||
rankings: Array<{
|
||
rank: number;
|
||
account: string;
|
||
adoptionCount: number;
|
||
province: string;
|
||
city: string;
|
||
}>;
|
||
topProvince: {
|
||
name: string;
|
||
completionData: number;
|
||
};
|
||
topCity: {
|
||
name: string;
|
||
completionData: number;
|
||
};
|
||
}
|
||
```
|
||
|
||
**4. 区域认种数据统计**
|
||
- 按省统计 / 按市统计 切换
|
||
- 柱状图 + 详情表格
|
||
```typescript
|
||
interface RegionStats {
|
||
region: string;
|
||
period: string; // 2023-10
|
||
adoptionCount: number;
|
||
percentage: number;
|
||
}
|
||
```
|
||
|
||
**5. 省/市公司运营统计**
|
||
```typescript
|
||
interface OperationStats {
|
||
summary: {
|
||
monthlyHashRate: string; // "1,200 TH/s"
|
||
cumulativeHashRate: string; // "15,000 TH/s"
|
||
monthlyMining: string; // "5.6 BTC"
|
||
cumulativeMining: string; // "67.8 BTC"
|
||
monthlyCommission: number; // ¥12,345
|
||
cumulativeCommission: number; // ¥150,000
|
||
monthlyAdoptionBonus: number; // ¥8,900
|
||
};
|
||
details: Array<{
|
||
accountType: 'province' | 'city';
|
||
accountName: string;
|
||
statMonth: string;
|
||
hashRate: string;
|
||
miningAmount: string;
|
||
commission: number;
|
||
}>;
|
||
}
|
||
```
|
||
|
||
**6. 收益明细与来源**
|
||
```typescript
|
||
interface RevenueDetail {
|
||
timestamp: string;
|
||
account: string;
|
||
source: 'mining' | 'adoption_completion' | 'share';
|
||
amount: number; // 带+号显示正数
|
||
relatedAddress: string; // bc1...xyz
|
||
transactionId: string; // TXN1234567890
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 4.7 系统设置模块 (`/settings`)
|
||
|
||
#### 设置分区
|
||
|
||
**1. 结算参数设置**
|
||
```typescript
|
||
interface SettlementConfig {
|
||
availableCurrencies: Array<'BNB' | 'OG' | 'USDT' | 'DST'>;
|
||
defaultCurrency: string;
|
||
}
|
||
```
|
||
|
||
**2. 龙虎榜设置**
|
||
```typescript
|
||
interface LeaderboardConfig {
|
||
virtualAccountEnabled: boolean;
|
||
virtualAccountCount: number;
|
||
boardSwitches: {
|
||
daily: boolean;
|
||
weekly: boolean;
|
||
monthly: boolean;
|
||
};
|
||
frontendDisplayCount: string; // "10, 20, 31"
|
||
}
|
||
```
|
||
|
||
**3. 认种限额设置**
|
||
```typescript
|
||
interface QuotaConfig {
|
||
singleAccountQuota: {
|
||
enabled: boolean;
|
||
days: number;
|
||
maxCount: number;
|
||
};
|
||
networkTotalQuota: {
|
||
enabled: boolean;
|
||
days: number;
|
||
maxCount: number;
|
||
};
|
||
}
|
||
```
|
||
|
||
**4. 考核规则设置**
|
||
```typescript
|
||
interface AssessmentConfig {
|
||
localUserPercentageThreshold: number; // 5%
|
||
exemptionEnabled: boolean; // 允许豁免
|
||
ladderTargets: LadderTarget[];
|
||
}
|
||
```
|
||
|
||
**5. 前端展示设置**
|
||
```typescript
|
||
interface DisplayConfig {
|
||
allowNonAdopterViewHeatmap: boolean;
|
||
heatmapDisplayMode: 'exact_count' | 'level'; // 高/中/低
|
||
}
|
||
```
|
||
|
||
**6. 后台账号与安全**
|
||
```typescript
|
||
interface SecurityConfig {
|
||
accounts: Array<{
|
||
username: string;
|
||
role: '超级管理员' | '运营人员';
|
||
status: 'active' | 'disabled';
|
||
lastLogin: string;
|
||
}>;
|
||
sensitiveOperationApprovers: number; // 审批人数
|
||
sensitiveOperations: string[]; // 需审批的操作
|
||
operationLogs: Array<{
|
||
timestamp: string;
|
||
operator: string;
|
||
type: string;
|
||
description: string;
|
||
approvalResult: 'approved' | 'pending' | 'rejected';
|
||
}>;
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 4.8 帮助中心模块 (`/help`)
|
||
|
||
#### 页面分区
|
||
|
||
**1. 搜索区**
|
||
- 搜索文档或问题的输入框
|
||
|
||
**2. 推荐文档卡片**
|
||
```typescript
|
||
interface RecommendedDoc {
|
||
title: string;
|
||
description: string;
|
||
helpfulCount: number;
|
||
notHelpfulCount: number;
|
||
}
|
||
```
|
||
固定展示3个推荐文档
|
||
|
||
**3. 文档列表**
|
||
```typescript
|
||
interface DocumentItem {
|
||
title: string;
|
||
category: '系统设置' | '账号安全' | '数据统计' | '授权管理';
|
||
lastUpdated: string;
|
||
rating: {
|
||
helpful: boolean | null;
|
||
};
|
||
}
|
||
```
|
||
|
||
**4. 常见问题 (FAQ)**
|
||
```typescript
|
||
interface FAQItem {
|
||
question: string;
|
||
answer: string;
|
||
expanded: boolean;
|
||
}
|
||
```
|
||
|
||
**5. 联系支持**
|
||
```typescript
|
||
interface SupportInfo {
|
||
phone: string; // "400-123-4567"
|
||
workingHours: string; // "工作日 9:00 - 18:00"
|
||
email: string; // "support@durian-adopt.com"
|
||
onlineChat: boolean; // 在线客服入口
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 5. UI/UX 设计规范
|
||
|
||
### 5.1 色彩系统
|
||
|
||
```scss
|
||
// 主色调
|
||
$primary-color: #1565C0; // 主蓝色 - 按钮、链接、激活状态
|
||
$primary-light: #1E88E5; // 浅蓝色 - Hover 状态
|
||
$primary-dark: #0D47A1; // 深蓝色 - 点击状态
|
||
|
||
// 辅助色
|
||
$success-color: #4CAF50; // 成功绿
|
||
$warning-color: #F5A623; // 警告黄/金色
|
||
$error-color: #E53935; // 错误红
|
||
$info-color: #2196F3; // 信息蓝
|
||
|
||
// 中性色
|
||
$text-primary: #212121; // 主要文字
|
||
$text-secondary: #757575; // 次要文字
|
||
$text-disabled: #BDBDBD; // 禁用文字
|
||
$border-color: #E0E0E0; // 边框色
|
||
$background-color: #F5F5F5; // 页面背景
|
||
$card-background: #FFFFFF; // 卡片背景
|
||
$sidebar-background: #1565C0; // 侧边栏背景
|
||
|
||
// 语义色
|
||
$increase-color: #4CAF50; // 增长 (+5.6%)
|
||
$decrease-color: #E53935; // 下降
|
||
```
|
||
|
||
### 5.2 字体系统
|
||
|
||
```scss
|
||
// 字体族
|
||
$font-family-base: 'PingFang SC', 'Microsoft YaHei', -apple-system, BlinkMacSystemFont, sans-serif;
|
||
$font-family-number: 'DIN Alternate', 'Roboto', $font-family-base;
|
||
|
||
// 字号
|
||
$font-size-xs: 12px; // 辅助文字、标签
|
||
$font-size-sm: 13px; // 表格内容
|
||
$font-size-base: 14px; // 正文
|
||
$font-size-md: 16px; // 小标题
|
||
$font-size-lg: 18px; // 二级标题
|
||
$font-size-xl: 20px; // 页面标题
|
||
$font-size-xxl: 24px; // 大数字
|
||
$font-size-display: 32px; // 统计数字
|
||
|
||
// 行高
|
||
$line-height-tight: 1.25;
|
||
$line-height-base: 1.5;
|
||
$line-height-loose: 1.75;
|
||
|
||
// 字重
|
||
$font-weight-regular: 400;
|
||
$font-weight-medium: 500;
|
||
$font-weight-semibold: 600;
|
||
$font-weight-bold: 700;
|
||
```
|
||
|
||
### 5.3 间距系统
|
||
|
||
```scss
|
||
// 基础间距 (4px 为基础单位)
|
||
$spacing-xs: 4px;
|
||
$spacing-sm: 8px;
|
||
$spacing-md: 12px;
|
||
$spacing-base: 16px;
|
||
$spacing-lg: 20px;
|
||
$spacing-xl: 24px;
|
||
$spacing-xxl: 32px;
|
||
$spacing-xxxl: 48px;
|
||
|
||
// 组件内间距
|
||
$padding-card: 24px;
|
||
$padding-modal: 24px;
|
||
$padding-input: 12px 16px;
|
||
$padding-button: 10px 24px;
|
||
|
||
// 页面边距
|
||
$page-padding: 24px;
|
||
$sidebar-width: 240px;
|
||
$sidebar-collapsed-width: 64px;
|
||
```
|
||
|
||
### 5.4 圆角系统
|
||
|
||
```scss
|
||
$border-radius-sm: 4px; // 小按钮、标签
|
||
$border-radius-base: 8px; // 输入框、卡片
|
||
$border-radius-lg: 12px; // 大卡片、弹窗
|
||
$border-radius-xl: 16px; // 特殊组件
|
||
$border-radius-round: 50%; // 圆形头像
|
||
$border-radius-pill: 999px; // 药丸形状
|
||
```
|
||
|
||
### 5.5 阴影系统
|
||
|
||
```scss
|
||
$shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);
|
||
$shadow-base: 0 2px 8px rgba(0, 0, 0, 0.08);
|
||
$shadow-md: 0 4px 12px rgba(0, 0, 0, 0.1);
|
||
$shadow-lg: 0 8px 24px rgba(0, 0, 0, 0.12);
|
||
$shadow-xl: 0 16px 48px rgba(0, 0, 0, 0.15);
|
||
```
|
||
|
||
### 5.6 动画系统
|
||
|
||
```scss
|
||
// 时长
|
||
$duration-fast: 150ms;
|
||
$duration-base: 250ms;
|
||
$duration-slow: 350ms;
|
||
|
||
// 缓动函数
|
||
$ease-in-out: cubic-bezier(0.4, 0, 0.2, 1);
|
||
$ease-out: cubic-bezier(0, 0, 0.2, 1);
|
||
$ease-in: cubic-bezier(0.4, 0, 1, 1);
|
||
|
||
// 常用动画
|
||
@mixin transition-base {
|
||
transition: all $duration-base $ease-in-out;
|
||
}
|
||
|
||
@mixin hover-lift {
|
||
transition: transform $duration-fast $ease-out, box-shadow $duration-fast $ease-out;
|
||
&:hover {
|
||
transform: translateY(-2px);
|
||
box-shadow: $shadow-md;
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 组件设计指南
|
||
|
||
### 6.1 基础组件清单
|
||
|
||
#### Button 按钮
|
||
```typescript
|
||
interface ButtonProps {
|
||
variant: 'primary' | 'secondary' | 'outline' | 'ghost' | 'danger';
|
||
size: 'sm' | 'md' | 'lg';
|
||
icon?: ReactNode;
|
||
iconPosition?: 'left' | 'right';
|
||
loading?: boolean;
|
||
disabled?: boolean;
|
||
fullWidth?: boolean;
|
||
children: ReactNode;
|
||
onClick?: () => void;
|
||
}
|
||
```
|
||
|
||
**样式规范**:
|
||
- Primary: 蓝色填充背景 `#1565C0`，白色文字
|
||
- Secondary: 白色背景，蓝色边框和文字
|
||
- Outline: 透明背景，灰色边框
|
||
- Ghost: 无边框，悬停显示背景
|
||
- Danger: 红色填充背景
|
||
|
||
#### Input 输入框
|
||
```typescript
|
||
interface InputProps {
|
||
type: 'text' | 'password' | 'email' | 'number';
|
||
size: 'sm' | 'md' | 'lg';
|
||
placeholder?: string;
|
||
prefix?: ReactNode; // 前置图标
|
||
suffix?: ReactNode; // 后置图标/清除按钮
|
||
error?: string;
|
||
disabled?: boolean;
|
||
value: string;
|
||
onChange: (value: string) => void;
|
||
}
|
||
```
|
||
|
||
#### Select 下拉选择
|
||
```typescript
|
||
interface SelectProps<T> {
|
||
options: Array<{ label: string; value: T }>;
|
||
value: T;
|
||
onChange: (value: T) => void;
|
||
placeholder?: string;
|
||
multiple?: boolean;
|
||
searchable?: boolean;
|
||
disabled?: boolean;
|
||
}
|
||
```
|
||
|
||
#### Table 表格
|
||
```typescript
|
||
interface TableProps<T> {
|
||
columns: Array<{
|
||
key: string;
|
||
title: string;
|
||
width?: number;
|
||
sortable?: boolean;
|
||
render?: (value: any, record: T) => ReactNode;
|
||
}>;
|
||
data: T[];
|
||
loading?: boolean;
|
||
pagination?: PaginationConfig;
|
||
rowSelection?: {
|
||
selectedRowKeys: string[];
|
||
onChange: (keys: string[]) => void;
|
||
};
|
||
onRowClick?: (record: T) => void;
|
||
}
|
||
```
|
||
|
||
#### Modal 弹窗
|
||
```typescript
|
||
interface ModalProps {
|
||
visible: boolean;
|
||
title: string;
|
||
width?: number;
|
||
onClose: () => void;
|
||
onConfirm?: () => void;
|
||
confirmText?: string;
|
||
cancelText?: string;
|
||
loading?: boolean;
|
||
children: ReactNode;
|
||
}
|
||
```
|
||
|
||
#### Card 卡片
|
||
```typescript
|
||
interface CardProps {
|
||
title?: string;
|
||
extra?: ReactNode; // 右上角操作区
|
||
padding?: boolean;
|
||
shadow?: boolean;
|
||
children: ReactNode;
|
||
}
|
||
```
|
||
|
||
### 6.2 布局组件
|
||
|
||
#### Sidebar 侧边栏
|
||
```typescript
|
||
interface SidebarProps {
|
||
collapsed: boolean;
|
||
onCollapse: (collapsed: boolean) => void;
|
||
activeKey: string;
|
||
menuItems: Array<{
|
||
key: string;
|
||
icon: ReactNode;
|
||
label: string;
|
||
path: string;
|
||
badge?: number;
|
||
}>;
|
||
}
|
||
```
|
||
|
||
**菜单项结构**:
|
||
```typescript
|
||
const menuItems = [
|
||
{ key: 'dashboard', icon: <DashboardIcon />, label: '仪表板', path: '/dashboard' },
|
||
{ key: 'users', icon: <UsersIcon />, label: '用户管理', path: '/users' },
|
||
{ key: 'leaderboard', icon: <TrophyIcon />, label: '龙虎榜', path: '/leaderboard' },
|
||
{ key: 'authorization', icon: <AuthIcon />, label: '授权管理', path: '/authorization' },
|
||
{ key: 'statistics', icon: <ChartIcon />, label: '数据统计', path: '/statistics' },
|
||
{ key: 'settings', icon: <SettingsIcon />, label: '系统设置', path: '/settings' },
|
||
// 底部固定
|
||
{ key: 'help', icon: <HelpIcon />, label: '帮助中心', path: '/help', position: 'bottom' },
|
||
{ key: 'logout', icon: <LogoutIcon />, label: '退出登录', path: '/logout', position: 'bottom' },
|
||
];
|
||
```
|
||
|
||
#### Header 顶部栏
|
||
```typescript
|
||
interface HeaderProps {
|
||
title: string;
|
||
breadcrumb: Array<{ label: string; path?: string }>;
|
||
actions?: ReactNode;
|
||
user: {
|
||
name: string;
|
||
role: string;
|
||
avatar: string;
|
||
};
|
||
notifications?: number;
|
||
}
|
||
```
|
||
|
||
### 6.3 图表组件
|
||
|
||
#### StatCard 统计卡片
|
||
```typescript
|
||
interface StatCardProps {
|
||
title: string;
|
||
value: number | string;
|
||
suffix?: string; // "棵", "人"
|
||
change?: {
|
||
value: number;
|
||
trend: 'up' | 'down';
|
||
};
|
||
icon?: ReactNode;
|
||
color?: string;
|
||
}
|
||
```
|
||
|
||
**视觉规范**:
|
||
- 卡片白色背景，8px 圆角
|
||
- 数字使用 `$font-family-number`，32px 字号
|
||
- 增长指标使用绿色，下降使用红色
|
||
- 带 `+` 或 `-` 前缀
|
||
|
||
#### LineChart 折线图
|
||
```typescript
|
||
interface LineChartProps {
|
||
data: Array<{ x: string; y: number }>;
|
||
xAxisKey: string;
|
||
yAxisKey: string;
|
||
color?: string;
|
||
gradient?: boolean; // 面积渐变填充
|
||
height?: number;
|
||
}
|
||
```
|
||
|
||
#### BarChart 柱状图
|
||
```typescript
|
||
interface BarChartProps {
|
||
data: Array<{ category: string; value: number }>;
|
||
colors?: string[];
|
||
horizontal?: boolean;
|
||
showLabels?: boolean;
|
||
height?: number;
|
||
}
|
||
```
|
||
|
||
#### DonutChart 环形图
|
||
```typescript
|
||
interface DonutChartProps {
|
||
data: Array<{ name: string; value: number; color: string }>;
|
||
innerRadius?: number;
|
||
outerRadius?: number;
|
||
centerContent?: ReactNode; // 中心显示内容
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 状态管理方案
|
||
|
||
### 7.1 Redux Toolkit (全局状态)
|
||
|
||
用于管理需要跨页面持久化的状态:
|
||
|
||
```typescript
|
||
// store/redux/slices/authSlice.ts
|
||
interface AuthState {
|
||
user: User | null;
|
||
token: string | null;
|
||
isAuthenticated: boolean;
|
||
permissions: string[];
|
||
}
|
||
|
||
// store/redux/slices/settingsSlice.ts
|
||
interface SettingsState {
|
||
sidebarCollapsed: boolean;
|
||
theme: 'light' | 'dark';
|
||
language: 'zh-CN' | 'en-US';
|
||
}
|
||
|
||
// store/redux/slices/notificationSlice.ts
|
||
interface NotificationState {
|
||
unreadCount: number;
|
||
notifications: Notification[];
|
||
}
|
||
```
|
||
|
||
### 7.2 Zustand (局部状态)
|
||
|
||
用于管理页面级别的临时状态:
|
||
|
||
```typescript
|
||
// store/zustand/useUserFiltersStore.ts
|
||
interface UserFiltersStore {
|
||
keyword: string;
|
||
province: string;
|
||
city: string;
|
||
status: string;
|
||
setKeyword: (keyword: string) => void;
|
||
setFilters: (filters: Partial<UserFilters>) => void;
|
||
resetFilters: () => void;
|
||
}
|
||
|
||
// store/zustand/useLeaderboardStore.ts
|
||
interface LeaderboardStore {
|
||
activeBoard: 'daily' | 'weekly' | 'monthly';
|
||
virtualSettings: VirtualSettings;
|
||
setActiveBoard: (board: string) => void;
|
||
updateVirtualSettings: (settings: Partial<VirtualSettings>) => void;
|
||
}
|
||
|
||
// store/zustand/useModalStore.ts
|
||
interface ModalStore {
|
||
activeModal: string | null;
|
||
modalData: any;
|
||
openModal: (name: string, data?: any) => void;
|
||
closeModal: () => void;
|
||
}
|
||
```
|
||
|
||
### 7.3 React Query (服务端状态)
|
||
|
||
用于管理 API 数据缓存:
|
||
|
||
```typescript
|
||
// hooks/useUsers.ts
|
||
export const useUsers = (filters: UserFilters) => {
|
||
return useQuery({
|
||
queryKey: ['users', filters],
|
||
queryFn: () => userService.getUsers(filters),
|
||
staleTime: 5 * 60 * 1000, // 5分钟缓存
|
||
});
|
||
};
|
||
|
||
// hooks/useStatistics.ts
|
||
export const useStatistics = (period: string) => {
|
||
return useQuery({
|
||
queryKey: ['statistics', period],
|
||
queryFn: () => statisticsService.getOverview(period),
|
||
refetchInterval: 30 * 1000, // 30秒自动刷新
|
||
});
|
||
};
|
||
```
|
||
|
||
---
|
||
|
||
## 8. API 集成规范
|
||
|
||
### 8.1 API 客户端配置
|
||
|
||
```typescript
|
||
// infrastructure/api/client.ts
|
||
import axios from 'axios';
|
||
|
||
const apiClient = axios.create({
|
||
baseURL: process.env.NEXT_PUBLIC_API_BASE_URL,
|
||
timeout: 30000,
|
||
headers: {
|
||
'Content-Type': 'application/json',
|
||
},
|
||
});
|
||
|
||
// 请求拦截器
|
||
apiClient.interceptors.request.use((config) => {
|
||
const token = store.getState().auth.token;
|
||
if (token) {
|
||
config.headers.Authorization = `Bearer ${token}`;
|
||
}
|
||
return config;
|
||
});
|
||
|
||
// 响应拦截器
|
||
apiClient.interceptors.response.use(
|
||
(response) => response.data,
|
||
(error) => {
|
||
if (error.response?.status === 401) {
|
||
store.dispatch(logout());
|
||
router.push('/login');
|
||
}
|
||
return Promise.reject(error);
|
||
}
|
||
);
|
||
```
|
||
|
||
### 8.2 API 端点定义
|
||
|
||
```typescript
|
||
// infrastructure/api/endpoints.ts
|
||
export const API_ENDPOINTS = {
|
||
// 认证
|
||
AUTH: {
|
||
LOGIN: '/auth/login',
|
||
LOGOUT: '/auth/logout',
|
||
REFRESH: '/auth/refresh',
|
||
FORGOT_PASSWORD: '/auth/forgot-password',
|
||
},
|
||
|
||
// 用户管理
|
||
USERS: {
|
||
LIST: '/users',
|
||
DETAIL: (id: string) => `/users/${id}`,
|
||
UPDATE: (id: string) => `/users/${id}`,
|
||
EXPORT: '/users/export',
|
||
},
|
||
|
||
// 龙虎榜
|
||
LEADERBOARD: {
|
||
RANKINGS: '/leaderboard/rankings',
|
||
SETTINGS: '/leaderboard/settings',
|
||
EXPORT: '/leaderboard/export',
|
||
},
|
||
|
||
// 授权管理
|
||
AUTHORIZATION: {
|
||
PROVINCE_COMPANIES: '/authorization/province-companies',
|
||
CITY_COMPANIES: '/authorization/city-companies',
|
||
ASSESSMENT_RULES: '/authorization/assessment-rules',
|
||
LADDER_TARGETS: '/authorization/ladder-targets',
|
||
},
|
||
|
||
// 数据统计
|
||
STATISTICS: {
|
||
OVERVIEW: '/statistics/overview',
|
||
TREND: '/statistics/trend',
|
||
REGION: '/statistics/region',
|
||
OPERATIONS: '/statistics/operations',
|
||
REVENUE: '/statistics/revenue',
|
||
},
|
||
|
||
// 系统设置
|
||
SETTINGS: {
|
||
ALL: '/settings',
|
||
SETTLEMENT: '/settings/settlement',
|
||
LEADERBOARD: '/settings/leaderboard',
|
||
QUOTA: '/settings/quota',
|
||
ASSESSMENT: '/settings/assessment',
|
||
DISPLAY: '/settings/display',
|
||
SECURITY: '/settings/security',
|
||
},
|
||
|
||
// 帮助中心
|
||
HELP: {
|
||
DOCUMENTS: '/help/documents',
|
||
FAQ: '/help/faq',
|
||
SEARCH: '/help/search',
|
||
},
|
||
};
|
||
```
|
||
|
||
### 8.3 通用响应格式
|
||
|
||
```typescript
|
||
// types/api.types.ts
|
||
interface ApiResponse<T> {
|
||
code: number;
|
||
message: string;
|
||
data: T;
|
||
}
|
||
|
||
interface PaginatedResponse<T> {
|
||
code: number;
|
||
message: string;
|
||
data: {
|
||
list: T[];
|
||
pagination: {
|
||
current: number;
|
||
pageSize: number;
|
||
total: number;
|
||
};
|
||
};
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 9. 开发规范与约定
|
||
|
||
### 9.1 命名规范
|
||
|
||
```typescript
|
||
// 文件命名
|
||
components/Button/Button.tsx // PascalCase 组件
|
||
components/Button/Button.module.scss // 样式模块
|
||
hooks/useAuth.ts // camelCase hooks
|
||
utils/formatters.ts // camelCase 工具
|
||
types/user.types.ts // kebab-case 类型文件
|
||
|
||
// 变量命名
|
||
const userName = 'admin'; // camelCase 变量
|
||
const MAX_RETRY_COUNT = 3; // UPPER_SNAKE_CASE 常量
|
||
const UserRole = { ADMIN: 'admin' }; // PascalCase 枚举
|
||
|
||
// 组件命名
|
||
const UserListPage = () => {}; // PascalCase 组件
|
||
const useUserData = () => {}; // use 前缀 hooks
|
||
|
||
// CSS 类命名 (BEM 风格)
|
||
.button {}
|
||
.button--primary {}
|
||
.button--disabled {}
|
||
.button__icon {}
|
||
```
|
||
|
||
### 9.2 代码组织
|
||
|
||
```typescript
|
||
// 组件文件结构
|
||
// components/Button/Button.tsx
|
||
import { FC } from 'react';
|
||
import styles from './Button.module.scss';
|
||
import type { ButtonProps } from './Button.types';
|
||
|
||
// 1. 类型定义 (或单独文件)
|
||
// 2. 常量定义
|
||
// 3. 辅助函数
|
||
// 4. 组件定义
|
||
// 5. 导出
|
||
|
||
export const Button: FC<ButtonProps> = ({
|
||
variant = 'primary',
|
||
size = 'md',
|
||
children,
|
||
...props
|
||
}) => {
|
||
return (
|
||
<button
|
||
className={`${styles.button} ${styles[`button--${variant}`]} ${styles[`button--${size}`]}`}
|
||
{...props}
|
||
>
|
||
{children}
|
||
</button>
|
||
);
|
||
};
|
||
```
|
||
|
||
### 9.3 Git 提交规范
|
||
|
||
```bash
|
||
# 格式: <type>(<scope>): <subject>
|
||
|
||
feat(users): 添加用户列表分页功能
|
||
fix(auth): 修复登录token失效问题
|
||
style(button): 调整按钮hover状态样式
|
||
refactor(api): 重构API请求拦截器
|
||
docs(readme): 更新项目说明文档
|
||
test(users): 添加用户服务单元测试
|
||
chore(deps): 更新依赖版本
|
||
```
|
||
|
||
### 9.4 注释规范
|
||
|
||
```typescript
|
||
/**
|
||
* 用户服务类
|
||
* 处理所有用户相关的业务逻辑
|
||
*/
|
||
class UserService {
|
||
/**
|
||
* 获取用户列表
|
||
* @param filters - 筛选条件
|
||
* @param pagination - 分页参数
|
||
* @returns 用户列表响应
|
||
*/
|
||
async getUsers(
|
||
filters: UserFilters,
|
||
pagination: PaginationParams
|
||
): Promise<PaginatedResponse<User>> {
|
||
// TODO: 添加缓存优化
|
||
// FIXME: 处理边界情况
|
||
return apiClient.get(API_ENDPOINTS.USERS.LIST, {
|
||
params: { ...filters, ...pagination },
|
||
});
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 10. 开发优先级与里程碑
|
||
|
||
### Phase 1: 基础框架搭建 (Week 1-2)
|
||
|
||
**目标**: 完成项目基础架构和核心组件库
|
||
|
||
```
|
||
├── 项目初始化
|
||
│ ├── Next.js 15 项目创建
|
||
│ ├── TypeScript 配置
|
||
│ ├── ESLint + Prettier 配置
|
||
│ ├── 目录结构创建
|
||
│ └── 环境变量配置
|
||
│
|
||
├── 样式系统
|
||
│ ├── CSS 变量定义
|
||
│ ├── SCSS Mixins
|
||
│ ├── 全局样式重置
|
||
│ └── 字体引入
|
||
│
|
||
├── 基础组件 (10个)
|
||
│ ├── Button
|
||
│ ├── Input
|
||
│ ├── Select
|
||
│ ├── Table (基础版)
|
||
│ ├── Modal
|
||
│ ├── Card
|
||
│ ├── Badge
|
||
│ ├── Avatar
|
||
│ ├── Loading
|
||
│ └── Toast
|
||
│
|
||
└── 布局组件
|
||
├── Sidebar
|
||
├── Header
|
||
└── PageContainer
|
||
```
|
||
|
||
### Phase 2: 认证与仪表板 (Week 3)
|
||
|
||
**目标**: 完成登录流程和仪表板页面
|
||
|
||
```
|
||
├── 登录模块
|
||
│ ├── 登录页面 UI
|
||
│ ├── 表单验证
|
||
│ ├── 登录 API 集成
|
||
│ ├── Token 管理
|
||
│ └── 路由守卫
|
||
│
|
||
├── 仪表板模块
|
||
│ ├── 统计卡片组件
|
||
│ ├── 折线图组件
|
||
│ ├── 柱状图组件
|
||
│ ├── 环形图组件
|
||
│ ├── 最近活动列表
|
||
│ └── 数据获取与展示
|
||
│
|
||
└── 状态管理
|
||
├── Redux Store 配置
|
||
├── Auth Slice
|
||
└── React Query 配置
|
||
```
|
||
|
||
### Phase 3: 用户管理 (Week 4)
|
||
|
||
**目标**: 完成用户管理全部功能
|
||
|
||
```
|
||
├── 用户列表
|
||
│ ├── 表格组件完善
|
||
│ ├── 搜索功能
|
||
│ ├── 高级筛选
|
||
│ ├── 分页功能
|
||
│ └── 排序功能
|
||
│
|
||
├── 用户操作
|
||
│ ├── 查看详情弹窗
|
||
│ ├── 编辑用户
|
||
│ ├── 批量选择
|
||
│ └── 导出 Excel
|
||
│
|
||
└── Zustand 集成
|
||
└── 用户筛选状态管理
|
||
```
|
||
|
||
### Phase 4: 龙虎榜与授权 (Week 5-6)
|
||
|
||
**目标**: 完成龙虎榜和授权管理模块
|
||
|
||
```
|
||
├── 龙虎榜模块
|
||
│ ├── 日/周/月榜切换
|
||
│ ├── 排名表格
|
||
│ ├── 榜单开关
|
||
│ ├── 虚拟排名设置
|
||
│ ├── 显示设置
|
||
│ └── 导出功能
|
||
│
|
||
└── 授权管理模块
|
||
├── 省公司管理
|
||
├── 市公司管理
|
||
├── 考核规则配置
|
||
├── 限制规则设置
|
||
└── 阶梯目标表格
|
||
```
|
||
|
||
### Phase 5: 数据统计 (Week 7)
|
||
|
||
**目标**: 完成数据统计全部图表和报表
|
||
|
||
```
|
||
├── 统计概览
|
||
│ ├── 顶部统计卡片
|
||
│ └── 趋势图表
|
||
│
|
||
├── 详细统计
|
||
│ ├── 龙虎榜统计
|
||
│ ├── 区域数据统计
|
||
│ ├── 公司运营统计
|
||
│ └── 收益明细
|
||
│
|
||
└── 导出功能
|
||
├── 运营报表导出
|
||
└── 明细数据导出
|
||
```
|
||
|
||
### Phase 6: 系统设置与帮助 (Week 8)
|
||
|
||
**目标**: 完成系统设置和帮助中心
|
||
|
||
```
|
||
├── 系统设置
|
||
│ ├── 结算参数
|
||
│ ├── 龙虎榜设置
|
||
│ ├── 认种限额
|
||
│ ├── 考核规则
|
||
│ ├── 前端展示
|
||
│ └── 账号与安全
|
||
│
|
||
├── 帮助中心
|
||
│ ├── 搜索功能
|
||
│ ├── 推荐文档
|
||
│ ├── 文档列表
|
||
│ ├── FAQ
|
||
│ └── 联系支持
|
||
│
|
||
└── 全局功能
|
||
├── 通知系统
|
||
└── 操作日志
|
||
```
|
||
|
||
### Phase 7: 测试与优化 (Week 9-10)
|
||
|
||
**目标**: 完成测试、性能优化和上线准备
|
||
|
||
```
|
||
├── 测试
|
||
│ ├── 单元测试
|
||
│ ├── 集成测试
|
||
│ └── E2E 测试
|
||
│
|
||
├── 性能优化
|
||
│ ├── 代码分割
|
||
│ ├── 图片优化
|
||
│ ├── 缓存策略
|
||
│ └── Bundle 分析
|
||
│
|
||
└── 部署准备
|
||
├── CI/CD 配置
|
||
├── 环境配置
|
||
└── 监控接入
|
||
```
|
||
|
||
---
|
||
|
||
## 附录
|
||
|
||
### A. 图标资源
|
||
|
||
建议使用以下图标来源:
|
||
- 侧边栏菜单图标: 自定义 SVG 或 Lucide Icons
|
||
- 操作图标: 保持与 Figma 设计一致
|
||
|
||
### B. 第三方库版本
|
||
|
||
```json
|
||
{
|
||
"dependencies": {
|
||
"react": "^18.2.0",
|
||
"next": "^15.0.0",
|
||
"typescript": "^5.0.0",
|
||
"@reduxjs/toolkit": "^2.0.0",
|
||
"zustand": "^4.4.0",
|
||
"@tanstack/react-query": "^5.0.0",
|
||
"axios": "^1.6.0",
|
||
"recharts": "^2.10.0",
|
||
"xlsx": "^0.18.5",
|
||
"dayjs": "^1.11.0",
|
||
"clsx": "^2.0.0"
|
||
}
|
||
}
|
||
```
|
||
|
||
### C. 环境变量
|
||
|
||
```bash
|
||
# .env.local
|
||
NEXT_PUBLIC_API_BASE_URL=http://localhost:8080/api
|
||
NEXT_PUBLIC_APP_NAME=榴莲认种管理后台
|
||
NEXT_PUBLIC_VERSION=1.0.0
|
||
```
|
||
|
||
---
|
||
|
||
**文档版本**: 1.0.0
|
||
**最后更新**: 2024年
|
||
**维护者**: Claude Code
|