zeronline
443 lines
18 KiB
Markdown
443 lines
18 KiB
Markdown
# 寸进（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 | 成就系统、月度报告 | 成就墙、报告页面 |
|