首次提交

2026-06-25 08:39:47 +08:00
parent 20a93c703a
commit c5cccd346b
169 changed files with 24720 additions and 0 deletions
@@ -0,0 +1,446 @@
+# 寸进（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 |