front/docs/前端调整.md

前端调整清单如下，核心是：**下游不再用 `inParameterList` / `formParameterList`，改为按 ContentType 拆分 Body、Query、Header。**

## 1. 接口详情页字段调整

### 删除/停用

- 下游接口不要再使用 `inParameterList`
- 不再使用 `formParameterList`
- 删除接口级“固定配置”Tab
- 下游表单中不再使用 `$FromBody`

### 新增字段

`SaveInterface` / `GetInterfaceById` 使用这些字段：

```ts
queryFormParameterList: FormParameterInput[]
headerFormParameterList: FormParameterInput[]
bodyFormParameterList: FormParameterInput[]

requestBodyParameterList: ParameterInput[]
mappingBodyParameterList: ParameterInput[]

inParameterList: ParameterInput[]
outParameterList: ParameterInput[]
```

---

## 2. 按 ContentType 显示 Tab

### Json / Xml 下游

显示：

- Query：KV
- Header：KV
- Body：参数树
- Response：参数树
- cURL：原样保留

隐藏：

- Mapping Body
- Body Form KV
- 上游 `inParameterList`

保存时传：

```ts
queryFormParameterList
headerFormParameterList
requestBodyParameterList
outParameterList
```

不要传：

```ts
inParameterList
bodyFormParameterList
mappingBodyParameterList
```

---

### FormUrlEncoded 下游

显示：

- Query：KV
- Header：KV
- Body：KV 表
- Mapping Body：参数树
- Response：参数树
- cURL：原样保留

保存时传：

```ts
queryFormParameterList
headerFormParameterList
bodyFormParameterList
mappingBodyParameterList
outParameterList
```

不要传：

```ts
inParameterList
requestBodyParameterList
```

---

### 上游接口

显示：

- In Parameters：参数树
- Response：参数树

保存时传：

```ts
inParameterList
outParameterList
```

不要传：

```ts
requestBodyParameterList
mappingBodyParameterList
bodyFormParameterList
```

`queryFormParameterList`、`headerFormParameterList` 可以传空数组。

---

## 3. FormParameterInput 调整

新增字段：

```ts
fieldPosition: 1 | 2 | 3
```

含义：

```ts
1 = Header
2 = Body
3 = Query
```

结构：

```ts
interface FormParameterInput {
  optionType: number
  id: number
  name: string
  value: string
  description?: string
  fieldPosition: 1 | 2 | 3
}
```

前端保存前要自动补：

- `queryFormParameterList[*].fieldPosition = 3`
- `headerFormParameterList[*].fieldPosition = 1`
- `bodyFormParameterList[*].fieldPosition = 2`

---

## 4. ParameterInput 调整

新增字段：

```ts
paraKind: 0 | 1
```

含义：

```ts
0 = Normal
1 = MappingBody
```

结构：

```ts
interface ParameterInput {
  optionType: number
  id: number
  pId: number
  name: string
  alias?: string
  cnName?: string
  type: number
  isRequired: boolean
  sort?: string
  description?: string
  paraKind: 0 | 1
}
```

前端保存前要自动补：

- 上游 `inParameterList[*].paraKind = 0`
- 下游 Json/Xml `requestBodyParameterList[*].paraKind = 0`
- 下游 FormUrlEncoded `mappingBodyParameterList[*].paraKind = 1`
- `outParameterList[*].paraKind = 0`

---

## 5. 占位符调整

新增：

```ts
$FromMappingBody
```

用于：

- FormUrlEncoded 的 `bodyFormParameterList`
- 必要时 Query/Header KV 引用映射结果

删除/停用：

```ts
$FromBody
```

FormUrlEncoded 示例：

```json
{
  "name": "notifyBizEventDTO",
  "value": "$FromMappingBody",
  "fieldPosition": 2
}
```

---

## 6. SaveInterface 请求组装

### Json 下游示例

```json
{
  "optionType": 1,
  "isUpStream": false,
  "serviceProviderId": 5,
  "name": "创建订单",
  "requestAddress": "https://api.example.com/order",
  "requestProtocol": 2,
  "requestMethod": 2,
  "contentType": 3,

  "queryFormParameterList": [
    {
      "optionType": 1,
      "id": 0,
      "name": "access_token",
      "value": "$FromAccount",
      "fieldPosition": 3
    }
  ],
  "headerFormParameterList": [],
  "requestBodyParameterList": [
    {
      "optionType": 1,
      "id": 1,
      "pId": 0,
      "name": "orderId",
      "alias": "orderId",
      "type": 1,
      "isRequired": true,
      "paraKind": 0
    }
  ],
  "outParameterList": [],

  "inParameterList": [],
  "bodyFormParameterList": [],
  "mappingBodyParameterList": []
}
```

### FormUrlEncoded 下游示例

```json
{
  "optionType": 1,
  "isUpStream": false,
  "serviceProviderId": 5,
  "name": "1688回调",
  "requestAddress": "https://gw.open.1688.com/openapi/http",
  "requestProtocol": 2,
  "requestMethod": 2,
  "contentType": 1,

  "queryFormParameterList": [
    {
      "optionType": 1,
      "id": 0,
      "name": "_aop_timestamp",
      "value": "$TimeStamp",
      "description": "ms",
      "fieldPosition": 3
    }
  ],
  "headerFormParameterList": [],
  "bodyFormParameterList": [
    {
      "optionType": 1,
      "id": 0,
      "name": "notifyBizEventDTO",
      "value": "$FromMappingBody",
      "fieldPosition": 2
    }
  ],
  "mappingBodyParameterList": [
    {
      "optionType": 1,
      "id": 1,
      "pId": 0,
      "name": "order",
      "alias": "order",
      "type": 3,
      "isRequired": true,
      "paraKind": 1
    }
  ],
  "outParameterList": [],

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

---

## 7. GetInterfaceById 回填规则

后端现在会返回：

```ts
queryFormParameterList
headerFormParameterList
bodyFormParameterList
requestBodyParameterList
mappingBodyParameterList
inParameterList
outParameterList
```

前端回填时：

- Json/Xml：Body Tab 绑定 `requestBodyParameterList`
- FormUrlEncoded：Body Tab 绑定 `bodyFormParameterList`
- FormUrlEncoded：Mapping Body Tab 绑定 `mappingBodyParameterList`
- 上游：入参树绑定 `inParameterList`
- Response：绑定 `outParameterList`
- Query：绑定 `queryFormParameterList`
- Header：绑定 `headerFormParameterList`

---

## 8. 映射页面调整

下游映射目标参数来源改为：

```ts
if (downstream.contentType === 1) {
  // FormUrlEncoded
  targetTree = mappingBodyParameterList
} else if (downstream.contentType === 3 || downstream.contentType === 4) {
  // Json / Xml
  targetTree = requestBodyParameterList
}
```

不要再用下游 `inParameterList`。

---

## 9. 前端校验规则

保存前校验：

### 上游

必须：

```ts
inParameterList
```

禁止有值：

```ts
requestBodyParameterList
mappingBodyParameterList
bodyFormParameterList
```

### 下游 Json / Xml

必须：

```ts
requestBodyParameterList
```

禁止有值：

```ts
inParameterList
mappingBodyParameterList
bodyFormParameterList
```

### 下游 FormUrlEncoded

必须：

```ts
bodyFormParameterList
mappingBodyParameterList
```

禁止有值：

```ts
inParameterList
requestBodyParameterList
```

---

## 10. 页面文案建议

- `Query`：请求 Query 参数
- `Header`：请求 Header 参数
- `Body`：
  - Json/Xml：请求体结构
  - FormUrlEncoded：表单字段
- `Mapping Body`：业务 JSON 映射体
- `Response`：响应结构

`$FromMappingBody` 显示文案：

```text
引用 Mapping Body 映射结果
```

`$FromBody` 从下拉选项中移除。