人才给力 · 接口解构app.rencaigeili.com
可复刻 CLI · 覆盖率约 95%
Interface Deconstruction Report

人才给力能做 CLI 复刻,
难的不是接口,是审批流语义

用已登录的浏览器会话把站点跑了一遍,从网络请求和前端 bundle 两路交叉,还原出全站服务分层、接口清单、请求参数与数据模型。结论:这是一套规整的 REST + JSON 接口,没有 GraphQL、没有请求签名、没有前端加密,用 curl 加一个 token 就能跑通全流程。

43实测命中端点
13实体类型
4服务前缀
6业务对象字段表
0请求签名 / 加密
采集时间 2026-11-20 · 租户 tnt_4ffd22769b90a7d6c317f007 · 账号 Johnson Xue(上海德筑)

00结论先说

三个判断,按确定性从高到低。

1. 接口层可以完整复刻。全站是同一套平台框架(Atlas 实体服务 + Workflow 流程服务 + User 身份服务 + Effex 检索服务),CRUD、检索、分页、乐观锁都在标准 HTTP 语义里,用任何语言写 CLI 都成立。
2. 真正的成本在业务语义,不在协议。「推进候选人到下一阶段」不是改个 status 字段,而是要带 revision、targetStageCode、stageFields、stageMeta 去走 stage-transitions;阶段码、必填字段、流转约束都定义在 pipeline-templates 里。要做稳,必须先把这个模板结构吃透。
3. 有一块拿不到现成结论:导出。页面上有导出按钮,但本次没有捕获到导出接口调用(大概率是前端本地生成或异步任务)。如果 CLI 要「一键导全量」,这块需要单独补测。

01架构分层

站点是 Next.js(Turbopack)单页应用,前端只做渲染,所有业务能力都在四个后端前缀后面。

/api/proxy/api/atlas/v1 · 实体与元数据

全站的核心。管实体类型、JSON Schema、实体 CRUD、批量 lookup、标签、事件流水、活动日志、分析看板、列表配置、日历。所有业务对象(候选人 / 职位 / 客户 / 合同 / 账单 / 发票)都在这一层。

/api/proxy/api/workflow/v1 · 流程

项目(project)、申请(application,即"候选人投到某项目"这条记录)、阶段流转、流程模板、按阶段统计。职位项目页和流程进度页全靠它。

/api/user-proxy/api/v1 · 身份与权限

短信登录、token 刷新/吊销、当前用户与租户、成员、角色、权限点、团队树、通知。CLI 的登录态由这里签发。

/api/effex/v1 · 检索与查重

独立服务,不挂 proxy。负责跨实体检索(search / search:count)和重复检测(dedup)。注意它的鉴权路径和另外三个不一样,见下一节。

实体是有物理表的

GET /entity-types 直接暴露了存储结构:13 种实体全部是 dedicated_table 模式,落在 atlas_data 库的独立表里,schema 带版本号和 checksum。

entityType物理表schema 版本CLI 里会用到
candidateatlas_data.entity_candidatev3人才库、寻访结果、推荐
jobatlas_data.entity_jobv3职位项目、JD 解析
clientatlas_data.entity_clientv3客户管理、客户树
contractatlas_data.entity_contractv4合同管理
billingatlas_data.entity_billingv1账单与业绩分成
invoiceatlas_data.entity_invoicev1开票、回款、快递
contactatlas_data.entity_contactv4客户联系人
companyatlas_data.entity_companyv1公司主体
user / teamatlas_data.entity_user / entity_team—顾问、团队归属
context / qa / bipo_employee同名表v1边缘对象,本期不涉及

02鉴权链

登录态拆成两段:短命的 access token 在内存里,长命的 refresh token 在 HttpOnly cookie 里。CLI 只要照着这个模型做 cookie jar,就不需要无头浏览器。

登录与刷新
# 1. 发短信验证码
POST /api/user-proxy/api/v1/auth/sms
Content-Type: application/json
{ "phone": "1xxxxxxxxxx", "purpose": "login" }

# 2. 登录:拿 accessToken,响应同时 Set-Cookie 下发 refresh token
POST /api/user-proxy/api/v1/auth/web/login
{ "account": "1xxxxxxxxxx", "code": "123456" }
→ { "accessToken": "...", "expiresIn": ..., "user": {...} }

# 3. 之后所有业务请求
Authorization: Bearer <accessToken>

# 4. token 过期:cookie 还在,静默换新的(不需要人工)
POST /api/user-proxy/api/v1/auth/web/token/refresh
→ { "accessToken": "..." }

# 5. 退出
POST /api/user-proxy/api/v1/auth/web/token/revoke

前端 HTTP client 的逻辑也印证了这一点:createPlatformHttpClient 统一加 Authorization: Bearer 和 credentials:'include',遇到 401 自动调一次 refreshAccessToken() 再重试原请求。这套模式在 CLI 里就是一个拦截器,实现成本很低。

实测踩到的坑,值得写进 CLI 的报错提示:只带 cookie、不带 Bearer 去请求 /api/effex/v1/search,返回的是 {"detail":"Authenticated tenant context required"}——不是 401,是 400 级别的一句话。也就是说 租户上下文是从 token 里解的,不是从 cookie 或 header 里拿的。CLI 如果只存 cookie 不存 token,会得到这个看起来很莫名的报错。

Tenant 切换

同一账号可能挂多个租户,切换走 POST /tenants/{id}/switch,之后 token 重签。CLI 建议把 tenantId 和 token 一起落地,并且在每次请求前校验 GET /users/me 里的当前租户,避免拿着 A 租户的 token 查 B 租户的数据。

03接口清单

下表按模块分组,是本次通过真实流量 + bundle 静态分析交叉验证得到的端点。带「实测」标记的是这一轮真的打到并返回 200 的;其余来自服务方法表,参数形态可信但未逐个回放。

方法路径参数 / 说明

共 0 条。列表随筛选实时更新。

04数据模型

所有实体共用同一个信封结构,业务字段按四个桶分类。这一点决定了 CLI 的序列化逻辑可以只写一次。

实体记录信封
{
  "id": "uuid",
  "tenantId": "tnt_...",
  "entityType": "candidate",
  "status": "active",
  "visibility": "tenant",
  "accessControl": {},
  "schemaVersion": 3,
  "schemaChecksum": "...",
  "data": {
    "standardFields": {},   // 平台定义的业务字段
    "customFields": {},     // 租户自定义字段
    "functionFields": {},   // 计算字段(只读)
    "rawData": {}           // 原始数据,例如简历解析结果
  },
  "revision": 7,             // 乐观锁,更新必须带
  "createdBy": "...", "createdAt": "...",
  "updatedBy": "...", "updatedAt": "..."
}

字段表分布在 JSON Schema 的 properties.standardFields.properties 里(注意不是 $defs,那个只有类型定义)。六个业务对象的字段规模差别很大:

CLI 设计上的一个便利:GET /entity-schemas/{type}?format=schema 是运行时拿得到的,也就是说 CLI 不需要把字段表硬编码进去——启动时拉一次 schema,就能自动生成 --set 的可选键、类型校验和补全。字段变更时 CLI 不需要重新发版。

另外几个复刻时容易踩的点:

  • 更新必须带 revision。PATCH /entities/{type}/{id} 不带最新 revision 会被拒,这是并发保护,不是 bug。
  • 写入要带数据源头。POST /entities/{type} 需要 X-Data-Source: platform,缺了会被当成外部导入走另一条校验。
  • 批量读用 lookup。详情页是 POST /entities/{type}/lookup 带 {ids, includeDeleted},一次拿一批,比拼 N 次单查划算得多。
  • 字段值有引用类型。userReference / clientReference / entityReference / fileReference 存的是 id 而不是对象,CLI 输出时要自己做一次展开或留 --expand 开关。

05检索 DSL

所有列表页的筛选、排序、分页,最终都收敛到同一个接口,用的是自研的过滤器树,不是简单的 query string。

POST /api/effex/v1/search
{
  "entityType": "candidate",
  "data": ["standardFields"],       // 返回哪些数据桶
  "pageSize": 50,                    // 1..200,默认 50
  "filters": [                       // 树形,最多 8 层 / 100 节点
    { "key": "standardFields.works.company", "values": ["字节跳动"], "operator": "=" },
    { "key": "standardFields.basicInfo.city", "values": ["上海", "北京"], "operator": "in" }
  ],
  "relationOperator": "and",
  "relationFilters": [],             // 跨实体关联筛选
  "sort": [{ "key": "updatedAt", "direction": "desc" }],
  "cursor": null                    // 游标分页,不是 offset
}
→ { "results": [{ "document": {...} }], "nextCursor": "..." }
→ POST /search:count 同 body,返回 { "totalSize": 1234 }

可用的 operator 是一张白名单,直接决定 CLI 的 --where 语法怎么设计:

比较

= != > >= < <= between

集合

in eq neq gt gte lt lte

文本 / 存在性

like not like starts with ends with exists not exists

分页是游标不是页号。响应里给 nextCursor,请求回传 cursor。这意味着 CLI 做「导出全量」时必须循环取游标,不能算 offset;同时要注意 pageSize 上限 200,全量拉取的请求数会比较多(1 万条 = 50 次请求),建议加并发与退避。

06流程与看板

「职位项目」和「流程进度」不是实体 CRUD,是独立的 workflow 服务;业务洞察是另一套看板查询。

项目 / 申请 / 阶段

核心对象只有三个:project(项目,通常对应一个职位)、application(候选人进项目的申请单)、pipeline-template(流程模板,定义阶段码和流转规则)。

推进候选人到下一阶段
# 创建申请:把候选人挂到项目下
POST /api/proxy/api/workflow/v1/applications
{ "projectId": "...", "primaryRefEntityType": "candidate", "primaryRefEntityId": "..." }

# 阶段流转:注意 revision 与 stageFields 都是必填
POST /api/proxy/api/workflow/v1/applications/{id}/stage-transitions
{ "revision": 3,
  "targetStageCode": "client_interview",
  "stageFields": { ... },   // 该阶段的必填字段
  "stageMeta":   { ... } }  // 阶段附加信息

两个列表接口的过滤参数相当丰富,基本覆盖了页面上所有筛选器的组合:

  • GET /projects:pipelineTemplateKey、stageCode、groupCode、ownerUserId*、participantUserId*、status、q、primaryRefEntityType/Id(s)、includeTotal、cursor。
  • GET /applications:limit、projectId、ownerUserId*、participantUserId*、search、joinedAtFrom/To、statGroup、stageCode、status、cursor。
  • GET /applications/stats:按阶段聚合计数,对应「流程进度」页的面包屑数字。
CLI 的甜点区在这里。rcgl pipeline move <app-id> --to <stage> 这种命令,价值远大于把列表查询包一层——因为顾问真正讨厌的操作是「一次性把 20 个候选人推进到同一阶段」,而这个动作在 Web 上要点 20 次。目前模板里已捕获到一个真实模板 id:46efffdd-c410-472c-a05e-92548ab030d1。

业务洞察看板

看板不是固定报表,是「配置 + 查询」两段式:先 GET /analytics/dashboards 拿到可用看板列表(已知两个:cgl_team_overview 团队总览、workbench_standard_overview 个人工作台),再 POST /analytics/dashboards/{key}/query 按参数查数。看板自己声明支持哪些筛选维度,页面上那句 invalid analytics configuration: dashboard does not expose a team filter 就是前端照抄后端的校验文案。

07实测与边界

哪些确认了,哪些没测,为什么没测。这一节是为了让后面接手的人不重复踩坑。

能力状态说明
登录态与租户识别已验证Bearer + HttpOnly cookie 双段模型,前端 401 自动刷新一次
实体 schema 读取已验证六个业务对象字段表全部取到,字段数与字段名逐项核对
实体类型与物理表已验证13 类实体、atlas_data 独立表、schema 版本
列表 / 详情 / 关联数据已验证职位、候选人详情页的实体、标签、事件流水都命中
流程模板与申请列表已验证模板详情可读,参数形态完整
检索 search / count部分DSL 结构从前端 bundle 读出且完整;用纯 cookie 回放时被租户上下文拦下,需带 Bearer 才能实测
创建 / 更新 / 删除未实测方法、路径、请求头已确认;故意没有在真实租户里写入,避免污染生产数据
阶段流转未实测同上,属于写操作,只做了结构确认
导出未捕获页面有导出按钮,但触发后没有观察到导出接口,需单独补测
文件下载已验证简历是 HTML 渲染件,路径 /files/tenants/{tenantId}/files/candidates/resumes/{uuid}.html;下载前先换 URL
权限 / 角色 / 团队已验证设置弹窗里的四个标签页接口全部命中

方法上的两条弯路

采集本身也踩了坑,记下来省得下次重来:

  1. 不能跨路由累加网络记录。整页加载会重置 performance 资源表,所以必须「一个路由一次完整加载 + 立即 drain」,跨页累加只会拿到一堆外壳 chunk、零个业务端点。
  2. 拿不到请求体。浏览器自动化接口只给 url / method / status / request_id,没有 postData;CDP 取 Network.getRequestPostData 会报 session not found;往页面里注入 fetch/XHR 钩子也捕不到(模块初始化时已经持有原生引用)。真正有效的是直接读前端 chunk 做静态分析——参数名、body 结构、鉴权拦截器都是这么还原的。

08CLI 复刻方案

如果要真做,命令树大致是这样。设计取向是「实体层通用 + 业务层薄封装」,不追求把每个页面都翻译成命令。

rcgl auth
login --phone 短信登录,落 token + cookie
refresh 静默续期
whoami 当前用户 / 租户 / 权限
switch <tenantId>
rcgl entity
types 13 类实体 + 物理表
schema <type> 运行时字段表
get <type> <id> --expand 引用展开
lookup <type> --ids a,b,c
create / update / delete 写操作,带 revision
events <type> <id> 变更流水
tags <type> <id>
rcgl search
run <entityType> --where ... --sort ... --limit 200
count <entityType> --where ...
export <entityType> 游标翻页 + CSV/NDJSON
rcgl project
list --stage --owner --status --q
get <id> 含 pipeline 模板
applications <projectId>
stats 按阶段聚合
rcgl pipeline
templates / template <id>
move <app-id> --to <stage> 单条推进
bulk-move --ids ... --to <stage> 批量的真正价值
rcgl analytics
dashboards 可用看板
query <key> --param k=v
rcgl file
url <fileId> 换出下载地址
get <fileId> -o resume.html
rcgl user
members / roles / teams
notifications --unread

实现要点

  • 一个 HTTP 客户端管全部。Base 分四个前缀,但 header、401 重试、错误映射共用一套。建议把 {"detail":"Authenticated tenant context required"} 显式映射成「token 缺失或租户不匹配」的提示。
  • token 存两处。refresh token 用 cookie jar 落地(~/.config/rcgl/cookies,权限 600),access token 存内存并在进程内按过期时间刷新。别把 access token 写进明文配置。
  • 写操作强制 dry-run。create / update / delete / move 默认打印将要发送的 body,加 --yes 才执行;写之前自动拉一次 revision,避免手填。
  • schema 驱动校验。启动拉 schema 做本地校验,字段拼错在客户端就拦住,不用等服务端 400。
  • 分页统一封装。cursor 循环、pageSize 上限 200、并发 3~5、429/5xx 指数退避。
合规与风险提示(做之前要想清楚):这套接口的操作对象是候选人个人信息与客户合同金额。CLI 一旦跑起来,批量导出和批量改状态都会留痕在 activity-events 里,且账号就是个人账号。建议:默认只读、写操作强制人工确认、导出走脱敏字段白名单、不在 CI 里存 cookie。

09还没做的部分

按投入产出排,下面这些是下一步真正要补的。

  1. 导出接口。点一次导出并抓一次流量,确认是前端生成还是异步任务;如果是 jobs/{id} 轮询模式,CLI 要额外做等待逻辑。
  2. 写入回放。在测试租户里完整跑一次 create → update → stage-transition,确认 stageFields 的必填约束和报错形态。
  3. 列表列配置。resolved-configs/entity_list/{type} 和 workflow_task_list/{key} 会带 query 参数,本次直接 GET 返回 400,需要照页面实际请求补齐。
  4. 限流。没有观察到 429,也没有 RateLimit-* 响应头;高频翻页前建议先小批量试。
  5. 审批流。账单和发票里出现 approvalFlowName / approvalCurrentHandler 等字段,说明背后有审批引擎,但这次没有进入审批节点操作,接口形态未知。