From 79fcefaebcf5982338ee9f5e69b2616975242ac3 Mon Sep 17 00:00:00 2001 From: root Date: Thu, 29 Jan 2026 05:57:48 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=E5=A4=9A=E4=BB=93?= =?UTF-8?q?=E6=8B=86=E5=88=86=E4=B8=8E=E8=BF=90=E7=BB=B4=E6=8C=87=E5=BC=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Document/05_部署运维.md | 22 +++++++ Document/16_仓库拆分与子模块使用说明.md | 77 +++++++++++++++++++++++++ Document/README.md | 18 ++++++ README.md | 50 +++++++++++----- 4 files changed, 154 insertions(+), 13 deletions(-) create mode 100644 Document/16_仓库拆分与子模块使用说明.md diff --git a/Document/05_部署运维.md b/Document/05_部署运维.md index f92e303..708de2f 100644 --- a/Document/05_部署运维.md +++ b/Document/05_部署运维.md @@ -1,5 +1,27 @@ # 外卖SaaS系统 - 部署运维 +## 0. 仓库与服务入口（必读） + +> 项目已拆分为多仓：AdminApi / TenantApi / Gateway / BuildingBlocks / Docs。本文档中若出现旧单仓路径（如 `src/TakeoutSaaS.Api`），请按以下映射替换为对应服务路径。 + +### 0.1 仓库划分 + +- **TakeoutSaaS.AdminApi**：管理后台 API（运营/客服/平台管理）。 +- **TakeoutSaaS.TenantApi**：租户端 API（MiniApi/UserApi）。 +- **TakeoutSaaS.Gateway**：YARP API 网关。 +- **TakeoutSaaS.BuildingBlocks**：共享基础组件库（以子模块方式引入）。 +- **TakeoutSaaS.Docs**：文档与运维资产。 + +### 0.2 旧路径映射（常见） + +- 旧：`src/TakeoutSaaS.Api` + 新：`src/Api/TakeoutSaaS.AdminApi`（AdminApi）或 `src/Api/TakeoutSaaS.MiniApi` / `src/Api/TakeoutSaaS.UserApi`（TenantApi）。 +- Dockerfile： + - AdminApi：`src/Api/TakeoutSaaS.AdminApi/Dockerfile` + - MiniApi：`src/Api/TakeoutSaaS.MiniApi/Dockerfile` + - UserApi：`src/Api/TakeoutSaaS.UserApi/Dockerfile` + - Gateway：独立仓库根目录 `Dockerfile`（若以子模块挂回 AdminApi，则为 `src/Gateway/TakeoutSaaS.ApiGateway/Dockerfile`） + ## 1. 环境要求 ### 1.1 开发环境 diff --git a/Document/16_仓库拆分与子模块使用说明.md b/Document/16_仓库拆分与子模块使用说明.md new file mode 100644 index 0000000..cc32b67 --- /dev/null +++ b/Document/16_仓库拆分与子模块使用说明.md @@ -0,0 +1,77 @@ +# 仓库拆分与子模块使用说明 + +> 目的：将 AdminApi 与 TenantApi 解耦，减少多租户对管理端的影响；同时沉淀共享基础库与文档运维资产，便于复用与独立发布。 + +## 1. 仓库划分 + +- **TakeoutSaaS.AdminApi**：管理后台 API（运营/客服/平台管理），允许跨租户查询（以路由 `tenantId` 作为单租户操作入口）。 +- **TakeoutSaaS.TenantApi**：租户端 API（MiniApi/UserApi），强制租户隔离，面向小程序/用户端。 +- **TakeoutSaaS.Gateway**：YARP 反向代理网关（路由、CORS、限流、可观测性）。 +- **TakeoutSaaS.BuildingBlocks**：共享基础组件库（`Shared.Abstractions` / `Shared.Kernel` / `Shared.Web`）。 +- **TakeoutSaaS.Docs**：文档与运维资产（架构、边界、部署、脚本等）。 + +## 2. 子模块策略 + +- **AdminApi** 通过 `git submodule` 引入： + - `TakeoutSaaS.BuildingBlocks` → `TakeoutSaaS.BuildingBlocks/` + - `TakeoutSaaS.Docs` → `TakeoutSaaS.Docs/` + - `TakeoutSaaS.Gateway` → `src/Gateway/TakeoutSaaS.ApiGateway/`（网关独立仓库，暂以子模块形式挂回） +- **TenantApi** 通过 `git submodule` 引入： + - `TakeoutSaaS.BuildingBlocks` → `TakeoutSaaS.BuildingBlocks/` + - `TakeoutSaaS.Docs` → `TakeoutSaaS.Docs/` + +## 3. 克隆与初始化 + +### 3.1 新克隆（推荐） + +```bash +# AdminApi +git clone --recurse-submodules -b dev git@github.com:msumshk/TakeoutSaaS.AdminApi.git + +# TenantApi +git clone --recurse-submodules -b dev git@github.com:msumshk/TakeoutSaaS.TenantApi.git +``` + +### 3.2 已有仓库补齐子模块 + +```bash +git submodule update --init --recursive +``` + +## 4. 子模块更新流程（推荐） + +> 原则：**子模块自身先提交**，再由宿主仓库提交“子模块指针变更”。 + +### 4.1 更新 Docs/BuildingBlocks 内容 + +1. 进入子模块目录（如 `TakeoutSaaS.Docs/`），正常 `git add/commit/push`。 +2. 回到宿主仓库根目录，提交子模块引用更新： + - `git add TakeoutSaaS.Docs` + - `git commit -m "docs: 更新文档子模块引用"` +3. 其他成员拉取宿主仓库后执行： + - `git submodule update --init --recursive` + +### 4.2 拉取子模块最新 dev（可选） + +```bash +git submodule update --remote --merge +``` + +> 注意：`--remote` 会移动子模块引用，需要在宿主仓库提交。 + +## 5. 常用运行入口 + +```bash +# AdminApi +dotnet run --project src/Api/TakeoutSaaS.AdminApi/TakeoutSaaS.AdminApi.csproj + +# TenantApi - MiniApi +dotnet run --project src/Api/TakeoutSaaS.MiniApi/TakeoutSaaS.MiniApi.csproj + +# TenantApi - UserApi +dotnet run --project src/Api/TakeoutSaaS.UserApi/TakeoutSaaS.UserApi.csproj + +# Gateway（独立仓库） +dotnet run --project TakeoutSaaS.ApiGateway.csproj +``` + diff --git a/Document/README.md b/Document/README.md index aa08578..d929a4a 100644 --- a/Document/README.md +++ b/Document/README.md @@ -125,6 +125,24 @@ --- +### 8. [API 边界与自检清单](15_API边界与自检清单.md) +- AdminApi / UserApi / MiniApi 职责边界 +- 路由前缀与鉴权约定 +- DTO/租户/安全自检项 + +**适合人群**：后端开发人员、接口对接人员 + +--- + +### 9. [仓库拆分与子模块使用说明](16_仓库拆分与子模块使用说明.md) +- AdminApi / TenantApi / Gateway 拆分说明 +- BuildingBlocks / Docs 子模块策略 +- 克隆、更新与提交流程 + +**适合人群**：所有开发人员、DevOps + +--- + ## 🚀 快速导航 ### 我是新人，从哪里开始？ diff --git a/README.md b/README.md index caaabce..6a1e15a 100644 --- a/README.md +++ b/README.md @@ -51,15 +51,31 @@ ## 快速开始 -### 1. 克隆项目 +### 1. 克隆仓库（已拆分为多仓 + 子模块） + +> 推荐使用 `--recurse-submodules` 一次性拉取共享库与文档子模块。 + +**管理后台 AdminApi** ```bash -git clone https://github.com/your-org/takeout-saas.git -cd takeout-saas +git clone --recurse-submodules -b dev git@github.com:msumshk/TakeoutSaaS.AdminApi.git +cd TakeoutSaaS.AdminApi +``` + +**租户端 TenantApi（MiniApi/UserApi）** +```bash +git clone --recurse-submodules -b dev git@github.com:msumshk/TakeoutSaaS.TenantApi.git +cd TakeoutSaaS.TenantApi +``` + +**若未使用 `--recurse-submodules`** +```bash +git submodule update --init --recursive ``` ### 2. 使用Docker Compose启动依赖服务（推荐） ```bash -# 启动PostgreSQL、Redis、RabbitMQ等服务 +# 在你的 docker-compose.yml 所在目录执行（示例） +# 启动 PostgreSQL、Redis、RabbitMQ 等服务 docker-compose up -d # 查看服务状态 @@ -67,22 +83,30 @@ docker-compose ps ``` ### 3. 配置数据库连接 -编辑 `src/TakeoutSaaS.Api/appsettings.Development.json` +编辑各服务的配置文件： +- AdminApi：`src/Api/TakeoutSaaS.AdminApi/appsettings.Development.json` +- MiniApi：`src/Api/TakeoutSaaS.MiniApi/appsettings.Development.json` +- UserApi：`src/Api/TakeoutSaaS.UserApi/appsettings.Development.json` -### 4. 执行数据库迁移 -```bash -cd src/TakeoutSaaS.Api -dotnet ef database update -``` +### 4. 执行数据库迁移（如需） + +迁移执行与设计期 DbContext 配置请参考：`Document/10_设计期DbContext配置指引.md`。 ### 5. 运行项目 ```bash -dotnet run +# AdminApi +dotnet run --project src/Api/TakeoutSaaS.AdminApi/TakeoutSaaS.AdminApi.csproj + +# MiniApi（TenantApi 仓库内） +dotnet run --project src/Api/TakeoutSaaS.MiniApi/TakeoutSaaS.MiniApi.csproj + +# UserApi（TenantApi 仓库内） +dotnet run --project src/Api/TakeoutSaaS.UserApi/TakeoutSaaS.UserApi.csproj ``` 访问 API 文档： -- 管理后台 AdminApi Swagger：http://localhost:5001/api/docs -- 小程序/用户端 MiniApi Swagger：http://localhost:5002/api/docs +- Swagger UI：`/api/docs`（旧入口 `/swagger` 仍保留） +- 端口以各项目 `Properties/launchSettings.json` 或部署配置为准 ## 字典管理