---
tags: UniCourse, Overview
---

# UniCourse 課程匯入指南

:::info
發現貴校課程沒有收錄在 UniCourse 裡面嗎？
歡迎透過 [e-mail] 聯絡我們
或是加入 Discord Server 參與討論（連結於目錄）
:::

> [ToC]

## Overview

首先，請讓我代表 UniCourse 團隊致上謝意。
UniCourse 是一個以學生為核心的開源平台，我們需要社群夥伴的幫助以完善課程資料，而你的任何貢獻都將使 UniCourse 社群變得越來越好。

:::info
在開始之前，請你先完成以下要求：

1. 加入 [UniCourse 的 Discord 伺服器](https://discord.gg/9avZ4rrTWZ)
2. 安裝好 [UniCourse CLI](https://github.com/UniCourse-TW/Backend/tree/main/packages/cli#readme)
3. 稍微理解 [JSON 的格式](https://developer.mozilla.org/zh-TW/docs/Learn/JavaScript/Objects/JSON)
4. 擁有具權限的 UniCourse 帳號（請在 Discord 上聯絡我們）

<details>
<summary>如何安裝 UniCourse CLI？</summary>

你可以透過以下指令安裝 `pnpm` 以及 `unicourse`：

**macOS & Linux**

curl -fsSL https://get.pnpm.io/install.sh | sh -
pnpm i -g @unicourse-tw/cli

**Windows**

iwr https://get.pnpm.io/install.ps1 -useb | iex
pnpm i -g @unicourse-tw/cli

[你可能想知道：安裝 pnpm 的詳細資訊](https://pnpm.io/installation)

</details>
:::

## Course Pack 是什麼？

Course Pack 是具有特定格式的 JSON 檔案，作為表示「課程」、「教師」、「學程」、「提供者」與它們之間關係的序列化數據。

:::spoiler 範例

{
    "$schema": "https://esm.sh/course-pack/schema.json",
    "teachers": [
        {
            "id": "teacher-1",
            "name": "Mr. Jacob"
        },
        {
            "id": "teacher-2",
            "name": "Mr. Sky"
        }
    ],
    "programs": [
        {
            "id": "program-1",
            "name": "Program No.1"
        },
        {
            "id": "program-2",
            "name": "Program No.2"
        }
    ],
    "entities": [
        {
            "name": "University of UniCourse",
            "courses": [],
            "children": [
                {
                    "name": "College of Arts",
                    "courses": [
                        {
                            "id": "2022-winter-1234",
                            "name": "Introduction to Art",
                            "description": "This course is an introduction to art.",
                            "code": "AG1234",
                            "year": 2022,
                            "term": 2,
                            "type": "Compulsory",
                            "credit": 3,
                            "teachers": [
                                "teacher-2"
                            ],
                            "programs": [
                                "program-1",
                                "program-2"
                            ],
                            "prerequisites": []
                        },
                        {
                            "id": "2022-winter-5678",
                            "name": "Art and Artificial Intelligence",
                            "description": "Artificial intelligence is a hot topic in the world today. This course will introduce you to the basics of AI and how it is used in art.",
                            "code": "AG5678",
                            "year": 2022,
                            "term": 2,
                            "type": "Elective",
                            "credit": 3,
                            "teachers": [
                                "teacher-1"
                            ],
                            "programs": [
                                "program-1"
                            ],
                            "prerequisites": []
                        }
                    ],
                    "children": [
                        {
                            "name": "Department of Western Art",
                            "courses": [
                                {
                                    "id": "2022-winter-4321",
                                    "name": "Basic Painting",
                                    "description": "This course is an introduction to basic painting techniques.",
                                    "code": "AW4321",
                                    "year": 2022,
                                    "term": 2,
                                    "type": "Compulsory",
                                    "credit": 3,
                                    "teachers": [
                                        "teacher-2"
                                    ],
                                    "programs": [
                                        "program-1",
                                        "program-2"
                                    ]
                                }
                            ],
                            "children": []
                        }
                    ]
                },
                {
                    "name": "College of Science and Engineering",
                    "courses": [],
                    "children": [
                        {
                            "name": "Department of Computer Science",
                            "courses": [
                                {
                                    "id": "2022-winter-9876",
                                    "name": "Computer Programming",
                                    "description": "This course introduces students to the basics of computer programming. We will use the C programming language to learn various concepts, including variables, functions, loops, and pointers.",
                                    "code": "CS9876",
                                    "year": 2022,
                                    "term": 2,
                                    "type": "Compulsory",
                                    "credit": 3,
                                    "teachers": [
                                        "teacher-1"
                                    ],
                                    "programs": [
                                        "program-2"
                                    ]
                                }
                            ],
                            "children": []
                        }
                    ]
                }
            ]
        }
    ]
}

:::

稍微大的範例：[師大 108-1 ~ 111-1 的 Course Pack](https://github.com/JacobLinCool/NTNU-Course-Crawler/releases/tag/20221106)

Schema Spec: [JSON Schema](https://esm.sh/course-pack/schema.json)

## 怎麼將課程資料打包成 Course Pack？

任何程式語言都可以將課程資料打包成 Course Pack，只需產生的 JSON 符合格式即可。

我們建議你在直接使用物件的名稱作為 `id`（Course Pack 中的唯一識別符），以利匯入時與系統上已經存有的相同物件合併。

:::info
目前我們只允許單次匯入小於 **100 MB** 的檔案，如需匯入大量資料，建議一學期一個檔案，分批匯入，相同 `id` 的物件將於遠端自動合併（需指定 `scope`，詳見下章）。
:::

此外，適用於 JavaScript / TypeScript 的 [course-pack](https://www.npmjs.com/package/course-pack) package 提供相關類型的型別檢查。

你無需擔心匯入時格式錯誤，UniCourse CLI 會在匯入前檢查格式。

## 如何匯入 Course Pack 到 UniCourse 裡？

首先，你需要登入 UniCourse CLI：

unicourse login --server https://api.unicourse.tw <username>

UniCourse CLI 會提示你輸入你的密碼，再按下 Enter 登入。

接著便可匯入 Course Pack：

unicourse import --scope <entity-id> <filename>

如果檔案格式正確的話，等待幾分鐘便可完成上傳與匯入。