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