# 寸进（InchStep）系统设计说明书

> 文档版本：v1.0  
> 更新日期：2026-06-24  
> 对应后端：Go + Gin + GORM | 前端：Next.js / React Native / 微信小程序  
> 状态：正式初稿

---

## 目录

1. 文档概述
2. 系统架构
3. 技术选型与版本
4. 模块设计
5. 安全设计
6. 性能设计
7. 错误处理规范
8. 日志与监控

---

## 1. 文档概述

### 1.1 文档目的

本文档是寸进（InchStep）综合成长打卡平台的技术设计说明书，面向后端、前端、测试、运维工程师，提供系统架构、模块划分、关键技术决策的详细说明。

### 1.2 适用范围

覆盖寸进平台 v1.0 全部功能模块的技术设计，包括：
- 后端 API 服务的架构与模块设计
- 前端三端（Web / App / 小程序）的架构要点
- 数据库设计与数据流
- 安全、性能、监控等横切关注点

### 1.3 参考文档

| 文档 | 说明 |
|------|------|
| 寸进_InchStep_详细需求说明书.md | 产品需求与功能规格 |
| docs/API设计文档.md | API 接口详细定义 |
| docs/数据库设计文档.md | 数据库详细设计 |
| docs/前端架构文档.md | 前端三端架构设计 |
| AGENTS.md | 仓库编码规范与指南 |

---

## 2. 系统架构

### 2.1 架构总览

`
┌─────────────────────────────────────────────────────────────┐
│                        用户层                               │
│    PC/移动浏览器     iOS/Android App      微信小程序          │
└──────────────────────┬──────────────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────────────┐
│                      前端层                                 │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
│  │  Web 端  │  │ App 端   │  │ 小程序   │  │ 管理后台 │   │
│  │ Next.js  │  │ RN       │  │ 原生/Taro│  │ React    │   │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘   │
│       └──────────────┼─────────────┼──────────────┘          │
│                      │  shared/   │                         │
│              类型定义 / 常量 / 工具函数                       │
└──────────────────────┬──────────────────────────────────────┘
                       │ HTTP REST (JSON)
                       ▼
┌──────────────────────────────────────────────────────────────┐
│                    API 网关层                                │
│           Nginx 反向代理 / 负载均衡 / 限流                   │
└──────────────────────┬──────────────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────────────┐
│                   后端服务层（Go + Gin）                      │
│                                                              │
│  ┌──────────────────────────────────────────────────────┐   │
│  │                  中间件                               │   │
│  │    JWT 认证  │  CORS  │  错误处理  │  统一响应        │   │
│  └──────────────────────────────────────────────────────┘   │
│                                                              │
│  ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐   │
│  │ 路由层  │ │ 处理器  │ │ 服务层  │ │ 模型层  │ │ 配置层  │   │
│  │ router │ │handler │ │service │ │ model  │ │ config │   │
│  └────────┘ └───┬────┘ └───┬────┘ └───┬────┘ └────────┘   │
│                 │          │           │                     │
│                 └──────────┼───────────┘                    │
│                            │                                │
└────────────────────────────┼────────────────────────────────┘
                             │
          ┌──────────────────┼──────────────────┐
          ▼                  ▼                  ▼
┌───────────────┐  ┌───────────────┐  ┌──────────────────┐
│   MySQL 8.0   │  │   Redis 7     │  │   S3 对象存储    │
│  主数据库      │  │  缓存/会话    │  │  图片/视频       │
│  GORM ORM    │  │  排行榜       │  │  资源文件        │
└───────────────┘  └───────────────┘  └──────────────────┘
`

### 2.2 架构风格

- **前后端分离**：前端三端（Web / App / 小程序）通过 RESTful API 与后端通信
- **后端单体应用**：v1.0 采用单体架构，按业务划分为 service 层，便于未来拆分为微服务
- **共享代码层**：shared/ 目录存放 TypeScript 类型定义、常量和工具函数，三端复用

### 2.3 关键技术决策

| 决策 | 选择 | 理由 |
|------|------|------|
| 后端语言 | Go 1.22 | 高性能、静态类型、编译部署简单、并发模型优秀 |
| Web 框架 | Gin | Go 生态最流行的 HTTP 框架，性能优异，中间件丰富 |
| ORM | GORM | 功能完善、自动迁移、与 Prisma 映射直观 |
| 数据库 | MySQL 8.0 | 成熟稳定、文档丰富、utf8mb4 完整支持中文 |
| 缓存 | Redis 7 | 连续天数缓存、排行榜、会话管理 |
| 认证 | JWT (golang-jwt/v5) | 无状态、多端共享、7 天有效期 |
| 密码哈希 | bcrypt (cost=12) | 安全强度高，Go 标准库支持 |
| 前端 Web | Next.js + App Router | SSR / SSG 支持、良好的 SEO、React 生态 |
| 移动端 | React Native | 跨平台、与 Web 共享业务逻辑 |
| 小程序 | 原生 / Taro | 微信生态，按需选择 |

---

## 3. 技术选型与版本

### 3.1 后端依赖

| 包名 | 用途 | 版本 |
|------|------|------|
| github.com/gin-gonic/gin | HTTP 框架 | v1.10+ |
| gorm.io/gorm | ORM | v1.25+ |
| gorm.io/driver/mysql | MySQL 驱动 | v1.5+ |
| github.com/golang-jwt/jwt/v5 | JWT 认证 | v5.2+ |
| github.com/joho/godotenv | .env 加载 | v1.5+ |
| golang.org/x/crypto | bcrypt 密码哈希 | v0.23+ |
| github.com/go-playground/validator/v10 | 请求校验 | v10.20+ |
| github.com/gin-contrib/cors | 跨域 | v1.7+ |
| github.com/stretchr/testify | 测试断言 | v1.9+ |

### 3.2 开发环境

| 工具 | 版本要求 |
|------|----------|
| Go | 1.22+ |
| MySQL | 8.0+ |
| Redis | 7.x |
| Docker | 24.x + Docker Compose |
| Node.js | 18+（前端构建） |

---

## 4. 模块设计

### 4.1 模块总览

`
server/internal/
├── config/         配置加载 —— 从环境变量 + .env 读取
├── database/       数据库初始化 —— GORM 连接 + AutoMigrate
├── models/         数据模型 —— Go struct，映射到 9 张表
├── middleware/     中间件 —— JWT 认证 / CORS / 错误处理
├── services/       核心业务服务
│   ├── user_service.go       用户模块
│   ├── checkin_service.go    打卡模块
│   ├── points_service.go     积分与成就模块
│   └── social_service.go     社交模块
├── handlers/       HTTP 处理器
│   ├── user_handler.go
│   ├── checkin_handler.go
│   └── social_handler.go
└── router/         路由注册——统一管理所有 API 路由
`

### 4.2 用户模块（User）

**职责**：用户注册/登录、个人资料管理、账号注销

**服务接口**：

| 方法 | 说明 |
|------|------|
| RegisterByPhone(phone) | 手机号注册 |
| GetByPhone(phone) | 手机号查找用户 |
| GetByID(id) | 按 ID 获取用户 |
| UpdateProfile(id, updates) | 更新资料（昵称/头像/签名/隐私） |
| DeleteAccount(id) | 注销账号（清除敏感信息） |

**隐私级别**：1=公开、2=仅好友可见、3=仅自己可见

**账号注销流程**：
1. 用户发起注销请求
2. 服务端清除手机号、昵称、头像等敏感字段
3. 保留用户 ID 和关联的打卡记录（用于统计）
4. 返回注销成功

### 4.3 打卡模块（CheckIn）

**核心数据流**：

`
用户创建打卡项 → 每日打卡 → 生成打卡记录 → 计算连续天数 → 发放积分 → 检查成就
`

**打卡项状态机**：

`
    创建
      │
      ▼
 ┌────────┐  暂停   ┌────────┐  恢复   ┌────────┐
 │ active │───────→│ paused │───────→│ active │
 └───┬────┘        └────────┘        └────┬───┘
     │ 归档                                  │ 归档
     ▼                                      ▼
 ┌──────────┐     软删除     ┌──────────┐
 │ archived │─────────────→│ deleted  │
 └──────────┘              └──────────┘
`

**连续天数算法**（时区感知）：
1. 获取指定打卡项的所有记录，按日期降序排列
2. 检查最近一次打卡是否在 48 小时内
3. 从最近一天开始向前遍历，相邻日期差为 24 小时则累加
4. 遇到断签（日期差 > 24 小时）则停止
5. 以 Asia/Shanghai 时区计算，非 UTC

**补卡规则**：
- 仅允许补签最近 7 天的缺失记录
- 每月前 3 次免费
- 超出部分消耗 5 积分/次
- 补卡记录标记为 makeup 状态

### 4.4 积分与成就模块（Points）

**积分系统**：

| 事件 | 积分值 | 限制 |
|------|--------|------|
| 每日打卡 | +1 | 每日每项 1 次 |
| 连续 7 天 | +5 | 达到时一次性 |
| 连续 30 天 | +20 | 达到时一次性 |
| 目标完成 | +10 | — |
| 分享动态 | +2 | 每日上限 3 次 |
| 评论 | +1 | 每日上限 5 次 |
| 邀请注册 | +15 | 每月上限 5 人 |

**成就系统**：
- 10 个预定义成就徽章，3 种稀有度（铜/银/金）
- 成就初始化在服务启动时通过 InitAchievements() 执行
- 用户达成条件后调用 UnlockAchievement() 解锁
- 解锁后发送系统通知

### 4.5 社交模块（Social）

**好友关系模型**：双向确认机制

`
请求方 → 发送请求 → 待对方接受 → 建立双向好友
                               → 可选拒绝
`

**动态广场**：
- 动态发布时 privacy=1（公开）才会出现在广场
- 默认按时间倒序排列
- Likes 和 Comments 字段用计数器实现（减少 JOIN）

**小组模型**：
- 创建者自动成为管理员
- 支持公开加入和私密审核（v1.0 简化处理）
- 小组有成员人数上限（默认 50 人）

---

## 5. 安全设计

### 5.1 认证机制

| 机制 | 实现 |
|------|------|
| 令牌 | JWT (HS256)，7 天有效期 |
| 密码存储 | bcrypt，cost=12 |
| 令牌传递 | HTTP Header: Authorization: Bearer <token> |
| 公开路由 | 仅 /api/auth/* 和 /health 免认证 |

### 5.2 数据安全

| 安全措施 | 说明 |
|----------|------|
| 隐私数据保护 | 服务层根据 privacy 字段过滤查询 |
| 环境变量 | 敏感信息（数据库、JWT 密钥）通过环境变量注入 |
| .env 禁止提交 | .env* 在 .gitignore 中，仅提交 .env.example |
| 账号注销 | 清除手机号等个人敏感信息 |

### 5.3 API 安全

| 措施 | 说明 |
|------|------|
| 统一认证中间件 | 所有非公开路由默认需认证 |
| 请求校验 | 使用 ShouldBindJSON + validator 标签 |
| 统一响应格式 | ApiResponse{Code, Message, Data} |
| CORS | 允许跨域请求，生产环境限制来源 |

---

## 6. 性能设计

### 6.1 性能目标

| 指标 | 目标 |
|------|------|
| API 响应时间（P95） | ≤ 200ms |
| 打卡操作端到端 | ≤ 500ms |
| 日历视图加载 | ≤ 800ms |
| 首页加载 | ≤ 1s |
| 并发支持 | 1000 QPS |

### 6.2 缓存策略

| 数据 | 缓存位置 | 策略 |
|------|----------|------|
| 连续天数 | Redis | 打卡时更新，失效时从 DB 重建 |
| 排行榜 | Redis Sorted Set | 定时计算后写入 |
| JWT 黑名单 | Redis | TTL 与 Token 有效期一致 |

### 6.3 数据库优化

| 策略 | 说明 |
|------|------|
| 索引 | user_id、item_id、check_date 建索引 |
| 分页 | 动态广场使用 Offset + Limit |
| 连接池 | GORM 默认连接池，生产环境调整最大连接数 |
| 查询优化 | 避免 N+1，使用 Preload 预加载关联 |

---

## 7. 错误处理规范

### 7.1 统一响应格式

`json
{
  "code": 0,
  "message": "ok",
  "data": { ... }
}
`

### 7.2 错误码规范

| HTTP 状态 | code | 说明 |
|-----------|------|------|
| 200 | 0 | 成功 |
| 400 | 400 | 请求参数错误 |
| 401 | 401 | 未认证或令牌无效 |
| 404 | 404 | 资源不存在 |
| 409 | 409 | 资源冲突（如手机号已注册） |
| 500 | 500 | 服务器内部错误 |

### 7.3 错误处理流程

`
请求 → 中间件检查认证 → 处理器校验参数 → 服务层执行业务逻辑
                                         ↓
                                    ┌────────┐
                                    │ 成功？  │
                                    └───┬────┘
                                        │
                    ┌───────────────────┼───────────────────┐
                    ▼                   ▼                   ▼
              Success(c, data)    Error(c, status, msg)  c.Error(err)
`

---

## 8. 日志与监控

### 8.1 日志规范

| 级别 | 使用场景 |
|------|----------|
| INFO | 请求开始/结束、用户注册、打卡成功 |
| WARN | 参数校验失败、补卡近上限、查询慢 |
| ERROR | 数据库异常、JWT 解析失败、panic |

### 8.2 Health Check

- 路由：GET /health
- 返回：{"status": "ok"}
- 可用于 Kubernetes Liveness/Readiness Probe

### 8.3 监控指标（规划中）

| 指标 | 说明 |
|------|------|
| QPS | 每秒请求数 |
| P50/P95/P99 | 响应时间分布 |
| 错误率 | 5xx 占比 |
| 数据库连接数 | 活跃连接数 |
| Redis 命中率 | 缓存命中率 |

---

## 附录 A：项目结构总览

`
F:\myProject\InchStep\
├── docs/                       # 设计文档
│   ├── 寸进_InchStep_详细需求说明书.md
│   ├── 系统设计说明书.md         # 本文件
│   ├── API设计文档.md
│   └── 数据库设计文档.md
├── server/                     # 后端 API（Go + Gin + GORM）
│   ├── cmd/api/main.go         # 入口
│   ├── internal/
│   │   ├── config/             # 配置加载
│   │   ├── database/           # 数据库初始化
│   │   ├── models/             # 数据模型（9 张表）
│   │   ├── middleware/         # JWT / CORS / 错误处理
│   │   ├── services/           # 4 个核心服务
│   │   ├── handlers/           # HTTP 处理器
│   │   └── router/             # 路由注册
│   ├── go.mod / go.sum
│   ├── Dockerfile
│   └── .env.example
├── shared/                     # 三端共享代码
├── web/                        # Web 端（Next.js）
├── mobile/                     # 移动端 App（React Native）
├── miniapp/                    # 微信小程序
├── admin/                      # 管理后台（React）
├── docker/docker-compose.yml   # Docker 编排
└── scripts/                    # 项目工具脚本
`

## 附录 B：版本规划

| 版本 | 后端重点 | 前端重点 |
|------|----------|----------|
| v1.0 MVP | 用户 + 打卡 + 基础统计 API | 三端同步上线，打卡核心流程 |
| v1.1 | 社交 API（好友/动态/排行榜） | 动态广场、排行榜 UI |
| v1.2 | 小组 API、对战 API | 小组详情、对战界面 |
| v1.3 | 成就系统、月度报告 | 成就墙、报告页面 |