# 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 统一返回：

```json
{
  "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/`、本地压缩包、凭据文件和其他本地产物推送到云仓库。

原因：

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

影响：

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