chore: initialize migration workspace

2026-07-02 10:38:13 +08:00
commit 705aec6ab2
44 changed files with 5988 additions and 0 deletions
--- a/working1/02-项目程序开发详细步骤.md
+++ b/working1/02-项目程序开发详细步骤.md
@@ -0,0 +1,526 @@
+# 02-项目程序开发详细步骤
+
+## 1. 开发总路线
+
+项目推荐按以下顺序推进：
+
+```text
+准备阶段
+  -> 建立 WebAPI 骨架
+  -> 建立通用契约和响应
+  -> 建立数据库 Provider 抽象
+  -> 实现 SQL Server Provider
+  -> 实现 Legacy 兼容入口
+  -> 加入 actionId 白名单
+  -> 实现文件上传下载
+  -> 实现 PostgreSQL Provider
+  -> 实现 MySQL Provider
+  -> Linux 部署和回归测试
+```
+
+## 2. 技术栈
+
+推荐：
+
+- 语言：C#
+- 框架：ASP.NET Core Web API
+- 运行时：.NET 10 LTS
+- 数据访问：ADO.NET + Provider 策略；必要时配合 Dapper
+- SQL Server 驱动：`Microsoft.Data.SqlClient`
+- PostgreSQL 驱动：`Npgsql`
+- MySQL 驱动：`MySqlConnector`
+- 部署：Linux + Docker 或 systemd
+- 反向代理：Nginx
+- 文档：OpenAPI/Swagger
+- 日志：Serilog 或 Microsoft.Extensions.Logging + OpenTelemetry
+
+## 3. 新项目结构
+
+建议结构：
+
+```text
+MesUniversalApi/
+  src/
+    MesUniversalApi.Api/
+    MesUniversalApi.Application/
+    MesUniversalApi.Contracts/
+    MesUniversalApi.Domain/
+    MesUniversalApi.Infrastructure/
+  tests/
+    MesUniversalApi.Tests/
+    MesUniversalApi.IntegrationTests/
+```
+
+当前移植根目录已先行创建为：
+
+```text
+MesUniversalApi/
+  src/
+  tests/
+  deploy/
+    docker/
+    systemd/
+  docs/
+  tools/
+  evidence/
+```
+
+职责：
+
+| 项目 | 职责 |
+| --- | --- |
+| `Api` | Controller、鉴权、Swagger、过滤器、中间件 |
+| `Application` | ActionService、LegacyTypeRouter、FileService、AuthService |
+| `Contracts` | 请求和响应 DTO |
+| `Domain` | ActionDefinition、DataSourceDefinition、业务模型 |
+| `Infrastructure` | 数据库 Provider、日志、配置、JWT |
+| `Tests` | 单元测试和集成测试 |
+
+### 3.1 开工前置条件
+
+开始 `T002 新 WebAPI 项目骨架创建` 之前，必须满足以下条件：
+
+1. 开发机已安装 `.NET 10 SDK`。
+2. `dotnet --list-sdks` 输出中包含 `10.0.x`。
+3. 在 `MesUniversalApi/` 根目录创建 `global.json`，锁定实际安装的 `10.0.x`。
+4. 不以 `net9.0` 或更低版本临时创建正式项目骨架。
+5. 旧系统目录只用于盘点和对照，新增代码只进入 `MesUniversalApi/`。
+
+截至 2026-07-02，当前机器仅检测到 `.NET SDK 9.0.311`，因此本轮只完成目录和文档准备，不执行 `net10.0` 项目生成。
+
+## 4. 第一步：创建 WebAPI 骨架
+
+建议命令：
+
+```bash
+cd MesUniversalApi
+dotnet new globaljson --sdk-version 10.0.xxx
+dotnet new sln -n MesUniversalApi
+dotnet new webapi -f net10.0 -n MesUniversalApi.Api -o src/MesUniversalApi.Api
+dotnet new classlib -f net10.0 -n MesUniversalApi.Application -o src/MesUniversalApi.Application
+dotnet new classlib -f net10.0 -n MesUniversalApi.Contracts -o src/MesUniversalApi.Contracts
+dotnet new classlib -f net10.0 -n MesUniversalApi.Domain -o src/MesUniversalApi.Domain
+dotnet new classlib -f net10.0 -n MesUniversalApi.Infrastructure -o src/MesUniversalApi.Infrastructure
+dotnet sln add src/**/*.csproj
+```
+
+说明：
+
+- `10.0.xxx` 需替换为开发机实际安装的 `.NET 10 SDK` 版本号。
+- 以上命令在 `.NET 10 SDK` 安装完成后执行。
+- 当前轮次不以 `net9.0` 代替 `net10.0` 创建正式骨架。
+
+依赖关系：
+
+```text
+Api -> Application -> Domain
+Api -> Contracts
+Application -> Contracts
+Application -> Infrastructure abstractions
+Infrastructure -> Domain / Contracts
+```
+
+## 5. 第二步：统一响应和异常处理
+
+定义响应：
+
+```csharp
+public sealed class ApiResponse<T>
+{
+    public string Code { get; init; } = "200";
+    public string Message { get; init; } = "";
+    public T? Data { get; init; }
+    public string TraceId { get; init; } = "";
+}
+```
+
+分页响应：
+
+```csharp
+public sealed class PageResult
+{
+    public IReadOnlyList<IDictionary<string, object?>> Rows { get; init; } = [];
+    public long Total { get; init; }
+    public int PageIndex { get; init; }
+    public int PageSize { get; init; }
+}
+```
+
+错误中间件：
+
+```text
+ExceptionHandlingMiddleware
+  -> 捕获异常
+  -> 记录 traceId/user/action
+  -> 返回 ApiResponse<object>
+```
+
+## 6. 第三步：配置数据源
+
+配置模型：
+
+```csharp
+public sealed class DataSourceDefinition
+{
+    public string Name { get; init; } = "";
+    public DatabaseKind Kind { get; init; }
+    public string ConnectionStringName { get; init; } = "";
+}
+```
+
+配置示例：
+
+```json
+{
+  "Database": {
+    "DefaultDataSource": "mes-main",
+    "DataSources": {
+      "mes-main": {
+        "Kind": "SqlServer",
+        "ConnectionStringName": "MES_SQLSERVER"
+      },
+      "mes-pg": {
+        "Kind": "PostgreSql",
+        "ConnectionStringName": "MES_POSTGRES"
+      },
+      "mes-mysql": {
+        "Kind": "MySql",
+        "ConnectionStringName": "MES_MYSQL"
+      }
+    }
+  }
+}
+```
+
+连接字符串用环境变量：
+
+```bash
+ConnectionStrings__MES_SQLSERVER="Server=...;Database=...;User Id=...;Password=...;TrustServerCertificate=True"
+ConnectionStrings__MES_POSTGRES="Host=...;Database=...;Username=...;Password=..."
+ConnectionStrings__MES_MYSQL="Server=...;Database=...;User ID=...;Password=..."
+```
+
+## 7. 第四步：实现 Provider 抽象
+
+核心接口：
+
+```csharp
+public interface IDatabaseProvider
+{
+    DatabaseKind Kind { get; }
+    Task<QueryResult> QueryAsync(DbExecutionContext context, CancellationToken ct);
+    Task<NonQueryResult> ExecuteAsync(DbExecutionContext context, CancellationToken ct);
+    Task<ScalarResult> ScalarAsync(DbExecutionContext context, CancellationToken ct);
+}
+```
+
+执行上下文：
+
+```csharp
+public sealed class DbExecutionContext
+{
+    public string DataSourceName { get; init; } = "";
+    public DatabaseKind DatabaseKind { get; init; }
+    public CommandKind CommandKind { get; init; }
+    public string CommandText { get; init; } = "";
+    public IReadOnlyList<DbParameterValue> Parameters { get; init; } = [];
+    public PageRequest? Page { get; init; }
+    public int CommandTimeoutSeconds { get; init; } = 60;
+}
+```
+
+Provider 实现顺序：
+
+1. `SqlServerProvider`
+2. `PostgreSqlProvider`
+3. `MySqlProvider`
+
+## 8. 第五步：SQL Server Provider
+
+先支持 SQL Server，原因：
+
+- 当前旧系统以 SQL Server 存储过程为主。
+- 先迁移入口，降低一次性风险。
+
+实现能力：
+
+- Text 查询。
+- Text 非查询。
+- StoredProcedure 查询。
+- StoredProcedure 非查询。
+- 输出参数。
+- DataSet/DataTable 动态 JSON。
+- 文件二进制。
+
+关键点：
+
+- 使用 `Microsoft.Data.SqlClient`。
+- `CommandType.StoredProcedure` 用于旧存储过程。
+- 参数名前缀统一由 Provider 处理。
+- 命令超时不要照搬 `0`，默认建议 60 秒，可按 action 配置。
+
+## 9. 第六步：Legacy 兼容入口
+
+Controller：
+
+```http
+POST /api/v1/legacy/execute
+```
+
+流程：
+
+```text
+LegacyController
+  -> 接收 type/name/param
+  -> LegacyTypeRouter
+  -> 白名单检查
+  -> LegacyParamParser
+  -> DbExecutionContext
+  -> Provider 执行
+  -> ApiResponse
+```
+
+优先兼容：
+
+- `11`
+- `111`
+- `12`
+- `13`
+- `15`
+- `16`
+- `2004`
+
+高风险 Type 先禁用：
+
+- `3`
+- `4`
+- `7`
+- `22`
+- `1001`
+- `1002`
+- `3001`
+
+## 10. 第七步：actionId 白名单
+
+新增接口：
+
+```http
+POST /api/v1/actions/{actionId}/execute
+```
+
+动作定义：
+
+```csharp
+public sealed class ActionDefinition
+{
+    public string ActionId { get; init; } = "";
+    public string Module { get; init; } = "";
+    public bool Enabled { get; init; }
+    public string[] RequiredRoles { get; init; } = [];
+    public IReadOnlyList<ParameterDefinition> Parameters { get; init; } = [];
+    public IReadOnlyDictionary<DatabaseKind, ProviderCommandDefinition> Commands { get; init; }
+        = new Dictionary<DatabaseKind, ProviderCommandDefinition>();
+}
+```
+
+执行流程：
+
+```text
+ActionController
+  -> ActionService
+  -> 读取 ActionDefinition
+  -> 校验权限
+  -> 校验参数
+  -> 根据 dataSource 选择 DatabaseKind
+  -> 根据 DatabaseKind 选择 CommandDefinition
+  -> Provider 执行
+  -> 统一响应
+```
+
+## 11. 第八步：文件上传下载
+
+上传接口：
+
+```http
+POST /api/v1/files/{actionId}/upload
+```
+
+下载接口：
+
+```http
+GET /api/v1/files/{actionId}/download
+```
+
+开发步骤：
+
+1. 定义文件 action。
+2. 实现上传大小限制。
+3. 实现扩展名白名单。
+4. 实现 MIME 校验。
+5. 实现数据库二进制写入。
+6. 实现下载响应头。
+7. 写文件 hash 校验测试。
+
+二进制类型：
+
+| 数据库 | 类型 |
+| --- | --- |
+| SQL Server | `varbinary(max)` |
+| PostgreSQL | `bytea` |
+| MySQL | `longblob` |
+
+## 12. 第九步：PostgreSQL Provider
+
+实现内容：
+
+- `NpgsqlConnection`
+- 参数转换。
+- Text 查询。
+- Function 查询。
+- 非查询执行。
+- `bytea` 文件读写。
+- `LIMIT/OFFSET` 分页。
+
+迁移建议：
+
+- SQL Server 查询型存储过程迁移为 PostgreSQL function。
+- 输出参数尽量改为返回列或 JSON。
+- 不做简单字符串替换，按 action 重写 SQL。
+
+## 13. 第十步：MySQL Provider
+
+实现内容：
+
+- `MySqlConnection`
+- 参数转换。
+- Text 查询。
+- `CALL procedure(...)`。
+- 非查询执行。
+- `longblob` 文件读写。
+- `LIMIT/OFFSET` 分页。
+
+注意：
+
+- MySQL procedure 输出参数处理与 SQL Server 不同。
+- 同一个 action 可为 MySQL 配置单独 SQL。
+- 不要求 SQL Server 存储过程原样迁移。
+
+## 14. 第十一步：鉴权与授权
+
+实现：
+
+- JWT 登录。
+- `[Authorize]` 保护执行类接口。
+- action 级权限。
+- 用户角色映射。
+- token 过期。
+
+不沿用旧模式：
+
+```text
+token 非空才校验
+```
+
+新模式：
+
+```text
+除登录和健康检查外，默认必须鉴权
+```
+
+## 15. 第十二步：日志与审计
+
+每次执行记录：
+
+- traceId
+- userId
+- clientIp
+- actionId
+- legacyType
+- legacyName
+- dataSource
+- databaseKind
+- commandKind
+- durationMs
+- rowsAffected
+- resultCode
+- errorSummary
+
+日志不记录明文密码和大二进制。
+
+## 16. 第十三步：Linux 部署
+
+Docker：
+
+```bash
+dotnet publish -c Release -o publish
+docker build -t mes-universal-api:1.0.0 .
+docker run -d -p 8080:8080 --env-file .env mes-universal-api:1.0.0
+```
+
+systemd：
+
+```ini
+[Service]
+WorkingDirectory=/opt/mes-api
+ExecStart=/usr/bin/dotnet /opt/mes-api/MesUniversalApi.Api.dll
+Restart=always
+Environment=ASPNETCORE_URLS=http://0.0.0.0:8080
+```
+
+Nginx 反代：
+
+```nginx
+location / {
+    proxy_pass http://127.0.0.1:8080;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+}
+```
+
+## 17. 第十四步：测试
+
+单元测试：
+
+- 参数解析。
+- 类型转换。
+- action 白名单。
+- 权限校验。
+- 响应包装。
+
+集成测试：
+
+- SQL Server 查询。
+- SQL Server 存储过程。
+- PostgreSQL 查询。
+- MySQL 查询。
+- 文件上传下载。
+- JWT 成功和失败。
+
+回归测试：
+
+```text
+旧 ashx 响应
+  vs
+新 legacy/execute 响应
+```
+
+性能测试：
+
+- 大查询。
+- 分页。
+- 文件上传下载。
+- 长存储过程。
+- 连接池。
+
+## 18. 首轮开发建议
+
+第一轮只做最小闭环：
+
+1. 安装并验证 `.NET 10 SDK`。
+2. 新建 WebAPI 项目。
+3. 加统一响应。
+4. 加 Swagger。
+5. 加 SQL Server Provider。
+6. 加一个 actionId 查询。
+7. 加一个 legacy Type=11 查询。
+8. Linux 本地或 Docker 启动。
+9. 记录验收证据。