From a07361007f85152550175fe7d465caed4c00a644 Mon Sep 17 00:00:00 2001 From: marco Date: Wed, 27 May 2026 12:13:58 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9E=20docs/README.md=20?= =?UTF-8?q?=E6=96=87=E6=A1=A3=E5=BA=93=E5=AF=BC=E8=88=AA(=E8=AF=B4?= =?UTF-8?q?=E6=98=8E=20api/=20=E4=BC=A0=E9=80=81=E9=97=A8=E7=BB=93?= =?UTF-8?q?=E6=9E=84)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - docs/README.md: 说明文档库结构(后端技术实现.md + api/), 重点讲 api/ 的 "索引 + 一接口一文件"传送门组织方式, 及新增接口时的维护约定 Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/README.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100644 docs/README.md diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..928ca30 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,21 @@ +# 后端文档库(docs/) + +`shaguabijia-app-server` 的文档都在这里。各文档作用: + +| 文档 / 目录 | 作用 | +|---|---| +| [后端技术实现.md](./后端技术实现.md) | **后端技术方案**:业务概览、分层架构与目录、登录链路、美团 CPS、领券透传、数据模型、配置与部署、已知问题。想了解"整个后端怎么回事"看这份。 | +| [api/](./api/) | **API 接口文档**(目录),采用"索引 + 一接口一文件",结构见下。想查"某个接口的协议"看这里。 | + +## api/ 目录是怎么组织的(传送门式) + +接口多了之后,单个大文件会臃肿、难维护,所以拆成 **一个索引 + 一个接口一个文件**: + +- **[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/` 下加一个 `<模块>-<接口>.md`,并到 `api/README.md` 总览表里补一行链接。这样索引始终是唯一的"传送门",细节各自独立、互不干扰。