# 榴莲认种管理后台 (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 { options: Array<{ label: string; value: T }>; value: T; onChange: (value: T) => void; placeholder?: string; multiple?: boolean; searchable?: boolean; disabled?: boolean; } ``` #### Table 表格 ```typescript interface TableProps { 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: , label: '仪表板', path: '/dashboard' }, { key: 'users', icon: , label: '用户管理', path: '/users' }, { key: 'leaderboard', icon: , label: '龙虎榜', path: '/leaderboard' }, { key: 'authorization', icon: , label: '授权管理', path: '/authorization' }, { key: 'statistics', icon: , label: '数据统计', path: '/statistics' }, { key: 'settings', icon: , label: '系统设置', path: '/settings' }, // 底部固定 { key: 'help', icon: , label: '帮助中心', path: '/help', position: 'bottom' }, { key: 'logout', icon: , 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) => void; resetFilters: () => void; } // store/zustand/useLeaderboardStore.ts interface LeaderboardStore { activeBoard: 'daily' | 'weekly' | 'monthly'; virtualSettings: VirtualSettings; setActiveBoard: (board: string) => void; updateVirtualSettings: (settings: Partial) => 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 { code: number; message: string; data: T; } interface PaginatedResponse { 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 = ({ variant = 'primary', size = 'md', children, ...props }) => { return ( ); }; ``` ### 9.3 Git 提交规范 ```bash # 格式: (): 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> { // 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