liyong/inchstep
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c5cccd346bbd88ccaf6e5323dd95096a54918d33
inchstep/docs/系统设计说明书.md
T
zeronline c5cccd346b 首次提交
2026-06-25 08:39:47 +08:00

18 KiB
Raw Blame History

寸进（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
公开路由 仅 /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 成就系统、月度报告 成就墙、报告页面
Reference in New Issue View Git Blame Copy Permalink