MesUniversalApi-Migration/working1/01-项目功能内容.md

01-项目功能内容

1. 项目目标

建设一个替代当前 MES_Manage/submit/MESCommonBase.ashx 的通用 WebAPI 服务，运行在 Linux 操作系统上，面向前台提供统一接口，并支持以下数据库：

• SQL Server
• PostgreSQL
• MySQL

新项目不是简单把 ashx 改成 WebAPI，而是把旧项目中“前台通过 Type/Name/Param 驱动 SQL 和存储过程”的模式改造成：

前台调用 WebAPI
  -> 后端按 actionId 或 legacy type 找白名单
  -> Provider 层选择 SQL Server / PostgreSQL / MySQL
  -> 统一参数、统一鉴权、统一响应、统一日志

1.1 目标 SDK 与目录基线

• 新项目目标 SDK 固定为 .NET 10。
• 新项目目标 TargetFramework 固定为 net10.0。
• 新代码根目录固定为 MesUniversalApi/。
• working/ 仅保留分析资料，working1/ 仅保留项目管理文档。
• 在 .NET 10 SDK 安装到位前，只进行文档、目录、资产盘点和接口梳理，不以 net9.0 临时创建正式项目。

2. 旧系统核心能力

旧系统入口：

MES_Manage/submit/MESCommonBase.ashx

旧系统主要能力：

能力	旧 Type	说明
Excel 导出	2001	调用 MESDownloadExcel.ExcelWebCall.ExcelFile
PDF 导出	2002	调用 ExcelWebCall.ExcelFilePdf
Excel 图片或指定扩展名导出	2003	读取 Form 第一项，生成下载文件
数据库文件下载	2004	调用 DataLink.ExePROCEDURE_Type2004
文件上传	15	读取 Request.Files[0]，调用 ExePROCEDURE_Type15
数据库文件下载	16	调用 ExePROCEDURE_Type16
IP 查询	4000	返回请求 IP
通用 SQL/存储过程调用	default	调用 DataLink.SqlWebCall(type,jsonData,dataobj)

SqlWebCall 的二次分发能力：

能力	旧 Type
加密、注册、登录	8888/5001/5002
旧协议存储过程	1/2/5
新协议存储过程	11/111/12/13/21
直接 SQL 查询或执行	3/4/22/1001/1002/3001
动态建表导入	7

3. 新项目功能范围

3.1 WebAPI 基础能力

新项目必须提供：

• HTTP JSON API。
• OpenAPI/Swagger 文档。
• JWT 鉴权。
• CORS 配置。
• 健康检查接口。
• 统一异常处理中间件。
• 统一响应结构。
• 结构化日志和审计日志。
• Linux 部署能力。

3.2 多数据库执行能力

新项目必须支持：

• SQL Server 连接和执行。
• PostgreSQL 连接和执行。
• MySQL 连接和执行。
• 参数绑定。
• 查询返回动态结果集。
• 非查询执行。
• 存储过程或函数调用。
• 分页查询。
• 文件二进制上传和下载。

数据库访问不允许散落在 Controller 中，必须通过 Provider 抽象：

IDatabaseProvider
  |-- SqlServerProvider
  |-- PostgreSqlProvider
  |-- MySqlProvider

3.3 旧协议兼容能力

新项目应提供短期兼容接口：

POST /api/v1/legacy/execute

兼容字段：

• type
• name
• param
• token
• pageSize
• pageList
• Pagination

兼容原则：

• 兼容不等于完全放开。
• name 必须命中白名单。
• 高风险 Type 默认不开放。
• 旧接口只作为迁移过渡，不作为长期推荐接口。

3.4 新 actionId 接口

新业务推荐使用：

POST /api/v1/actions/{actionId}/execute

例如：

POST /api/v1/actions/quality.line.query/execute

好处：

• 前台不再传 SQL。
• 前台不再传存储过程名。
• 后端可按 actionId 做权限、参数、数据库命令和审计控制。

3.5 文件接口

上传：

POST /api/v1/files/{actionId}/upload

下载：

GET /api/v1/files/{actionId}/download

文件功能要求：

• 支持 multipart 上传。
• 支持文件大小限制。
• 支持扩展名白名单。
• 支持下载文件名 UTF-8 编码。
• 支持跨域读取 Content-Disposition。
• 支持数据库 BLOB 或外部文件存储。

3.6 报表导出

旧 2001/2002/2003 迁移为报表 action。

建议接口：

POST /api/v1/reports/{reportId}/export

输出格式：

• Excel
• PDF
• 后续可扩展 CSV

4. 不在首期范围内的内容

首期不建议做：

• 一次性把所有 SQL Server 存储过程自动翻译成 MySQL/PostgreSQL。
• 继续开放任意 SQL 执行给前台。
• 重写全部前端。
• 重写所有 Excel 模板。
• 建立复杂低代码平台。

首期重点应是：

WebAPI 化 + SQL Server 兼容 + 白名单治理 + Provider 抽象

5. 旧 Type 到新功能映射

旧 Type	新项目目标功能	首期策略
2001	Excel 导出	转报表 action
2002	PDF 导出	转报表 action
2003	扩展导出	评估后转报表 action
2004	文件下载	转文件下载 action
15	文件上传	转文件上传 action
16	文件下载	转文件下载 action
4000	IP 查询	独立诊断接口
1/2/5	旧协议存储过程	兼容但必须白名单
11/111/12/13/21	新协议存储过程	优先兼容
8888/5001/5002	加密、注册、登录	迁移到 Auth API
3/4/7/22/1001/1002/3001	直接 SQL 或建表	默认禁用或仅管理端审计开放

6. 目标质量属性

6.1 安全

• 所有执行业务接口默认要求登录。
• action 必须白名单。
• 参数必须按定义校验。
• 禁止前台任意传 SQL。
• 文件上传必须校验大小和类型。
• 连接字符串不进入代码仓库。

6.2 可移植

• 运行在 Linux。
• 支持 Docker。
• 支持 systemd。
• 不依赖 IIS。
• 不依赖 .NET Framework。

6.3 可观测

• 每次执行有 traceId。
• 每个 action 记录耗时。
• 记录数据库类型和数据源。
• 记录错误摘要。
• 支持健康检查。

6.4 可维护

• Controller 只负责 HTTP 协议。
• 业务编排在 Application 层。
• 数据库差异在 Infrastructure Provider 层。
• 任务推进受 04-任务矩阵.md 控制。

6.5 目录边界

• 不在 MES_Manage/ 和 02DataLinkMesWork/ 中直接展开新 WebAPI 开发。
• 不把新项目证据散落到旧项目目录。
• 新项目代码、测试、部署、工具和附件统一进入 MesUniversalApi/。
• working1/05-验收证据.md 负责证据索引，原始附件优先放到 MesUniversalApi/evidence/。

7. 首批验收目标

首批可验收功能：

1. WebAPI 项目可在 Linux 启动。
2. Swagger 可打开。
3. JWT 登录和鉴权可用。
4. SQL Server Provider 可执行旧 Type=11 查询。
5. Legacy 接口可接收旧格式请求。
6. actionId 接口可执行一个白名单查询。
7. 文件下载可返回正确文件名和二进制。
8. 审计日志可记录用户、action、数据库、耗时、结果。