# 01-项目功能内容

## 1. 项目目标

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

- SQL Server
- PostgreSQL
- MySQL

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

```text
前台调用 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. 旧系统核心能力

旧系统入口：

```text
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 抽象：

```text
IDatabaseProvider
  |-- SqlServerProvider
  |-- PostgreSqlProvider
  |-- MySqlProvider
```

### 3.3 旧协议兼容能力

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

```http
POST /api/v1/legacy/execute
```

兼容字段：

- `type`
- `name`
- `param`
- `token`
- `pageSize`
- `pageList`
- `Pagination`

兼容原则：

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

### 3.4 新 actionId 接口

新业务推荐使用：

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

例如：

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

好处：

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

### 3.5 文件接口

上传：

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

下载：

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

文件功能要求：

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

### 3.6 报表导出

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

建议接口：

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

输出格式：

- Excel
- PDF
- 后续可扩展 CSV

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

首期不建议做：

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

首期重点应是：

```text
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、数据库、耗时、结果。