From b587e8c1e11f6de26443faa95430afcac3569de5 Mon Sep 17 00:00:00 2001
From: MSuMshk <2039814060@qq.com>
Date: Sat, 22 Nov 2025 21:20:49 +0800
Subject: [PATCH 01/56] feat(shared-web): add shared swagger and tracing
utilities
---
0_Document/10_TODO.md | 62 +++++++++++
.../Controllers/HealthController.cs | 28 +++++
src/Api/TakeoutSaaS.AdminApi/Program.cs | 76 +++++++++++++
.../Controllers/HealthController.cs | 28 +++++
src/Api/TakeoutSaaS.MiniApi/Program.cs | 76 +++++++++++++
.../Controllers/HealthController.cs | 28 +++++
src/Api/TakeoutSaaS.UserApi/Program.cs | 76 +++++++++++++
.../Diagnostics/TraceContext.cs | 25 +++++
.../Results/ApiResponse.NonGeneric.cs | 31 ++++++
.../Results/ApiResponse.cs | 105 ++++++++++++++++++
.../ApplicationBuilderExtensions.cs | 22 ++++
.../Extensions/ServiceCollectionExtensions.cs | 48 ++++++++
.../Filters/ValidateModelAttribute.cs | 29 +++++
.../Middleware/CorrelationIdMiddleware.cs | 85 ++++++++++++++
.../Middleware/ExceptionHandlingMiddleware.cs | 86 ++++++++++++++
.../Middleware/RequestLoggingMiddleware.cs | 43 +++++++
.../Middleware/SecurityHeadersMiddleware.cs | 27 +++++
.../Swagger/ConfigureSwaggerOptions.cs | 60 ++++++++++
.../Swagger/SwaggerDocumentSettings.cs | 22 ++++
.../Swagger/SwaggerExtensions.cs | 65 +++++++++++
.../TakeoutSaaS.Shared.Web.csproj | 23 ++++
.../TakeoutSaaS.Module.Tenancy.csproj | 13 +++
22 files changed, 1058 insertions(+)
create mode 100644 0_Document/10_TODO.md
create mode 100644 src/Api/TakeoutSaaS.AdminApi/Controllers/HealthController.cs
create mode 100644 src/Api/TakeoutSaaS.AdminApi/Program.cs
create mode 100644 src/Api/TakeoutSaaS.MiniApi/Controllers/HealthController.cs
create mode 100644 src/Api/TakeoutSaaS.MiniApi/Program.cs
create mode 100644 src/Api/TakeoutSaaS.UserApi/Controllers/HealthController.cs
create mode 100644 src/Api/TakeoutSaaS.UserApi/Program.cs
create mode 100644 src/Core/TakeoutSaaS.Shared.Abstractions/Diagnostics/TraceContext.cs
create mode 100644 src/Core/TakeoutSaaS.Shared.Abstractions/Results/ApiResponse.NonGeneric.cs
create mode 100644 src/Core/TakeoutSaaS.Shared.Abstractions/Results/ApiResponse.cs
create mode 100644 src/Core/TakeoutSaaS.Shared.Web/Extensions/ApplicationBuilderExtensions.cs
create mode 100644 src/Core/TakeoutSaaS.Shared.Web/Extensions/ServiceCollectionExtensions.cs
create mode 100644 src/Core/TakeoutSaaS.Shared.Web/Filters/ValidateModelAttribute.cs
create mode 100644 src/Core/TakeoutSaaS.Shared.Web/Middleware/CorrelationIdMiddleware.cs
create mode 100644 src/Core/TakeoutSaaS.Shared.Web/Middleware/ExceptionHandlingMiddleware.cs
create mode 100644 src/Core/TakeoutSaaS.Shared.Web/Middleware/RequestLoggingMiddleware.cs
create mode 100644 src/Core/TakeoutSaaS.Shared.Web/Middleware/SecurityHeadersMiddleware.cs
create mode 100644 src/Core/TakeoutSaaS.Shared.Web/Swagger/ConfigureSwaggerOptions.cs
create mode 100644 src/Core/TakeoutSaaS.Shared.Web/Swagger/SwaggerDocumentSettings.cs
create mode 100644 src/Core/TakeoutSaaS.Shared.Web/Swagger/SwaggerExtensions.cs
create mode 100644 src/Core/TakeoutSaaS.Shared.Web/TakeoutSaaS.Shared.Web.csproj
create mode 100644 src/Modules/TakeoutSaaS.Module.Tenancy/TakeoutSaaS.Module.Tenancy.csproj
diff --git a/0_Document/10_TODO.md b/0_Document/10_TODO.md
new file mode 100644
index 0000000..7157dbf
--- /dev/null
+++ b/0_Document/10_TODO.md
@@ -0,0 +1,62 @@
+# TODO Roadmap
+
+说明:本清单覆盖当前阶段的骨架搭建与核心基础能力(不含部署与CI/CD,留到项目跑通后再做)。
+
+## A. 基础骨架与规范
+- [x] 统一返回结果/异常处理中间件(Shared.Web)
+- [x] 模型验证、验证失败统一输出(Shared.Web)
+- [x] 统一日志(Serilog)与请求日志/TraceId(Shared.Web)
+- [x] API 版本化与分组(AdminApi、MiniApi、UserApi)
+- [x] Swagger 定制(鉴权按钮、分组说明、示例)
+- [x] 安全中间件:Security Headers、CORS 策略(按端区分)
+
+## B. 认证与权限
+- [ ] JWT 颁发与刷新(AdminApi、MiniApi)
+- [ ] RBAC 权限模型(角色/权限/策略)与特性授权(AdminApi)
+- [ ] 小程序登录(微信 code2Session)并绑定用户账户(MiniApi)
+- [ ] 登录防刷限流(MiniApi)
+
+## C. 多租户与参数字典
+- [ ] 多租户中间件:从 Header/域名解析租户(Shared.Web + Tenancy)
+- [ ] EF Core 全局查询过滤(tenant_id)
+- [ ] 参数字典模块(系统参数/业务参数)CRUD 与缓存(Dictionary 模块)
+
+## D. 数据访问与多数据源
+- [ ] EF Core 10 基础上下文、实体基类、审计字段
+- [ ] 读写分离/多数据源配置(主写、从读;或按租户切库预留)
+- [ ] Dapper 基础设施封装(统计/报表类查询)
+
+## E. 文件与存储
+- [ ] 存储模块抽象(本地/MinIO/云厂商适配)
+- [ ] 上传接口(AdminApi、MiniApi)与签名直传预留
+- [ ] 图片/文件访问安全策略(防盗链、过期签名)
+
+## F. 短信与消息队列
+- [ ] 短信模块(阿里云/腾讯云 适配占位)与验证码发送
+- [ ] MQ 模块(RabbitMQ)Publisher/Subscriber 抽象
+- [ ] 业务事件定义(订单创建/支付成功等)与事件发布入口
+
+## G. 调度与定时任务
+- [ ] 调度模块(Quartz/Hangfire 二选一,默认 Hangfire)
+- [ ] 基础任务:订单超时取消、优惠券过期处理、日志清理
+- [ ] 调度面板(后续 AdminUI 对接)
+
+## H. 第三方配送对接(仅第三方)
+- [ ] 配送适配抽象(达达/闪送/顺丰同城等)
+- [ ] 统一下单/取消/查询接口与回调验签
+- [ ] AdminApi 后台运力单查询与补单
+
+## I. 网关与横切能力
+- [ ] YARP 路由拆分(/api/admin、/api/mini、/api/user)
+- [ ] 网关级限流与请求日志
+- [ ] 透传鉴权/租户标识与统一错误页
+
+## J. 测试与质量
+- [ ] 单元测试工程骨架(xUnit + FluentAssertions)
+- [ ] 集成测试基座(WebApplicationFactory、测试容器)
+- [ ] 静态分析与风格规范(.editorconfig)
+
+## K. 文档与规范落地
+- [ ] 在文档中补充:仅第三方配送的接口与回调规范
+- [ ] MiniApi 认证流程图(微信登录)与错误码
+- [ ] 模块间调用关系图与依赖边界
diff --git a/src/Api/TakeoutSaaS.AdminApi/Controllers/HealthController.cs b/src/Api/TakeoutSaaS.AdminApi/Controllers/HealthController.cs
new file mode 100644
index 0000000..68ca72d
--- /dev/null
+++ b/src/Api/TakeoutSaaS.AdminApi/Controllers/HealthController.cs
@@ -0,0 +1,28 @@
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Http;
+using Microsoft.AspNetCore.Mvc;
+using TakeoutSaaS.Shared.Abstractions.Results;
+using TakeoutSaaS.Shared.Web.Api;
+
+namespace TakeoutSaaS.AdminApi.Controllers;
+
+///
+/// 管理后台 - 健康检查。
+///
+[ApiVersion("1.0")]
+[Route("api/admin/v{version:apiVersion}/[controller]")]
+public class HealthController : BaseApiController
+{
+ ///
+ /// 获取服务健康状态。
+ ///
+ /// 健康状态
+ [HttpGet]
+ [AllowAnonymous]
+ [ProducesResponseType(typeof(ApiResponse