docs: API 文档拆分为 docs/api/(索引+一接口一文件), 补全遗漏的 coupon/step

- 单文件 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>

docs/api/README.md

@@ -0,0 +1,105 @@
+# 傻瓜比价 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` 必须为高熵随机串(生产严禁用默认值)。