> ## Documentation Index
> Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Templates 集合

`templates` 中範本庫裡的每個範本一個文件。範本的檔案（專案 zip 與 PDF）不在這裡：它們保存在 filestore 的 `template/<_id>/v/<version>/` 之下。此集合屬於 web 模組 `template-gallery`（`services/web/modules/template-gallery`）。schema 是 `services/web/modules/template-gallery/app/src/models/Template.mjs` 中的 Mongoose 模型 `Template`；邏輯位於 `services/web/modules/template-gallery/app/src/TemplateGalleryManager.mjs` 以及同目錄下的 `TemplateGalleryHelper.mjs`。

#### 欄位

| 欄位 | 型別 | 含義 | 來源 |
| - | - | - | - |
| `_id` | ObjectId | 由 Mongoose 設定。它也是 filestore 中範本檔案所在的資料夾。 | `TemplateGalleryHelper.mjs:148-150` |
| `name` | String | 標題。必填，最多 150 個字元。發布時依名稱查找範本，編輯時會拒絕其他範本已使用的名稱，因此即使沒有索引，名稱也保持唯一。 | `Template.mjs:7`, `TemplateGalleryHelper.mjs:50-52`, `TemplateGalleryManager.mjs:30-38,55` |
| `category` | String | 分類連結 `/templates/<key>`，其中 `<key>` 是 `OVERLEAF_TEMPLATE_CATEGORIES` 中的一個值或 `all`。必填。 | `Template.mjs:8`, `services/web/modules/template-gallery/index.mjs:17-31`, `TemplateGalleryManager.mjs:206` |
| `descriptionMD` | String | 輸入的原始描述，Markdown 格式。最多 4096 個字元。範本庫會搜尋它。 | `Template.mjs:10`, `TemplateGalleryHelper.mjs:53-55`, `TemplateGalleryManager.mjs:207-212` |
| `description` | String | 由 `descriptionMD` 轉譯並清理後的 HTML。每次設定 `descriptionMD` 時都會設定。 | `Template.mjs:9`, `TemplateGalleryHelper.mjs:224-228` |
| `authorMD` | String | 輸入的原始作者，Markdown 格式。最多 512 個字元。範本庫會搜尋它。 | `Template.mjs:12`, `TemplateGalleryHelper.mjs:56-58` |
| `author` | String | 由 `authorMD` 轉譯的 HTML，只保留連結。每次設定 `authorMD` 時都會設定。 | `Template.mjs:11`, `TemplateGalleryHelper.mjs:229-232` |
| `license` | String | 在表單中選擇的授權文字。必填，最多 512 個字元。 | `Template.mjs:13`, `TemplateGalleryHelper.mjs:59-61` |
| `mainFile` | String | 來源專案根 doc 的路徑，不含開頭的斜線。必填：沒有根 doc 的專案無法發布。 | `Template.mjs:14`, `TemplateGalleryHelper.mjs:112-114` |
| `compiler` | String | 來源專案的編譯器。必填。 | `Template.mjs:15`, `TemplateGalleryHelper.mjs:122` |
| `imageName` | String | 來源專案的 TeX Live 映像檔。範本頁面只顯示其最後一部分。 | `Template.mjs:16`, `TemplateGalleryHelper.mjs:123`, `TemplateGalleryManager.mjs:249-253` |
| `language` | String | 來源專案的拼字檢查語言。可在編輯表單中變更。 | `Template.mjs:17`, `TemplateGalleryHelper.mjs:124` |
| `version` | Number | 從 1 開始，每次以相同名稱重新發布範本時加一。每個版本的檔案位於 `v/<version>/` 之下。必填。 | `Template.mjs:18`, `TemplateGalleryManager.mjs:74-79` |
| `owner` | ObjectId | 首次發布該範本的使用者。覆寫重新發布時保留原擁有者。 | `Template.mjs:19`, `TemplateGalleryManager.mjs:70-79` |
| `project_id` | ObjectId | 最近一次發布所用的專案。每次發布時更新。 | `Template.mjs:20`, `TemplateGalleryManager.mjs:81-84` |
| `lastUpdated` | Date | 最近一次發布或編輯的時間。必填，預設為目前時間。 | `Template.mjs:21-27`, `TemplateGalleryHelper.mjs:125`, `TemplateGalleryManager.mjs:41` |
| `__v` | Number | Mongoose 的版本鍵。schema 沒有關閉它。 | Mongoose 預設 |

#### 寫入方

| 程式碼 | 作用 |
| - | - |
| `TemplateGalleryManager.mjs:53-97`（`createTemplateFromProject`） | `POST /template/new/:Project_id`。複製專案的設定（`TemplateGalleryHelper.mjs:94-134`），把 zip 與 PDF 上傳到 filestore 並儲存。如果名稱已被使用，就回傳衝突，除非用戶端要求覆寫：此時更新該範本並增加其 `version`，然後刪除上一個版本的檔案。 |
| `TemplateGalleryManager.mjs:21-47`（`editTemplate`） | `POST /template/:template_id/edit`。把送出的欄位指派給文件，重新轉譯 `description` 與 `author`，並設定 `lastUpdated`。編輯表單會送出 `name`、`license`、`category`、`language`、`authorMD` 與 `descriptionMD` 中有變更的欄位（`services/web/modules/template-gallery/frontend/js/pages/template/util/api.ts:22-29`）。 |
| `TemplateGalleryHelper.mjs:186-222`（`deleteTemplateAssets`） | `DELETE /template/:template_id/delete` 刪除文件以及指定版本的檔案（`TemplateGalleryManager.mjs:49-51`）。 |

只有網站管理員與 `OVERLEAF_TEMPLATES_USER_ID` 中的使用者可以呼叫這三個路由（`services/web/modules/template-gallery/app/src/Router.mjs:55-62,70-84`, `PermissionsMiddleware.mjs:8-19`）。

#### 讀取方

| 程式碼 | 作用 |
| - | - |
| `TemplateGalleryManager.mjs:158-183`（`getTemplate`） | 依 `_id` 或 `name` 查找一個範本，用於範本頁面與 `GET /api/template`（`services/web/modules/template-gallery/app/src/TemplateGalleryController.mjs:210-232`）。如果 `project_id` 指向已不存在的專案，回應中會省略它；文件本身不會被修改。 |
| `TemplateGalleryManager.mjs:190-236`（`getCategoryTemplates`） | `GET /api/templates`：一個分類的一頁結果，在 `name`、`authorMD` 與 `descriptionMD` 中搜尋，依 `lastUpdated` 或 `name`（不區分大小寫）排序。 |
| `TemplateGalleryHelper.mjs:64-80`（`canUserOverrideTemplate`） | 讀取 `owner`，以便在衝突訊息中顯示擁有者。 |

#### 索引

| 名稱 | 鍵 | 選項 | 遷移 |
| - | - | - | - |
| `_id_` | `_id: 1` | | 預設 |

Mongoose 的 `autoIndex` 已關閉（`services/web/app/src/infrastructure/Mongoose.mjs:7`）。`tools/migrations/20190912145030_create_templates_indexes.mjs`（唯一的 `project_id`、`user_id`、`name`）標記為 `server-pro` 與 `saas`，因此不會在 CE 中執行，CE 只執行 `server-ce` 遷移（`server-ce/init_scripts/900_run_web_migrations.sh`）。

#### 備註

* 上游把 `templates` 視為過時的集合，並在自己的網站上刪除它（`tools/migrations/20241002180623_drop_unused_collections.mjs`，標記為 `saas`）。在 Ayakaleaf Pro 中，範本庫模組會使用它。
* 依名稱排序使用不區分大小寫的定序，`TemplateGalleryManager.mjs:186-188` 處的註解指出 `name` 索引也需要相同的定序。CE 沒有 `name` 索引，因此 Mongo 在記憶體中排序。
* 刪除來源專案或擁有者不會刪除範本。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.