5.1 KiB
5.1 KiB
API 边界与自检清单
目的：明确 Admin/User/Mini 三个 API 的职责边界，避免跨端耦合。开发新接口或改动现有控制器时请对照自检，确保租户、安全、DTO、路由符合约定。
说明：仓库已拆分为
TakeoutSaaS.AdminApi（管理后台）与TakeoutSaaS.TenantApi（UserApi/MiniApi）。本文档只对边界与自检项作约束，控制器清单仅对 AdminApi 维护，其余端以各自仓库代码为准。
1. AdminApi（管理后台）
- 归属仓库：
TakeoutSaaS.AdminApi - 面向对象：平台运营、客服、内部管理。
- 职责：商户/门店/商品/订单/支付/配送/字典/权限/RBAC/审计/系统参数等后台管理与洞察。
- 鉴权：JWT + RBAC（
[Authorize]+PermissionAuthorize）；不强制租户头，AdminApi 默认不做租户隔离（内部工具允许跨租户查询）。如需限定租户，请在路由/参数中显式指定tenantId并在应用层校验。 - 路由前缀：
api/admin/v{version}/...。 - DTO/约束：仅管理字段，禁止返回 C 端敏感信息；long -> string；严禁实体直接返回。
- 现有控制器（以仓库代码为准）：
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。 - 自检清单：
- 是否需要权限校验？未加则补
[Authorize]+PermissionAuthorize（内部只读工具也至少需要[Authorize]，避免误暴露）。 - 是否调用了应用层 CQRS，而非在 Controller 写业务？
- DTO 是否按管理口径，未暴露用户端字段？
- 是否使用参数化/AsNoTracking/投影，避免 N+1？
- 路由和 Swagger 示例是否明确权限含义（AdminApi 不要求租户头）？
- 是否需要权限校验？未加则补
- 自检记录：已移除租户侧控制器（如
TenantsController、TenantPackagesController、TenantBillingsController等）。UsersController仅管理平台管理员账号（Portal=Admin且TenantId=null），不做租户侧兼容/兜底。
2. UserApi（C 端用户）
- 归属仓库：
TakeoutSaaS.TenantApi - 面向对象：App/H5 普通用户。
- 职责：菜单浏览、下单、支付、评价、地址、售后、订单查询、支付/配送回调（验证签名）等用户闭环。
- 鉴权：用户 JWT，租户隔离；幂等接口需校验。
- 路由前缀：
api/user/v{version}/...。 - DTO/约束：仅用户侧可见字段，屏蔽后台配置字段；long -> string。
- 现有控制器：以
TakeoutSaaS.TenantApi仓库为准（此处不维护清单，避免与代码偏差）。 - 自检清单：
- 是否暴露给用户的纯前台功能？后台配置请放 AdminApi。
- 是否做租户隔离、用户鉴权、签名/幂等校验？
- 响应是否脱敏且只含用户需要的字段？
- 是否避免跨端复用后台 DTO/命令？
- 回调路由是否验证签名/防重放？
3. MiniApi（小程序端）
- 归属仓库：
TakeoutSaaS.TenantApi - 面向对象：微信/小程序前端。
- 职责：小程序登录/刷新、当前用户档案、订阅消息、直传凭证、小程序场景特定的下单/浏览等。
- 鉴权：小程序登录态/Token，租户隔离；必要时区分渠道。
- 路由前缀：
api/mini/v{version}/...。 - DTO/约束：遵循小程序接口规范，错误码与前端对齐；long -> string。
- 现有控制器：以
TakeoutSaaS.TenantApi仓库为准（此处不维护清单，避免与代码偏差）。 - 自检清单：
- 是否为小程序特有流程（code2session、订阅消息、直传等）？通用用户接口放 UserApi。
- 是否完成租户/鉴权校验，区分渠道标识？
- 请求/响应是否符合小程序对错误码与字段的约定？
- 是否避免使用后台管理 DTO/权限模型？
- 上传/直传接口是否限制 MIME/大小并做鉴权？
4. 共通约束
- 分层：Controller 仅做路由/DTO 转换，业务放 Application 层 Handler。
- 租户：TenantApi 必须强制租户隔离；AdminApi 作为内部平台工具默认允许跨租户查询，但必须受 RBAC 与审计约束。
- 日志/观测：TraceId/SpanId 已贯通；/metrics、/healthz 按服务暴露。
- 命名：输入
XxxRequest、输出XxxDto；文件名与类名一致；布尔属性加Is/Has。 - 发布前检查：运行
dotnet build，必要时补 Swagger 示例、单元测试（核心逻辑 100% 覆盖，服务 ≥70%）。