zeronline
447 lines
17 KiB
Markdown
447 lines
17 KiB
Markdown
# 寸进（InchStep）前端架构文档
|
||
|
||
> 文档版本：v1.0
|
||
> Web 端：Next.js + TypeScript + App Router
|
||
> 移动端 App：React Native
|
||
> 微信小程序：原生 / Taro
|
||
> 管理后台：React + TypeScript
|
||
> 更新日期：2026-06-24
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
1. 文档概述
|
||
2. 三端架构总览
|
||
3. Web 端架构（Next.js）
|
||
4. 移动端 App 架构（React Native）
|
||
5. 微信小程序架构
|
||
6. 管理后台架构
|
||
7. 共享层设计
|
||
8. 页面路由设计
|
||
9. 状态管理规范
|
||
|
||
---
|
||
|
||
## 1. 文档概述
|
||
|
||
本文档定义寸进平台前端三端（Web / App / 小程序）和管理后台的架构设计、页面路由、组件规范和状态管理策略。三端功能对齐、同步上线，通过 shared/ 层共享类型定义与常量。
|
||
|
||
---
|
||
|
||
## 2. 三端架构总览
|
||
|
||
`
|
||
┌──────────────────────────────────────────────────────────────────┐
|
||
│ shared/ 层 │
|
||
│ ┌──────────────────┐ ┌──────────────────┐ ┌───────────────┐ │
|
||
│ │ types/ │ │ constants/ │ │ utils/ │ │
|
||
│ │ TypeScript 类型 │ │ 分类/积分/成就 │ │ 日期格式化 │ │
|
||
│ │ 接口定义 │ │ 分页/隐私级别 │ │ 校验函数 │ │
|
||
│ └──────────────────┘ └──────────────────┘ └───────────────┘ │
|
||
└──────────────────────────────────────────────────────────────────┘
|
||
│ │ │
|
||
▼ ▼ ▼
|
||
┌──────────────────┐ ┌──────────────────┐ ┌─────────────────────┐
|
||
│ Web 端 │ │ 移动端 App │ │ 微信小程序 │
|
||
│ Next.js │ │ React Native │ │ 原生 / Taro │
|
||
│ │ │ │ │ │
|
||
│ ┌────────────┐ │ │ ┌────────────┐ │ │ ┌──────────────┐ │
|
||
│ │ App Router │ │ │ │ 导航 │ │ │ │ 页面路由 │ │
|
||
│ │ 页面路由 │ │ │ │ TabBar │ │ │ │ TabBar │ │
|
||
│ └────────────┘ │ │ └────────────┘ │ │ └──────────────┘ │
|
||
│ ┌────────────┐ │ │ ┌────────────┐ │ │ ┌──────────────┐ │
|
||
│ │ 组件 │ │ │ │ 组件 │ │ │ │ 自定义组件 │ │
|
||
│ │ CheckInCard │ │ │ │ CheckInCard│ │ │ │ 打卡卡片 │ │
|
||
│ │ 图表/排行 │ │ │ │ 图表/排行 │ │ │ │ 排行榜 │ │
|
||
│ └────────────┘ │ │ └────────────┘ │ │ └──────────────┘ │
|
||
│ ┌────────────┐ │ │ ┌────────────┐ │ │ ┌──────────────┐ │
|
||
│ │ 服务层 │ │ │ │ 服务层 │ │ │ │ API Client │ │
|
||
│ │ API Client │ │ │ │ API Client │ │ │ │ 请求封装 │ │
|
||
│ └────────────┘ │ │ └────────────┘ │ │ └──────────────┘ │
|
||
└──────────────────┘ └──────────────────┘ └─────────────────────┘
|
||
│ │ │
|
||
└────────────────────────┼────────────────────────┘
|
||
│ HTTP REST
|
||
▼
|
||
┌──────────────────┐
|
||
│ 后端 API 服务 │
|
||
│ Go + Gin │
|
||
└──────────────────┘
|
||
`
|
||
|
||
---
|
||
|
||
## 3. Web 端架构（Next.js）
|
||
|
||
### 3.1 目录结构
|
||
|
||
`
|
||
web/
|
||
├── src/
|
||
│ ├── app/ # Next.js App Router 页面
|
||
│ │ ├── layout.tsx # 根布局
|
||
│ │ ├── page.tsx # 首页（待打卡列表）
|
||
│ │ ├── login/ # 登录页
|
||
│ │ ├── checkin/
|
||
│ │ │ ├── [id]/ # 打卡项详情
|
||
│ │ │ ├── create/ # 创建打卡项
|
||
│ │ │ └── calendar/ # 日历视图
|
||
│ │ ├── social/
|
||
│ │ │ ├── feed/ # 动态广场
|
||
│ │ │ ├── friends/ # 好友列表
|
||
│ │ │ └── groups/[id]/ # 小组详情
|
||
│ │ ├── profile/ # 个人主页
|
||
│ │ ├── leaderboard/ # 排行榜
|
||
│ │ └── achievements/ # 成就墙
|
||
│ ├── components/ # 共享 UI 组件
|
||
│ │ ├── CheckInCard.tsx # 打卡卡片
|
||
│ │ ├── CalendarView.tsx # 日历视图
|
||
│ │ ├── StreakBadge.tsx # 连续天数徽标
|
||
│ │ ├── PointDisplay.tsx # 积分展示
|
||
│ │ ├── FeedCard.tsx # 动态卡片
|
||
│ │ ├── LeaderBoard.tsx # 排行榜
|
||
│ │ ├── CategoryIcon.tsx # 分类图标
|
||
│ │ └── Layout/
|
||
│ │ ├── NavBar.tsx # 导航栏
|
||
│ │ └── TabBar.tsx # 底部 Tab
|
||
│ ├── services/ # API 客户端
|
||
│ │ ├── api.ts # 通用请求封装（fetch/Axios）
|
||
│ │ ├── auth.ts # 认证相关
|
||
│ │ ├── checkin.ts # 打卡相关
|
||
│ │ └── social.ts # 社交相关
|
||
│ └── utils/ # 工具函数
|
||
│ ├── date.ts # 日期格式化（moment/dayjs）
|
||
│ └── storage.ts # localStorage 封装
|
||
├── __tests__/
|
||
└── package.json
|
||
`
|
||
|
||
### 3.2 路由设计
|
||
|
||
| 路径 | 页面 | 说明 |
|
||
|------|------|------|
|
||
| / | 首页 | 今日待打卡列表 + 快捷打卡 |
|
||
| /login | 登录页 | 手机号登录/注册 |
|
||
| /checkin/[id] | 打卡项详情 | 日历视图 + 统计 |
|
||
| /checkin/create | 创建打卡项 | 表单 |
|
||
| /social/feed | 动态广场 | Feed 流 |
|
||
| /social/friends | 好友列表 | |
|
||
| /social/groups/[id] | 小组详情 | 成员看板 |
|
||
| /profile | 个人主页 | 成长档案 |
|
||
| /leaderboard | 排行榜 | 周榜/月榜 |
|
||
| /achievements | 成就墙 | 徽章网格 |
|
||
|
||
### 3.3 渲染策略
|
||
|
||
| 页面 | 策略 | 说明 |
|
||
|------|------|------|
|
||
| 登录页 | CSR | 客户端渲染 |
|
||
| 首页 | CSR + SWR | 客户端渲染，SWR 缓存 |
|
||
| 打卡详情 | CSR | 需认证 |
|
||
| 动态广场 | CSR + ISR | SSR 首屏，ISR 增量更新 |
|
||
| 个人主页 | CSR | 需认证 |
|
||
|
||
---
|
||
|
||
## 4. 移动端 App 架构（React Native）
|
||
|
||
### 4.1 目录结构
|
||
|
||
`
|
||
mobile/
|
||
├── src/
|
||
│ ├── modules/ # 功能模块
|
||
│ │ ├── auth/ # 登录/注册
|
||
│ │ ├── checkin/ # 打卡模块
|
||
│ │ │ ├── screens/ # 页面
|
||
│ │ │ ├── components/ # 模块专属组件
|
||
│ │ │ └── hooks/ # 自定义 Hooks
|
||
│ │ ├── social/ # 社交模块
|
||
│ │ ├── profile/ # 个人中心
|
||
│ │ ├── leaderboard/ # 排行榜
|
||
│ │ └── achievements/ # 成就墙
|
||
│ ├── components/ # 全局共享组件
|
||
│ │ ├── CheckInCard.tsx
|
||
│ │ ├── CalendarView.tsx
|
||
│ │ └── ...
|
||
│ ├── navigation/ # 导航配置
|
||
│ │ ├── RootNavigator.tsx # 根导航
|
||
│ │ ├── TabNavigator.tsx # 底部 Tab
|
||
│ │ └── types.ts # 导航类型
|
||
│ ├── services/ # API 客户端
|
||
│ │ ├── api.ts # Axios 封装
|
||
│ │ └── ...
|
||
│ └── utils/ # 工具函数
|
||
├── android/
|
||
├── ios/
|
||
├── __tests__/
|
||
└── package.json
|
||
`
|
||
|
||
### 4.2 导航结构
|
||
|
||
`
|
||
RootNavigator (Stack)
|
||
├── LoginScreen (未登录时展示)
|
||
└── MainTab (已登录)
|
||
├── Tab: 首页 → HomeStack
|
||
│ ├── HomeScreen (待打卡列表)
|
||
│ ├── CheckInDetailScreen
|
||
│ └── CheckInCreateScreen
|
||
├── Tab: 社交 → SocialStack
|
||
│ ├── FeedScreen (动态广场)
|
||
│ ├── FriendListScreen
|
||
│ └── GroupDetailScreen
|
||
├── Tab: 排行榜 → LeaderboardScreen
|
||
├── Tab: 成就 → AchievementScreen
|
||
└── Tab: 我的 → ProfileStack
|
||
├── ProfileScreen
|
||
├── SettingsScreen
|
||
└── AchievementWallScreen
|
||
`
|
||
|
||
### 4.3 平台特性
|
||
|
||
| 特性 | 实现方式 |
|
||
|------|----------|
|
||
| 推送通知 | Firebase Cloud Messaging (FCM) / APNs |
|
||
| 本地通知 | react-native-push-notification |
|
||
| 图片选择 | react-native-image-picker |
|
||
| 存储 | AsyncStorage |
|
||
| 状态管理 | React Context / Zustand |
|
||
| 日期处理 | dayjs（与 Web 一致） |
|
||
|
||
---
|
||
|
||
## 5. 微信小程序架构
|
||
|
||
### 5.1 目录结构
|
||
|
||
`
|
||
miniapp/
|
||
├── pages/
|
||
│ ├── index/ # 首页（待打卡列表）
|
||
│ ├── checkin/
|
||
│ │ ├── detail/ # 打卡项详情
|
||
│ │ └── create/ # 创建打卡项
|
||
│ ├── social/
|
||
│ │ ├── feed/ # 动态广场
|
||
│ │ └── friends/ # 好友列表
|
||
│ ├── profile/ # 个人主页
|
||
│ └── leaderboard/ # 排行榜
|
||
├── components/ # 自定义组件
|
||
│ ├── checkin-card/ # 打卡卡片组件
|
||
│ ├── calendar-view/ # 日历组件
|
||
│ └── nav-bar/ # 导航栏
|
||
├── services/ # API 客户端
|
||
│ └── api.js # wx.request 封装
|
||
├── utils/ # 工具函数
|
||
├── app.json # 小程序全局配置
|
||
├── app.js # 小程序入口
|
||
└── project.config.json # 项目配置
|
||
`
|
||
|
||
### 5.2 TabBar 配置
|
||
|
||
`json
|
||
{
|
||
"tabBar": {
|
||
"list": [
|
||
{ "pagePath": "pages/index/index", "text": "打卡", "iconPath": "..." },
|
||
{ "pagePath": "pages/social/feed/index", "text": "广场", "iconPath": "..." },
|
||
{ "pagePath": "pages/profile/index", "text": "我的", "iconPath": "..." }
|
||
]
|
||
}
|
||
}
|
||
`
|
||
|
||
### 5.3 小程序限制与适配
|
||
|
||
| 限制 | 应对方案 |
|
||
|------|----------|
|
||
| 包体积 ≤ 2MB | 使用分包加载：pages 按模块分包 |
|
||
| 无原生导航动画 | 使用 wx.navigateTo 标准动画 |
|
||
| 登录态管理 | wx.login + 后端自定义登录态 |
|
||
| 图片上传 | wx.uploadFile + CDN 直传 |
|
||
|
||
---
|
||
|
||
## 6. 管理后台架构
|
||
|
||
### 6.1 目录结构
|
||
|
||
`
|
||
admin/
|
||
├── src/
|
||
│ ├── pages/ # 页面
|
||
│ │ ├── Dashboard.tsx # 数据概览
|
||
│ │ ├── Users.tsx # 用户管理
|
||
│ │ ├── Posts.tsx # 动态审核
|
||
│ │ ├── Reports.tsx # 数据统计
|
||
│ │ └── Settings.tsx # 系统设置
|
||
│ ├── components/ # 通用组件
|
||
│ │ ├── Table.tsx
|
||
│ │ ├── SearchBar.tsx
|
||
│ │ └── StatCard.tsx
|
||
│ ├── services/ # API 客户端
|
||
│ └── utils/
|
||
├── __tests__/
|
||
└── package.json
|
||
`
|
||
|
||
### 6.2 功能页面
|
||
|
||
| 页面 | 功能 |
|
||
|------|------|
|
||
| 数据概览 | DAU、打卡量、注册量趋势 |
|
||
| 用户管理 | 用户列表、搜索、禁用 |
|
||
| 动态审核 | 内容审核、违规处理 |
|
||
| 数据统计 | 模块分布、活跃度分析 |
|
||
| 系统设置 | 推送配置、公告管理 |
|
||
|
||
---
|
||
|
||
## 7. 共享层设计
|
||
|
||
### 7.1 类型定义（shared/types/index.ts）
|
||
|
||
` ypescript
|
||
// 用户
|
||
interface IUser { id, phone?, nickname?, avatar?, bio?, motto?, privacy, points, createdAt }
|
||
|
||
// 打卡
|
||
interface ICheckInItem { id, userId, name, icon?, category, dailyGoal?, cycleType, privacy, status, createdAt }
|
||
interface ICheckInRecord { id, itemId, userId, checkDate, status, note?, images? }
|
||
type CheckInCategory = 'study' | 'health' | 'habit' | 'hobby' | 'goal'
|
||
type CycleType = 'daily' | 'weekly' | 'every_other_day' | 'custom'
|
||
type ItemStatus = 'active' | 'paused' | 'archived' | 'deleted'
|
||
type RecordStatus = 'normal' | 'makeup'
|
||
type PrivacyLevel = 1 | 2 | 3
|
||
|
||
// 社交
|
||
interface IGroup { id, name, cover?, intro?, type, maxMember }
|
||
interface ApiResponse<T> { code: number, message: string, data?: T }
|
||
`
|
||
|
||
### 7.2 常量定义（shared/constants/index.ts）
|
||
|
||
` ypescript
|
||
// 打卡分类
|
||
CHECKIN_CATEGORIES = { study: '学习成长', health: '健康生活', habit: '习惯自律', hobby: '兴趣爱好', goal: '目标任务' }
|
||
|
||
// 积分规则
|
||
POINTS = { CHECKIN: 1, STREAK_7: 5, STREAK_30: 20, GOAL_COMPLETE: 10, POST_SHARE: 2, COMMENT: 1, INVITE_USER: 15 }
|
||
|
||
// 成就列表
|
||
ACHIEVEMENTS = [{ id: 'first_checkin', name: '初露锋芒', rarity: 'bronze' }, ...]
|
||
|
||
// 分页
|
||
PAGE_SIZE = 20
|
||
|
||
// 隐私标签
|
||
PRIVACY_LABEL = { 1: '公开', 2: '仅好友可见', 3: '仅自己可见' }
|
||
`
|
||
|
||
### 7.3 共享方式
|
||
|
||
| 端 | 共享方式 |
|
||
|---|----------|
|
||
| Web 端 | TypeScript 路径别名：@shared/types |
|
||
| 移动端 App | 通过 npm link 或 monorepo（pnpm workspace）引用 |
|
||
| 微信小程序 | 手动复制类型文件（纯类型定义无运行时依赖） |
|
||
| 管理后台 | 与 Web 端同仓库，直接引用 |
|
||
|
||
---
|
||
|
||
## 8. 页面路由设计
|
||
|
||
### 8.1 全局导航结构
|
||
|
||
`
|
||
未登录
|
||
├── 登录页（手机号登录/注册）
|
||
└── 关于页
|
||
|
||
已登录（底部 TabBar）
|
||
├── 首页 Tab
|
||
│ ├── 待打卡列表（今日项 + 快捷打卡）
|
||
│ ├── 打卡项详情（日历 + 统计 + 编辑）
|
||
│ ├── 创建打卡项（表单）
|
||
│ └── 日历视图（按月切换 + 筛选）
|
||
│
|
||
├── 社交 Tab
|
||
│ ├── 动态广场（Feed 流）
|
||
│ ├── 好友列表（搜索 + 添加）
|
||
│ └── 小组详情（看板 + 成员）
|
||
│
|
||
├── 排行榜 Tab
|
||
│ ├── 好友榜
|
||
│ ├── 全平台榜
|
||
│ └── 小组榜
|
||
│
|
||
├── 成就 Tab
|
||
│ ├── 成就墙（网格展示）
|
||
│ └── 成就详情
|
||
│
|
||
└── 我的 Tab
|
||
├── 个人主页（成长档案）
|
||
├── 设置（隐私/通知/账号）
|
||
└── 关于
|
||
`
|
||
|
||
### 8.2 页面数据依赖
|
||
|
||
| 页面 | 需要的数据 | API 调用 |
|
||
|------|-----------|----------|
|
||
| 首页 | 今日打卡项列表、连续天数 | GET /checkin/items, GET /checkin/streak/:id |
|
||
| 打卡详情 | 打卡项信息、月度记录 | GET /checkin/items/:id, GET /checkin/records |
|
||
| 动态广场 | 公开动态列表 | GET /social/feed |
|
||
| 个人主页 | 用户信息、统计数据 | GET /users/profile, GET /checkin/stats/monthly |
|
||
| 排行榜 | 排名数据 | GET /leaderboard/*（规划中） |
|
||
| 成就墙 | 所有成就、用户成就 | GET /achievements, GET /achievements/mine |
|
||
|
||
---
|
||
|
||
## 9. 状态管理规范
|
||
|
||
### 9.1 推荐方案
|
||
|
||
| 端 | 状态管理 | 说明 |
|
||
|---|----------|------|
|
||
| Web 端 | React Context + SWR | SWR 管理服务端状态，Context 管理 UI 状态 |
|
||
| 移动端 App | Zustand | 轻量级、无 boilerplate |
|
||
| 微信小程序 | 全局 Data | 小程序原生状态管理 |
|
||
| 管理后台 | React Context | 简单全局状态 |
|
||
|
||
### 9.2 认证状态
|
||
|
||
` ypescript
|
||
// 三端统一的认证状态
|
||
interface AuthState {
|
||
token: string | null
|
||
user: IUser | null
|
||
isAuthenticated: boolean
|
||
}
|
||
|
||
// 登录流程
|
||
1. 检查 localStorage / AsyncStorage 中是否有 Token
|
||
2. 有 Token → 设置到请求头 → 获取用户信息
|
||
3. 无 Token → 跳转登录页
|
||
4. 登录成功 → 保存 Token → 更新状态
|
||
5. Token 过期 → 清除 Token → 跳转登录页
|
||
`
|
||
|
||
---
|
||
|
||
## 附录：三端差异对照
|
||
|
||
| 功能 | Web 端 | 移动端 App | 微信小程序 |
|
||
|------|--------|-----------|-----------|
|
||
| 导航 | Next.js Router | React Navigation | wx.navigateTo |
|
||
| HTTP 请求 | fetch / Axios | Axios | wx.request |
|
||
| 本地存储 | localStorage | AsyncStorage | wx.setStorageSync |
|
||
| 推送 | Browser Notification | FCM / APNs | 订阅消息 |
|
||
| 支付 | 支付宝/微信支付 | 内购 | 微信支付 |
|
||
| 图片 | next/image | react-native-image-picker | wx.chooseImage |
|