MesUniversalApi-Migration/working1/06-决策记录.md

06-决策记录

本文件记录关键技术决策。格式参考 ADR。

状态说明：

• 已采纳
• 待确认
• 废弃

ADR-001 - 使用 C# 与 ASP.NET Core Web API

状态：已采纳

日期：2026-07-02

背景：

• 当前系统为 C#/.NET Framework + .ashx。
• 目标系统要求运行在 Linux。
• 前台通过 WebAPI 调用。

决策：

• 新项目使用 C#。
• Web 框架使用 ASP.NET Core Web API。
• 运行时优先使用 .NET 10 LTS。

原因：

• 与现有代码和团队知识体系最接近。
• ASP.NET Core 可跨平台运行。
• WebAPI、Swagger、JWT、HealthCheck、日志、Docker 支持成熟。

影响：

• 旧 .ashx 不直接迁移，改为 Controller。
• 旧 .NET Framework 依赖需要替换为 .NET 跨平台库。

ADR-002 - 使用 Provider 策略支持多数据库

状态：已采纳

日期：2026-07-02

背景：

• 目标支持 SQL Server、PostgreSQL、MySQL。
• 三种数据库在参数、分页、存储过程、函数、二进制字段、标识符引用方面存在差异。

决策：

• 定义 IDatabaseProvider 抽象。
• 分别实现 SqlServerProvider、PostgreSqlProvider、MySqlProvider。
• 数据库差异只允许在 Provider 层处理。

原因：

• 避免 Controller 和业务层散落数据库判断。
• 允许同一个 actionId 对不同数据库配置不同 SQL 或函数。
• 便于单独测试每种数据库。

影响：

• 首期要设计好 DbExecutionContext 和参数模型。
• 不追求三种数据库完全共用同一段 SQL。

ADR-003 - 使用 actionId 白名单替代前台任意传 SQL/存储过程名

状态：已采纳

日期：2026-07-02

背景：

• 旧系统 Name/name 可由前台传入。
• Name/name 可能是存储过程名、SQL 文本或表名。
• 存在较高安全风险。

决策：

• 新接口以 actionId 作为业务动作标识。
• actionId 在后端白名单中配置 SQL、存储过程、参数、权限。
• legacy 接口也必须经过白名单。

原因：

• 降低 SQL 注入和越权执行风险。
• 便于审计。
• 便于多数据库为同一个 action 配置不同实现。

影响：

• 需要建设 action 配置。
• 前台后续要逐步从 type/name/param 迁移到 actionId/parameters。

ADR-004 - 保留 Legacy 接口作为迁移过渡

状态：已采纳

日期：2026-07-02

背景：

• 现有前台可能大量依赖 Type/Name/Param。
• 一次性改前台和后端风险较大。

决策：

• 新项目提供 /api/v1/legacy/execute。
• 兼容旧字段，但不允许任意执行。
• 高风险 Type 默认禁用或限制。

原因：

• 降低迁移成本。
• 可逐个业务回归。
• 为前台改造争取时间。

影响：

• 需要实现 LegacyTypeRouter 和 LegacyParamParser。
• 需要维护旧 Type 到 action 的映射。

ADR-005 - SQL Server 优先落地，再扩展 PostgreSQL 和 MySQL

状态：已采纳

日期：2026-07-02

背景：

• 当前系统主要依赖 SQL Server。
• 直接同步完成三类数据库会扩大风险。

决策：

• 第一阶段先实现 SQL Server Provider。
• 在 SQL Server 上跑通 legacy 兼容和 actionId。
• 再实现 PostgreSQL Provider。
• 再实现 MySQL Provider。

原因：

• 先保证现有业务迁移可行。
• Provider 抽象可在 SQL Server 实战中校准。
• 后续数据库迁移按 action 渐进完成。

影响：

• 多数据库不是第一天全部完成。
• 任务矩阵需要把三类数据库分开验收。

ADR-006 - 不自动翻译全部 SQL Server 存储过程

状态：已采纳

日期：2026-07-02

背景：

• SQL Server、PostgreSQL、MySQL 语法和过程语义差异明显。
• 自动翻译容易造成隐性错误。

决策：

• 不做全量自动 SQL 翻译。
• 按 actionId 逐个迁移。
• 每个 action 针对不同数据库配置独立 command。

原因：

• 便于测试。
• 便于控制风险。
• 避免假兼容。

影响：

• 迁移周期会按业务 action 分批推进。
• 需要建立回归测试样本。

ADR-007 - 统一 JSON 响应格式

状态：已采纳

日期：2026-07-02

背景：

• 旧接口返回格式混杂：数组 JSON、result=1/0、{code,message,data}、文本、空响应、NULL。

决策：

• 新 JSON API 统一返回：

{
  "code": "200",
  "message": "",
  "data": {},
  "traceId": ""
}

原因：

• 前台处理更简单。
• 错误更清晰。
• 审计和排障更方便。

影响：

• legacy 兼容接口可短期保留旧格式，但新接口必须统一格式。

ADR-008 - 强制鉴权而不是 token 非空才校验

状态：已采纳

日期：2026-07-02

背景：

• 旧代码中很多方法只在 token 非空时校验。
• 不传 token 时可能继续执行。

决策：

• 新系统除登录、健康检查等公开接口外，默认都要求 JWT 鉴权。
• action 再做权限校验。

原因：

• 明确安全边界。
• 防止前台漏传 token 导致绕过。
• 便于统一审计用户身份。

影响：

• 前台必须接入登录和 Bearer Token。
• legacy 接口也默认要求 JWT。

ADR-009 - 高风险 Type 默认禁用或治理后开放

状态：已采纳

日期：2026-07-02

背景：

旧系统以下 Type 风险较高：

• 3
• 4
• 7
• 22
• 1001
• 1002
• 3001

决策：

• 生产环境默认禁用。
• 如确需保留，必须在管理端、内网、强审计、白名单条件下开放。

原因：

• 这些 Type 涉及直接 SQL、动态建表、命令执行。
• 多数据库迁移后风险会扩大。

影响：

• 需要逐个找替代 action。
• 需要和前台确认是否仍在使用。

ADR-010 - 文件存储优先支持数据库二进制，后续可扩展对象存储

状态：待确认

日期：2026-07-02

背景：

• 旧系统文件上传下载通过数据库存取 byte[]。
• 新系统需要兼容旧业务。
• 大文件放数据库可能影响性能和备份。

决策：

• 首期兼容数据库二进制。
• 设计 FileService 时预留对象存储或文件系统扩展。

原因：

• 首期降低迁移成本。
• 后续可按文件大小和业务类型分流。

待确认：

• 是否有大文件场景。
• 是否已有对象存储、NAS 或 MinIO。
• 是否要求文件加密和病毒扫描。

ADR-011 - 新移植代码目录独立使用 MesUniversalApi

状态：已采纳

日期：2026-07-02

背景：

• 当前仓库根目录同时包含旧 WebSite、旧类库、分析资料和管理文档。
• 如果直接在旧系统目录中混合创建新 WebAPI 代码，后续盘点、验收和回归会变得混乱。

决策：

• 新移植项目统一放在 MesUniversalApi/。
• working/ 继续保留旧系统分析资料。
• working1/ 继续保留项目管理文档。

原因：

• 代码边界清晰。
• 旧系统可继续作为回归基线。
• 便于后续单独初始化 git 仓库、部署和验收。

影响：

• T002 及后续所有新代码、测试、部署和工具脚本都从 MesUniversalApi/ 开始。
• 不在 MES_Manage/、02DataLinkMesWork/ 等旧目录中直接展开新 WebAPI 开发。

ADR-012 - 在 .NET 10 SDK 到位前只做基线准备，不用低版本临时落地

状态：已采纳

日期：2026-07-02

背景：

• 新项目目标运行时已确定为 .NET 10。
• 当前开发机仅检测到 .NET SDK 9.0.311。

决策：

• 在 .NET 10 SDK 安装到位前，只做文档、目录、任务、证据和资产盘点准备。
• 不以 net9.0 或更低版本临时创建正式项目骨架。
• 待 .NET 10 SDK 安装后，再在 MesUniversalApi/ 中创建 global.json 和正式项目文件。

原因：

• 避免先建低版本项目再返工升级。
• 避免把环境缺口误判为代码问题。
• 保持目标技术基线一致。

影响：

• 当前轮次不会生成可编译的 net10.0 项目代码。
• T002 的执行前置条件明确依赖 .NET 10 SDK 安装完成。

ADR-013 - 云仓库只提交迁移资料和新移植目录

状态：已采纳

日期：2026-07-02

背景：

• 当前本地根目录同时包含旧系统源码、IDE 状态、二进制产物、压缩包、分析资料和新移植目录。
• 用户要求把当前迁移工作提交到云仓库。

决策：

• 云仓库只跟踪 working/、working1/ 和 MesUniversalApi/。
• 不把旧系统全量源码、.vs/、本地压缩包、凭据文件和其他本地产物推送到云仓库。

原因：

• 保持仓库聚焦于迁移工作本身。
• 降低无关大文件和本地状态污染。
• 避免把本地凭据文件一并入库。

影响：

• 云仓库是迁移工作仓库，不是旧系统完整备份仓库。
• 如果后续确需纳入某部分旧代码，应单独评估并更新范围控制规则。