docs: README 翻新到当前结构 + 上线清单改中文名 + 文档库导航补全

- README.md 翻新: 从 v0.1.0 登录模块版更新到当前(钱包/提现/签到/省钱/看广告/CPS); 目录结构按现状重写(integrations 含 pangle/wxpay、repositories 含全部数据访问、 core 含 ratelimit/rewards);API 改为按组速览 + 链 docs/api;建表步骤改为 alembic upgrade head(原步骤是过时的 autogenerate init);部署补微信支付证书同步 - docs/ad_reward_golive_checklist.md → docs/看广告赚金币上线清单.md(改中文名) - docs/README.md 文档库导航补 integrations/ + 数据库迁移.md + 看广告上线清单 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-27 21:10:44 +08:00
parent c61997b876
commit 9a2599bc3a
3 changed files with 98 additions and 114 deletions
@@ -2,10 +2,15 @@

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

-> 占坑期已有的试验后台 `shaguabijia-server` 是无状态 mock,本项目是正式版,
-> 引入账号体系、JWT 登录态、Alembic 迁移、SQLite 起步可平滑切 PostgreSQL。
+覆盖:**账号体系**(极光一键登录 / 短信登录 + JWT)、**福利钱包**(金币 / 现金 / 签到 / 任务 / 省钱战绩)、**微信提现**(商家转账到零钱)、**看广告发奖**(穿山甲 GroMore S2S 回调)、**美团 CPS**(领券透传 / 比价推荐)。

-详细技术说明见 [docs/后端技术实现.md](docs/后端技术实现.md)(登录链路、极光 RSA、部署 checklist)。
+> 占坑期的试验后台 `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 怎么建表 / 升级)

 ---

@@ -16,57 +21,75 @@
 | 语言 | Python 3.11+ | |
 | Web | FastAPI 0.115+ | |
 | ASGI | uvicorn[standard] | |
-| ORM | SQLAlchemy 2.0 | Mapped/DeclarativeBase 新风格 |
+| ORM | SQLAlchemy 2.0 | Mapped / DeclarativeBase 新风格 |
 | 迁移 | Alembic | render_as_batch 兼容 SQLite |
-| DB | SQLite | 后续切 PostgreSQL 只改 `DATABASE_URL` |
+| DB | SQLite 起步 | 切 PostgreSQL 只改 `DATABASE_URL` |
 | Auth | JWT (PyJWT) | access(2h) + refresh(30d) |
-| 极光一键登录 | httpx + cryptography | RSA 解密,逻辑参考试验后台 |
+| 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 入口 + /health + CORS
-│   ├── core/
+│   ├── 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)
-│   │   ├── logging.py         统一日志配置
 │   │   ├── security.py        JWT 签发 / 校验 / token 对
-│   │   ├── jiguang.py         极光 REST 调用 + RSA 解密
-│   │   └── sms.py             短信验证码 (mock 实现)
-│   ├── db/
-│   │   ├── base.py            DeclarativeBase
-│   │   └── session.py         engine + SessionLocal + get_db
-│   ├── models/
-│   │   └── user.py            User 表
-│   ├── schemas/
-│   │   └── auth.py            登录/Token 相关 Pydantic
-│   ├── repositories/         数据访问(早期叫 crud,已并入)
-│   │   └── user.py            upsert_user_for_login 等(+ 钱包/签到/任务/省钱/发奖)
-│   └── api/
-│       ├── deps.py            get_current_user (Bearer 校验)
-│       └── v1/
-│           └── auth.py        /api/v1/auth/* 路由
+│   │   ├── 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/                   迁移脚本
-│   ├── env.py
-│   ├── script.py.mako
-│   └── versions/              (空,第一次跑 alembic revision 生成)
+├── alembic/                   数据库迁移(versions/ 9 个迁移;文件名已去 hex 前缀,链靠文件内 down_revision)
 ├── alembic.ini
-│
-├── deploy/
-│   ├── shaguabijia-app-server.service   systemd unit
-│   └── nginx/
-│       └── app-api.shaguabijia.com.conf
-│
-├── secrets/                   不入 git。放 jverify_rsa_private.pem
-├── data/                      不入 git。SQLite 文件默认在这里
-├── tests/                     冒烟 + auth 流程
-│
+├── 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
@@ -76,98 +99,63 @@ shaguabijia-app-server/

 ## API 接口

-| 方法 | 路径 | 说明 | 鉴权 |
+完整契约见 **[docs/api/README.md](docs/api/README.md)**(总览表 + 一接口一文件)。按组速览:
+
+| 组 | 前缀 | 端点数 | 鉴权 |
 |---|---|---|---|
-| GET  | `/health` | 健康检查 | 无 |
-| POST | `/api/v1/auth/jverify-login` | 极光一键登录(`loginToken` → 注册即登录 → 签发 token 对) | 无 |
-| POST | `/api/v1/auth/sms/send` | 发短信验证码(mock 阶段任意 6 位通过) | 无 |
-| POST | `/api/v1/auth/sms/login` | 手机号+验证码登录 | 无 |
-| POST | `/api/v1/auth/refresh` | 用 `refresh_token` 换新的 token 对 | 无 |
-| GET  | `/api/v1/auth/me` | 获取当前登录用户 | `Bearer access_token` |
-| POST | `/api/v1/auth/logout` | 登出(占位,客户端清 token) | `Bearer access_token` |
+| 健康检查 | `/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 | 无 |

-登录类接口的响应统一格式:
-```json
-{
-  "access_token": "eyJxxx...",
-  "refresh_token": "eyJxxx...",
-  "token_type": "Bearer",
-  "expires_in": 7200,
-  "refresh_expires_in": 2592000,
-  "user": {
-    "id": 1,
-    "phone": "13800138000",
-    "nickname": null,
-    "avatar_url": null,
-    "register_channel": "jverify",
-    "status": "active",
-    "created_at": "2026-05-23T04:30:00Z",
-    "last_login_at": "2026-05-23T04:30:00Z"
-  }
-}
-```
-
-文档启动后看 `http://localhost:8770/docs` (Swagger UI)。
+登录类接口响应统一是 `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
+source .venv/bin/activate      # Windows: .venv\Scripts\activate
 pip install -e ".[dev]"
 ```

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

-如果要测极光一键登录,把 RSA 私钥放到 `./secrets/jverify_rsa_private.pem`。
-没放也不影响其他接口(`sms`/`/health` 等),只是 `jverify-login` 会 502。
-
-### 3. 建表(首次)
-
+### 3. 建表 / 升级数据库
 ```bash
-# 生成首版 migration(已有 User model,会自动生成 create_table)
-alembic revision --autogenerate -m "init user table"
-# 应用 migration
-alembic upgrade head
-```
-
-后续改 model 后:
-```bash
-alembic revision --autogenerate -m "add nickname index"
-alembic upgrade head
+mkdir -p data            # SQLite 库目录
+alembic upgrade head     # 按迁移链建到最新(幂等)
 ```
+> 详见 [docs/数据库迁移.md](docs/数据库迁移.md)。只想迁移不启服务:`bash scripts/migrate.sh`。

 ### 4. 跑起来
-
 ```bash
-uvicorn app.main:app --reload --port 8770
+./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 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"}'
-# 拿到 access_token 后:
 curl http://localhost:8770/api/v1/auth/me -H "Authorization: Bearer <access_token>"
 ```

 ### 5. 测试
-
 ```bash
 pytest -q
 ```
@@ -176,17 +164,13 @@ pytest -q

 ## 部署(生产)

-参考 `deploy/`,部署到 `app-api.shaguabijia.com`:
-
+部署到 `app-api.shaguabijia.com`(参考 `deploy/`):
 ```bash
-# 一次性
-ssh server "apt-get install -y python3.11-venv python3-pip"
-
 # 后续更新
-rsync -avz --exclude='__pycache__' --exclude='.venv' --exclude='data' --exclude='secrets/jverify_rsa_private.pem' \
+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 "
@@ -196,8 +180,7 @@ ssh server "
    systemctl restart shaguabijia-app-server
 "
 ```
-
-详见 `deploy/shaguabijia-app-server.service` 和 `deploy/nginx/app-api.shaguabijia.com.conf`。
+详见 `deploy/`。**看广告发奖上线**前对照 [docs/看广告赚金币上线清单.md](docs/看广告赚金币上线清单.md)(GroMore 回调配置、清理调试脚手架、端到端验收)。

 ---

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

-极光一键登录的具体实现(REST 调用、RSA padding 试错顺序)直接参考自试验后台,
-逻辑等价。
+极光一键登录的实现(REST 调用、RSA padding 试错顺序)参考自试验后台,逻辑等价。
@@ -6,7 +6,10 @@
 |---|---|
 | [后端技术实现.md](./后端技术实现.md) | **后端技术方案**:业务概览、分层架构与目录、登录链路、美团 CPS、领券透传、数据模型、配置与部署、已知问题。想了解"整个后端怎么回事"看这份。 |
 | [api/](./api/) | **API 接口文档**(目录),采用"索引 + 一接口一文件",结构见下。想查"某个接口的协议"看这里。 |
+| [integrations/](./integrations/) | **集成层实现文档**(目录):穿山甲验签 / 微信支付 / 极光 / 短信 / 美团 CPS 等 SDK 集成的签名、加解密、协议细节与踩坑。想知道"接外部服务那块到底怎么实现"看这里。 |
+| [数据库迁移.md](./数据库迁移.md) | **Alembic 迁移指南**:clone 后如何建表、日常升级、新增迁移、迁移文件命名约定。想"把数据库跑起来 / 改表结构"看这份。 |
 | [待办与技术债.md](./待办与技术债.md) | **待办与技术债账本**:记"现在先简化、以后要补"的事 + 跨前后端技术债(P1 鉴权/用户绑定、引擎移植待办等),免遗忘。想知道"还欠什么、以后要补什么"看这份。 |
+| [看广告赚金币上线清单.md](./看广告赚金币上线清单.md) | **看广告发奖上线 checklist**:跨前后端,记上线前必做(GroMore 回调配置、清理调试脚手架、端到端验收)。上线"看广告赚金币"前对照这份。 |

 ## api/ 目录是怎么组织的(传送门式)