267 lines
6.7 KiB
Markdown
267 lines
6.7 KiB
Markdown
# 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、数据库、耗时、结果。
|