# 动态表接口文档

## 基础信息

- **基础路径**: `/api/enterprise/castTaskInfo`
- **接口分组**: 成本监审任务填报
- **适用范围**: 动态表（模板类型3）

---

## 1. 新增监审期间记录

### 接口信息
- **路径**: `/addPeriodRecord`
- **方法**: `POST`
- **描述**: 新增监审期间记录，用于动态表。**必须先创建监审期间记录，然后才能编辑保存数据**

### 请求参数

**请求体**: `CostAuditPeriodRecord`

| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| uploadId | String | 条件必填 | 关联上传记录ID（如果为空，需要提供catalogId和surveyTemplateId自动创建） |
| auditedUnitId | String | 是 | 企业ID |
| auditPeriod | String | 是 | 监审期间（年份，如：2024） |
| catalogId | String | 条件必填 | 监管目录ID（当uploadId为空时必填） |
| surveyTemplateId | String | 条件必填 | 成本调查表模板ID（当uploadId为空时必填） |
| reportingTime | LocalDateTime | 否 | 填报时间（不传则使用当前时间） |

### 请求示例

#### 方式一：已有uploadId

```json
{
  "uploadId": "upload123",
  "auditedUnitId": "unit123",
  "auditPeriod": "2024"
}
```

#### 方式二：没有uploadId，自动创建

```json
{
  "catalogId": "catalog123",
  "surveyTemplateId": "template123",
  "auditedUnitId": "unit123",
  "auditPeriod": "2024"
}
```

### 响应示例

```json
{
  "code": 200,
  "message": "新增监审期间记录成功",
  "value": {
    "id": "period123",
    "uploadId": "upload123",
    "auditedUnitId": "unit123",
    "auditPeriod": "2024",
    "reportingTime": "2025-12-22T14:12:23",
    "createTime": "2025-12-22T14:12:23",
    "updateTime": "2025-12-22T14:12:23"
  }
}
```

### 错误响应

```json
{
  "code": 500,
  "message": "uploadId为空时，catalogId和surveyTemplateId不能为空",
  "value": null
}
```

或

```json
{
  "code": 500,
  "message": "auditPeriod不能为空",
  "value": null
}
```

---

## 2. 查询监审期间记录列表

### 接口信息
- **路径**: `/listPeriodRecord`
- **方法**: `POST`
- **描述**: 查询监审期间记录列表，返回记录列表

### 请求参数

**请求体**: `CostAuditPeriodRecord`

| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| uploadId | String | 是 | 关联上传记录ID |
| auditedUnitId | String | 是 | 企业ID |

### 请求示例

```json
{
  "uploadId": "upload123",
  "auditedUnitId": "unit123"
}
```

### 响应示例

```json
{
  "code": 200,
  "message": "success",
  "value": [
    {
      "id": "period1",
      "uploadId": "upload123",
      "auditedUnitId": "unit123",
      "auditPeriod": "2024",
      "reportingTime": "2025-12-22T14:12:23",
      "createTime": "2025-12-22T14:12:23",
      "updateTime": "2025-12-22T15:12:23"
    },
    {
      "id": "period2",
      "uploadId": "upload123",
      "auditedUnitId": "unit123",
      "auditPeriod": "2023",
      "reportingTime": "2025-12-21T14:12:23",
      "createTime": "2025-12-21T14:12:23",
      "updateTime": "2025-12-21T15:12:23"
    }
  ]
}
```

---

## 3. 删除监审期间记录

### 接口信息
- **路径**: `/deletePeriodRecord`
- **方法**: `POST`
- **描述**: 删除监审期间记录

### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | String | 是 | 记录ID |

### 请求示例

```
POST /api/enterprise/castTaskInfo/deletePeriodRecord?id=period123
```

### 响应示例

```json
{
  "code": 200,
  "message": "删除监审期间记录成功",
  "value": null
}
```

---

## 4. 保存成本调查表模板上传数据（动态表）

### 接口信息
- **路径**: `/saveUploadData`
- **方法**: `POST`
- **描述**: 保存成本调查表模板上传数据（动态表专用）。**必须先创建监审期间记录，然后在数据中包含 `periodRecordId`**

### 请求参数

**请求体**: `List<CostSurveyTemplateUploadData>`

| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| uploadId | String | 否 | 关联上传记录ID（如果为空，会根据catalogId和surveyTemplateId自动创建） |
| auditedUnitId | String | 是 | 企业ID |
| periodRecordId | String | **是** | 关联监审期间记录ID（**动态表必填**） |
| rowid | String | 是 | 行数据ID（标识同一行的数据） |
| rkey | String | 是 | 数据key（动态字段名） |
| rvalue | String | 否 | 数据值（动态字段值） |
| catalogId | String | 条件必填 | 监管目录ID（当uploadId为空时必填） |
| surveyTemplateId | String | 条件必填 | 成本调查表模板ID（当uploadId为空时必填） |

### 请求示例

```json
[
  {
    "uploadId": "upload123",
    "auditedUnitId": "unit123",
    "periodRecordId": "period123",
    "rowid": "row1",
    "rkey": "机构名称",
    "rvalue": "XX公司"
  },
  {
    "uploadId": "upload123",
    "auditedUnitId": "unit123",
    "periodRecordId": "period123",
    "rowid": "row1",
    "rkey": "机构地址",
    "rvalue": "XX市XX区"
  }
]
```

### 响应示例

```json
{
  "code": 200,
  "message": "保存数据成功",
  "value": null
}
```

### 错误响应

```json
{
  "code": 500,
  "message": "动态表需要先创建监审期间记录，periodRecordId不能为空",
  "value": null
}
```

---

## 5. 查询成本调查表模板上传数据（动态表）

### 接口信息
- **路径**: `/getUploadData`
- **方法**: `POST`
- **描述**: 查询成本调查表模板上传数据，返回实体类列表（支持按periodRecordId查询）

### 请求参数

**请求体**: `CostSurveyTemplateUploadData`

| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| uploadId | String | 是 | 关联上传记录ID |
| auditedUnitId | String | 是 | 企业ID |
| periodRecordId | String | 否 | 关联监审期间记录ID（不传则查询所有数据） |

### 请求示例

```json
{
  "uploadId": "upload123",
  "auditedUnitId": "unit123",
  "periodRecordId": "period123"
}
```

### 响应示例

```json
{
  "code": 200,
  "message": "success",
  "value": [
    {
      "id": "data1",
      "uploadId": "upload123",
      "auditedUnitId": "unit123",
      "periodRecordId": "period123",
      "rowid": "row1",
      "rkey": "机构名称",
      "rvalue": "XX公司"
    },
    {
      "id": "data2",
      "uploadId": "upload123",
      "auditedUnitId": "unit123",
      "periodRecordId": "period123",
      "rowid": "row1",
      "rkey": "机构地址",
      "rvalue": "XX市XX区"
    }
  ]
}
```

---

## 使用流程说明

### 动态表完整操作流程

1. **创建监审期间记录**
   - 调用 `/addPeriodRecord` 创建监审期间记录
   - 获取返回的 `periodRecordId`

2. **保存数据**
   - 调用 `/saveUploadData` 保存数据
   - **必须在数据中包含 `periodRecordId`**

3. **查询监审期间记录列表**
   - 调用 `/listPeriodRecord` 查询已创建的监审期间记录列表

4. **查询数据**
   - 调用 `/getUploadData` 查询数据（可指定 `periodRecordId` 查询特定期间的数据）

5. **删除监审期间记录**
   - 调用 `/deletePeriodRecord` 删除监审期间记录