inchstep/docs/前端架构文档.md

寸进（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 { 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