Developers

开发者 API｜能力总览与接入说明

基于 app/backend（Go + Gin）的现状整理：你可以安全地告诉集成方哪些事已经存在，哪些仍在路线图。本站不列出未经核对的 REST 路径清单。

打开文档中心 Web 控制台
Bearer Token 会话 JSON API（逐步补充专用路由） Worker 回调与任务租约

核心实体与定位

技术栈
Go + Gin + Ent/SQL 迁移
正式 API 基地址
https://geo.aimmme.com/geoapi/v1
公开暴露方式
由 Nginx 反代到内部 Go 服务，不暴露开发端口
Answer Block

直接回答

用短答案先把产品、服务与适用边界先讲清楚，便于用户和 AI 抽取。

Q: 现在的 API 文档交付形态是什么？

A: 以「能力总览 + 快速开始 + 示例」为主；完整 OpenAPI 将与专用路由审计一同发布，不在此处提前承诺路径列表。

Q: 认证怎么做？

A: 与主流 SaaS 一致，登录后使用访问令牌（Bearer）。正式对外基地址统一为 `https://geo.aimmme.com/geoapi/v1`，具体可开放路径以接入文档与路由审计结果为准。

架构事实（已确认）

  1. 单体 Go 服务 暴露 HTTP API；Vue 前端通过反向代理或同域静态资源访问（本地开发通过 Vite 代理 /api）。
  2. GEO 扩展 位于 internal/geo，与 geo_records、geo_automation_jobs 等表协同；用户隔离以 user_id 为主（手册注明 tenant_id 仍在演进）。
  3. Worker 通过独立进程轮询/批量领取任务并回写结果状态，与 API 之间通过共享数据库及约定好的任务字段通信——而不是在浏览器里直连 Playwright。

认证与安全（已确认）

  • 登录接口接受邮箱/密码 JSON，返回访问令牌；随后的 Authorization: Bearer <token> 调用受保护路由。
  • 不要在营销站或公开示例里粘贴真实 token；演示请使用一次性即删账号。
  • Turnstile / 频控等能力由后端开关控制，以部署环境变量为准。

正式接入基地址

正式对外基地址固定为：

https://geo.aimmme.com/geoapi/v1

接入方应只保存这个公网基地址；内部 Go 服务端口、开发代理路径与本地调试命令不作为正式 API 地址对外发布。完整路径清单将在路由审计和 OpenAPI 片段确认后再开放。

GEO 业务 API 的现状

  • 许多模块仍通过通用记录/任务接口暴露；专用列表 API（文章、关键词等）在差距清单中标记为下一步。
  • 请勿假设 已存在涵盖全部模块的 OpenAPI JSON；对接前请阅读仓库 internal/geo 以及最新迁移。

Worker / Webhook（概述）

  • Worker consuming 队列的模式在架构方案中有专节描述；若你需要从外部系统「投递任务」，应通过受控的 API（或数据库受控写入）完成，而不是直接调用 Playwright。

路线图（公开可承诺）

里程碑 说明
M1 稳定公开认证与会话文档
M2 为高频模块（文章、关键词、发布任务）提供专用 REST + OpenAPI 片段
M3 引入 Sandbox API Key 与 webhook replay 保护

若在集成时需要 NDA 级别的字段表，请通过 联系 走企业流程。

参考阅读

  • docs/aimeGeo-系统架构方案.md
  • docs/aimeGeo-本地运行手册.md