diff --git a/docs/frontend-repository-download-git.md b/docs/frontend-repository-download-git.md new file mode 100644 index 0000000..268af6d --- /dev/null +++ b/docs/frontend-repository-download-git.md @@ -0,0 +1,617 @@ +# 仓库 ZIP、TAR.GZ 下载与 HTTPS Git 前端对接文档 + +本文供前端开发独立对接已实现的仓库归档下载、Git 克隆信息和项目 Git 凭据管理。前置条件是网站已有登录态,并已取得项目的 `projectCode`。本文所有域名、编码、SHA 和 Token 示例均为占位值。 + +## 1. 功能范围 + +| 功能 | 工作区 | 社区 | +| --- | --- | --- | +| 下载 ZIP、TAR.GZ | 登录用户下载本人项目;默认最新 main,也支持历史提交 | 可匿名下载当前已发布版本 | +| clone、fetch、pull、push | 通过项目 Git Token 操作本人仓库 | 先 Fork 到自己的工作区,再使用副本的 Git 接入 | +| Git LFS | 支持实体上传、下载和 verify | 不提供社区 Git 协议入口 | +| 本地 push 后的网站变化 | 刷新工作区后显示最新内容和历史 | 保持原发布版本,用户手动发布后才更新 | + +归档与 Git 的资源边界不同: + +- ZIP、TAR.GZ 是仓库文件快照,不含提交历史;LFS 保留指针,不下载实体;子模块不递归下载。 +- Git clone/fetch 获取 Git 数据;安装并启用 git-lfs 后,客户端可通过 LFS 协议获取实体。子模块仍需客户端自行处理,不会自动递归下载。 +- 单独绑定于 OSS 的封面、URDF、STEP、GLB、零件、拼装及行走资源均不会自动加入归档或 Git 仓库。仓库内本来就有的同类文件按仓库内容处理。 + +## 2. 地址、身份与通用约定 + +### 2.1 两类入口 + +浏览器调用本文 `/api/**` 接口;本地 Git/git-lfs 客户端使用后端返回的 `cloneUrl`,访问 `/git/**`。 + +```text +浏览器: /api/workspace/projects/{projectCode}/git → 获取连接信息 +浏览器: /api/workspace/projects/{projectCode}/git/tokens → 管理项目 Git Token +终端: /git/projects/{projectCode}.git/... → Git/LFS 协议 +``` + +这两类路径由同一个社区 API 应用处理。`/git` 不带 `/api` 前缀。`cloneUrl` 可能使用与业务 API 不同的公网域名,前端必须使用接口返回值,不自行拼接、替换域名或改成 `/api/git`。 + +前端只需配置业务 `API_BASE`,例如同源代理 `/api`,或后端提供的完整 `https://api.example.com/api`。后文请求示例的 `path` 均不再重复 `/api`。 + +### 2.2 两类 Token + +| 凭据 | 获取方式 | 使用位置 | +| --- | --- | --- | +| 网站登录 Token | 现有网页登录流程 | 浏览器请求头 `Authorization: Bearer <网站登录 Token>` | +| 项目 Git Token | 本文创建凭据接口 | 本地 Git 的 HTTP Basic 密码;用户名使用连接信息中的 `username` | + +两类 Token 不能互用。普通用户不需要 Gitea 账号;前端不接收、不配置 Gitea 管理凭据或技术账号凭据。项目 Git Token 继承现有网站登录的身份边界:当前邮箱加图片验证码不验证邮箱归属。 + +社区匿名下载建议不发送 Authorization;失效的网站 Token 即使用于公开接口,也可能导致 401。 + +### 2.3 JSON、编码与时间 + +成功的归档下载返回二进制,其余本文浏览器接口使用以下统一 JSON。所有成功响应均为 HTTP 200,包括创建、撤销;撤销成功 `data=null`。 + +```json +{ + "code": "OK", + "message": "成功", + "data": null, + "requestId": "44444444444444444444444444444444" +} +``` + +失败使用非 2xx HTTP 状态及同样的包装,`code` 为错误码。按 HTTP 状态和 `code` 判断,不通过中文 `message` 区分错误;提示可展示 `message`,排查时提供 `requestId`。反向代理异常也可能返回非 JSON,前端需要兜底。 + +- `projectCode`、`userCode` 作为不透明字符串传递,兼容现有 12 位和历史 32 位编码;不要固定长度或使用数据库 ID。`tokenCode` 也是接口返回的业务编码。 +- SHA 必须使用完整的 40 或 64 位十六进制字符串,不提交页面展示的缩写。 +- 本文凭据时间为上海时间 `Asia/Shanghai`,格式如 `2026-11-03T10:00:00`,可能带小数秒、没有时区后缀;解析时补 `+08:00`,不要补 `Z`。 +- 请求体使用 JSON 时设置 `Content-Type: application/json`。无需跨域 Cookie,不设置 `credentials: 'include'`。 +- `/api/**` 按部署白名单支持跨域,暴露 `X-Request-Id`、`Content-Disposition`、`Retry-After`。本地开发可代理 `/api`;浏览器不需要代理或调用 `/git`。 + +## 3. 浏览器接口清单 + +以下路径均为完整路径;“登录”指网站 Bearer Token。 + +| 方法 | 路径 | 登录 | 成功 data / 响应 | +| --- | --- | --- | --- | +| GET | `/api/workspace/projects/{projectCode}/archive` | 必须,本人项目 | ZIP 或 TAR.GZ 附件 | +| GET | `/api/community/projects/{projectCode}/archive` | 可匿名 | 当前发布版本附件 | +| GET | `/api/workspace/projects/{projectCode}/git` | 必须,本人项目 | `GitConnection` | +| GET | `/api/workspace/projects/{projectCode}/git/tokens` | 必须,本人项目 | `PageResult` | +| POST | `/api/workspace/projects/{projectCode}/git/tokens` | 必须,本人项目 | `IssuedGitToken`,明文只返回一次 | +| DELETE | `/api/workspace/projects/{projectCode}/git/tokens/{tokenCode}` | 必须,本人项目 | `null` | + +## 4. ZIP、TAR.GZ 下载 + +### 4.1 请求参数与版本 + +两个归档接口使用以下查询参数,无请求体: + +| 参数 | 工作区 | 社区 | 约束 | +| --- | --- | --- | --- | +| `format` | 可选 | 可选 | 省略为 `zip`;仅接受 `zip`、`tar.gz`,区分大小写。空字符串也返回 400 | +| `commitSha` | 可选 | 禁止 | 工作区省略时读取当前 main;指定时使用本项目完整提交 SHA。社区只要出现该参数就返回 400,包括 `commitSha=` | + +```http +GET /api/workspace/projects/7m4k9x2p8q6r/archive?format=zip +Authorization: Bearer <网站登录 Token> +``` + +```http +GET /api/community/projects/7m4k9x2p8q6r/archive?format=tar.gz +``` + +工作区仅允许本人未删除且 READY 的项目;社区仅允许 READY、已发布且未删除的项目。其他用户的工作区项目返回 404。 + +服务端在受理时固定本次下载的完整 SHA。假设发布 A 后工作区又提交 B:社区下载 A,工作区默认下载 B,工作区传入 A 的 SHA 则下载 A。传输期间的新提交或重新发布不会切换本次版本;撤回或删除后的新社区下载返回 404。 + +### 4.2 成功响应与下载交互 + +| 项目 | ZIP | TAR.GZ | +| --- | --- | --- | +| HTTP 状态 | 200 | 200 | +| Content-Type | `application/zip` | `application/gzip` | +| 文件名 | `{projectCode}-{SHA前12位}.zip` | `{projectCode}-{SHA前12位}.tar.gz` | + +响应带 `Content-Disposition: attachment`、`Cache-Control: no-store`、`X-Request-Id`。`Content-Length` 不保证存在。归档根目录、文件层级、符号链接及 `.gitattributes` 导出行为沿用 Gitea。 + +页面提供“下载 ZIP”“下载 TAR.GZ”,历史版本页面的工作区下载传入对应完整 SHA。点击后展示下载中状态、防止重复点击,提供取消;成功按 Blob 保存,失败先按 JSON 解析。工作区不能用无法附加 Bearer 请求头的普通下载链接,也不能把 Token 拼到 URL。 + +归档默认最大 1 GiB、上游处理和读取预算 5 分钟、每实例并发 2、每 IP 每分钟 10 次,部署可调整。此限制独立于普通文件 50 MiB 读取限制。通用请求拦截器不要使用 10~30 秒超时提前截断归档;如设置超时,应与后端约定,默认预留至少 400 秒。 + +发附件前的错误返回 JSON;传输开始后的错误会停止响应,此时 HTTP 可能仍为 200,不能再返回 JSON。网络错误、超时、取消后应丢弃残缺文件;没有长度信息时浏览器也不一定识别所有截断情况,解压失败应提示手动重新下载。不提供断点续传、下载任务或进度查询;没有总长度时不要展示虚构百分比。 + +### 4.3 下载错误 + +| HTTP / code | 前端处理 | +| --- | --- | +| 400 `BAD_REQUEST` | 检查 format、完整 SHA;社区删除 commitSha 参数 | +| 401 `UNAUTHORIZED` | 工作区引导登录;匿名社区请求移除失效 Token | +| 404 `NOT_FOUND` | 项目、提交不存在,或无权限、未发布、已撤回、已删除 | +| 409 `CONFLICT` | 工作区项目尚未就绪,刷新项目状态 | +| 413 `ARCHIVE_TOO_LARGE` | 告知归档超过服务端上限 | +| 429 `ARCHIVE_BUSY` / `RATE_LIMITED` | 参考 Retry-After,允许用户稍后手动重试 | +| 502 `GITEA_ERROR` | 上游归档异常,展示 requestId 便于排查 | +| 503 `GITEA_NOT_CONFIGURED` | 服务端仓库配置未完成,联系后端 | +| 504 `ARCHIVE_TIMEOUT` | 提示下载超时,可手动重新下载 | +| 499 `ARCHIVE_CANCELLED` | 发包前取消;浏览器主动取消通常直接抛出 AbortError | + +## 5. Git 连接信息与凭据管理 + +以下四个接口全部使用网站 Bearer Token,响应均设置 `Cache-Control: no-store`。 + +### 5.1 获取连接信息 + +`GET /api/workspace/projects/{projectCode}/git`,无查询参数、无请求体。需要项目 READY。成功 data: + +```json +{ + "cloneUrl": "https://git.example.com/git/projects/7m4k9x2p8q6r.git", + "username": "111111111111", + "defaultBranch": "main", + "headCommitSha": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", + "publishedCommitSha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", + "writeStatus": "IDLE", + "canPush": true +} +``` + +| 字段 | 类型 | 页面用途 | +| --- | --- | --- | +| `cloneUrl` | string | 克隆地址、复制命令;原样使用 | +| `username` | string | Git Basic 用户名,即当前网站用户 userCode | +| `defaultBranch` | string | 当前固定 `main` | +| `headCommitSha` | string | 本次读取到的工作区 main 完整 SHA | +| `publishedCommitSha` | string 或 null | 当前发布 SHA;未发布时为 null,发布状态仍以项目详情为准 | +| `writeStatus` | `IDLE` / `WRITING` / `REVIEW` | 仓库写入状态 | +| `canPush` | boolean | 当前写入状态、技术账号及 main 保护核验是否允许推送;实际推送仍会重新校验 | + +`canPush=true` 也需要 READ_WRITE 凭据,不能理解为只读 Token 可以 push。`canPush=false` 时仍可展示克隆信息和凭据管理,不要仅凭它禁止创建首个读写 Token:创建读写 Token 时后端会初始化或核验 main 保护。 + +Git 是否可用由部署开关 `GIT_ENABLED` 控制。关闭时本接口及创建凭据返回 503 `GIT_UNAVAILABLE`,凭据列表和撤销仍可使用。当前没有单独的功能开关查询接口,前端按本接口结果展示“本地开发暂未启用”。 + +### 5.2 查询凭据列表 + +`GET /api/workspace/projects/{projectCode}/git/tokens?page=1&size=20`。 + +| 参数 | 默认值 | 范围 | +| --- | --- | --- | +| `page` | 1 | 1~100000 | +| `size` | 20 | 1~100 | + +成功 data: + +```json +{ + "items": [ + { + "tokenCode": "33333333333333333333333333333333", + "name": "我的笔记本", + "scope": "READ_WRITE", + "status": "ACTIVE", + "createdAt": "2026-11-03T10:00:00", + "expiresAt": "2027-02-01T10:00:00", + "revokedAt": null, + "lastUsedAt": null + } + ], + "page": 1, + "size": 20, + "total": 1 +} +``` + +列表包含有效、过期、已撤销凭据,按创建时间倒序,空列表 `items=[]`。不返回明文、摘要或数据库 ID。 + +| 字段 | 类型与含义 | +| --- | --- | +| `tokenCode` | string,撤销时使用的业务编码 | +| `name` | string,凭据名称 | +| `scope` | `READ_ONLY`:clone/fetch/pull、LFS 下载;`READ_WRITE`:同时允许 push main 和 LFS 上传 | +| `status` | `ACTIVE`:有效;`EXPIRED`:过期;`REVOKED`:已撤销或因账号会话版本变化失效 | +| `createdAt` / `expiresAt` | string,创建和到期时间 | +| `revokedAt` | string 或 null;会话版本导致失效时 status 可为 REVOKED,但此字段仍为 null | +| `lastUsedAt` | string 或 null;最近成功认证时间,最多每 5 分钟写回一次,不能视作实时在线状态 | + +### 5.3 创建凭据 + +`POST /api/workspace/projects/{projectCode}/git/tokens`,JSON 请求: + +```json +{ + "name": "我的笔记本", + "scope": "READ_WRITE", + "expiresInDays": 90 +} +``` + +| 字段 | 必填 | 约束 | +| --- | --- | --- | +| `name` | 是 | 非空,最多 64 字符;提交前去掉首尾空格,后端保存时也会去掉 | +| `scope` | 是 | 精确使用 `READ_ONLY` 或 `READ_WRITE` | +| `expiresInDays` | 否 | 整数 1~365;省略或 null 为 90 天 | + +每项目默认最多 10 个有效凭据,服务端可调低额度;过期、已撤销及会话版本失效的凭据不占有效额度。达到额度返回 409 `CONFLICT`。读写凭据创建时后端会核验或初始化 main 保护;不兼容时拒绝创建,不覆盖已有更严格规则。 + +成功 data 为: + +```json +{ + "credential": { + "tokenCode": "33333333333333333333333333333333", + "name": "我的笔记本", + "scope": "READ_WRITE", + "status": "ACTIVE", + "createdAt": "2026-11-03T10:00:00", + "expiresAt": "2027-02-01T10:00:00", + "revokedAt": null, + "lastUsedAt": null + }, + "token": "vbg_<仅本次响应返回的项目Git凭据明文>" +} +``` + +`credential` 是元数据,`token` 才是 Git 密码。明文仅返回一次,不能再次查询。成功后刷新凭据列表和连接信息,并在独立区域一次性展示明文、提供复制按钮。明文仅保留在当前展示状态,关闭弹窗、切换项目或离开页面时清除;不要写入 localStorage、sessionStorage、URL、埋点或日志,也不要直接记录整个创建响应。 + +创建请求不要自动重试。超时、断网或用户取消时可能已经创建成功;先刷新列表核对,无法取得明文的凭据应撤销后重新创建。 + +### 5.4 撤销凭据 + +`DELETE /api/workspace/projects/{projectCode}/git/tokens/{tokenCode}`,无请求体,成功 `data=null`。重复撤销同一已存在凭据也成功;不存在、属于其他项目或其他用户的凭据返回 404。 + +成功后刷新列表。撤销、过期、账号禁用或账号会话版本改变后,新的 Git/LFS 请求会被拒绝;已受理传输不保证立即中止或回滚。普通网站退出登录不撤销项目 Git Token。 + +当前没有修改凭据名称、修改权限、续期或重新查询明文的接口;需要调整时撤销并新建。 + +### 5.5 浏览器管理接口错误 + +| HTTP / code | 前端处理 | +| --- | --- | +| 400 `BAD_REQUEST` | 检查字段、枚举、名称长度、到期天数和分页参数 | +| 401 `UNAUTHORIZED` | 网站登录失效,按现有登录流程处理 | +| 404 `NOT_FOUND` | 项目或凭据不存在、已删除或不属于本人 | +| 409 `CONFLICT` | 创建凭据时可能为有效额度已满;连接信息或创建凭据时也可能为项目未就绪,展示服务端 message 并刷新核对 | +| 409 `PROJECT_BUSY` | 项目正在处理,稍后手动重试 | +| 503 `GIT_UNAVAILABLE` | 功能未启用或依赖不可用;已有凭据仍可查询和撤销 | +| 503 `GIT_POLICY_UNAVAILABLE` | 技术账号、仓库或 main 保护不兼容,联系后端处理 | +| 502 / 503 / 504 其他依赖错误 | 展示 message 和 requestId;创建结果不明时先核对列表,不自动重发 | + +## 6. 页面流程与本地开发指引 + +### 6.1 页面入口和状态 + +1. 工作区和社区详情提供 ZIP、TAR.GZ 下载;“克隆与本地开发”只在本人工作区提供。社区展示“Fork 到我的工作区”,完成后进入新项目。 +2. 打开本地开发面板时,可以并行获取连接信息和凭据列表;两者独立处理错误,功能关闭也保留列表、撤销入口。 +3. 展示 cloneUrl、username、main SHA、发布 SHA、写入状态,以及创建、列表、撤销操作。列表行以 tokenCode 为标识。 +4. 创建成功展示一次性明文,刷新列表和连接信息;复制命令中不包含任何 Token。 +5. 提供“刷新工作区”按钮,重新读取当前目录、已打开文件、历史及连接信息;有未保存输入时保留输入并提示版本变化,不静默覆盖。 +6. push 成功后仍显示“需要手动发布到社区”。刷新版本后让用户确认发布,不能自动调用发布接口。 + +| writeStatus | 建议提示与操作 | +| --- | --- | +| `IDLE` | 当前无写入保护;结合 canPush 展示推送可用性 | +| `WRITING` | 正在写入,请稍后刷新;暂缓新的网页保存、上传和发布 | +| `REVIEW` | 写入结果核对中;禁用新的仓库写入和发布,保留用户未保存输入,允许刷新核对 | + +canPush=false 且 IDLE 时可提示“当前暂不可推送,请创建读写凭据或联系管理员核对配置”,不能仅凭此布尔值猜测唯一原因。canPush、SHA 和状态都是读取时的快照,不代替后端实时校验。没有面向前端的 push 任务或进度查询接口,不要求接入 Webhook。 + +### 6.2 可展示给用户的终端步骤 + +克隆前安装 Git 和 git-lfs。使用接口返回的实际 cloneUrl 替换下方占位符: + +```bash +git lfs install +git -c credential.useHttpPath=true clone --single-branch --branch main +cd <本地仓库目录> +git config credential.useHttpPath true + +git add . +git commit -m "更新项目" +git push origin main + +# 后续拉取 +git pull origin main +``` + +终端询问用户名时填写连接信息中的 `username`,密码填写刚创建的项目 Git Token。操作系统凭据管理器可保存凭据。同一域名的不同项目使用不同 Token,示例中的 `credential.useHttpPath=true` 必须保留。 + +仅允许 main 正常快进更新和合并提交,禁止强推、删除 main、推送其他分支或标签、多引用推送、push-options、signed-push 扩展;普通签名提交支持,本地作者、邮箱、时间、签名及 SHA 原样保留。已有其他分支和标签可读取,本期不清理历史数据。 + +LFS 支持实体上传、下载和 verify;不支持文件锁,锁创建/删除返回 501,locks/verify 返回空集合。只读 Token 不能 push 或上传 LFS。 + +本地版本落后时先 pull、处理冲突再 push,不提示用户强推。push 超时或断开不能直接当作失败,也不要自动重推;先刷新工作区和历史核对。 + +### 6.3 与现有网站接口配合 + +| 场景 | 已有接口与用法 | +| --- | --- | +| 社区 Fork | `POST /api/community/projects/{projectCode}/forks`,body 为 `{ "name": "我的副本", "publishedCommitSha": "社区详情的完整发布SHA" }`;成功 data 为新项目,使用其 projectCode 进入工作区 | +| 刷新根目录 | `GET /api/workspace/projects/{projectCode}/tree`;读取最新 main 时省略 commitSha;响应 data.commitSha 为本次版本 | +| 刷新文件 | `GET /api/workspace/projects/{projectCode}/files?path=...`;查询值用 URLSearchParams 编码,可传相同 commitSha 保持目录和文件版本一致 | +| 刷新历史 | `GET /api/workspace/projects/{projectCode}/commits?page=1&size=20` | +| 手动发布 | `PUT /api/workspace/projects/{projectCode}/publication`,body 为 `{ "commitSha": "用户确认发布的最新main完整SHA" }`;成功 data 为更新后的项目 | +| 刷新社区 | `GET /api/community/projects/{projectCode}`;社区目录和文件禁止传 commitSha | + +上述工作区、Fork、发布接口使用网站 Bearer Token。发布版本已变化导致 409 时,刷新版本并让用户重新确认,不自动换 SHA 再发布。网页保存同样使用原编辑基准 SHA;409 时保留输入,处理差异后再提交。`updatedAt` 不代表仓库最新提交时间,版本比较使用 SHA;是否当前已发布使用项目详情的 `publishStatus`。 + +Fork 也是写操作,不自动重试;失败或超时先核对工作区列表。完整项目、目录、文件和 Fork 的类型及约束见 [用户端完整接口文档](vibemake-api.md)。 + +## 7. 可复用 TypeScript 示例 + +以下两个代码块可放入同一个前端模块。示例无需依赖完整接口文档中的 request 方法;`platformToken` 始终指网站登录 Token。 + +### 7.1 类型、JSON 请求和凭据管理 + +```typescript +const API_BASE = '/api'; // 同源代理;也可替换为部署提供的完整 API 基础地址,无末尾斜杠。 + +export interface ApiResponse { + code: string; + message: string; + data: T; + requestId: string; +} + +export interface PageResult { + items: T[]; + page: number; + size: number; + total: number; +} + +export interface GitConnection { + cloneUrl: string; + username: string; + defaultBranch: string; + headCommitSha: string; + publishedCommitSha: string | null; + writeStatus: 'IDLE' | 'WRITING' | 'REVIEW'; + canPush: boolean; +} + +export type GitScope = 'READ_ONLY' | 'READ_WRITE'; + +export interface GitTokenView { + tokenCode: string; + name: string; + scope: GitScope; + status: 'ACTIVE' | 'EXPIRED' | 'REVOKED'; + createdAt: string; + expiresAt: string; + revokedAt: string | null; + lastUsedAt: string | null; +} + +export interface CreateGitTokenInput { + name: string; + scope: GitScope; + expiresInDays?: number | null; +} + +export interface IssuedGitToken { + credential: GitTokenView; + token: string; // 仅本次展示,不持久化、不记录整个响应。 +} + +export class ApiError extends Error { + constructor( + public readonly status: number, + public readonly code: string, + message: string, + public readonly requestId: string | null, + public readonly retryAfter: string | null = null, + ) { + super(message); + this.name = 'ApiError'; + } +} + +async function readEnvelope(response: Response): Promise> { + let body: ApiResponse; + try { + body = await response.json(); + } catch { + throw new ApiError(response.status, 'BAD_RESPONSE', '接口响应异常,请稍后重试', + response.headers.get('X-Request-Id'), response.headers.get('Retry-After')); + } + if (!body || typeof body.code !== 'string' || typeof body.message !== 'string') { + throw new ApiError(response.status, 'BAD_RESPONSE', '接口响应格式异常', + response.headers.get('X-Request-Id')); + } + return body; +} + +function responseError(response: Response, body: ApiResponse): ApiError { + return new ApiError(response.status, body.code, body.message, + body.requestId ?? response.headers.get('X-Request-Id'), + response.headers.get('Retry-After')); +} + +async function apiRequest( + path: string, + platformToken: string, + options: { method?: 'GET' | 'POST' | 'DELETE'; body?: unknown; signal?: AbortSignal } = {}, +): Promise { + const headers: Record = { Authorization: `Bearer ${platformToken}` }; + if (options.body !== undefined) headers['Content-Type'] = 'application/json'; + const response = await fetch(`${API_BASE}${path}`, { + method: options.method ?? 'GET', + headers, + credentials: 'omit', + cache: 'no-store', + body: options.body === undefined ? undefined : JSON.stringify(options.body), + signal: options.signal, + }); + const body = await readEnvelope(response); + if (!response.ok || body.code !== 'OK') throw responseError(response, body); + return body.data; +} + +function gitPath(projectCode: string): string { + return `/workspace/projects/${encodeURIComponent(projectCode)}/git`; +} + +export function getGitConnection(projectCode: string, platformToken: string, signal?: AbortSignal) { + return apiRequest(gitPath(projectCode), platformToken, { signal }); +} + +export function listGitTokens( + projectCode: string, platformToken: string, page = 1, size = 20, signal?: AbortSignal, +) { + const query = new URLSearchParams({ page: String(page), size: String(size) }); + return apiRequest>( + `${gitPath(projectCode)}/tokens?${query}`, platformToken, { signal }); +} + +export function createGitToken( + projectCode: string, platformToken: string, input: CreateGitTokenInput, signal?: AbortSignal, +) { + return apiRequest(`${gitPath(projectCode)}/tokens`, platformToken, { + method: 'POST', body: { ...input, name: input.name.trim() }, signal, + }); // 不添加自动重试。 +} + +export function revokeGitToken(projectCode: string, tokenCode: string, platformToken: string) { + return apiRequest( + `${gitPath(projectCode)}/tokens/${encodeURIComponent(tokenCode)}`, + platformToken, { method: 'DELETE' }); +} + +export function parseShanghaiTime(value: string): Date { + return new Date(`${value}+08:00`); // 仅用于本文无时区后缀的时间字段。 +} +``` + +### 7.2 归档下载、文件保存与主动取消 + +```typescript +export async function downloadRepositoryArchive( + scope: 'workspace' | 'community', + projectCode: string, + format: 'zip' | 'tar.gz' = 'zip', + options: { platformToken?: string; commitSha?: string; signal?: AbortSignal } = {}, +): Promise { + if (scope === 'workspace' && !options.platformToken) throw new Error('请先登录'); + if (scope === 'community' && options.commitSha !== undefined) { + throw new Error('社区归档仅支持当前已发布版本,请移除 commitSha'); + } + const query = new URLSearchParams({ format }); + if (options.commitSha !== undefined) query.set('commitSha', options.commitSha); + const response = await fetch( + `${API_BASE}/${scope}/projects/${encodeURIComponent(projectCode)}/archive?${query}`, + { + headers: options.platformToken + ? { Authorization: `Bearer ${options.platformToken}` } : {}, + credentials: 'omit', + cache: 'no-store', + signal: options.signal, + }, + ); + if (!response.ok) { + const failure = await readEnvelope(response); + throw responseError(response, failure); + } + + const expectedType = format === 'zip' ? 'application/zip' : 'application/gzip'; + const actualType = response.headers.get('Content-Type')?.split(';')[0].trim().toLowerCase(); + if (actualType !== expectedType) { + await response.body?.cancel(); + throw new ApiError(response.status, 'BAD_RESPONSE', '接口未返回预期的压缩包', + response.headers.get('X-Request-Id')); + } + const blob = await response.blob(); // 收到响应头后,取消仍可中止响应体读取。 + const requestId = response.headers.get('X-Request-Id'); + const contentLength = response.headers.get('Content-Length'); + if (contentLength !== null && blob.size !== Number(contentLength)) { + throw new ApiError(response.status, 'ARCHIVE_INCOMPLETE', '压缩包接收不完整,请重新下载', requestId); + } + if (options.signal?.aborted) throw new DOMException('下载已取消', 'AbortError'); + + const disposition = response.headers.get('Content-Disposition') ?? ''; + const encodedName = disposition.match(/filename\*=UTF-8''([^;]+)/i)?.[1]; + const plainName = disposition.match(/filename="([^"]+)"/i)?.[1]; + let filename = plainName ?? `${projectCode}.${format}`; + if (encodedName) { + try { filename = decodeURIComponent(encodedName); } catch { /* 使用后备文件名。 */ } + } + filename = filename.replace(/[\\/\u0000-\u001f\u007f]/g, '_'); + const objectUrl = URL.createObjectURL(blob); + try { + const link = document.createElement('a'); + link.href = objectUrl; + link.download = filename; + document.body.appendChild(link); + link.click(); + link.remove(); + } finally { + setTimeout(() => URL.revokeObjectURL(objectUrl), 1000); + } +} + +// 示例:在点击事件中传入实际项目编码和网站登录 Token。 +export async function handleWorkspaceDownload( + projectCode: string, platformToken: string, controller: AbortController, +) { + try { + await downloadRepositoryArchive('workspace', projectCode, 'zip', { + platformToken, signal: controller.signal, + }); + } catch (error) { + if (controller.signal.aborted) return; // 用户主动停止,不提示“服务器错误”。 + throw error; // 页面统一提示 ApiError.message 或网络异常,不记录 Token。 + } +} + +// 点击下载:创建并保留 const controller = new AbortController(),传给上面的函数。 +// 点击停止或离开页面:controller.abort()。下一次下载必须创建新的 controller。 +// 社区匿名下载:downloadRepositoryArchive('community', projectCode, 'tar.gz')。 +``` + +`BAD_RESPONSE`、`ARCHIVE_INCOMPLETE` 是示例前端封装错误码,不是后端业务码。网络错误、用户取消及接收二进制时的异常未必有 JSON 或 requestId。Blob 会占用浏览器内存或存储,页面应限制重复下载;HTTP 200、Blob 保存成功均不能替代压缩包完整性校验。 + +## 8. Git 协议说明与用户故障提示 + +本节用于编写终端指引和排查,不要求前端实现 Git/LFS 协议。Git 客户端自动访问这些路径: + +| 方法 | 路径 | +| --- | --- | +| GET | `/git/projects/{projectCode}.git/info/refs?service=git-upload-pack` | +| GET | `/git/projects/{projectCode}.git/info/refs?service=git-receive-pack` | +| POST | `/git/projects/{projectCode}.git/git-upload-pack` | +| POST | `/git/projects/{projectCode}.git/git-receive-pack` | +| Git LFS 客户端自动调用 | `/git/projects/{projectCode}.git/info/lfs/**` | + +协议响应为 Git pkt-line/pack 或 LFS 标准结构,不是网站 ApiResponse。401 带 Basic challenge,429 带 Retry-After;LFS action 使用服务端签发的短期凭据,由 git-lfs 自动处理。不要用浏览器的 apiRequest 包装去请求上述路径,也不要将它们作为普通网页打开方式。 + +| 协议错误码/状态 | 给用户的处理指引 | +| --- | --- | +| 401 `GIT_UNAUTHORIZED` | 检查网站 userCode、项目 Git Token、是否过期或撤销;不要使用网站登录 Token | +| 403 `GIT_READ_ONLY` | 使用 READ_WRITE 凭据后再 push 或上传 LFS | +| 400 `GIT_COMMAND_REJECTED` | 仅推送 main,去掉其他引用及不支持的推送扩展 | +| 409 `GIT_STALE_MAIN` | 先拉取并处理冲突,再推送 | +| 409 `CONFLICT` / `PROJECT_BUSY` | 项目未就绪或正在处理,刷新核对 | +| 409 或 503 `REMOTE_RESULT_UNKNOWN` | 结果核对中,暂缓写入和发布,先刷新工作区及历史 | +| 429 `GIT_BUSY` | 请求频率或并发超限,稍后手动重试 | +| 413 `GIT_TRANSFER_TOO_LARGE` / `GIT_METADATA_TOO_LARGE` / `LFS_TOO_LARGE` | 请求超过服务端限制,缩小请求或联系管理员 | +| 503 `GIT_UNAVAILABLE` / `GIT_POLICY_UNAVAILABLE` | 功能或依赖暂不可用,联系管理员 | +| 504 `GIT_TIMEOUT` / 502 `GIT_UPSTREAM_ERROR` | 涉及 push 时先核对工作区,不能仅凭断网或超时判定未写入 | +| 501 `LFS_LOCKS_UNSUPPORTED` | 当前不支持 LFS 文件锁 | + +原生 Git 也可能输出标准引用拒绝信息;不能仅凭 HTTP 200 判断 push 成功,应以 Git 客户端最终结果和刷新后的工作区 SHA 为准。 + +默认 Git pack 单次上限 5 GiB、LFS 单对象 1 GiB、元数据 8 MiB、LFS batch 最多 500 对象;单次 Git/LFS 请求预算 10 分钟。每实例读取/push/LFS 并发为 4/2/8;每用户每分钟 Git 120 次、LFS 600 次,每 IP 每分钟认证失败最多 20 次。均可由部署调整,与归档、JSON、multipart 和在线文件读取限制独立。 + +## 9. 前端联调验收 + +- [ ] 本人工作区和匿名社区均可下载 ZIP、TAR.GZ,文件名及解压后的中文路径、子目录、二进制正确。 +- [ ] 发布 A 后提交 B:社区归档仍为 A,工作区默认 B,指定历史 SHA 可下载 A;社区请求不携带 commitSha。 +- [ ] 下载处理 401、404、413、429、非 JSON 代理错误、取消、网络中断;限制重复点击并释放 Blob URL。 +- [ ] 只有本人工作区提供本地开发入口;社区先 Fork,再使用新项目编码;非本人项目、已删除项目的管理请求被拒绝。 +- [ ] 正确区分网站登录 Token、项目 Git Token、tokenCode;cloneUrl 原样使用,明文不进入缓存、URL、日志或埋点。 +- [ ] 凭据列表支持分页、有效/过期/撤销状态和空时间;创建校验名称、权限、到期天数及额度,创建结果未知不自动重试。 +- [ ] 一次性明文正确展示和复制,关闭展示后清除;列表无法重新获取明文;撤销后刷新列表。 +- [ ] 功能关闭时展示不可用提示,仍可查询、撤销已有凭据;canPush=false 不直接阻止创建首个读写凭据。 +- [ ] 按网站展示的地址、用户名和凭据完成 clone、commit、push、pull;同域名两个项目可使用不同凭据,LFS 正常上传下载。 +- [ ] push 后刷新工作区显示最新目录、文件和历史,保留未保存输入;社区保持原版本,确认手动发布后才更新。 +- [ ] 正确展示 WRITING、REVIEW;结果未知时不重复写入、不自动发布;只读、强推、其他引用等拒绝场景有明确指引。 + +部署联调前由后端确认 Git 功能已开启、数据库扩展已执行、返回的 cloneUrl 可达,公网 `/git/**` 保留路径转发至社区 API。归档代理读取超时默认至少 400 秒,Git/LFS 至少 660 秒并关闭请求、响应缓冲及缓存。前端不负责保存上游凭据或配置 Gitea。 + +完整业务接口见 [用户端接口文档](vibemake-api.md),部署细节见 [README](../README.md#https-git-网关)。 diff --git a/docs/vibemake-api.md b/docs/vibemake-api.md index 6eefd4b..b27b8a5 100644 --- a/docs/vibemake-api.md +++ b/docs/vibemake-api.md @@ -6,6 +6,8 @@ 当前支持项目、文件、目录、提交、手动发布、快照 Fork、评论和点赞,以及可配置开启的 Maker AI(聊天问答、查找、创建空项目、Fork)。项目发布后,后续提交只更新工作区,需要再次调用发布接口才更新社区代码。没有服务端草稿保存、独立工作区实体或项目类型表。 +ZIP、TAR.GZ 下载和 HTTPS Git 本地开发的独立前端交付文档见 [仓库下载与 Git 接入](frontend-repository-download-git.md),包含六个浏览器接口、页面流程、TypeScript 示例及联调清单。 + ## 阅读导航 - [接入约定](#接入约定) @@ -1633,7 +1635,7 @@ Fork 每用户每分钟 10 次、URDF 批次签名 20 次、封面签名 30 次 ## HTTPS Git 与本地开发 -Git 网关默认关闭,开启后仅本人工作区可 clone/fetch/pull/push;社区项目先 Fork。网站身份沿用邮箱加图片验证码,当前不验证邮箱归属,Git Token 继承此身份校验边界。普通用户不需要 Gitea 账号。 +Git 网关由部署开关 `GIT_ENABLED` 控制,开启后仅本人工作区可 clone/fetch/pull/push;社区项目先 Fork。网站身份沿用邮箱加图片验证码,当前不验证邮箱归属,Git Token 继承此身份校验边界。普通用户不需要 Gitea 账号。 ### 接口清单与数据