目录
基本信息三条必读规则（API 自述，消费纪律）实测坑（2026-08-17 首轮）对犀见的资源映射（29 资源中的关键项）犀见侧实现要点（P1 接入任务的规格）

数据中台统一 API 对接笔记（ai.iphome.cn/api/v1）

2026-08-17 用户宣布就绪并提供 token（妥存 server/.env 的 CENTRAL_API_TOKEN，绝不入库）。首轮实测调通：56 项目 / POI 含经纬度 / 达人库 35 字段 / 联系方式三要素全部真实拉到。文档源：GET /api/v1/llms-full.txt（17,042 行，目录驱动自更新）｜ OpenAPI：/api/v1/openapi.json

基本信息

Base：https://ai.iphome.cn/api/v1 ｜认证：Authorization: Bearer <token> ｜全 GET
端点式样：/catalog（资源清单）、/catalog/{resource}（字段说明）、/data/{resource}?任意字段=值&from=&to=&limit=（任意字段名可当过滤参数）
单点查询（文档 v2 新增，2026-08-17 重读）：GET /data/{resource}/{id} —— 已知 ID 直接拿逐日明细+区间汇总，15 资源支持（talent=uid / merchant-poi=poi_id / short-video=video_id / order=order_id / project=id 等）。汇总自动剔除比率类字段（rate/pct/ratio/avg/gpm，剔除项在响应 not_summed 列出——比率相加无意义，API 侧主动防错）
通道定案（用户 2026-08-17）：本 token 专为犀见开设，统一走本 API，MCP 通道弃用（原"MCP 仅调研"口径作废）
响应壳：{resource, row_count, limit, offset, has_more, duration_ms, caliber_note, rows[]}

三条必读规则（API 自述，消费纪律）

caliber_note 随行：每个响应带口径说明——如 short-video 是样本口径（UGC 每日仅 TOP500），求和会偏低，总量查 video-stats-daily。忽略 caliber_note 是最常见的用错方式
data_maturity：settled=数据已定型可对账结算；growing=当日仍在生成只看趋势
项目隔离：可见范围由 token 决定，project_id 只能缩小不能放大

实测坑（2026-08-17 首轮）

偶发"类型骨架"响应：返回字段类型结构（unquoted-key 伪 JSON）而非数据，无稳定触发规律（疑实例路由/LLM 教学模式）——client 必须检测（JSON 解析失败即骨架）并重试，实测重试 1 次即拿到数据
limit 上限因资源而异（project 200 / addfriend 类 500 / upload-batch 2000——见各资源 catalog）
format 等非字段参数会被当过滤字段报 400（"任意字段名都能当过滤参数"的副作用）

对犀见的资源映射（29 资源中的关键项）

中台资源	实测	犀见消费场景
`project`（56 个）	id/code/project_key/name/region/status/priority/owner_*	P0-4 项目域主数据源：项目选择下拉直接来自此（犀见 project 表转同步镜像或直查——待定）
`merchant-poi`（29 字段）	poi_id/poi_name/省市区/address/latitude/longitude/poi_category/business_hours/电话×3	场次 POI 必填的数据源（建场次时选商家带出 POI）；估价引擎距离计算的坐标源
`merchant-profile`	merchant_name/brand_names/aweme_accounts/business_score/month_verify_gmv/listed_poi_count	项目→商户带出（单商户项目免填链路）
`talent`（35 字段）	uid/unique_id/nick_name/城市/fans_count/等级四件套/credit_score	达人广场主来源（二批定案：中台为主、集星现役过渡）
`talent-contact`	secret_number（虚拟号）/caller_phone/wechat_id	建联三要素——比现有渠道全
`talent-plan`	实测 0 行（暂空）	达人合作计划与结算，待中台侧灌数
`short-video`（62 字段）	video_id/播放/互动/GMV/author_type/video_power_level	P1-6 推荐 SOP 六维数据源（注意样本口径）
`video-stats-daily`	按 author_type 日汇总 GMV/核销/播放/新发布	总量口径（对账/看板用）
`order`（26 字段，回溯 2022）	order_id/券码/talent_name/pay/verify/refund	履约核销对账
`laike-domain` / `syj-domain`	来客/生意经全域 metrics	扩展储备（生意经无权限问题被中台解决）
`search-word` / `review` / `ad-delivery` / `xhs-*`	热搜/评价/投流/小红书	P2 舆情与投放分析储备

犀见侧实现要点（P1 接入任务的规格）

app/central.py 升级或新建 central_api.py：Bearer 认证（CENTRAL_API_TOKEN）、骨架检测重试（JSON parse fail → 重试 ≤3 次退避 2s）、caliber_note 透传落日志、httpx trust_env=False
同步策略照既有纪律：值变才写（fingerprint）、受控集合、水位游标；项目/POI/商户属低频主数据（小时级对账足够）
达人广场切换（集星→中台 talent）：字段映射兼容层（uid/unique_id 同名可直映，等级四件套字段名核对）——P1-6.x 排期；enrich 单达人可用单点查询 /data/talent/{uid}（免列表过滤）
场次选 POI：/data/merchant-poi/{poi_id} 单点 + 按 project_id 过滤列表——建场次流程的选择器数据源