docs: 新建 docs/integrations 集成层文档 + api 文档变薄
- 新增 docs/integrations/(README + jiguang/sms/meituan/pangle/wxpay 各一篇): 记录各 SDK 集成的签名/验签/加解密/协议细节与踩坑(对齐 app/integrations 分层) - docs/api 接口文档变薄: 受影响接口头部加「集成实现」链接,把验签/RSA/CPS 签名 等重逻辑描述移到集成文档;ad-pangle-callback 验签段精简为指针 - docs/api/README 补架构说明(api 薄 / 重逻辑在 integrations) - 后端技术实现.md 目录树补全(福利/钱包/签到/省钱/发奖端点 + crud/integrations 现状), pangle/wxpay 标注移入 integrations - ad_reward_golive_checklist 路径同步 core→integrations Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
OuYingJun1024
+41
-16
@@ -41,44 +41,69 @@
|
||||
|
||||
## 3. 分层架构与目录结构
|
||||
|
||||
标准 FastAPI 分层,一个请求自上而下穿过:**api(薄,收发) → integrations(外部) / repositories(数据) → models / db**。
|
||||
标准 FastAPI 分层,一个请求自上而下穿过:**api(薄,收发) → integrations(外部 SDK) / crud · repositories(数据) → models / db**。重逻辑(SDK 签名/加解密/外部 HTTP)落 `integrations`,集成层细节见 [docs/integrations/](./integrations/README.md)。
|
||||
|
||||
```
|
||||
app/
|
||||
├── main.py # FastAPI 入口:注册 3 个 router、CORS、/health、lifespan
|
||||
├── main.py # FastAPI 入口:注册全部 router、CORS、/health、lifespan
|
||||
├── api/
|
||||
│ ├── deps.py # 共享依赖:get_current_user(鉴权)、get_db(注入 session)
|
||||
│ └── v1/
|
||||
│ ├── auth.py # 登录 6 个端点
|
||||
│ ├── coupon.py # 领券透传 /coupon/step(转发 pricebot,唯一需鉴权的业务接口)
|
||||
│ └── meituan.py # 美团 3 个端点 + feed 拼接逻辑(_interleave / _TOPIC_ROUNDS)
|
||||
│ └── v1/ # 接口层(薄):解析请求 → 调 crud/integration → 组装响应 + HTTP 错误码
|
||||
│ ├── auth.py # 登录 6 端点(极光一键登录 / 短信 send+login / refresh / me / logout)
|
||||
│ ├── coupon.py # 领券透传 /coupon/step(转发 pricebot)
|
||||
│ ├── meituan.py # 美团 3 端点 + feed 拼接(_interleave / _TOPIC_ROUNDS)
|
||||
│ ├── wallet.py # 钱包/提现 11 端点(余额/流水/兑换/绑微信/提现/查单)
|
||||
│ ├── signin.py # 签到 2 端点(状态 / 执行签到)
|
||||
│ ├── tasks.py # 一次性任务 2 端点(列表 / 领取)
|
||||
│ ├── savings.py # 省钱 3 端点(汇总 / 战绩 / 明细)
|
||||
│ └── ad.py # 看广告发奖 3 端点(穿山甲 S2S 回调 / 进度 / 联调发奖)
|
||||
├── schemas/ # Pydantic:API 收发的数据契约(与客户端对齐字段看这里)
|
||||
│ ├── auth.py
|
||||
│ └── meituan.py
|
||||
├── integrations/ # 外部服务客户端(2026-05 从 core 拆出)
|
||||
│ ├── meituan.py
|
||||
│ ├── welfare.py # 钱包/签到/任务/省钱 收发模型
|
||||
│ └── ad.py # 看广告发奖收发模型
|
||||
├── integrations/ # 外部服务/SDK 客户端(重逻辑:签名/加解密/外部 HTTP)
|
||||
│ ├── jiguang.py # 极光 REST 验 token + RSA 解密(多 padding 试错)
|
||||
│ ├── meituan.py # 美团 CPS 网关签名 + query_coupon / get_referral_link
|
||||
│ └── sms.py # 短信验证码(mock,进程内存冷却表)
|
||||
├── core/ # 基础设施(仅保留)
|
||||
│ ├── sms.py # 短信验证码(mock,进程内存冷却表)
|
||||
│ ├── pangle.py # 穿山甲激励视频发奖回调验签(SHA256,2026-05 从 core 移入)
|
||||
│ └── wxpay.py # 微信支付 V3 商家转账(提现)+ code 换 openid(2026-05 从 core 移入)
|
||||
├── core/ # 基础设施(无外部业务集成)
|
||||
│ ├── config.py # pydantic-settings
|
||||
│ ├── security.py # JWT 签发/校验
|
||||
│ ├── ratelimit.py # 同 IP 滑动窗口限流依赖
|
||||
│ ├── rewards.py # 发奖/兑换/提现额度等业务常量与换算
|
||||
│ └── logging.py
|
||||
├── repositories/ # 数据访问(2026-05 由 crud 改名)
|
||||
├── crud/ # 福利业务数据访问 + 事务(钱包/签到/任务/省钱/发奖)
|
||||
│ ├── wallet.py # 账户/流水/兑换/提现单(调 integrations/wxpay)
|
||||
│ ├── signin.py # 签到记录 / 连续天数 / 档位
|
||||
│ ├── task.py # 一次性任务领取
|
||||
│ ├── savings.py # 省钱汇总 / 战绩 / 明细
|
||||
│ └── ad_reward.py # 看广告发奖(按 trans_id 幂等 + 每日上限)
|
||||
├── repositories/ # user 域数据访问(2026-05 由 crud 改名沿用)
|
||||
│ └── user.py # get_user_by_id / get_user_by_phone / upsert_user_for_login
|
||||
├── models/user.py # ORM:user 表结构
|
||||
├── models/ # ORM 表结构
|
||||
│ ├── user.py # user(含微信 openid/nickname/avatar)
|
||||
│ ├── wallet.py # 金币账户 / 金币流水 / 现金流水 / 提现单
|
||||
│ ├── signin.py # 签到记录
|
||||
│ ├── task.py # 任务领取记录
|
||||
│ ├── savings.py # 省钱明细 / 店铺菜品
|
||||
│ └── ad_reward.py # 看广告发奖记录
|
||||
└── db/
|
||||
├── base.py # DeclarativeBase
|
||||
└── session.py # engine + get_db
|
||||
|
||||
alembic/ # 数据库迁移(versions/ 目前仅 init_user_table)
|
||||
alembic/ # 数据库迁移(versions/ 目前 9 个迁移,down_revision 链式)
|
||||
deploy/ # systemd(.service) + nginx(.conf)
|
||||
secrets/ # 极光 RSA 私钥(不入 git,仅 .gitkeep 占位)
|
||||
tests/ # pytest(conftest + test_auth + test_health)
|
||||
secrets/ # 极光 RSA 私钥 / 微信支付证书(不入 git,仅 .gitkeep 占位)
|
||||
scripts/ # 运维脚本(对账 / 重置签到 / 重置福利 / 模拟穿山甲回调)
|
||||
tests/ # pytest(auth / health / welfare / withdraw / ad_reward / coupon_proxy)
|
||||
run.sh # 本地启动脚本
|
||||
docs/api/ # API 接口文档(索引 README + 一接口一文件)
|
||||
docs/integrations/ # 集成层实现文档(SDK 签名/加解密/协议细节)
|
||||
```
|
||||
|
||||
> **命名说明**:`api/v1/` 的 `v1` 用于 URL 版本化(移动端无法强制即时升级,需新旧版本并存能力);`integrations` 装外部集成、`repositories` 装数据访问,与 `core`(基础设施)分离。`coupon.py` 是领券透传,勿与 `meituan.py` 里的 `coupons`(券列表)混淆。
|
||||
> **命名说明**:`api/v1/` 的 `v1` 用于 URL 版本化(移动端无法强制即时升级,需新旧版本并存能力);`integrations` 装外部 SDK 集成、`crud`/`repositories` 装数据访问、`core` 装基础设施,三者分离。**数据访问层有两个目录是历史遗留**:user 域在 `repositories/`(早期 crud 改名),后来的福利业务在 `crud/`,职责相同。`coupon.py` 是领券透传,勿与 `meituan.py` 里的 `coupons`(券列表)混淆。
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user