# learn_git

**Repository Path**: wwanger/learn_git

## Basic Information

- **Project Name**: learn_git
- **Description**: 儿童打卡APP+后台管理
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-09
- **Last Updated**: 2026-07-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 家庭儿童打卡激励 App

一个帮助家庭培养儿童良好习惯的打卡激励应用，通过积分、徽章、心愿单等机制，让孩子在游戏化的体验中养成自律习惯。

## 目录

- [功能特性](#功能特性)
- [技术栈](#技术栈)
- [项目结构](#项目结构)
- [快速开始](#快速开始)
  - [环境要求](#环境要求)
  - [本地部署](#本地部署)
  - [局域网部署](#局域网部署)
- [API 接口](#api-接口)
- [数据库设计](#数据库设计)
- [移动端配置](#移动端配置)
  - [Android](#android)
  - [iOS](#ios)
- [部署指南](#部署指南)
- [开发文档](#开发文档)
- [许可证](#许可证)

## 功能特性

### 👧 儿童端
- **打卡任务**：每日任务列表，一键打卡完成
- **积分系统**：完成任务获得积分奖励
- **徽章成就**：达成目标解锁精美徽章
- **心愿单**：用积分兑换心仪礼品
- **连击奖励**：连续打卡获得额外奖励

### 👨‍👩‍👧 家长端
- **计划管理**：创建、编辑、启用/禁用任务计划
- **审核打卡**：确认孩子打卡真实性（可选模式）
- **积分调整**：灵活调整孩子积分
- **心愿审核**：审核并设置心愿积分和库存
- **家庭管理**：邀请家庭成员，管理家庭

### ⚙️ 系统特性
- **离线同步**：支持离线打卡，联网后自动同步
- **实时通知**：WebSocket 推送状态变更
- **多端支持**：Android / iOS 双平台
- **安全认证**：JWT + PIN 码双重验证

## 技术栈

### 后端
| 技术 | 版本 | 用途 |
|------|------|------|
| Spring Boot | 3.2.0 | 应用框架 |
| Spring Security | 6.x | 安全框架 |
| Spring Data JPA | 3.2.x | ORM框架 |
| Spring Data Redis | 3.2.x | Redis访问 |
| Spring WebSocket | 6.x | 实时通信 |
| PostgreSQL | 15 | 主数据库 |
| Redis | 7 | 缓存/会话 |
| MinIO | Latest | 对象存储 |
| JWT (jjwt) | 0.12.3 | 身份认证 |
| Flyway | 9.x | 数据库迁移 |

### Android
| 技术 | 版本 | 用途 |
|------|------|------|
| Kotlin | 1.9.x | 编程语言 |
| Jetpack Compose | 1.6.x | UI框架 |
| Room | 2.6.x | 本地数据库 |
| Retrofit | 2.9.x | 网络请求 |
| Hilt | 2.51.x | 依赖注入 |

### iOS
| 技术 | 版本 | 用途 |
|------|------|------|
| Swift | 6.0 | 编程语言 |
| SwiftUI | iOS 16+ | UI框架 |
| URLSession | iOS 16+ | 网络请求 |
| Keychain | iOS 16+ | 安全存储 |

## 项目结构

```
ForLearn/
├── backend/                          # Spring Boot 后端
│   ├── src/main/java/com/example/signin/
│   │   ├── controller/               # REST API 控制层
│   │   ├── service/                  # 业务逻辑层
│   │   ├── repository/               # 数据访问层
│   │   ├── entity/                   # JPA 实体类
│   │   ├── dto/                      # 数据传输对象
│   │   ├── config/                   # 配置类
│   │   ├── security/                 # 安全模块
│   │   └── exception/                # 异常处理
│   ├── src/main/resources/
│   │   ├── application.yml           # 应用配置
│   │   └── db/migration/             # Flyway 迁移脚本
│   └── pom.xml                       # Maven 依赖
│
├── android/                          # Android 客户端
│   └── app/src/main/
│       ├── java/com/example/signin/
│       │   ├── ui/                   # 界面层
│       │   ├── viewmodel/            # 视图模型
│       │   ├── data/                 # 数据层
│       │   │   ├── remote/           # 远程数据
│       │   │   ├── database/         # 本地数据库
│       │   │   └── repository/       # 仓库层
│       │   └── di/                   # 依赖注入
│       └── res/                      # 资源文件
│
├── ios/                              # iOS 客户端
│   └── SigninApp/
│       ├── Views/                    # 视图层
│       ├── ViewModel/                # 视图模型
│       ├── Data/                     # 数据层
│       │   ├── Model/                # 数据模型
│       │   ├── Network/              # 网络层
│       │   └── Storage/              # 存储层
│       └── SigninApp.xcodeproj       # Xcode 项目
│
├── docs/                             # 项目文档
│   ├── architecture.md               # 系统架构文档
│   ├── deployment.md                 # 部署指南
│   ├── android/android_architecture.md
│   ├── ios/ios_architecture.md
│   └── api/api_doc.md                # API 接口文档
│
├── docker-compose.yml                # Docker Compose 配置
└── README.md                         # 项目说明
```

## 快速开始

### 环境要求

| 工具 | 版本 |
|------|------|
| JDK | 17+ |
| Maven | 3.8+ |
| Docker | 20+ |
| Docker Compose | 2.0+ |
| Android Studio | Hedgehog+ |
| Xcode | 15+（仅 macOS） |

### 本地部署

```bash
# 1. 进入项目目录
cd ForLearn

# 2. 启动所有服务
docker-compose up -d

# 3. 查看服务状态
docker-compose ps

# 4. 测试服务
curl http://localhost:8080/api/v1/health
```

### 服务端口

| 服务 | 端口 | 说明 |
|------|------|------|
| 后端 API | 8080 | REST API 接口 |
| PostgreSQL | 5432 | 数据库 |
| Redis | 6379 | 缓存 |
| MinIO | 9000 | 对象存储 |
| MinIO 控制台 | 9001 | 管理界面 |

### 初始化 MinIO

首次启动后，访问 `http://localhost:9001`：
- 用户名：`minioadmin`
- 密码：`minioadmin`

创建名为 `signin` 的 Bucket。

### 局域网部署

如需在局域网内通过手机访问：

```cmd
# 获取本机 IP 地址
ipconfig

# 配置防火墙（Windows）
netsh advfirewall firewall add rule name="Signin App" dir=in action=allow protocol=TCP localport=8080
```

修改移动端配置文件中的服务器地址为你的局域网 IP。

## API 接口

完整 API 文档请参考 [docs/api/api_doc.md](docs/api/api_doc.md)

### 核心接口

| 模块 | 接口 | 方法 |
|------|------|------|
| 认证 | `/api/v1/auth/login` | POST |
| 认证 | `/api/v1/auth/send-code` | POST |
| 家庭 | `/api/v1/family` | GET/POST |
| 计划 | `/api/v1/plan` | GET/POST |
| 打卡 | `/api/v1/checkin` | GET/POST |
| 积分 | `/api/v1/point/balance` | GET |
| 心愿 | `/api/v1/wish` | GET/POST |
| 徽章 | `/api/v1/badge` | GET |

### 认证方式

```
Authorization: Bearer <access_token>
```

## 数据库设计

### 核心数据表

| 表名 | 说明 |
|------|------|
| `users` | 用户信息 |
| `families` | 家庭信息 |
| `family_members` | 家庭成员关系 |
| `plans` | 计划任务 |
| `checkins` | 打卡记录 |
| `point_balances` | 积分余额 |
| `point_transactions` | 积分流水 |
| `wishes` | 心愿列表 |
| `wish_redemptions` | 心愿兑换记录 |
| `badges` | 徽章定义 |
| `user_badges` | 用户徽章 |
| `streaks` | 连击记录 |

### 数据流转

```
用户注册 → 创建家庭 → 加入成员 → 创建计划 → 完成打卡 → 获得积分 → 兑换心愿
```

## 移动端配置

### Android

1. 使用 Android Studio 打开 `android/` 目录
2. 修改 `RetrofitClient.kt` 中的服务器地址：

```kotlin
private const val BASE_URL = "http://你的服务器IP:8080/api/v1/"
```

3. 构建并运行

### iOS

1. 使用 Xcode 打开 `ios/SigninApp.xcodeproj`
2. 修改 `APIClient.swift` 中的服务器地址：

```swift
private let baseURL = "http://你的服务器IP:8080/api/v1"
```

3. 在 `Info.plist` 中配置 ATS（局域网 HTTP）：

```xml
<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
    <key>NSAllowsLocalNetworking</key>
    <true/>
</dict>
```

4. 构建并运行

## 部署指南

详细部署文档请参考 [docs/deployment.md](docs/deployment.md)

### 服务器配置建议

| 配置 | 最低 | 推荐 |
|------|------|------|
| CPU | 2核 | 2核 |
| 内存 | 4GB | 8GB |
| 带宽 | 3Mbps | 5Mbps |
| 存储 | 40GB SSD | 80GB SSD |

### Docker Compose 部署

```bash
# 创建环境变量文件
cat > .env << EOF
DB_PASSWORD=your-password
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin
JWT_SECRET=your-256-bit-secret-key
SPRING_PROFILES_ACTIVE=prod
EOF

# 启动服务
docker-compose --env-file .env up -d
```

## 开发文档

| 文档 | 路径 |
|------|------|
| 系统架构 | [docs/architecture.md](docs/architecture.md) |
| 部署指南 | [docs/deployment.md](docs/deployment.md) |
| Android 架构 | [docs/android/android_architecture.md](docs/android/android_architecture.md) |
| iOS 架构 | [docs/ios/ios_architecture.md](docs/ios/ios_architecture.md) |
| API 文档 | [docs/api/api_doc.md](docs/api/api_doc.md) |

## 许可证

MIT License