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