chore: initialize migration workspace

working1/06-决策记录.md

@@ -0,0 +1,384 @@
+# 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/`、本地压缩包、凭据文件和其他本地产物推送到云仓库。
+
+原因：
+
+- 保持仓库聚焦于迁移工作本身。
+- 降低无关大文件和本地状态污染。
+- 避免把本地凭据文件一并入库。
+
+影响：
+
+- 云仓库是迁移工作仓库，不是旧系统完整备份仓库。
+- 如果后续确需纳入某部分旧代码，应单独评估并更新范围控制规则。