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

API 边界与自检清单

目的：明确 Admin/User/Mini 三个 API 的职责边界，避免跨端耦合。开发新接口或改动现有控制器时请对照自检，确保租户、安全、DTO、路由符合约定。

1. AdminApi（管理后台）

• 面向对象：运营、客服、商户管理员。
• 职责：租户/门店/商品/订单/支付/配送/字典/权限/RBAC/审计/任务调度等后台管理与洞察。
• 鉴权：JWT + RBAC（[Authorize] + PermissionAuthorize），租户头不再强制（单租户操作以路由 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。
• 自检清单：
  1. 是否需要权限/租户过滤？未加则补 [Authorize] + 租户解析。
  2. 是否调用了应用层 CQRS，而非在 Controller 写业务？
  3. DTO 是否按管理口径，未暴露用户端字段？
  4. 是否使用参数化/AsNoTracking/投影，避免 N+1？
  5. 路由和 Swagger 示例是否含租户/权限说明？
• 自检记录：RolesController 新增模板列表/详情/复制/初始化端点，均已套用 [Authorize] + PermissionAuthorize、仅调用 CQRS/DTO，依赖租户头隔离。TenantPackagesController 与 TenantsController(配额校验) 均使用权限码、DTO 映射，配额校验要求携带租户头防越权。新增租户账单/公告/通知控制器，全部采用 CQRS、权限校验与租户参数，列表分页、未暴露实体。

2. UserApi（C 端用户）

• 面向对象：App/H5 普通用户。
• 职责：菜单浏览、下单、支付、评价、地址、售后、订单查询、支付/配送回调（验证签名）等用户闭环。
• 鉴权：用户 JWT，租户隔离；幂等接口需校验。
• 路由前缀：api/user/v{version}/...。
• DTO/约束：仅用户侧可见字段，屏蔽后台配置字段；long -> string。
• 现有控制器：当前仅 HealthController（业务接口待补）。
• 自检清单：
  1. 是否暴露给用户的纯前台功能？后台配置请放 AdminApi。
  2. 是否做租户隔离、用户鉴权、签名/幂等校验？
  3. 响应是否脱敏且只含用户需要的字段？
  4. 是否避免跨端复用后台 DTO/命令？
  5. 回调路由是否验证签名/防重放？

3. MiniApi（小程序端）

• 面向对象：微信/小程序前端。
• 职责：小程序登录/刷新、当前用户档案、订阅消息、直传凭证、小程序场景特定的下单/浏览等。
• 鉴权：小程序登录态/Token，租户隔离；必要时区分渠道。
• 路由前缀：api/mini/v{version}/...。
• DTO/约束：遵循小程序接口规范，错误码与前端对齐；long -> string。
• 现有控制器：AuthController、MeController、FilesController、HealthController。
• 自检清单：
  1. 是否为小程序特有流程（code2session、订阅消息、直传等）？通用用户接口放 UserApi。
  2. 是否完成租户/鉴权校验，区分渠道标识？
  3. 请求/响应是否符合小程序对错误码与字段的约定？
  4. 是否避免使用后台管理 DTO/权限模型？
  5. 上传/直传接口是否限制 MIME/大小并做鉴权？

4. 共通约束

• 分层：Controller 仅做路由/DTO 转换，业务放 Application 层 Handler。
• 租户：所有写/读需租户过滤；严禁跨租户访问。
• 日志/观测：TraceId/SpanId 已贯通；/metrics、/healthz 按服务暴露。
• 命名：输入 XxxRequest、输出 XxxDto；文件名与类名一致；布尔属性加 Is/Has。
• 发布前检查：运行 dotnet build，必要时补 Swagger 示例、单元测试（核心逻辑 100% 覆盖，服务 ≥70%）。