@ (#111)
docs/api目录文档分类和补全 --------- Co-authored-by: guke <guke@autohome.com.cn> Reviewed-on: #111
This commit was merged in pull request #111.
This commit is contained in:
+73
-22
@@ -1,32 +1,83 @@
|
||||
# 后端文档库(docs/)
|
||||
# 文档索引
|
||||
|
||||
`shaguabijia-app-server` 的文档都在这里。结构:**根目录放总览,其余按领域/用途分目录**。
|
||||
项目文档结构说明。后续大模型增补/更新文档时，按此分类找到对应目录。
|
||||
|
||||
## 根目录
|
||||
---
|
||||
|
||||
| 文档 | 作用 |
|
||||
|---|---|
|
||||
| [后端技术实现.md](./后端技术实现.md) | **后端技术方案总览**:业务概览、分层架构与目录、登录链路、美团 CPS、领券/比价透传、数据模型、配置与部署、已知问题。想了解"整个后端怎么回事"先看这份。 |
|
||||
| README.md | 本文件:文档库索引/传送门。 |
|
||||
## API 接口文档 (`api/`)
|
||||
|
||||
## 子目录
|
||||
按业务领域分类，每个子目录对应一类接口。
|
||||
|
||||
| 目录 | 作用 |
|
||||
|---|---|
|
||||
| [api/](./api/) | **API 接口文档**:"索引 + 一接口一文件"(组织方式见下)。想查"某个接口的协议"看这里。 |
|
||||
| [database/](./database/) | **数据库文档**:每张表一个文件(表结构/字段/索引/约定) + 两份迁移指南——[数据库迁移.md](./database/数据库迁移.md)(Alembic 操作:clone 后建表/日常升级/新增迁移/多 head 排查) + [postgres-migration.md](./database/postgres-migration.md)(SQLite → PostgreSQL 切换步骤,配套 `scripts/init_postgres.py`)。想"把库跑起来 / 改表结构 / 查某张表"看这里。 |
|
||||
| [integrations/](./integrations/) | **集成层实现文档**:穿山甲验签 / 微信支付 / 极光 / 短信 / 美团 CPS 等 SDK 集成的签名、加解密、协议细节与踩坑。想知道"接外部服务那块到底怎么实现"看这里。 |
|
||||
| [guides/](./guides/) | **开发 / 上线 / 功能 指南**:[待办与技术债.md](./guides/待办与技术债.md)(跨前后端 backlog,P1 鉴权/用户绑定、引擎移植待办等,"还欠什么、以后要补什么"看这份) + [看广告赚金币上线清单.md](./guides/看广告赚金币上线清单.md)(看广告发奖上线 checklist) + [邀请功能-实现原理与本地测试.md](./guides/邀请功能-实现原理与本地测试.md)(invite-mvp 实现原理 + 本地内网全链路测试) + [CPS发券分发与微信授权.md](./guides/CPS发券分发与微信授权.md)(**CPS 发券系统交接文档**:设群/建活动/生成落地页短链/美团对账/统计 + 微信网页授权拿 openid 做用户级统计;含数据流/表/平台差异/端点/配置/代码地图/排障/技术债)。 |
|
||||
### 分类目录
|
||||
|
||||
## api/ 目录是怎么组织的(传送门式)
|
||||
| 目录 | 分类 | URL 前缀 | 说明 |
|
||||
|------|------|----------|------|
|
||||
| [api/auth/](api/auth/) | 认证 | `/api/v1/auth` | 用户登录（极光一键登录/短信验证码）、Token 刷新（access + refresh）、登出、当前用户信息查询 |
|
||||
| [api/ad/](api/ad/) | 广告 | `/api/v1/ad` | 穿山甲 S2S 回调验签发奖、激励视频/信息流广告奖励结算、eCPM 上报、发奖状态查询、测试发奖（仅本地） |
|
||||
| [api/wallet/](api/wallet/) | 钱包 | `/api/v1/wallet` | 账户资产查询（金币/现金余额）、金币与现金流水、兑换规则与执行、绑定/解绑微信、提现申请/状态/记录、免确认收款授权 |
|
||||
| [api/coupon/](api/coupon/) | 领券 | `/api/v1/coupon` | CPS 领券透传（step/session）、引导窗频控（should-show/shown/dismiss/reset）、每日完成状态、累计领券统计 |
|
||||
| [api/compare/](api/compare/) | 比价记录 | `/api/v1/compare` | 比价记录上报/列表/详情/统计、比价战绩里程碑查询及奖励领取（按成功比价数解锁金币） |
|
||||
| [api/savings/](api/savings/) | 省钱 | `/api/v1/savings` + `/api/v1/platform/savings-feed` | 省钱大作战（battle）、省钱明细/汇总、平台省钱动态 Feed |
|
||||
| [api/signin/](api/signin/) | 签到 | `/api/v1/signin` | 每日签到执行、签到加速（看广告多领）、签到状态查询 |
|
||||
| [api/tasks/](api/tasks/) | 任务 | `/api/v1/tasks` | 任务列表查询、任务奖励领取（按 task_key） |
|
||||
| [api/invite/](api/invite/) | 邀请 | `/api/v1/invite` | 邀请码/分享链接生成、已邀请列表、邀请绑定（支持 clipboard/manual/fingerprint 三种归因） |
|
||||
| [api/user/](api/user/) | 用户 | `/api/v1/user` | 个人资料编辑（昵称）、头像上传、新手引导状态/完成标记、注销账号 |
|
||||
| [api/device/](api/device/) | 设备 | `/api/v1/device` | 设备注册/推送 token 更新、无障碍存活心跳、掉线检测（后置 pull）、告警确认 |
|
||||
| [api/platform/](api/platform/) | 平台配置 | `/api/v1/platform` | 平台统计数据、Feature Flag 开关、广告配置（穿山甲 ID）、App 版本更新检查（OTA）；全部不鉴权 |
|
||||
| [api/intent/](api/intent/) | 意图/电商 | `/api/v1/intent` + `/api/v1/price` + `/api/v1/ecom` | 比价意图识别（Phase 1 单次/多帧/预券）、电商意图识别、比价步进（Phase 2） |
|
||||
| [api/meituan/](api/meituan/) | 美团 CPS | `/api/v1/meituan` | 美团券列表/信息流/推广链接/销量榜；全部无鉴权 |
|
||||
| [api/other/](api/other/) | 其它 | 分散 | 健康检查、CPS 短链重定向（含微信 OAuth）、反馈提交/配置/记录、埋点上报、订单上报、更低价上报、Trace 收尾 |
|
||||
| [api/admin/](api/admin/) | 管理后台 | `/admin/api` | Admin 独立子应用，二级目录按子资源拆分：`auth/`(登录)、`users/`(用户管理/财务操作)、`wallet/`(流水查询)、`withdraws/`(提现审核/对账)、`feedbacks/`(反馈处理)、`admins/`(管理员管理)、`ad/`(广告对账/收益)；单文件留根：审计日志、数据大盘、跑马灯种子、统计概览 |
|
||||
| [api/internal/](api/internal/) | 内部接口 | `/internal` | 服务间调用（pricebot→app-server）：价格事实回写、店铺映射、启动确认样本、App 版本写入；X-Internal-Secret 鉴权 |
|
||||
|
||||
接口多了之后,单个大文件会臃肿、难维护,所以拆成 **一个索引 + 一个接口一个文件**:
|
||||
### 接口索引入口
|
||||
|
||||
- **[api/README.md](./api/README.md) — 入口/传送门**
|
||||
一张总览表列出**全部接口**(方法、路径、鉴权),每行链接到该接口的独立文档;另含**通用约定**(错误码、时间格式等)和**复用数据结构**(`TokenPair` / `UserOut` / `CouponCard` 等)。它本身不展开每个接口的细节,只负责"指路"。
|
||||
- **api/<模块>-<接口>.md — 单接口文档**
|
||||
每个接口一个文件,只写自己的入参 / 出参 / 错误码 / 说明。命名按 `<模块>-<接口>`,如 `auth-jverify-login.md`、`coupon-step.md`、`meituan-feed.md`。
|
||||
完整接口列表（含路径、方法、鉴权方式）见 [api/README.md](api/README.md)。
|
||||
|
||||
**查某个接口的协议**:先打开 [api/README.md](./api/README.md) 的总览表 → 找到接口 → 点链接进对应文档。
|
||||
### 文档命名规则
|
||||
|
||||
> **新增接口时**:在 `api/` 下加一个 `<模块>-<接口>.md`,并到 `api/README.md` 总览表里补一行链接。这样索引始终是唯一的"传送门",细节各自独立、互不干扰。
|
||||
单端点文档按 URL 路径命名：`{prefix}-{resource}.md`（如 `wallet-withdraw.md`、`auth-sms-send.md`）。
|
||||
含子资源的合并文档按族命名（如 `device-liveness.md` 覆盖 register/heartbeat/liveness/liveness-ack 四个端点）。
|
||||
文件名唯一确定文档位置：大类目录 + 文件名前缀 → 直接匹配。
|
||||
|
||||
---
|
||||
|
||||
## 数据库文档 (`database/`)
|
||||
|
||||
数据库表结构说明，每表一个文件，[database/OVERVIEW.md](database/OVERVIEW.md) 为索引入口。
|
||||
|
||||
---
|
||||
|
||||
## 第三方集成 (`integrations/`)
|
||||
|
||||
外部 SDK/API 集成架构与实现说明：[integrations/README.md](integrations/README.md)。
|
||||
|
||||
| 文件 | 说明 |
|
||||
|------|------|
|
||||
| [jiguang.md](integrations/jiguang.md) | 极光一键登录（REST 验证 + RSA 解密） |
|
||||
| [pangle.md](integrations/pangle.md) | 穿山甲广告 S2S 回调 |
|
||||
| [wxpay.md](integrations/wxpay.md) | 微信支付 V3（提现/授权） |
|
||||
| [meituan.md](integrations/meituan.md) | 美团 CPS 网关 |
|
||||
|
||||
---
|
||||
|
||||
## 开发指南 (`guides/`)
|
||||
|
||||
| 文件 | 说明 |
|
||||
|------|------|
|
||||
| [邀请功能-实现原理与本地测试.md](guides/邀请功能-实现原理与本地测试.md) | 邀请系统实现细节 |
|
||||
| [CPS发券分发与微信授权.md](guides/CPS发券分发与微信授权.md) | CPS 发券 + 微信网页授权流程 |
|
||||
| [看广告赚金币上线清单.md](guides/看广告赚金币上线清单.md) | 广告功能上线检查清单 |
|
||||
| [待办与技术债.md](guides/待办与技术债.md) | 待办事项与技术债务 |
|
||||
|
||||
---
|
||||
|
||||
## 架构与设计 (`superpowers/`)
|
||||
|
||||
需求规格与设计文档，按 `YYYY-MM-DD-<topic>-design.md` 命名。
|
||||
|
||||
---
|
||||
|
||||
## 后端技术实现 (`后端技术实现.md`)
|
||||
|
||||
后端整体技术架构说明。
|
||||
|
||||
Reference in New Issue
Block a user