# MAM

**Repository Path**: dantylee/mam

## Basic Information

- **Project Name**: MAM
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-30
- **Last Updated**: 2026-04-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MAM — Made Any Money? 💰

> 一个讨论赚钱了么的微信小程序。记录每一天的打卡，见证自己在赚钱路上的坚持。

> 技术栈：**uni-app（前端）+ FastAPI（后端）+ SQLite + Redis + Nginx + Docker**

## 项目结构

```
MAM/
├── backend/                 # FastAPI 后端
│   ├── app/
│   │   ├── api/v1/          # RESTful 路由层
│   │   │   ├── auth.py      # 认证接口
│   │   │   ├── checkin.py   # 打卡接口
│   │   │   └── user.py      # 用户接口
│   │   ├── core/
│   │   │   ├── config.py    # 配置管理
│   │   │   ├── security.py  # JWT + 密码工具
│   │   │   └── limiter.py   # slowapi 限流器
│   │   ├── db/              # 数据库配置
│   │   ├── models/          # SQLAlchemy 模型
│   │   ├── schemas/         # Pydantic Schema
│   │   ├── services/        # 业务逻辑层
│   │   └── main.py          # 应用入口
│   ├── Dockerfile
│   └── requirements.txt
├── frontend/                # uni-app 前端
│   ├── pages/
│   │   ├── login/           # 登录页
│   │   ├── index/           # 首页打卡
│   │   └── records/         # 打卡记录
│   ├── store/user.js        # Pinia 状态管理
│   ├── utils/
│   │   ├── api.js           # API 接口定义
│   │   └── request.js       # 请求封装
│   └── pages.json           # 页面路由配置
├── nginx/
│   └── nginx.conf           # Nginx 反向代理配置
├── docker-compose.yml       # Docker 编排
└── README.md
```

---

## 快速开始

### 一、后端部署（Docker）

#### 1. 配置环境变量

在服务器上创建 `.env` 文件：

```bash
cd /home/danty/workspace/MAM

cat > .env << 'EOF'
WX_APPID=你的小程序AppID
WX_SECRET=你的小程序密钥
JWT_SECRET_KEY=随机32位以上字符串（用于签名 JWT）
REDIS_PASSWORD=自定义Redis密码
APP_ENV=production
EOF
```

#### 2. 启动服务

```bash
cd /home/danty/workspace/MAM

# 首次启动（删除旧数据库，从干净状态开始）
docker-compose down
docker volume rm mam_db-data 2>/dev/null || true
docker-compose --env-file .env up -d

# 修改代码后重新部署
docker-compose build --no-cache backend
docker-compose up -d backend

# 查看日志确认启动成功
docker-compose logs backend | tail -30
docker-compose logs -f backend
```

#### 3. 验证后端

```bash
# 本地测试（服务器上执行）
curl http://localhost/health

# 服务器 IP 访问（浏览器访问）
# http://192.168.146.128/health
```

#### 4. 配置 Nginx SSL（可选，生产环境）

将 SSL 证书文件放到 `nginx/ssl/` 目录：
- `cert.pem`
- `cert.key`

腾讯云、阿里云均有免费 SSL 证书申请。

---

### 二、前端开发（uni-app）

#### 1. 安装依赖

```bash
cd frontend

# 使用 HBuilderX：
# 1. 打开 HBuilderX
# 2. 文件 → 导入 → 从本地项目导入 → 选择 frontend 目录
# 3. 顶部菜单：运行 → 运行到小程序模拟器 → 微信开发者工具

# 或使用命令行：
npm install
```

#### 2. 配置 API 地址

编辑 `frontend/utils/request.js`：
```js
// 开发环境：连接本地后端
const BASE_URL = 'http://localhost:8000/api/v1'

// 生产环境：连接服务器（替换为你的服务器地址）
const BASE_URL = 'https://your-domain.com/api/v1'
```

#### 3. 运行和调试

```bash
cd frontend

# 使用 HBuilderX：
# 顶部菜单：运行 → 运行到小程序模拟器 → 微信开发者工具

# 或使用微信开发者工具直接打开：
# 编译 uni-app 项目后，在微信开发者工具中打开 dist/dev/mp-weixin 目录
```

#### 4. 编译发布

```bash
cd frontend

# HBuilderX：发行 → 小程序-微信
# 或命令行：
npm run build:h5  # H5 版本
npm run build:mp-weixin  # 微信小程序
```

---

### 三、微信小程序配置

在微信公众平台（mp.weixin.qq.com）：
1. 开发管理 → 开发设置 → 服务器域名
2. 添加 `request 合法域名`：`https://your-domain.com`（生产环境）
3. 开发期间可先在微信开发者工具中勾选"不校验合法域名"

---

## API 接口文档（RESTful）

开发环境访问：`http://localhost:8000/docs`

| 资源 | 方法 | 路径 | 说明 |
|------|------|------|------|
| 认证 | POST | `/api/v1/auth/login` | 微信登录/注册 |
| 打卡 | POST | `/api/v1/checkins` | 今日打卡 |
| 打卡列表 | GET | `/api/v1/checkins` | 打卡记录列表（分页） |
| 打卡统计 | GET | `/api/v1/checkins/stats` | 打卡统计数据 |
| 用户信息 | GET | `/api/v1/users/me` | 获取当前用户信息 |
| 健康检查 | GET | `/health` | 服务健康状态 |

### 请求示例

**微信登录：**
```bash
curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"code": "微信返回的code"}'
```

**今日打卡：**
```bash
curl -X POST http://localhost:8000/api/v1/checkins \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"remark": "今天也要加油！"}'
```

**获取打卡列表：**
```bash
curl http://localhost:8000/api/v1/checkins?page=1&page_size=20 \
  -H "Authorization: Bearer <token>"
```

---

## 🛡️ 风控设计说明

### 1. 微信登录风控
- ✅ `code` **一次性消费**，不重复使用（微信官方保证）
- ✅ `session_key` **不入库、不缓存**，用后即弃
- ✅ `openid` 不直接暴露给前端，JWT 中存 `user_id`
- ✅ 登录接口 slowapi 限流 **10次/分钟/IP**（防爆破）
- ✅ 注册时记录 IP，便于后续异常排查

### 2. 接口限流（双层）
- **Nginx 层**（第一道）：`limit_req_zone` 精细限流
  - 登录接口：10次/分钟
  - 打卡接口：5次/分钟
  - 全局：10次/秒 burst=20
- **slowapi 层**（第二道）：基于 Redis，精准限流
  - 默认：60次/分钟
  - 登录：10次/分钟
  - 打卡：5次/分钟

### 3. 打卡防重复
- 数据库 `UniqueConstraint("user_id", "checkin_date")`
- 并发安全：捕获 `IntegrityError`，幂等返回

### 4. JWT 安全
- Token 有效期 7 天（可配置）
- 生产环境使用随机32位+ 密钥
- 不存储在 session（无状态）

### 5. 前端防刷
- 按钮防重复点击（2~3秒冷却）
- 401 自动清除 token 并跳转登录

### 6. Nginx 安全头
```
X-Frame-Options: DENY
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
server_tokens: off（隐藏版本号）
```

### 7. 生产环境额外建议
- [x] 关闭 `/docs`（已自动处理：`APP_ENV=production` 时关闭）
- [ ] 数据库迁移到 PostgreSQL
- [ ] 配置 fail2ban 封禁持续触发限流的 IP
- [ ] 定期轮换 JWT_SECRET_KEY（配合 token 刷新机制）
- [ ] 接入腾讯云 WAF 或宝塔防火墙