docs: 更新多仓拆分与运维指引

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 开发环境

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
+```
+

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
+
+---
+
 ## 🚀 快速导航
 
 ### 我是新人，从哪里开始？