shaguabijia-app-server/README.md

# shaguabijia-app-server

傻瓜比价正式 App 后端 — FastAPI + SQLAlchemy + JWT。

覆盖:**账号体系**(极光一键登录 / 短信登录 + JWT)、**福利钱包**(金币 / 现金 / 签到 / 任务 / 省钱战绩)、**微信提现**(商家转账到零钱)、**看广告发奖**(穿山甲 GroMore S2S 回调)、**美团 CPS**(领券透传 / 比价推荐)。

> 占坑期的试验后台 `shaguabijia-server` 是无状态 mock;本项目是正式版,引入账号体系、JWT 登录态、Alembic 迁移,SQLite 起步可平滑切 PostgreSQL。

**文档导航**(都在 [docs/](docs/README.md)):
- [docs/api/](docs/api/README.md) — **接口契约**(索引 + 一接口一文件)
- [docs/integrations/](docs/integrations/README.md) — **集成层**(SDK 签名 / 加解密 / 协议细节)
- [docs/后端技术实现.md](docs/后端技术实现.md) — **架构与链路**(分层、登录、CPS、数据模型)
- [docs/数据库迁移.md](docs/数据库迁移.md) — **数据库迁移**(Alembic 怎么建表 / 升级)

---

## 技术栈

| 维度 | 选型 | 说明 |
|---|---|---|
| 语言 | Python 3.11+ | |
| Web | FastAPI 0.115+ | |
| ASGI | uvicorn[standard] | |
| ORM | SQLAlchemy 2.0 | Mapped / DeclarativeBase 新风格 |
| 迁移 | Alembic | render_as_batch 兼容 SQLite |
| DB | SQLite 起步 | 切 PostgreSQL 只改 `DATABASE_URL` |
| Auth | JWT (PyJWT) | access(2h) + refresh(30d) |
| HTTP 客户端 | httpx | 调极光 / 微信 / 美团 / 穿山甲 |
| 加解密 | cryptography | 极光 RSA 解密、微信 V3 签名 / 敏感字段加密 |
| 微信支付 | 商家转账到零钱 V3 | 提现;懒加载商户证书 |
| 配置 | pydantic-settings | `.env` 加载 |
| 测试 | pytest + TestClient | |

---

## 架构分层

一个请求自上而下:**api(薄,收发) → integrations(外部 SDK) / repositories(数据) → models / db**。

- `api/v1/` 只做"解析请求 → 调 repositories/integration → 组装响应 + HTTP 错误码映射",不放重逻辑。
- **SDK 集成的重逻辑(签名 / 验签 / 加解密 / 外部 HTTP)一律在 `integrations/`**,换方案 / 换供应商只动这一层。
- 数据访问统一在 `repositories/`(早期叫 `crud/`,已并入)。

## 目录结构

```
shaguabijia-app-server/
├── app/
│   ├── main.py                FastAPI 入口:注册全部 router + /health + CORS + lifespan
│   ├── api/
│   │   ├── deps.py            共享依赖:get_current_user(Bearer 校验)、get_db
│   │   └── v1/                接口层(薄)
│   │       ├── auth.py        认证 6 端点(极光 / 短信 send+login / refresh / me / logout)
│   │       ├── wallet.py      钱包 / 提现 11 端点(余额 / 流水 / 兑换 / 绑微信 / 提现 / 查单)
│   │       ├── signin.py      签到 2 端点
│   │       ├── tasks.py       一次性任务 2 端点
│   │       ├── savings.py     省钱 3 端点(汇总 / 战绩 / 明细)
│   │       ├── ad.py          看广告发奖 3 端点(穿山甲回调 / 进度 / 联调发奖)
│   │       ├── coupon.py      领券透传 /coupon/step(转发 pricebot)
│   │       └── meituan.py     美团 CPS 3 端点(券列表 / feed / 换链)
│   ├── integrations/          外部服务 / SDK 客户端(重逻辑)
│   │   ├── jiguang.py         极光 REST 验 token + RSA 解密(多 padding 试错)
│   │   ├── sms.py             短信验证码(mock,进程内冷却表)
│   │   ├── meituan.py         美团 CPS 网关签名 + query_coupon / get_referral_link
│   │   ├── pangle.py          穿山甲激励视频发奖回调验签(SHA256)
│   │   └── wxpay.py           微信支付 V3 商家转账(提现)+ code 换 openid
│   ├── core/                  基础设施(无外部业务集成)
│   │   ├── config.py          Settings (pydantic-settings)
│   │   ├── security.py        JWT 签发 / 校验 / token 对
│   │   ├── ratelimit.py       同 IP 滑动窗口限流依赖
│   │   ├── rewards.py         发奖 / 兑换 / 提现额度等业务常量与换算
│   │   └── logging.py         统一日志配置
│   ├── repositories/          数据访问 + 事务(早期叫 crud,已并入)
│   │   ├── user.py            upsert_user_for_login 等
│   │   ├── wallet.py          账户 / 流水 / 兑换 / 提现单(调 integrations/wxpay)
│   │   ├── signin.py          签到记录 / 连续天数 / 档位
│   │   ├── task.py            一次性任务领取
│   │   ├── savings.py         省钱汇总 / 战绩 / 明细
│   │   └── ad_reward.py       看广告发奖(按 trans_id 幂等 + 每日上限)
│   ├── models/                ORM 表结构(user / wallet / signin / task / savings / ad_reward)
│   ├── schemas/               Pydantic 收发契约(auth / meituan / welfare / ad)
│   └── db/                    base.py(DeclarativeBase) + session.py(engine / get_db)
│
├── alembic/                   数据库迁移(versions/ 9 个迁移;文件名已去 hex 前缀,链靠文件内 down_revision)
├── alembic.ini
├── deploy/                    systemd(.service) + nginx(.conf)
├── secrets/                   不入 git:极光 RSA 私钥 / 微信支付证书
├── data/                      不入 git:SQLite 文件默认在这里
├── scripts/                   运维脚本(migrate 迁移 / 对账 / 重置签到·福利 / 模拟穿山甲回调)
├── tests/                     pytest(auth / health / welfare / withdraw / ad_reward / coupon_proxy)
├── docs/                      文档库(api/ + integrations/ + 技术实现 / 迁移 / 待办)
├── run.sh                     本地启动(自动先跑迁移再起服务)
├── pyproject.toml
├── .env.example
└── README.md
```

---

## API 接口

完整契约见 **[docs/api/README.md](docs/api/README.md)**(总览表 + 一接口一文件)。按组速览:

| 组 | 前缀 | 端点数 | 鉴权 |
|---|---|---|---|
| 健康检查 | `/health` | 1 | 无 |
| 认证 Auth | `/api/v1/auth` | 6 | 登录类无 / `me`·`logout` Bearer |
| 钱包·提现 Wallet | `/api/v1/wallet` | 11 | Bearer(`exchange-info` 无) |
| 签到 Signin | `/api/v1/signin` | 2 | Bearer |
| 任务 Tasks | `/api/v1/tasks` | 2 | Bearer |
| 省钱 Savings | `/api/v1/savings` | 3 | Bearer |
| 看广告发奖 Ad | `/api/v1/ad` | 3 | 回调验签 / 其余 Bearer |
| 领券 Coupon | `/api/v1/coupon` | 1 | Bearer |
| 美团 CPS Meituan | `/api/v1/meituan` | 3 | 无 |

登录类接口响应统一是 `TokenWithUser`(access/refresh token 对 + user);金额字段一律以**分**为单位(`*_cents`)。`APP_ENV` 非 prod 时开 `http://localhost:8770/docs`(Swagger UI)。

---

## 本地开发

### 1. 装依赖
```bash
cd shaguabijia-app-server
python3.11 -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
```

### 2. 配置
```bash
cp .env.example .env
# 至少改 JWT_SECRET_KEY;测美团填 MT_CPS_*;测提现填 WXPAY_*/WECHAT_*;测看广告填 PANGLE_*
```
测极光一键登录把 RSA 私钥放到 `./secrets/jverify_rsa_private.pem`(没放也不影响其他接口,只是 `jverify-login` 返 502)。

### 3. 建表 / 升级数据库
```bash
mkdir -p data            # SQLite 库目录
alembic upgrade head     # 按迁移链建到最新(幂等)
```
> 详见 [docs/数据库迁移.md](docs/数据库迁移.md)。只想迁移不启服务:`bash scripts/migrate.sh`。

### 4. 跑起来
```bash
./run.sh                 # 监听 0.0.0.0:8770,自动先跑迁移;改代码自动重启
# 或手动: uvicorn app.main:app --reload --port 8770
```
冒烟:
```bash
curl http://localhost:8770/health        # {"status":"ok"}
# mock 登录闭环
curl -X POST http://localhost:8770/api/v1/auth/sms/send  -H 'Content-Type: application/json' -d '{"phone":"13800138000"}'
curl -X POST http://localhost:8770/api/v1/auth/sms/login -H 'Content-Type: application/json' -d '{"phone":"13800138000","code":"123456"}'
curl http://localhost:8770/api/v1/auth/me -H "Authorization: Bearer <access_token>"
```

### 5. 测试
```bash
pytest -q
```

---

## 部署(生产)

部署到 `app-api.shaguabijia.com`(参考 `deploy/`):
```bash
# 后续更新
rsync -avz --exclude='__pycache__' --exclude='.venv' --exclude='data' --exclude='secrets/*' \
    ./ server:/opt/shaguabijia-app-server/

# 证书 / 私钥单独同步(首次 / 更换时):极光私钥 + 微信支付商户私钥·平台公钥
scp secrets/jverify_rsa_private.pem server:/opt/shaguabijia-app-server/secrets/

ssh server "
    cd /opt/shaguabijia-app-server &&
    .venv/bin/pip install --quiet -e . &&
    .venv/bin/alembic upgrade head &&
    systemctl restart shaguabijia-app-server
"
```
详见 `deploy/`。**看广告发奖上线**前对照 [docs/看广告赚金币上线清单.md](docs/看广告赚金币上线清单.md)(GroMore 回调配置、清理调试脚手架、端到端验收)。

---

## 与试验后台的差异(为什么不直接复用 shaguabijia-server)

| 维度 | 试验后台 (shaguabijia-server) | 本项目 (shaguabijia-app-server) |
|---|---|---|
| 数据库 | stdlib sqlite3,无 ORM | SQLAlchemy 2.0 + Alembic |
| 业务 | mock parse(无账号体系) | 账号 + 钱包 / 提现 / 签到 / 看广告 / CPS |
| 登录态 | 无,客户端发 phone 当 ID | JWT access + refresh |
| 配置 | 硬编码 | pydantic-settings + `.env` |
| 域名 | api.shaguabijia.com(试验) | app-api.shaguabijia.com(正式) |

极光一键登录的实现(REST 调用、RSA padding 试错顺序)参考自试验后台,逻辑等价。