知识库首页 外链提交资料 navigation-projects-api.md

navigation projects api

本地来源：外链提交/外链资料/2k买的发外链工具/外链自动化/vibe-backlinks-vd-main/docs/navigation-projects-api.md

外链库 & 项目管理 API 摘要

基础 Host：http://localhost:10707

本文覆盖「外链库（Backlink Directories）」与「项目（Projects）」相关的 REST 接口，帮助你在本地一次性建设外链导航库并追踪每个项目的提交进度。

通用契约

  • 所有接口均返回 JSON，统一包裹为： json { "code": 0, "data": { ... }, "errorMsg": "" }
  • code = 0 表示成功；其余错误码参见 src/lib/api/response.ts，本文涉及的主要有：
    • 2001 Unauthorized、2002 InvalidJsonPayload
    • 3001-3003 目录相关错误
    • 3101-3103 项目相关错误
    • 3201-3203 提交相关错误
  • 请求体全部为 JSON，必须包含 Content-Type: application/json。
  • 鉴权：
  • GET /api/directories 允许匿名搜索。
  • 其余目录及所有项目相关接口都要求用户已登录（getRequestUserId）。未登录时返回 401 + code:2001。

API 登录指引

所有鉴权依赖 Better Auth（见 src/lib/auth.ts、src/app/api/auth/[...all]/route.ts）。在本地开发 (NODE_ENV=development) 时默认打开邮箱+密码登录，同时可选接入 Google OAuth（需配置 GOOGLE_CLIENT_ID/SECRET）。常见方式：

  1. 使用示例登录界面 - 启动 npm run dev，在浏览器打开 http://localhost:10707/en/example/internal-login。 - 该页面调用 src/lib/auth-client.ts 的 signUp.email / signIn.email，可直接注册或登录，成功后浏览器会保存 better-auth.session_token Cookie，API 请求（同域或 fetch(..., { credentials: 'include' })）即可携带会话。
  2. 直接走 API（适合脚本或集成测试） ```bash # 注册 curl -i -X POST http://localhost:10707/api/auth/sign-up/email \ -H "Content-Type: application/json" \ -d '{"email":"[email protected]","password":"Passw0rd!","name":"Demo"}'

# 登录 curl -i -X POST http://localhost:10707/api/auth/sign-in/email \ -H "Content-Type: application/json" \ -d '{"email":"[email protected]","password":"Passw0rd!"}' `` - 响应头会返回Set-Cookie: better-auth.session_token=...; HttpOnly; Path=/。 - 之后可用该 Cookie 访问GET http://localhost:10707/api/auth/session验证会话，并在调用目录/项目接口时附带（curl --cookie "better-auth.session_token=..." ...）。 3. **Google 登录（可选）**：当.env中提供 Google OAuth 证书并在浏览器触发signInWithGoogle()时，Better Auth 会重定向至/api/auth/sign-in/social，流程结束后同样写入better-auth.session_token`。

只要浏览器或 API 客户端持有该 Cookie，getRequestUserId 就能解析用户 ID，从而通过上述鉴权校验。

外链库（/api/directories）

该模块负责维护可投稿的站点清单（含 DR、流量、语言等）。

列表：GET http://localhost:10707/api/directories

  • 查询参数 | 参数 | 类型 | 说明 | | --- | --- | --- | | search | string | 对 name 和 url 模糊匹配（内部移除 %、_ 再拼接 %term%）。 | | language | string | 按语言精确匹配（存储为小写）。 | | category | string | 按类别精确匹配。 |
  • 响应：{ directories: BacklinkDirectory[] }
  • BacklinkDirectory 字段：id, name, url, dr, monthlyTraffic, language, category, notes, followType, pricing, source, createdAt, updatedAt。
  • source 用于区分内置导航库（base）与用户新增的自定义站点（custom）。

导出：GET http://localhost:10707/api/directories/export

  • 允许匿名访问，直接返回可下载的 JSON 文件，文件名形如 backlink-directories-2024-05-09T12-34-56-789Z.json。
  • 响应体是未包裹的数组，元素结构为： ts type BaseDirectoryJson = { name: string link: string dofollow?: string pricing?: string language?: string traffic?: number dr?: number category?: string }
  • 仅导出数据库中的自定义站点数据，不包含 backlinks/merged_backlinks.json 里的内置导航库。
  • 字段回退策略：
  • dofollow、pricing、language、category 为空时会填入 'unknown'。
  • traffic、dr 为空时会回退为 0。
  • link 始终使用数据库中的标准化 URL（含协议）。
  • 可用于一次性同步「所有外链站」列表到本地脚本或第三方工具。

新增：POST http://localhost:10707/api/directories

  • 需要登录。
  • 请求体字段 & 校验 | 字段 | 约束 | | --- | --- | | name | 必填，字符串 ≤ 120 字，禁止为空。 | | url | 必填，合法 HTTP(S) URL，内部会去掉 hash。 | | dr | 可选，0–100 的数字，可保留 2 位小数。 | | monthlyTraffic | 可选，非负整数。 | | language | 可选，字符串 ≤ 32 字符，自动转为小写。 | | category | 可选，字符串 ≤ 64 字符。 | | notes | 可选，≤ 800 字，允许为空字符串。 |
  • 成功响应：{ directory: BacklinkDirectory }
  • 去重逻辑：服务端会在写库前使用规范化 URL + origin（协议+域名）与已有目录（含内置库）比对，若已存在则直接返回该目录且不会新增，避免 https://example.com 与 https://example.com/blog 等重复站点。
  • 失败示例：字段缺失或非法时返回 400 + code:3001 DirectoryValidationFailed。

更新：PUT http://localhost:10707/api/directories/{id}

  • 需要登录。
  • 规则
  • 允许局部更新（所有字段同上，partial=true）。
  • 至少提供一个合法字段，否则 400 + “No changes supplied”。
  • 不存在的 id 返回 404 + code:3002。
  • 成功响应：{ directory: BacklinkDirectory }

删除：DELETE http://localhost:10707/api/directories/{id}

  • 需要登录。
  • 删除成功返回 { deleted: true }；若 id 不存在，返回 404 + code:3002。

项目（/api/projects）

项目用于聚合一个域名/产品的所有投稿记录。

列表：GET http://localhost:10707/api/projects

  • 需要登录，会自动按 userId 过滤。
  • 响应：{ projects: BacklinkProjectSummary[] }
  • 每个元素包含常规字段 (id, name, targetUrl, description, metadata, createdAt, updatedAt, userId) 以及 submissionStats 统计：{ total, queued, submitted, approved, rejected, ignored }。

新增：POST http://localhost:10707/api/projects

  • 请求体字段 & 校验 | 字段 | 约束 | | --- | --- | | name | 必填，≤ 100 字。 | | description | 可选，≤ 800 字，允许空字符串（存储为 null）。 | | targetUrl | 可选，合法 HTTP(S) URL。 | | metadata | 可选，JSON 对象或 null，用于存储项目的自定义信息。 |
  • 响应：{ project: BacklinkProject }
  • 校验失败 → 400 + code:3101。

查询单个：GET http://localhost:10707/api/projects/{projectId}

  • 需要登录，且只可访问自己的项目。
  • 未找到或不属于当前用户 → 404 + code:3102。
  • 成功返回 { project: BacklinkProject }。

更新：PUT http://localhost:10707/api/projects/{projectId}

  • 与创建字段一致，全部为可选局部更新。
  • 至少提供一个合法字段，否则 400 + code:3101。
  • 成功返回 { project: BacklinkProject }。

删除：DELETE http://localhost:10707/api/projects/{projectId}

  • 成功返回 { deleted: true }；无权限或不存在则 404 + code:3102。

项目投稿记录（/api/projects/{projectId}/submissions）

此资源将项目与外链站的投稿状态关联，可用于展示以目录为维度的投放进度。

列表：GET http://localhost:10707/api/projects/{projectId}/submissions

  • 需要登录并拥有项目权限。
  • 响应： json { "project": BacklinkProject, "submissions": BacklinkProjectSubmission[] }
  • BacklinkProjectSubmission 字段：id, projectId, directoryId, status, submissionUrl, notes, lastCheckedAt, createdAt, updatedAt。
  • status 值域：queued, submitted, approved, rejected, ignored（仅存储已提交状态）。

新建 / 更新投稿：POST http://localhost:10707/api/projects/{projectId}/submissions

  • 请求体字段 & 校验 | 字段 | 约束 | | --- | --- | | directoryId | 与 directoryUrl 二选一。若传入则需为非空字符串，服务端会先尝试按 ID 精确匹配。 | | directoryUrl | 与 directoryId 二选一。可输入完整 URL 或仅主域，服务端会在外链库中按 URL（含模糊 host 匹配）寻找对应目录。 | | status | 必填，允许值：not_submitted, queued, submitted, approved, rejected, ignored。传 not_submitted 将删除该目录的投稿记录。 | | submissionUrl | 可选，合法 HTTP(S) URL。 | | notes | 可选，≤ 800 字，允许空串→null。 | | lastCheckedAt | 可选，合法日期字符串，可转成 Date。 |
  • 响应：{ submission: BacklinkProjectSubmission | null }
  • 当 status = not_submitted 时，记录被删除，submission 返回 null。
  • 错误处理
  • 未提供可识别的目录（ID 或 URL）或格式不合法 → 400 + code:3201。
  • 目录不存在、项目不属于当前用户等服务器校验失败 → 500 + code:3203（日志会记录具体原因）。
  • 匹配逻辑：当传入 URL 时，服务端先尝试精确匹配，再按 origin（协议+域名）和域名模糊 LIKE 查询，便于通过 example.com、https://example.com/blog 等输入定位既有目录。

友链（/api/friend-links）

友链 API 允许你复用项目权限并直接写入项目在前端页面展示的友链内容。

新增：POST http://localhost:10707/api/friend-links

  • 需要登录，并确保 projectId 指向当前用户拥有的项目，否则返回 404 + code:3102。
  • 请求体字段 & 校验 | 字段 | 约束 | | --- | --- | | projectId | 必填，字符串，指向已有项目 ID。 | | name | 必填，≤ 120 字。 | | htmlSnippet | 可选，≤ 8000 字符；允许空字符串（存储为 null）。 | | url | 可选，合法 HTTP(S) URL，可与 htmlSnippet 二选一。 |
  • 必须至少提供 htmlSnippet 或 url，两者同时为空时会返回 400 + code:3301。
  • 响应：{ link: FriendLink }，字段结构参见 src/types/friend-links.ts。
  • 错误码：字段非法时 3301 FriendLinkValidationFailed，项目不存在或无权限时 3102 ProjectNotFound，其余写库异常时 3303 FriendLinkPersistenceFailed。

使用以上接口即可在本地 http://localhost:10707 环境下完成外链库维护、项目投稿进度追踪以及友链管理。

业务提示

  • 列表接口支持无感刷新：GET /api/directories 无需鉴权，可直接在营销落地页调用；项目及提交相关接口必须在授权后使用（如通过会话 Cookie）。
  • 写操作全部在服务端进行字段标准化：
  • 字符串会裁剪、限制长度并在需要时转小写。
  • URL 统一剥离 #fragment，保证同一站点不会因 hash 不一致被视为不同记录。
  • 数值校验（DR、流量）在 0 上界/整型范围内完成，可避免将错误数据写入数据库。
  • 提交状态是冪等的：相同 projectId + directoryId 会在 POST 时 upsert，便于在前端直接覆盖写入。

本文档为站内渲染。原始文件本地路径：saas/source/backlinks/外链提交-外链资料-2k买的发外链工具-外链自动化-vibe-backlinks-vd-main-docs-naviga-d0a43b.md（仅本地保留，不入库不部署）