首次提交

docs/系统设计说明书.md

@@ -0,0 +1,442 @@
+# 寸进（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 | 成就系统、月度报告 | 成就墙、报告页面 |