docs: 更新 AdminApi 边界与拆分说明

Document/15_API边界与自检清单.md

@@ -2,28 +2,32 @@
 
 > 目的：明确 Admin/User/Mini 三个 API 的职责边界，避免跨端耦合。开发新接口或改动现有控制器时请对照自检，确保租户、安全、DTO、路由符合约定。
 
+> 说明：仓库已拆分为 `TakeoutSaaS.AdminApi`（管理后台）与 `TakeoutSaaS.TenantApi`（UserApi/MiniApi）。本文档只对边界与自检项作约束，控制器清单仅对 AdminApi 维护，其余端以各自仓库代码为准。
+
 ## 1. AdminApi（管理后台）
-- **面向对象**：运营、客服、商户管理员。
+- **归属仓库**：`TakeoutSaaS.AdminApi`
-- **职责**：租户/门店/商品/订单/支付/配送/字典/权限/RBAC/审计/任务调度等后台管理与洞察。
+- **面向对象**：平台运营、客服、内部管理。
-- **鉴权**：JWT + RBAC（`[Authorize]` + `PermissionAuthorize`），租户头不再强制（单租户操作以路由 `tenantId` 为准）。
+- **职责**：商户/门店/商品/订单/支付/配送/字典/权限/RBAC/审计/系统参数等后台管理与洞察。
+- **鉴权**：JWT + RBAC（`[Authorize]` + `PermissionAuthorize`）；**不强制租户头**，AdminApi 默认不做租户隔离（内部工具允许跨租户查询）。如需限定租户，请在路由/参数中显式指定 `tenantId` 并在应用层校验。
 - **路由前缀**：`api/admin/v{version}/...`。
 - **DTO/约束**：仅管理字段，禁止返回 C 端敏感信息；long -> string；严禁实体直接返回。
-- **现有控制器**：`AuthController`、`DeliveriesController`、`DictionaryController`、`FilesController`、`MerchantsController`、`OrdersController`、`PaymentsController`、`PermissionsController`、`RolesController`、`StoresController`、`SystemParametersController`、`TenantPackagesController`、`TenantsController`、`TenantBillingsController`、`TenantAnnouncementsController`、`TenantNotificationsController`、`UserPermissionsController`、`HealthController`。
+- **现有控制器（以仓库代码为准）**：`AuthController`、`CacheMetricsController`、`DeliveriesController`、`DictionaryController`、`DictionaryGroupsController`、`DictionaryItemsController`、`DictionaryLabelOverridesController`、`FilesController`、`HealthController`、`InventoryController`、`MenusController`、`MerchantCategoriesController`、`MerchantsController`、`OrdersController`、`PaymentsController`、`PermissionsController`、`ProductsController`、`RoleTemplatesController`、`StoreAuditsController`、`StorePickupController`、`StoreQualificationsController`、`StoreShiftsController`、`StoreStaffsController`、`StoreTableAreasController`、`StoreTablesController`、`StoresController`、`SystemParametersController`、`UsersController`。
 - **自检清单**：
-  1. 是否需要权限/租户过滤？未加则补 `[Authorize]` + 租户解析。
+  1. 是否需要权限校验？未加则补 `[Authorize]` + `PermissionAuthorize`（内部只读工具也至少需要 `[Authorize]`，避免误暴露）。
   2. 是否调用了应用层 CQRS，而非在 Controller 写业务？
   3. DTO 是否按管理口径，未暴露用户端字段？
   4. 是否使用参数化/AsNoTracking/投影，避免 N+1？
-  5. 路由和 Swagger 示例是否含租户/权限说明？
+  5. 路由和 Swagger 示例是否明确权限含义（AdminApi 不要求租户头）？
-- **自检记录**：RolesController 新增模板列表/详情/复制/初始化端点，均已套用 `[Authorize]` + `PermissionAuthorize`、仅调用 CQRS/DTO，依赖租户头隔离。TenantPackagesController 与 TenantsController(配额校验) 均使用权限码、DTO 映射，配额校验要求携带租户头防越权。新增租户账单/公告/通知控制器，全部采用 CQRS、权限校验与租户参数，列表分页、未暴露实体。
+- **自检记录**：已移除租户侧控制器（如 `TenantsController`、`TenantPackagesController`、`TenantBillingsController` 等）。`UsersController` 仅管理平台管理员账号（`Portal=Admin` 且 `TenantId=null`），不做租户侧兼容/兜底。
 
 ## 2. UserApi（C 端用户）
+- **归属仓库**：`TakeoutSaaS.TenantApi`
 - **面向对象**：App/H5 普通用户。
 - **职责**：菜单浏览、下单、支付、评价、地址、售后、订单查询、支付/配送回调（验证签名）等用户闭环。
 - **鉴权**：用户 JWT，租户隔离；幂等接口需校验。
 - **路由前缀**：`api/user/v{version}/...`。
 - **DTO/约束**：仅用户侧可见字段，屏蔽后台配置字段；long -> string。
-- **现有控制器**：当前仅 `HealthController`（业务接口待补）。
+- **现有控制器**：以 `TakeoutSaaS.TenantApi` 仓库为准（此处不维护清单，避免与代码偏差）。
 - **自检清单**：
   1. 是否暴露给用户的纯前台功能？后台配置请放 AdminApi。
   2. 是否做租户隔离、用户鉴权、签名/幂等校验？
@@ -32,12 +36,13 @@
   5. 回调路由是否验证签名/防重放？
 
 ## 3. MiniApi（小程序端）
+- **归属仓库**：`TakeoutSaaS.TenantApi`
 - **面向对象**：微信/小程序前端。
 - **职责**：小程序登录/刷新、当前用户档案、订阅消息、直传凭证、小程序场景特定的下单/浏览等。
 - **鉴权**：小程序登录态/Token，租户隔离；必要时区分渠道。
 - **路由前缀**：`api/mini/v{version}/...`。
 - **DTO/约束**：遵循小程序接口规范，错误码与前端对齐；long -> string。
-- **现有控制器**：`AuthController`、`MeController`、`FilesController`、`HealthController`。
+- **现有控制器**：以 `TakeoutSaaS.TenantApi` 仓库为准（此处不维护清单，避免与代码偏差）。
 - **自检清单**：
   1. 是否为小程序特有流程（code2session、订阅消息、直传等）？通用用户接口放 UserApi。
   2. 是否完成租户/鉴权校验，区分渠道标识？
@@ -47,7 +52,7 @@
 
 ## 4. 共通约束
 - **分层**：Controller 仅做路由/DTO 转换，业务放 Application 层 Handler。
-- **租户**：所有写/读需租户过滤；严禁跨租户访问。
+- **租户**：TenantApi 必须强制租户隔离；AdminApi 作为内部平台工具默认允许跨租户查询，但必须受 RBAC 与审计约束。
 - **日志/观测**：TraceId/SpanId 已贯通；/metrics、/healthz 按服务暴露。
 - **命名**：输入 `XxxRequest`、输出 `XxxDto`；文件名与类名一致；布尔属性加 `Is/Has`。
 - **发布前检查**：运行 `dotnet build`，必要时补 Swagger 示例、单元测试（核心逻辑 100% 覆盖，服务 ≥70%）。

Document/16_仓库拆分与子模块使用说明.md

@@ -15,10 +15,10 @@
 - **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/`
+- **Gateway** 保持独立仓库：不以子模块形式挂回 AdminApi/TenantApi（避免耦合与引用链）。
 
 ## 3. 克隆与初始化
 
@@ -30,6 +30,9 @@ git clone --recurse-submodules -b dev git@github.com:msumshk/TakeoutSaaS.AdminAp
 
 # TenantApi
 git clone --recurse-submodules -b dev git@github.com:msumshk/TakeoutSaaS.TenantApi.git
+
+# Gateway
+git clone -b dev git@github.com:msumshk/TakeoutSaaS.Gateway.git
 ```
 
 ### 3.2 已有仓库补齐子模块
@@ -62,16 +65,15 @@ git submodule update --remote --merge
 ## 5. 常用运行入口
 
 ```bash
-# AdminApi
+# AdminApi（在 TakeoutSaaS.AdminApi 仓库根目录）
 dotnet run --project src/Api/TakeoutSaaS.AdminApi/TakeoutSaaS.AdminApi.csproj
 
-# TenantApi - MiniApi
+# TenantApi - MiniApi（在 TakeoutSaaS.TenantApi 仓库根目录）
 dotnet run --project src/Api/TakeoutSaaS.MiniApi/TakeoutSaaS.MiniApi.csproj
 
-# TenantApi - UserApi
+# TenantApi - UserApi（在 TakeoutSaaS.TenantApi 仓库根目录）
 dotnet run --project src/Api/TakeoutSaaS.UserApi/TakeoutSaaS.UserApi.csproj
 
-# Gateway（独立仓库）
+# Gateway（在 TakeoutSaaS.Gateway 仓库根目录）
 dotnet run --project TakeoutSaaS.ApiGateway.csproj
 ```
-