---
title: 附件
description: 文件上传（本地 / OSS 直传）、记录落库、删除与静态访问
pageClass: g3-api
---

# 附件

文件接口，前缀 `/file/**`。有两种存储模式，由 `erp.file.storage-type` 决定（`local` / `aliyun-oss`）。

| 模式 | 上传链路 |
|---|---|
| `local` | 前端直接 POST 文件 → 后端写盘 + 落库 |
| `aliyun-oss` | 取凭证 → 前端直传 OSS → 回调后端落库 |

> **第一步先问模式**：调 `/file/config` 拿到当前模式，再决定走哪条链路。前端组件不要写死。

## `POST` `/file/config`

返回当前存储模式。

<G3ApiPayload title="响应" :code="0">

```json
{
  "code": 0,
  "message": "操作成功",
  "data": { "storageType": "local" }
}
```

</G3ApiPayload>

## `POST` `/file/upload`

**本地上传**（`storage-type=local` 时使用）。支持多文件，**是 `multipart/form-data`，不是 JSON**。

<G3ApiParams title="表单字段">

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `files` | file[] | 是 | 文件，key 固定为 `files`，可重复 |
| `father` | string | 是 | 宿主业务主键（存宿主 `b_id`） |
| `moduleId` | string | 是 | 模块编码 |
| `cateId` | string | | 分类 ID |

</G3ApiParams>

<G3ApiPayload title="请求">

```bash
curl -X POST http://localhost:8088/api/file/upload \
  -H 'Authorization: Bearer <token>' \
  -F 'files=@report.pdf' \
  -F 'father=1234567890' \
  -F 'moduleId=v_b_othercompany' \
  -F 'cateId=987654321'
```

</G3ApiPayload>

<G3ApiPayload title="响应" :code="0">

```json
{
  "code": 0,
  "message": "操作成功",
  "data": [
    {
      "subid": "1234567890123",
      "mx_filename": "report.pdf",
      "mx_filesize": "20480",
      "mx_fileext": "pdf",
      "mx_mapfilename": "/api/file/static/G3HD/2026/10/13/abc.pdf",
      "father": "1234567890",
      "mx_moduleid": "v_b_othercompany",
      "mx_cate_id": "987654321"
    }
  ]
}
```

</G3ApiPayload>

- `mx_mapfilename` 就是**访问地址**，预览 / 下载直接用它。
- `subid` 是雪花 ID，**本地模式由后端自己取号**后写入 `bf_files`（前端不用管）。

## `POST` `/file/upload-credential`

**取 OSS 直传凭证**（`storage-type=aliyun-oss` 时使用）。无请求字段。

后端转发到 g3oss，`bucket` 即当前机构码。

<G3ApiPayload title="响应" :code="0">

```json
{
  "code": 0,
  "message": "操作成功",
  "data": {
    "accessid": "LTAI...",
    "policy": "eyJleHBpcmF0aW9uIjoi...",
    "signature": "abc123==",
    "dir": "G3HD/",
    "host": "https://g3soft.oss-cn-hangzhou.aliyuncs.com",
    "expire": 1700000000
  }
}
```

</G3ApiPayload>

> **字段以 g3oss 实际返回为准**：后端只做 `readValue(...).Map` 的**原样透传**，不加工也不改名。
> 上面是 OSS 直传的常见字段形状，接入时请以实际返回为准；凭证有有效期，取到后应尽快直传。

## `POST` `/file/save-record`

**OSS 直传完成后回调落库**（`storage-type=aliyun-oss` 时使用）。本地模式不需要单独调它。

<G3ApiParams title="请求字段">

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `subid` | number | 是 | 上传前取的雪花 ID |
| `father` | string | 是 | 宿主业务主键 |
| `mx_moduleid` | string | 是 | 模块编码 |
| `mx_cate_id` | string | | 分类 ID |
| `mx_filename` | string | 是 | 原始文件名 |
| `mx_filesize` | string | 是 | 文件大小（字节） |
| `mx_fileext` | string | 是 | 扩展名 |
| `mx_mapfilename` | string | 是 | OSS 返回的完整 URL |

</G3ApiParams>

<G3ApiPayload title="响应" :code="0">

```json
{
  "code": 0,
  "message": "操作成功",
  "data": { "subid": "1234567890123", "message": "记录已保存" }
}
```

</G3ApiPayload>

> **`subid` 在 OSS 链路必须由前端在上传前取号**（调 `/data/nextid`），因为凭证直传时后端不在链路上，无法代为取号。
> 本地链路则相反：**后端自己取号**，前端不用传。两条链路都不能依赖数据库自增。

## `POST` `/file/delete`

删除文件：**先删存储、后删 DB 行**。

<G3ApiParams title="请求字段">

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `subid` | string | 是 | 文件记录 ID |

</G3ApiParams>

<G3ApiPayload title="响应" :code="0">

```json
{ "code": 0, "message": "操作成功", "data": null }
```

</G3ApiPayload>

外部对象操作**不属于数据库事务**：

- 删存储失败 → **不删数据库行**（保持可重试）。
- 数据库删除失败 → 保留可重试的清理记录。

记录不存在时静默返回成功（幂等）。

## `GET` `/file/static/{fileName}`

**本地模式**下的文件访问入口。不是 JSON 接口，直接返回文件流。

```text
GET /api/file/static/G3HD/2026/10/13/abc.pdf
```

- 路径形如 `{orgId}/{yyyy}/{MM}/{dd}/{file}`，与 `mx_mapfilename` 去掉前缀后的部分对应。
- 带**路径穿越防护**：解析后必须仍在存储根目录内，否则 404。
- 响应头带 `Content-Disposition: inline`，浏览器可直接预览。

## 相关数据表

| 表 | 说明 |
|---|---|
| `bf_files` | 文件记录（主键 `subid` 雪花 ID，`father` 存宿主主键） |
| `bf_files_category` | 文件分类（`b_module_id` 为空表示跨模块通用分类） |

## 常见错误

| 场景 | 表现 |
|---|---|
| 本地上传时缺少 `files` | `1000` 参数错误 |
| 文件静态访问越界或不存在 | **HTTP 404**（这条路径不走统一响应格式） |
| OSS 凭证获取失败 | `1000`「获取 OSS 上传凭证失败: {状态码}」 |
| 存储模式不匹配 | 例如 `local` 模式下调 `/file/save-record` 会落库成功但文件并不存在——**要先查 `/file/config`** |