> ## 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.

# Gitea Sync Project States 集合

`giteaSyncProjectStates` 为每个关联到 Gitea 仓库的项目保存一个文档：关联的是哪个仓库，以及上一次同步停在哪里。 该集合属于 `gitea-sync` web 模块（`services/web/modules/gitea-sync`）。schema 位于 `services/web/modules/gitea-sync/app/models/giteaSyncProjectStates.mjs`，所有访问都经过 `services/web/modules/gitea-sync/app/src/SyncStateManager.mjs`。 字段与 [GitHub Sync Project States](https://ayakaleaf-pro.mintlify.site/zh-CN/dev/data-model/github-sync-project-states-collection) 相同。

#### 字段

| 字段 | 类型 | 含义 | 来源 |
| - | - | - | - |
| `_id` | ObjectId | 创建时由 Mongoose 设置。 | |
| `projectId` | ObjectId | 关联的项目。必填。schema 写了 `unique: true`，但不会建立任何索引（见“索引”）。 | `giteaSyncProjectStates.mjs:8` |
| `repoFullName` | String | 以 `owner/name` 形式表示的仓库（Gitea 的 `full_name`）。必填。 | `giteaSyncProjectStates.mjs:9`, `GiteaApiClient.mjs:315` |
| `defaultBranchName` | String | 项目同步所用的分支。在关联项目时设置，之后不再更改：导入时为导入表单提交的分支；导出时为新仓库的默认分支，API 未返回时为 `main`。默认 `null`。 | `giteaSyncProjectStates.mjs:10`, `GiteaSyncHandler.mjs:175-181,233-239`, `GiteaApiClient.mjs:314-317` |
| `mergeStatus` | String | `clean`、`conflict` 或 `diverged`。默认 `clean`。 | `giteaSyncProjectStates.mjs:11` |
| `lastSyncCommit` | String | 上次同步时已同步分支上的提交 SHA。默认 `null`。 | `giteaSyncProjectStates.mjs:12` |
| `lastSyncVersion` | Number | 上次同步时的项目历史版本，在刷新历史后从 project-history 的 `GET /project/:id/version` 读取。默认 `null`。 | `giteaSyncProjectStates.mjs:13`, `services/web/modules/gitea-sync/app/src/HistoryManager.mjs:8-17` |
| `unmergedBranchName` | String | 发生冲突时：存放 Overleaf 更改的临时分支，命名为 `overleaf-YYYY-MM-DD-HHMMSS`。没有冲突时为 `null`。 | `giteaSyncProjectStates.mjs:14`, `GitMerge.mjs:814-818` |
| `unmergedBranchHead` | String | 发生冲突时：该分支的头提交。默认 `null`。 | `giteaSyncProjectStates.mjs:15` |
| `conflictVersion` | Number | 发生冲突时：记录冲突时的项目历史版本。默认 `null`。 | `giteaSyncProjectStates.mjs:16` |
| `__v` | Number | Mongoose 版本键。schema 没有关闭它。 | Mongoose 默认 |

#### 写入方

| 代码 | 作用 |
| - | - |
| `SyncStateManager.mjs:9-14` (`createProjectState`) | 创建文档：将仓库导入为新项目之后（`services/web/modules/gitea-sync/app/src/GiteaSyncHandler.mjs:175-181`），或将项目导出到新仓库之后（`GiteaSyncHandler.mjs:233-239`，仅限所有者，已关联时拒绝）。 |
| `SyncStateManager.mjs:16-21` (`updateProjectState`) | 对更改的字段执行 `$set`。当 `lastSyncCommit` 不再是已同步分支的祖先（`services/web/modules/gitea-sync/app/src/GiteaApiClient.mjs:431`），或者该提交已不存在且用户有推送权限（`GiteaSyncHandler.mjs:123,126-137`）时，`getMergeOverview` 会设置 `mergeStatus: 'diverged'`。 同步（`services/web/modules/gitea-sync/app/src/GitMerge.mjs`）成功时会更新 `lastSyncCommit`/`lastSyncVersion`（例如 `:152,189,231`），用 `unmergedBranchName`、`unmergedBranchHead` 和 `conflictVersion` 记录冲突（`:214-220`），并在冲突解决后清除它们（`:257-264`）。 |
| `SyncStateManager.mjs:23-25` (`removeProjectState`) | 在所有者取消关联项目时（`GiteaSyncHandler.mjs:83-97`）以及已删除项目过期时（`services/web/modules/gitea-sync/index.mjs:46-48`）删除文档。 |

#### 读取方

| 代码 | 作用 |
| - | - |
| `GiteaSyncHandler.mjs:39-60` (`getProjectState`) | 向编辑器提供 `mergeStatus`、`repoFullName` 和 `unmergedBranchName`。没有文档时返回 `need-export`，这个值从不存储。 |
| `GiteaSyncHandler.mjs:110-143` (`getMergeOverview`) | 将 `lastSyncCommit` 和 `lastSyncVersion` 与 Gitea 及项目历史进行比较，列出新的提交。 |
| `GiteaSyncHandler.mjs:200` (`exportProject`) | 拒绝导出已关联的项目。 |
| `GitMerge.mjs:36` (`doGitMergeWithoutLock`) | 在同步开始时加载状态。 |

#### 索引

| 名称 | 键 | 选项 | 迁移 |
| - | - | - | - |
| `_id_` | `_id: 1` | | default |

Mongoose 的 `autoIndex` 已关闭（`services/web/app/src/infrastructure/Mongoose.mjs:7`），因此 schema 中 `projectId` 上的 `unique: true` 不会创建任何索引。 没有迁移为该集合创建索引。

#### 说明

* Gitea 的 API 不能像 GitHub 那样在分支之外创建提交。能快进时，同步会直接提交到已同步分支上；否则提交到临时分支，再通过 pull request 合并（`GitMerge.mjs:16-21`）。
* 同步在项目的 `gitSync` 锁下运行，与 GitHub Sync 和 GitLab Sync 共用（`GitMerge.mjs:25-32`）。
* 已删除的项目会保留其文档，直到项目过期。
* 用户的 Gitea 令牌位于 [Gitea Sync User Credentials](https://ayakaleaf-pro.mintlify.site/zh-CN/dev/data-model/gitea-sync-user-credentials-collection)。


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