# 方案 B 详细设计：下游接口明细对齐 API 调试（ApiTest）

> **决策**：采用方案 B（大改），传输层（Query / Body / Header）与映射层（Mapping Body）分离，页面与数据模型对齐 `/api/apiDebugger`。  
> **范围**：`itfx-master` 后端 + `oms0414` 前端 + 数据迁移 + 映射/发布/导入导出/授权联动。  
> **关联文档**：[下游接口明细改造方案-小改vs大改.md](./下游接口明细改造方案-小改vs大改.md)

---

## 目录

1. [目标与原则](#1-目标与原则)
2. [概念模型前后对比](#2-概念模型前后对比)
3. [表结构前后对比](#3-表结构前后对比)
4. [枚举与常量前后对比](#4-枚举与常量前后对比)
5. [接口契约前后对比](#5-接口契约前后对比)
6. [转发与映射逻辑前后对比](#6-转发与映射逻辑前后对比)
7. [前端页面与数据流前后对比](#7-前端页面与数据流前后对比)
8. [关联能力改动清单](#8-关联能力改动清单)
9. [数据迁移方案](#9-数据迁移方案)
10. [兼容策略与版本节奏](#10-兼容策略与版本节奏)
11. [实施阶段建议](#11-实施阶段建议)

---

## 1. 目标与原则

### 1.1 目标

| # | 目标 |
|---|------|
| G1 | 下游接口明细 Request 区与 **ApiTest** 一致：`Query` / `Body` / `Header` 为 KV 表，`Mapping Body` 为参数树 |
| G2 | 解决 **Form 字段值为 JSON** 时，上游映射应对 **JSON 内部结构**（Mapping Body），表单字段用 **`$FromMappingBody`** 引用 |
| G3 | 运行时 **按 FieldPosition** 把表单写入 URL Query、Header、Form Body |
| G4 | 接口映射、发布、导入导出与新区分方式一致 |

### 1.2 设计原则

- **传输层**（真实 HTTP）：`t_parameter_form` + `FieldPosition`（Query / Body / Header）
- **映射层**（上游 → 下游）：`t_parameter` + `ParaKind = MappingBody`
- **Json 下游接口**：Mapping Body 树 **同时** 作为映射目标与 `SerializationBody` 的数据源（无 Form Body KV 或 Body KV 为空）
- **接口级 FixedParameter**：逐步收敛——**Header/Query 迁入 Form**；Fixed 保留 **服务商级**、**Url 路径占位**、**脚本动态写入** 场景
- **兼容一期**：`GetInterfaceById` 仍返回 `formParameterList` / `inParameterList`（聚合旧字段），`SaveInterface` 同时接受新旧字段，服务端以新字段为准

---

## 2. 概念模型前后对比

### 2.1 改造前（现状）

```text
┌─────────────────────────────────────────────────────────────┐
│ 下游接口明细 (InterfaceDetail)                               │
├─────────────────────────────────────────────────────────────┤
│ Query Tab        → formParameterList (t_parameter_form)      │
│                  ⚠️ 后端全部当作 FormUrlEncoded Body，非 URL Query │
├─────────────────────────────────────────────────────────────┤
│ Body Tab         → inParameterList (t_parameter, IsInPara)   │
│                  ⚠️ 同时承担：Json HTTP Body + 上游映射目标    │
├─────────────────────────────────────────────────────────────┤
│ 固定配置 Tab      → FixedParameter 独立 API (t_parameter_fixed) │
│                  Header / Query / Body / Url                 │
├─────────────────────────────────────────────────────────────┤
│ cURL Tab         → inParams 字符串示例                       │
├─────────────────────────────────────────────────────────────┤
│ Response Tab     → outParameterList                          │
└─────────────────────────────────────────────────────────────┘
```

### 2.2 改造后（方案 B）

```text
┌─────────────────────────────────────────────────────────────┐
│ 下游接口明细 (对齐 ApiTest)                                   │
├─────────────────────────────────────────────────────────────┤
│ Query Tab        → queryFormParameterList                    │
│                  FieldPosition = Query → 运行时 URL Query     │
├─────────────────────────────────────────────────────────────┤
│ Body Tab         → bodyFormParameterList                     │
│                  FieldPosition = Body → FormUrlEncoded 等     │
│                  值可为 $FromMappingBody / $TimeStamp / 留空   │
├─────────────────────────────────────────────────────────────┤
│ Header Tab       → headerFormParameterList                   │
│                  FieldPosition = Header → 请求头              │
├─────────────────────────────────────────────────────────────┤
│ Mapping Body Tab → mappingBodyParameterList                  │
│                  ParaKind = MappingBody → 仅上游映射 + 序列化源 │
├─────────────────────────────────────────────────────────────┤
│ cURL Tab         → inParams（不变）                           │
├─────────────────────────────────────────────────────────────┤
│ Response Tab     → outParameterList（不变）                   │
└─────────────────────────────────────────────────────────────┘

（可选）服务商级 / Url 固定项 → 仍在 t_parameter_fixed，接口明细页「固定配置」可隐藏或仅高级入口
```

### 2.3 职责对照表

| 概念 | 改造前 | 改造后 |
|------|--------|--------|
| URL Query 键值 | 主要靠 `FixedFieldList`（Query）或没有 | **`bodyForm` 之外**：`queryFormParameterList` |
| 请求头 | `FixedFieldList`（Header） | **`headerFormParameterList`** + 服务商级 Fixed |
| Form 业务字段 | 全部 `formParameterList` → 进 Form Body | **`bodyFormParameterList`**，按 ContentType 组装 |
| 上游映射目标（下游侧） | `inParameterList`（IsInPara） | **`mappingBodyParameterList`**（ParaKind=MappingBody） |
| Json HTTP Body | `inParameterList` 序列化 | **`mappingBodyParameterList`** 序列化（Json 接口） |
| 表单里塞整段 JSON | `$FromBody`（语义混） | **`$FromMappingBody`**（明确指向映射结果） |

---

## 3. 表结构前后对比

### 3.1 `t_parameter`（参数树）

#### 改造前

| 列 | 类型 | 说明 |
|----|------|------|
| Id | int PK | |
| InterfaceId | int | |
| PId | int | 父节点 |
| Name / Alias / CnName | string | |
| Type | int | ParameterType |
| IsRequired | bool | |
| **IsInPara** | bool | **true=入参，false=出参** |
| Description / Sort | | |
| 审计字段 | | |

**语义**：`IsInPara=true` 的记录 = 入参树 = 映射目标 +（Json 时）HTTP Body 结构。

#### 改造后

| 列 | 类型 | 说明 | 变更 |
|----|------|------|------|
| （原有列） | | | 保留 |
| **ParaKind** | int NOT NULL DEFAULT 0 | 见下表 | **新增** |

**ParaKind 枚举（建议）**

| 值 | 名称 | 说明 |
|----|------|------|
| 0 | Normal | 默认；**出参**仅 Normal；**上游接口入参**仍为 Normal + IsInPara |
| 1 | MappingBody | **仅下游**：映射体树；`IsInPara` 仍为 true |
| 2 | TransportBody | **可选**，若 Json 接口要把「HTTP Body 结构」与「映射体」拆成两棵树时使用；一期可不用 |

**约束（逻辑）**

```text
IF ParaKind = MappingBody  → 必须 IsInPara = true，且仅用于下游接口 (IsUpStream=false)
IF IsInPara = false        → ParaKind 必须为 Normal（出参）
```

#### DDL 示例

```sql
ALTER TABLE t_parameter
  ADD ParaKind INT NOT NULL DEFAULT 0 COMMENT '0=Normal,1=MappingBody,2=TransportBody(预留)';

CREATE INDEX IX_t_parameter_InterfaceId_ParaKind
  ON t_parameter (InterfaceId, ParaKind, IsInPara)
  WHERE IsDeleted = 0;
```

---

### 3.2 `t_parameter_form`（表单 KV）

#### 改造前

| 列 | 说明 |
|----|------|
| Id, InterfaceId | |
| Name, Value, Description | Value 为占位符或常量 |
| 审计字段 | |
| **无位置字段** | 全部视为 FormUrlEncoded 的 Body 字典 |

#### 改造后

| 列 | 说明 | 变更 |
|----|------|------|
| （原有列） | | 保留 |
| **FieldPosition** | int NOT NULL DEFAULT 2 | **新增**；对齐 `FieldPosition` 枚举 |

**FieldPosition 使用范围（form 表）**

| 值 | 枚举 | 用于 form 表 |
|----|------|--------------|
| 1 | Header | ✅ |
| 2 | Body | ✅（历史数据默认值） |
| 3 | Query | ✅ |
| 4 | Url | ❌ 仍用 Fixed（路径替换） |
| 5 | Nothing | ❌ |

#### DDL 示例

```sql
ALTER TABLE t_parameter_form
  ADD FieldPosition INT NOT NULL DEFAULT 2 COMMENT '1=Header,2=Body,3=Query';

CREATE INDEX IX_t_parameter_form_InterfaceId_Position
  ON t_parameter_form (InterfaceId, FieldPosition)
  WHERE IsDeleted = 0;
```

---

### 3.3 `t_parameter_fixed`（固定参数）

#### 改造前

| 列 | 说明 |
|----|------|
| ServiceProviderId / InterfaceId | 二选一或兼有 |
| FieldName, FieldValue | 可含 `$FromBody` 等 |
| FieldPositions | 逗号分隔多位置：`Header,Body,Query,Url` |

**接口明细页**通过独立 API `FixedParameter/MaintainParameter` 维护。

#### 改造后（策略）

| 场景 | 改造后归属 | 说明 |
|------|------------|------|
| 接口级 Header / Query 固定 KV | **迁入 `t_parameter_form`** | 与 ApiTest 一致，随 `SaveInterface` 保存 |
| 接口级 Body 固定路径绑定 | 可迁入 form（Body）或保留 Fixed（Body） | 若值为 `$FromMappingBody` 路径片段，优先 Fixed Body 逻辑保留 |
| **服务商级** 通用 Header/签名 | **保留 `t_parameter_fixed`** | `ServiceProviderId` 有值 |
| **Url** 路径 `{id}` 替换 | **保留 Fixed（Url）** | form 表不支持 Url |
| 脚本运行时 `AddHeader` | **保留 Fixed 动态能力** | `ForwardCoreContext.AddHeader` |

**一期可不删表、不删 API**，仅接口明细 UI 隐藏「固定配置」；数据迁移把 `InterfaceId IS NOT NULL` 且 `FieldPositions` 含 Header/Query 的行复制到 form 表。

---

### 3.4 `t_interface` / 其它表

| 表 | 变更 |
|----|------|
| `t_interface` | 无结构变更（`ContentType`、`MappedParamType` 仍控制序列化） |
| `t_interface_map` / `t_interface_map_detail` | 无结构变更；**JOIN 参数时增加 ParaKind 条件** |
| `t_interface_return_config` | 无变更 |

---

### 3.5 ER 关系（改造后）

```mermaid
erDiagram
  t_interface ||--o{ t_parameter : "出参 Normal"
  t_interface ||--o{ t_parameter : "MappingBody IsInPara"
  t_interface ||--o{ t_parameter_form : "Query Body Header"
  t_interface ||--o{ t_parameter_fixed : "服务商级 Url"
  t_service_provider ||--o{ t_parameter_fixed : "服务商级"

  t_parameter {
    int ParaKind "0 Normal 1 MappingBody"
    bool IsInPara
  }

  t_parameter_form {
    int FieldPosition "1 Header 2 Body 3 Query"
  }
```

---

## 4. 枚举与常量前后对比

### 4.1 新增 / 扩展

| 类型 | 改造前 | 改造后 |
|------|--------|--------|
| **ParameterPlaceholder** | FromAccount, FromBody, TimeStamp, DateTime, Url, Token | **+ FromMappingBody** → `"$FromMappingBody"` |
| **GlobalConst** | `FromBody` 等 | **+ `FromMappingBody`** |
| **ParaKind**（新枚举） | 无 | Normal=0, MappingBody=1, TransportBody=2（可选） |
| **FormParameterItem** | id,name,value,description | **+ fieldPosition** |
| **InterfaceFormFieldDto**（运行时） | Name, Value, Description | **+ FieldPosition** |

### 4.2 Dictionary API

```http
GET api/Dictionary/GetList?type=ParameterPlaceholder
```

**改造后** 返回增加一项：

```json
{ "key": 7, "value": "$FromMappingBody" }
```

（具体 key 值以实现为准，前后端 `itfxEnums.ts` 同步。）

### 4.3 占位符语义（改造后定稿）

| 占位符 | 作用域 | 替换时机 | 替换结果 |
|--------|--------|----------|----------|
| `$FromMappingBody` | Form（Query/Body/Header） | ReplacePlaceholder / SetContentType | `OriginalInterfaceMappedInput` 按 ContentType 序列化后的字符串（整段） |
| `$FromBody` | Form / Fixed | **兼容保留** | Form：同现行（整段 TargetInterfaceInput 或映射体，与现网一致）；Fixed：从 `OriginalInterfaceMappedInput` 按 FieldName 路径取值 |
| `$FromAccount` | Form / Fixed | ReplacePlaceholder | 账户字段 |
| `$TimeStamp` / `$DateTime` | Form / Fixed | ReplacePlaceholder | 时间 |
| `$Url` | Form / Fixed | ReplacePlaceholder | 请求地址 |
| `$token` | Fixed 为主 | ReplacePlaceholder | 授权 token |

**推荐**：新配置 JSON 业务字段统一用 **`$FromMappingBody`**；`$FromBody` 仅兼容老数据。

---

## 5. 接口契约前后对比

### 5.1 `GET Interface/GetInterfaceById`

#### 改造前响应（节选）

```json
{
  "id": 1001,
  "name": "1688回调",
  "contentType": 1,
  "mappedParamType": 3,
  "inParameterList": [ { "id": 1, "pId": 0, "name": "order", "alias": "order", "type": 3 } ],
  "outParameterList": [ ],
  "formParameterList": [
    { "id": 10, "name": "notifyBizEventDTO", "value": "$FromBody", "description": "..." }
  ]
}
```

#### 改造后响应（完整约定）

```json
{
  "id": 1001,
  "name": "1688回调",
  "contentType": 1,
  "mappedParamType": 3,

  "queryFormParameterList": [
    { "id": 11, "name": "_aop_timestamp", "value": "$TimeStamp", "description": "ms", "fieldPosition": 3 }
  ],
  "bodyFormParameterList": [
    { "id": 10, "name": "notifyBizEventDTO", "value": "$FromMappingBody", "description": "", "fieldPosition": 2 }
  ],
  "headerFormParameterList": [
    { "id": 12, "name": "Content-Type", "value": "application/x-www-form-urlencoded", "fieldPosition": 1 }
  ],
  "mappingBodyParameterList": [
    { "id": 1, "pId": 0, "name": "order", "alias": "order", "type": 3, "isRequired": true, "paraKind": 1 }
  ],
  "outParameterList": [ ],

  "formParameterList": [ ],
  "inParameterList": [ ]
}
```

**兼容字段（只读聚合，便于老客户端）**

| 字段 | 聚合规则 |
|------|----------|
| `formParameterList` | `query` + `body` + `header` 三个列表合并 |
| `inParameterList` | 若 `mappingBodyParameterList` 非空 → 等于其副本；否则沿用 DB 中 `ParaKind=Normal & IsInPara`（迁移期） |

---

### 5.2 `POST Interface/SaveInterface`

#### 改造前请求（节选）

```json
{
  "optionType": 3,
  "id": 1001,
  "isUpStream": false,
  "serviceProviderId": 5,
  "name": "1688回调",
  "contentType": 1,
  "inParameterList": [ { "optionType": 3, "id": 1, "pId": 0, "name": "order", "alias": "order", "type": 3 } ],
  "outParameterList": [ ],
  "formParameterList": [ { "optionType": 0, "id": 10, "name": "notifyBizEventDTO", "value": "$FromBody" } ],
  "inParams": "curl ..."
}
```

#### 改造后请求（标准）

```json
{
  "optionType": 3,
  "id": 1001,
  "isUpStream": false,
  "serviceProviderId": 5,
  "name": "1688回调",
  "contentType": 1,
  "mappedParamType": 3,

  "queryFormParameterList": [
    { "optionType": 0, "id": 11, "name": "_aop_timestamp", "value": "$TimeStamp", "description": "ms", "fieldPosition": 3 }
  ],
  "bodyFormParameterList": [
    { "optionType": 0, "id": 10, "name": "notifyBizEventDTO", "value": "$FromMappingBody", "fieldPosition": 2 }
  ],
  "headerFormParameterList": [
    { "optionType": 0, "id": 12, "name": "X-Custom", "value": "fixed", "fieldPosition": 1 }
  ],
  "mappingBodyParameterList": [
    { "optionType": 3, "id": 1, "pId": 0, "name": "order", "alias": "order", "type": 3, "isRequired": true }
  ],
  "outParameterList": [ ],
  "inParams": "curl ..."
}
```

**`FormParameterInput` 扩展**

```csharp
public class FormParameterInput : FormParameterItem
{
    public OptionType OptionType { get; set; }
    public FieldPosition FieldPosition { get; set; }  // 新增；也可由所在列表推断
}
```

**`ParameterInput` 扩展**

```csharp
// ParameterInput 已有字段基础上
public ParaKind ParaKind { get; set; }  // 映射体列表传入 MappingBody；出参传 Normal
```

#### 保存时服务端合并规则（改造后）

```text
1. mappingBodyParameterList → 写入 t_parameter (IsInPara=true, ParaKind=MappingBody)
2. outParameterList         → 写入 t_parameter (IsInPara=false, ParaKind=Normal)
3. query/body/header 三列表 → 合并写入 t_parameter_form（带 FieldPosition）
4. 若仍收到 formParameterList（旧前端）→ 全部 FieldPosition=Body，且不与 body 列表重复 id
5. 若仍收到 inParameterList（旧前端）→ 当作 mappingBodyParameterList（迁移期）
6. Json 接口且 mappingBody 为空但 in 有值     → 同 5，并打日志提示升级
```

---

### 5.3 `GET FormParameter/GetParameterList`

#### 改造前

```http
GET FormParameter/GetParameterList?interfaceId=1001
→ List<FormParameterItem>  // 无 position
```

#### 改造后（二选一）

**选项 1（推荐）**：扩展原接口

```http
GET FormParameter/GetParameterList?interfaceId=1001&fieldPosition=3
→ 按 position 过滤；不传则返回全部（带 fieldPosition 字段）
```

**选项 2**：废弃，统一走 `GetInterfaceById`。

---

### 5.4 `POST FixedParameter/MaintainParameter`

| 维度 | 改造前 | 改造后 |
|------|--------|--------|
| 接口明细页 | 主要维护入口 | **隐藏**；Header/Query 改走 SaveInterface |
| 服务商管理 / 高级配置 | 使用 | **保留** |
| 行为 | 写 `t_parameter_fixed` | 不变；转发时与 form **合并**（见 §6.3） |

---

### 5.5 映射相关接口

#### `GET InterfaceMap/EditMapDetails` / `GetMapParameterCascadedList`

| 维度 | 改造前 | 改造后 |
|------|--------|--------|
| 下游入参映射目标 | `t_parameter` 且 `IsInPara=true`（全部入参） | **`ParaKind = MappingBody`**（无则回退全部 IsInPara，迁移期） |
| 上游系统接口入参 | `IsInPara=true` | **不变**（上游无 Mapping Body 概念） |

#### `POST InterfaceMap/SaveParameterMaps`（保存映射明细）

- 映射明细仍引用 `t_parameter.Id`；Mapping Body 节点 id 为新 id 空间，**与旧 in 参 id 可能变化**，迁移需重导映射或跑 id 映射脚本。

---

### 5.6 上游接口 `SaveInterface`（IsUpStream=true）

| 字段 | 改造后 |
|------|--------|
| `mappingBodyParameterList` | **不使用**（或忽略） |
| `inParameterList` | **仍为**上游业务入参树（Normal） |
| `query/body/headerForm` | 可选；一般上游为空 |
| UI | 上游 InterfaceDetail **不展示** Mapping Body Tab（或展示但禁用） |

---

### 5.7 TypeScript 类型（前端 `typings.d.ts` 目标）

```typescript
type FormParameterItem = {
  id?: number;
  name?: string;
  value?: string;
  description?: string;
  fieldPosition?: 1 | 2 | 3; // Header Body Query
};

type InterfaceParameterOutputValueObject = {
  // ...existing
  paraKind?: 0 | 1 | 2;
};

type InterfaceOutput = {
  // ...existing
  queryFormParameterList?: FormParameterItem[];
  bodyFormParameterList?: FormParameterItem[];
  headerFormParameterList?: FormParameterItem[];
  mappingBodyParameterList?: InterfaceParameterOutputValueObject[];
  /** @deprecated 聚合字段，勿写入 Save */
  formParameterList?: FormParameterItem[];
  /** @deprecated 聚合字段 */
  inParameterList?: InterfaceParameterOutputValueObject[];
};

type SaveInterfaceInput = {
  // ...existing
  queryFormParameterList?: FormParameterInput[];
  bodyFormParameterList?: FormParameterInput[];
  headerFormParameterList?: FormParameterInput[];
  mappingBodyParameterList?: ParameterInput[];
};
```

---

## 6. 转发与映射逻辑前后对比

### 6.1 总流程

#### 改造前

```text
OriginalInterfaceInput
    → InParamRestructure(InParamTreeList from 下游全部 IsInPara)
    → OriginalInterfaceMappedInput
    → ReplacePlaceholder(Fixed + Form)
    → SerializationBody (按 ContentType)
    → RequestAsync
         Fixed → Url / Query / Header
         Form  → 仅 FormUrlEncoded 整包 Body
```

#### 改造后

```text
OriginalInterfaceInput
    → InParamRestructure(MappingBodyTreeList)    ← 仅 ParaKind=MappingBody
    → OriginalInterfaceMappedInput
    → ReplacePlaceholder(Fixed + Form 分位置)
    → SerializationBody
         Json/Xml: 序列化 OriginalInterfaceMappedInput
         FormUrlEncoded: 见 6.2
    → RequestAsync
         Fixed → Url（保留）
         Form(Query) → UriBuilder.Query
         Form(Header) → msg.Headers
         Form(Body) + Fixed(Body) → SetContentType
```

---

### 6.2 `SetContentType`（FormUrlEncoded）前后对比

#### 改造前

```csharp
// 所有 FormFieldList 打成一个字典作为 Body
if (context.FormFieldList.Count != 0) {
    var field = context.FormFieldList.FirstOrDefault(x => x.Value == GlobalConst.FromBody);
    if (field != null) field.Value = body; // body = TargetInterfaceInput
    nameValueCollection = context.FormFieldList.ToDictionary(x => x.Name, x => x.Value);
}
```

#### 改造后

```csharp
var bodyForms = context.FormFieldList.Where(x => x.FieldPosition == FieldPosition.Body).ToList();
// 替换 $FromMappingBody / $FromBody
foreach (var item in bodyForms) {
    if (item.Value == GlobalConst.FromMappingBody)
        item.Value = JsonConvert.SerializeObject(context.OriginalInterfaceMappedInput);
    // ... 其它占位符
}
msg.Content = new FormUrlEncodedContent(bodyForms.ToDictionary(x => x.Name, x => x.Value));
// Query / Header 已在 RequestAsync 前文处理，不进入此字典
```

---

### 6.3 `RequestAsync` 前后对比

| 步骤 | 改造前 | 改造后 |
|------|--------|--------|
| Url 替换 | `FixedFieldList` Url | **不变** |
| Query | `FixedFieldList` Query | **Form Query** + Fixed Query（合并，见下） |
| Header | `FixedFieldList` Header | **Form Header** + Fixed Header |
| Body | `SetContentType` | **仅 Form Body** + Fixed Body 注入映射路径 |

**合并优先级（建议写死到代码与文档）**

```text
同一 FieldName + 同一位置：
  接口级 Form  > 接口级 Fixed  > 服务商级 Fixed
```

---

### 6.4 `ReplacePlaceholder` 前后对比

| 处理对象 | 改造前 | 改造后 |
|----------|--------|--------|
| `FixedFieldList` | `$FromBody` 路径取值 | **保留**；可增加 `$FromMappingBody` 整段序列化 |
| `FormFieldList` | 仅 TimeStamp/DateTime/Url/FromAccount | **+ `$FromMappingBody`**；Query/Header 同样支持 TimeStamp 等 |
| Form 中 `$FromBody` | 在 SetContentType 用 TargetInterfaceInput 替换 | **建议标记过时**，逻辑保留 |

---

### 6.5 `InterfaceForwardQuery` 构建上下文

#### 改造前

```csharp
FormFieldList = await GetFormFieldListAsync(interfaceId); // 全部 form，无 position
InParamTreeList = JsonHelper.BuildTreeList(items);       // 全部 IsInPara 映射项
```

#### 改造后

```csharp
FormFieldList = await GetFormFieldListAsync(interfaceId); // 含 FieldPosition
InParamTreeList = JsonHelper.BuildTreeList(
    items.Where(x => x.ParaKind == ParaKind.MappingBody)); // 映射配置来自 MappingBody
```

**授权接口** `GetFormFieldListAsync` / `InParamTreeList`：授权若依赖表单，按授权接口自身配置；`InParamTreeList = null` 保持不变。

---

### 6.6 `InParamRestructure` 数据源

| 维度 | 改造前 | 改造后 |
|------|--------|--------|
| 树来源 | 下游映射 SQL 拉取的 **全部 IsInPara** | **仅 MappingBody** 节点 |
| Json 接口 HTTP Body | 同一棵树序列化 | 同一棵 **MappingBody** 树序列化 |
| 出参映射 | OutParamTreeList | **不变** |

---

### 6.7 ContentType 分支（产品规则）

| ContentType | Query Tab | Body Tab | Mapping Body | HTTP Body 来源 |
|-------------|-----------|----------|--------------|----------------|
| **Json (3)** | 可选 | 通常空 | **必填**（映射+序列化） | `Serialize(OriginalInterfaceMappedInput)` |
| **FormUrlEncoded (1)** | 常用 | 常用（含 `$FromMappingBody`） | **必填**（映射） | Form Body 字典 |
| **Xml (4)** | 可选 | 可选 | 必填 | Xml 序列化映射体 |
| **FormData (2)** | 二期 | 二期 | 必填 | 暂可抛不支持 |

---

## 7. 前端页面与数据流前后对比

### 7.1 InterfaceDetail Request 区 Tab

| Tab | 改造前 | 改造后 |
|-----|--------|--------|
| Query | form 表（误标） | KV 表 → `queryFormParameterList` |
| Body | **参数树** inParameterList | **KV 表** → `bodyFormParameterList` |
| Header | 无（在固定配置） | **KV 表** → `headerFormParameterList` |
| Mapping Body | 无 | **参数树** → `mappingBodyParameterList` |
| 固定配置 | FixedParameter API | **默认隐藏** / 高级入口 |
| cURL | 有 | 有；智能填充拆到 Q/H/B/Mapping |

### 7.2 `ServiceProviderInterfaceModal` 加载/保存

#### 改造前

```typescript
queryParams.value = interfaceData.formParameterList || [];
requestParams.value = interfaceData.inParameterList || [];
// save: formParameterList from query table only
// save: inParameterList from request tree
```

#### 改造后

```typescript
queryParams.value = interfaceData.queryFormParameterList || [];
bodyFormParams.value = interfaceData.bodyFormParameterList || [];
headerParams.value = interfaceData.headerFormParameterList || [];
mappingBodyParams.value = interfaceData.mappingBodyParameterList || [];

// save: 四个列表分别组装 optionType
// 不再把 query 写入 inParameterList
```

### 7.3 `curlToInterfaceFill` 智能填充

| cURL 部分 | 改造前 | 改造后 |
|-----------|--------|--------|
| `?a=1&b=2` | 进 queryParams（实为 form） | **queryFormParameterList** |
| `-H` | 部分进 Fixed / 忽略 | **headerFormParameterList** |
| `--data-raw` JSON | 解析进 **inParameterList** 树 | 结构进 **mappingBodyParameterList**；若 FormUrlEncoded 单字段则 **body** 表一项 `$FromMappingBody` |
| JSON 形态 query 值 | `$FromBody` | **`$FromMappingBody`** |

### 7.4 与 ApiTest 组件复用（建议）

```text
components/
  RequestTabs/
    QueryKeyValueTable.vue    ← 从 ApiTest 抽
    HeaderKeyValueTable.vue
    BodyKeyValueTable.vue
    MappingBodyTreeTable.vue  ← 从 InterfaceDetail 原 Body 树抽
```

---

## 8. 关联能力改动清单

| 模块 | 文件/服务 | 改造要点 |
|------|-----------|----------|
| 接口保存/读取 | `InterfaceService` | 拆分列表、兼容聚合 |
| 表单参数 | `FormParameterService` | FieldPosition CRUD、按位置查询 |
| 树形参数 | `ParameterService` | ParaKind、MappingBody 维护 |
| 转发 | `DefaultForwardFlow` | RequestAsync、SetContentType、ReplacePlaceholder |
| 上下文加载 | `InterfaceForwardQuery` | Form 带 position；InParamTreeList 过滤 MappingBody |
| 映射 SQL | `InterfaceMapRepository` | JOIN 参数加 ParaKind |
| 映射编辑 API | `InterfaceMapService.Details` | 级联列表过滤 |
| 导入导出 | `ServiceProviderImportExportService` | form position + paraKind |
| 授权 | `ServiceProviderAuthService` | 确认入参列表来源（MappingBody 或仍为原 in） |
| 发布/缓存 | `ForwardCoreContextCache` | DTO 增加 FieldPosition、ParaKind |
| 字典 | `ParameterPlaceholder` 枚举 | +FromMappingBody |
| 前端枚举 | `itfxEnums.ts` | 同步 |
| 文档 | `itfx枚举说明.md` | 更新 |
| 上游接口页 | `UpstreamInterfaceModal` | 不展示 Mapping Body |
| 映射配置页 | `upstreamInterfaceConfig*` | 下游侧展示 MappingBody 别名 |
| 历史页 | `newPort.vue` | 同步或废弃 |

---

## 9. 数据迁移方案

### 9.1 迁移步骤（建议顺序）

```text
Step 1  DDL：t_parameter.ParaKind、t_parameter_form.FieldPosition
Step 2  备份相关表
Step 3  form：历史行 FieldPosition = 2 (Body)
Step 4  parameter：下游接口 IsInPara=true 且 ContentType=FormUrlEncoded
         → ParaKind = MappingBody（原 in 树整体迁移）
Step 5  parameter：下游接口 ContentType=Json
         → 原 in 树 ParaKind = MappingBody（同时作为 HTTP body 定义）
Step 6  fixed：InterfaceId NOT NULL 且 FieldPositions 含 Header/Query
         → INSERT INTO t_parameter_form（去重策略按 FieldName+Position）
Step 7  验证映射明细 MappedParaId 仍指向有效 parameter.Id
Step 8  发布缓存刷新 / 全量发布后回归
```

### 9.2 迁移 SQL 示意

```sql
-- form 默认 Body
UPDATE t_parameter_form SET FieldPosition = 2 WHERE FieldPosition IS NULL OR FieldPosition = 0;

-- 下游入参 → MappingBody（需按接口表 IsUpStream=0 关联，示意）
UPDATE p SET p.ParaKind = 1
FROM t_parameter p
INNER JOIN t_interface i ON p.InterfaceId = i.Id
WHERE p.IsInPara = 1 AND p.IsDeleted = 0 AND i.IsUpStream = 0;

-- Fixed → Form（Header=1, Query=3）需脚本逐行解析 FieldPositions，不建议单条 SQL 粗暴合并
```

### 9.3 回滚

- 保留 `ParaKind`、`FieldPosition` 列，回滚代码读旧逻辑：忽略新列，按 `IsInPara` + 全量 form 聚合。
- 迁移前务必备份 `t_parameter`、`t_parameter_form`、`t_interface_map_detail`。

---

## 10. 兼容策略与版本节奏

### 10.1 API 版本

| 阶段 | 后端 | 前端 |
|------|------|------|
| **V1 并行** | Save 接受新旧字段；Get 返回新旧字段 | 新页面只发新字段 |
| **V2** | Save 对新字段必填（下游）；旧字段 deprecated 日志 | 移除旧 Tab |
| **V3** | 可选移除 `formParameterList` 聚合 | — |

### 10.2 行为兼容矩阵

| 场景 | 未迁移数据 | 已迁移数据 |
|------|------------|------------|
| GetById | `inParameterList` 有值，mapping 空 → 前端用 in 填 Mapping Tab | 四列表 + mapping 正常 |
| Save 旧前端 | 仅 form + in → 服务端按 §5.2 规则 4、5 拆分 | — |
| 转发 | ParaKind 全 0 → 等同改造前 | 新逻辑 |

---

## 11. 实施阶段建议

| 阶段 | 内容 | 产出 |
|------|------|------|
| **P0** | DDL + 枚举 + Get/Save 契约 + 单元测试 | 可存可取 |
| **P1** | DefaultForwardFlow + InterfaceForwardQuery + 占位符 | 可转发 |
| **P2** | 映射 SQL + 发布缓存 + 导入导出 | 可发布 |
| **P3** | 前端 InterfaceDetail 重写 + Modal 保存 + curl 填充 | 可配置 |
| **P4** | 数据迁移 + 选生产接口回归 | 上线 |
| **P5** | 隐藏固定配置、文档、培训 | 收尾 |

---

## 附录 A：改造前后单接口完整示例（1688 风格 FormUrlEncoded）

### 改造前

**库内**

- `t_parameter`：order.{field} 树，`IsInPara=1`
- `t_parameter_form`：`notifyBizEventDTO=$FromBody`，无 position

**运行时**

- 映射到 order 树 → 序列化 → 填入 notifyBizEventDTO → 与其它 form 字段一起 POST

### 改造后

**库内**

- `t_parameter`：order 树，`ParaKind=1`（MappingBody）
- `t_parameter_form`：`(notifyBizEventDTO, $FromMappingBody, Body=2)`，`(timestamp, $TimeStamp, Query=3)`

**运行时**

- 映射到 MappingBody 树 → `OriginalInterfaceMappedInput` → `$FromMappingBody` 填入 Body 表单字段 → Query 拼 URL → POST

---

## 附录 B：后端类改动速查

| 类 | 变更 |
|----|------|
| `FormParameterEntity` | +FieldPosition |
| `ParameterEntity` | +ParaKind |
| `FormParameterItem/Input` | +FieldPosition |
| `ParameterInput` / `InterfaceParameterOutputValueObject` | +ParaKind |
| `InterfaceOutput` | +3 form 列表 + mappingBodyParameterList |
| `SaveInterfaceInput` | 同上 |
| `InterfaceFormFieldDto` | +FieldPosition |
| `GlobalConst` | +FromMappingBody |
| `ParameterPlaceholder` | +FromMappingBody |

---

*文档版本：2026-06-02 · 方案 B 定稿详细设计*