# files

**Repository Path**: zcxsythenew/files

## Basic Information

- **Project Name**: files
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2020-02-19
- **Last Updated**: 2021-06-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# files

多语言学习网站的文件服务器。可用来上传图片、音频等文件，将可能用于 NARRATION 模块。也可用于上传 Excel 文件，然后用指定的 Excel 文件创建课程。

服务器需要 `scope` 为 `user_info` 的有效 `access_token` 才可以访问。

## API 文档

### 登录和注册

有关 `token` 的相关文档，参考[这里](https://gitee.com/zcxsythenew/backend)。

### 错误处理

当客户端通过上一节所述的认证步骤之后，对于后续发生的错误处理如下：

- 响应状态码：4xx / 5xx
- 响应体：

```json
{
    "error": "invalid_request"
}
```

常出现的 `error` 值为：

- `invalid_request`。参数不正确，返回 422 状态码。
- `not_found`。未找到，返回 404 状态码。当用户修改或删除不存在的信息时可能出现。
- `forbidden`。拒绝，返回 403 状态码。当所查询、修改、删除的内容并不是由当前用户创建，或往其他人创建的课程中添加内容时会出现。
- `server_error`。服务器错误，返回 500 状态码。

可能（但不一定）会出现 `detail` 字段。例如：

```json
{
  "error": "invalid_request",
  "detail": [ { "message": "required", "field": "title", "code": "missing_field" } ]
}
```

如果服务器返回 403 错误，且没有 `error` 字段，而是返回 `message`：`invalid csrf token`，则代表请求被 Egg.js 拦截。这种情况下的返回格式是 Egg.js 规定的，无法更改。

### 获取 CSRF Token

- `GET /csrf`
- 响应状态码：200
- 响应体：纯文本字符串，为 CSRF Token
- 此 Token 同时也写入 Cookie

### 访问根文件目录

- `GET /files`
- scope: `file`
- 响应状态码：200
- 响应体：

```json5
[
    {
        "id": 1,
        "name": "image.jpg",
        "mime": "image/jpeg",
        "folder_type": false, // 文件
        "folder": null, // null 表示根目录
        "created_at": "2016-09-27T07:53:31.872Z",
        "updated_at": "2016-09-27T07:53:31.872Z"
    },
    {
        "id": 2,
        "name": "folder name",
        "folder_type": true, // 文件夹
        "folder": null, // null 表示根目录
        "created_at": "2016-09-27T07:53:31.872Z",
        "updated_at": "2016-09-27T07:53:31.872Z"
    }
]
```

### 访问文件夹

- `GET /files/:id` 此 id 必须为文件夹的 id
- scope: `file`
- 响应状态码：200
- 响应体：

```json5
{
    "id": 20,
    "name": "folder name",
    "folder_type": true, // 文件夹
    "folder": 4, // 所在文件夹的 id，null 表示根目录
    "data": [ // 文件夹内包含的内容
        {
            "id": 30,
            "name": "image.jpg",
            "mime": "image/jpeg",
            "folder_type": false, // 文件夹下的文件
            "folder": 20, // 子文件位于 20 号文件夹
            "created_at": "2016-09-27T07:53:31.872Z",
            "updated_at": "2016-09-27T07:53:31.872Z"
        },
        {
            "id": 31,
            "name": "folder name",
            "folder_type": false, // 文件夹下的文件夹
            "folder": 20, // 子文件夹位于 20 号文件夹
            "created_at": "2016-09-27T07:53:31.872Z",
            "updated_at": "2016-09-27T07:53:31.872Z"
        }
    ],
    "created_at": "2016-09-27T07:53:31.872Z",
    "updated_at": "2016-09-27T07:53:31.872Z"
}
```

### 访问文件（下载）

- `GET /files/:id` 此 id 必须为文件的 id
- scope: `file`
- 响应状态码：200
- 响应 `Content-Type`：文件的 `mime` 类型
- 响应体：二进制流

### 上传文件

- `POST /files`
- scope: `file`
- 请求 `Content-Type`：`multipart/form-data`
- 具体请求格式可参考下列 HTML 代码：

```html
<!-- 可以选择用其它方式上传，
     只要格式与此 HTML 的上传
     格式等价即可 -->
<form action="/files" method="post" enctype="multipart/form-data">
    <ul>
        <!-- 此处输入文件夹的 ID -->
        <li><label>Folder: <input name="folder" type="number" /></label></li>

        <!-- 选择文件区域 -->
        <li><label>File: <input name="file" type="file" /></label></li>

        <!-- 上传按钮 -->
        <!-- 提交后，服务器将根据选择的文件存入文件名和 MIME 类型 -->
        <li><input type="submit" /></li>
    </ul>
</form>
```

- 响应状态码：201
- 响应体：

```json
{
    "id": 1
}
```

### 创建文件夹

- `POST /folders`
- scope: `file`
- 请求体：

```json5
{
    "name": "folder name",
    "folder": 1, // 若在根目录下创建，此值为 null，或者省略
}
```

- 响应状态码：201
- 响应体：

```json
{
    "id": 1
}
```

### 更改名称（文件或文件夹）

- `PUT /files/:id`
- scope: `file`
- 请求体：

```json
{
    "name": "new file or folder name"
}
```

- 响应状态码：204
- 响应体：空

注意：更改名称不会改变文件的 MIME 类型。访问（下载）文件时，服务器返回的 `Content-Type` 仍然以上传文件时的 MIME 类型为准。

## 删除文件或文件夹

- `DELETE /files/:id`
- scope: `file`
- 请求体：空
- 响应状态码：204
- 响应体：空

删除文件夹时，将进行递归删除。

## QuickStart

<!-- add docs here for user -->

see [egg docs][egg] for more detail.

### Development

```bash
npm i
npm run dev
open http://localhost:7001/
```

### Deploy

```bash
npm start
npm stop
```

### npm scripts

- Use `npm run lint` to check code style.
- Use `npm test` to run unit test.
- Use `npm run autod` to auto detect dependencies upgrade, see [autod](https://www.npmjs.com/package/autod) for more detail.

[egg]: https://eggjs.org