marco
a2263b48a0
- 单文件 docs/API.md 拆成 docs/api/: README.md(传送门索引: 11 接口总览表 + 通用约定 + 复用结构) + 11 个一接口一文件, 便于接口增多后维护 - 补全此前 API.md 与技术文档均遗漏的核心接口 coupon-step.md (一键领券透传 pricebot-backend, 唯一需 JWT 鉴权的业务接口) - 更新 后端技术实现.md: 业务补"领券透传"块、目录补 coupon.py、新增 coupon/step 节、 配置补 PRICEBOT_*、接口索引改指向 docs/api/ Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
106 lines
5.2 KiB
Markdown
106 lines
5.2 KiB
Markdown
# 傻瓜比价 App 后端 — API 接口文档（索引）
|
||
|
||
> Base URL:生产 `https://app-api.shaguabijia.com`;本地联调 `http://<开发机>:8770`
|
||
> 协议:HTTP / JSON,请求与响应体均 `application/json`,字段统一 **snake_case**
|
||
> 鉴权:需鉴权的接口在请求头带 `Authorization: Bearer <access_token>`
|
||
> 最后更新:2026-05-27
|
||
|
||
---
|
||
|
||
## 接口总览
|
||
|
||
| # | 方法 + 路径 | 鉴权 | 详情 |
|
||
|---|---|---|---|
|
||
| 1 | `GET /health` | 无 | [详情](./health.md) |
|
||
| 2 | `POST /api/v1/auth/jverify-login` | 无 | [详情](./auth-jverify-login.md) |
|
||
| 3 | `POST /api/v1/auth/sms/send` | 无 | [详情](./auth-sms-send.md) |
|
||
| 4 | `POST /api/v1/auth/sms/login` | 无 | [详情](./auth-sms-login.md) |
|
||
| 5 | `POST /api/v1/auth/refresh` | 无 | [详情](./auth-refresh.md) |
|
||
| 6 | `GET /api/v1/auth/me` | Bearer | [详情](./auth-me.md) |
|
||
| 7 | `POST /api/v1/auth/logout` | Bearer | [详情](./auth-logout.md) |
|
||
| 8 | `POST /api/v1/coupon/step` | Bearer | [详情](./coupon-step.md) |
|
||
| 9 | `POST /api/v1/meituan/coupons` | 无 | [详情](./meituan-coupons.md) |
|
||
| 10 | `POST /api/v1/meituan/feed` | 无 | [详情](./meituan-feed.md) |
|
||
| 11 | `POST /api/v1/meituan/referral-link` | 无 | [详情](./meituan-referral-link.md) |
|
||
|
||
> ⚠️ 美团三个接口当前**无鉴权**,且 `referral-link` 的 `sid` 允许客户端传值覆盖默认渠道——见各接口"备注"。
|
||
> `coupon/step` 是后端**唯一需要 JWT 鉴权的业务接口**。
|
||
|
||
---
|
||
|
||
## 通用约定
|
||
|
||
- **时间格式**:ISO 8601 UTC（如 `2026-05-27T12:34:56Z`）
|
||
- **错误响应**:FastAPI 标准结构 `{"detail": "<错误信息>"}`,配合语义化 HTTP 状态码:
|
||
- `400` 业务参数错（如验证码不对）
|
||
- `401` 未认证 / token 无效或过期 / 用户被禁（响应头带 `WWW-Authenticate: Bearer`）
|
||
- `403` 账号被禁用
|
||
- `422` 请求体字段校验失败（FastAPI 自动校验,如手机号格式）
|
||
- `429` 触发限流（短信发送过频）
|
||
- `502` 上游调用失败（极光验证/解密失败、美团接口失败）
|
||
- **接口文档（交互式）**:`APP_ENV` 非 prod 时开放 `GET /docs`（Swagger UI）、`GET /redoc`;生产环境关闭。
|
||
|
||
---
|
||
|
||
## 复用数据结构
|
||
|
||
### TokenPair
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| `access_token` | string | 访问令牌,之后每个鉴权请求带 `Authorization: Bearer <它>` |
|
||
| `refresh_token` | string | 刷新令牌 |
|
||
| `token_type` | string | 固定 `"Bearer"` |
|
||
| `expires_in` | int | access 剩余秒数（默认 7200 = 2h） |
|
||
| `refresh_expires_in` | int | refresh 剩余秒数（默认 2592000 = 30d） |
|
||
|
||
### TokenWithUser
|
||
继承 `TokenPair` 全部字段,额外多一个 `user`（`UserOut`）。登录类接口成功时返回此结构。
|
||
|
||
### UserOut
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| `id` | int | 用户主键 |
|
||
| `phone` | string | 手机号 |
|
||
| `nickname` | string \| null | 昵称（当前无接口可改,恒为 null） |
|
||
| `avatar_url` | string \| null | 头像（同上） |
|
||
| `register_channel` | string | 注册渠道:`jverify` / `sms` |
|
||
| `status` | string | `active` / `disabled` / `deleted` |
|
||
| `created_at` | datetime | 注册时间 |
|
||
| `last_login_at` | datetime | 最近登录时间 |
|
||
|
||
### CouponCard（券卡片,`coupons` 与 `feed` 的 `items` 元素）
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| `product_view_sign` | string | **换链主键**（传给 `referral-link`） |
|
||
| `platform` | int | `1`=外卖/到家, `2`=到店 |
|
||
| `biz_line` | int \| null | 到店子类:1到餐 2到综 3酒店 4门票 |
|
||
| `name` | string | 商品名 |
|
||
| `head_image_url` | string | 头图 |
|
||
| `brand_name` | string \| null | 品牌名 |
|
||
| `brand_logo_url` | string \| null | 品牌 logo |
|
||
| `sell_price` | string | 现价 |
|
||
| `original_price` | string | 原价 |
|
||
| `discount_amount` | string | 优惠额 = 原价 − 现价 |
|
||
| `commission_rate` | string | 佣金比例,如 `"1.4%"` |
|
||
| `commission_amount` | string \| null | 预估佣金（元） |
|
||
| `sale_volume` | string \| null | 销量 |
|
||
| `poi_name` | string \| null | 最近门店名 |
|
||
| `distance_text` | string \| null | 格式化距离,如 `"600m"` / `"1.5km"` |
|
||
| `distance_meters` | float \| null | 原始距离（米） |
|
||
| `available_poi_num` | int \| null | 可用门店数 |
|
||
| `coupon_num` | int \| null | 券张数 |
|
||
| `valid_days` | int \| null | 券有效天数 |
|
||
| `price_label` | string \| null | 如 `"15天低价"` |
|
||
| `rank_label` | string \| null | 如 `"2小时北京外卖销量榜第1名"` |
|
||
| `rating_label` | string \| null | 如 `"4.6分"` |
|
||
|
||
---
|
||
|
||
## 附:鉴权与刷新机制
|
||
|
||
- **签发**:登录成功后签发 access(HS256,2h) + refresh(30d),payload 含 `sub`(user_id)、`typ`(access/refresh)、`iat`、`exp`。
|
||
- **携带**:客户端对需鉴权接口自动加 `Authorization: Bearer <access>`（登录类接口跳过）。
|
||
- **校验**（`/me`、`/logout`）:验签 → 验过期 → 验 `typ=access` → 查库确认用户存在且 `status=active`,任一不过 → 401。
|
||
- **续期**:access 过期触发 401 → 客户端用 refresh 调 `/refresh` 换新 token 对并重放原请求;refresh 也失效 → 清本地、跳登录。
|
||
- **无状态**:token 不落库,服务端无法主动吊销(logout 为占位),靠短 access 有效期限制泄露风险。JWT 密钥 `JWT_SECRET_KEY` 必须为高熵随机串(生产严禁用默认值)。
|