shaguabijia-app-server/docs/后端技术实现.md

# 傻瓜比价 App Server — 后端技术实现

> 域名:`app-api.shaguabijia.com`(HTTPS,nginx 反代)
> 仓库:`shaguabijia-app-server`
> 当前版本:v0.1.0(登录模块)
> 最后更新:2026-05-23

---

## 1. 本次实施范围

本阶段目标是搭正式 App 后端的**账号与登录**能力,供 Android 正式版(`shaguabijia-app-android`)对接。

已实现:

| 能力 | 状态 | 说明 |
|---|---|---|
| 极光一键登录 | ✅ 已联调 | `loginToken` → 极光 REST 验真 → RSA 解密手机号 → 注册/登录 |
| 短信验证码登录 | ✅ mock 可用 | 开发阶段任意 6 位通过,便于无短信供应商时联调 |
| JWT 双 token | ✅ | access(2h) + refresh(30d) |
| 用户表 + ORM | ✅ | SQLAlchemy 2.0 + Alembic |
| `/me` 鉴权 | ✅ | Bearer access_token |
| 单元测试 | ✅ | health + sms 登录闭环 + refresh + 限流 |

未做(后续迭代):

- 真实短信供应商(阿里云/腾讯云)
- logout 服务端 token 黑名单(jti)
- 昵称/头像修改、注销账号
- PostgreSQL 生产切库(当前 SQLite 起步)

---

## 2. 与试验后台的关系

| 维度 | 试验后台 `shaguabijia-server` | 正式后台 `shaguabijia-app-server` |
|---|---|---|
| 域名 | `api.shaguabijia.com` | `app-api.shaguabijia.com` |
| 数据库 | stdlib sqlite3,手写 SQL | SQLAlchemy 2.0 + Alembic |
| 账号体系 | 仅占坑(phone 当 ID) | User 表 + JWT |
| 极光验 token | ✅ 有 | ✅ 移植并增强 |
| 短信登录 | ❌ | ✅ mock |
| 配置 | 硬编码 | pydantic-settings + `.env` |

**极光一键登录的核心逻辑**(REST 调用、RSA padding 试错顺序)直接参考试验后台 `app/api/auth.py`,
等价实现在 `app/core/jiguang.py`。

试验后台 RSA 私钥部署在服务器 `/opt/shaguabijia-server/secrets/jverify_rsa_private.pem`(不入 git)。
正式后台因原私钥不可用,在极光控制台**重新生成 1024-bit RSA 密钥对**并上传公钥。

---

## 3. 技术栈

| 维度 | 选型 | 说明 |
|---|---|---|
| 语言 | Python 3.11+ | 本地开发用 3.13 |
| Web | FastAPI 0.115+ | OpenAPI 自动生成 |
| ASGI | uvicorn[standard] | 生产 `--host 127.0.0.1 --port 8770` |
| ORM | SQLAlchemy 2.0 | Mapped 新风格 |
| 迁移 | Alembic | `render_as_batch` 兼容 SQLite |
| DB | SQLite | 生产可改 `DATABASE_URL` 切 PostgreSQL |
| Auth | PyJWT | HS256,access + refresh |
| 极光 | httpx + cryptography | REST 验 token + RSA 解密 |
| 配置 | pydantic-settings | `.env` 加载 |
| 测试 | pytest + httpx TestClient | 临时文件 SQLite |

---

## 4. 登录链路

### 4.1 极光一键登录(主路径)

```
Android SDK loginAuth
    → 客户端拿到 loginToken
    → POST /api/v1/auth/jverify-login  { login_token, operator }
    → 后端 POST 极光 loginTokenVerify (Basic Auth = AppKey:MasterSecret)
    → 极光返回 RSA 加密的手机号(base64)
    → 后端用私钥解密(PKCS1v15,实测电信 CT 走此 padding)
    → upsert User(phone 唯一) → 签 JWT → 返回 TokenWithUser
```

**关键配置**(与 Android 端必须一致):

| 项 | 值 |
|---|---|
| 包名 | `com.jishisongfu.shaguabijia` |
| 极光 AppKey | `966b451a8d9cfe12d173ea9d` |
| RSA 公钥 | 极光控制台「加密公钥」(1024-bit,≤220 字符) |
| RSA 私钥 | `secrets/jverify_rsa_private.pem`(不入 git) |

**RSA 密钥说明**:

- 密钥对由我方生成(`openssl genrsa 1024`),公钥上传极光控制台
- 极光控制台限制公钥长度 ≤220 字符,因此用 **1024-bit** 而非 2048-bit
- 私钥路径由 `JG_PRIVATE_KEY_PATH` 指定,懒加载;文件不存在时 `jverify-login` 返回 502

### 4.2 短信登录(mock 路径)

```
POST /api/v1/auth/sms/send   { phone }     → 60s 冷却,不真发短信
POST /api/v1/auth/sms/login  { phone, code } → 任意 6 位通过(SMS_MOCK=true)
    → upsert User → 签 JWT → 返回 TokenWithUser
```

### 4.3 Token 刷新

```
POST /api/v1/auth/refresh  { refresh_token }
    → 校验 refresh token → 签新 access+refresh 对
```

Android 端通过 OkHttp `Authenticator` 在 401 时自动调用。

---

## 5. 数据模型

### User 表

| 字段 | 类型 | 说明 |
|---|---|---|
| id | INTEGER PK | 自增 |
| phone | VARCHAR UNIQUE | 手机号,登录主键 |
| register_channel | VARCHAR | `jverify` / `sms` |
| nickname | VARCHAR NULL | 预留 |
| avatar_url | VARCHAR NULL | 预留 |
| status | VARCHAR | `active` / `disabled` |
| created_at | DATETIME | 注册时间 |
| last_login_at | DATETIME | 最近登录 |

`upsert_user_for_login`:phone 存在则更新 `last_login_at`,不存在则注册。

---

## 6. API 一览

| 方法 | 路径 | 鉴权 | 说明 |
|---|---|---|---|
| GET | `/health` | 无 | 健康检查 |
| POST | `/api/v1/auth/jverify-login` | 无 | 极光一键登录 |
| POST | `/api/v1/auth/sms/send` | 无 | 发短信(mock) |
| POST | `/api/v1/auth/sms/login` | 无 | 短信登录 |
| POST | `/api/v1/auth/refresh` | 无 | 刷新 token |
| GET | `/api/v1/auth/me` | Bearer | 当前用户 |
| POST | `/api/v1/auth/logout` | Bearer | 登出占位 |

Swagger UI: `http://localhost:8770/docs`

---

## 7. 目录结构

```
app/
├── main.py                 # FastAPI 入口,lifespan,CORS
├── core/
│   ├── config.py           # pydantic-settings
│   ├── security.py         # JWT 签发/校验
│   ├── jiguang.py          # 极光 REST + RSA 解密
│   └── sms.py              # 短信 mock(内存验证码)
├── db/
│   ├── base.py
│   └── session.py          # engine + get_db
├── models/user.py
├── schemas/auth.py
├── crud/user.py
└── api/
    ├── deps.py             # get_current_user
    └── v1/auth.py          # 登录路由

alembic/                    # 数据库迁移
deploy/                     # systemd + nginx
secrets/                    # RSA 私钥(不入 git)
tests/                      # pytest
```

---

## 8. 本地联调(真机 + LAN)

后端监听所有网卡,供同一 WiFi 下的测试机访问:

```bash
source .venv/bin/activate
uvicorn app.main:app --host 0.0.0.0 --port 8770 --reload
```

Android debug 包 `BASE_URL` 指向开发机 LAN IP(配置在 `local.properties`,不入 git):

```
debug.api.host=192.168.x.x
debug.api.port=8770
```

真机浏览器访问 `http://192.168.x.x:8770/health` 应返回 `{"status":"ok"}`。

---

## 9. 部署要点

```bash
# 代码同步(排除 secrets 和 data)
rsync -avz --exclude='.venv' --exclude='data' --exclude='secrets/*.pem' \
    ./ server:/opt/shaguabijia-app-server/

# 私钥单独 scp(仅首次或轮换时)
scp secrets/jverify_rsa_private.pem server:/opt/shaguabijia-app-server/secrets/

# 迁移 + 重启
ssh server "cd /opt/shaguabijia-app-server && .venv/bin/alembic upgrade head && systemctl restart shaguabijia-app-server"
```

生产 checklist:

- [ ] `JWT_SECRET_KEY` 换成随机长字符串
- [ ] `APP_ENV=prod`, `APP_DEBUG=false`
- [ ] RSA 私钥权限 `chmod 600`
- [ ] nginx SSL 证书有效
- [ ] `alembic upgrade head` 已执行

---

## 10. 已知问题与后续

| 项 | 说明 |
|---|---|
| logout 无服务端失效 | 目前靠客户端清 token;后续可加 jti 黑名单表 |
| SMS 为 mock | 上线前需接真实短信供应商并设 `SMS_MOCK=false` |
| SQLite 并发 | 生产流量上来后切 PostgreSQL,只改 `DATABASE_URL` |
| 极光 RSA 1024-bit | 极光控制台限制所致;仅加密 11 位手机号,可接受 |

---

## 11. 联调验证记录(2026-05-23)

本地 LAN 联调已通过:

```
# 短信登录
POST /api/v1/auth/sms/login → 200, user_id=2, phone=177****82

# 极光一键登录
POST /api/v1/auth/jverify-login → 200, operator=CT, token_len=448
[JG] decrypted with padding=PKCS1v15
jverify_login ok user_id=3, phone=153****91
```

Android 端包名、签名、极光 AppKey 与控制台一致,SDK init 8000,loginAuth 6000。