nearboss 业务数据 API

给 Agent 使用的 nearboss 业务数据 API。纯接口契约：只列端点 + 输入参数 + 输出参数。基于真实库表校验、优化建议、目标态 v1 / 优化态 v2 全部结论蒸馏。不含意图识别 —— 自然语言→端点+参数的转换由消费侧（本项目）负责，本文档只定义 API 本身。版本前缀：/pos/ai/v1；时间一律 13 位 epoch 毫秒（UTC+4）；金额一律 Money 对象。

0. 公共约定

0.1 响应信封 `Envelope<T>`（所有端点统一外壳）

字段	类型	说明
`api_version`	string	契约版本，如 `v1`
`code`	int	0=成功；非 0 见 `error`
`message`	string	人类可读信息
`data`	T	业务载荷（各端点 Output）
`error`	Error?	失败时存在
`meta`	Meta?	货币/时区/数据来源等自描述
`request_id`	string	链路追踪
`server_time`	epoch ms	服务端时间

失败回真实 HTTP 状态（400/401/403/404/409/410/422/429/503）。

0.2 `Error`

字段	类型	说明
`error_code`	string	语义码，如 `AIGENT_QUERY_RANGE_TOO_LARGE`
`category`	enum	`validation` / `conflict` / `degraded` / `not_found` / `rate_limited` / `unsupported`
`retriable`	bool	是否可退避重试
`details`	object?	结构化补充（如 `{max_days,requested_days}`）
`retry_after_ms`	int?	retriable 时的建议退避

0.3 `Money`

字段	类型	说明
`amount`	int	最小货币单位整数（fils）
`currency`	string	ISO 4217，如 `AED`
`minor_unit`	int	小数位数，AED=2

0.4 `PageMeta`（分页响应共用）

{ total, page, page_size, pages, has_next }

0.5 分页/排序/投影请求壳（列表类端点共用入参）

字段	类型	默认	说明
`page`	int	1	页码
`page_size`	int	20	≤100
`sort`	`[{field,order}]`	—	`order∈ASC\|DESC`
`view`	enum	`FULL`	`SLIM`=仅 id/name/status 等轻量列

一、数据专家 API

1.1 指标查询 `POST /pos/ai/v1/metrics:query`

聚合 / 趋势 / 同比三形态合一。

Input

字段	类型	必填	说明
`store_id`	string	✓	门店
`metrics`	string[]	✓	指标 key（见 §1.6 白名单，可多选）
`aggregation`	enum	✓	`SUM\|AVG\|MAX\|MIN\|COUNT`
`time_granularity`	enum	✓	`DAY\|MONTH\|YEAR\|NONE`（NONE=区间汇总单值）
`date_from`	epoch ms	✓	区间起（含）
`date_to`	epoch ms	✓	区间止（含）
`compare`	enum	—	`NONE\|WOW\|MOM\|YOY`，默认 NONE

Output

字段	类型	说明
`series`	Row[]	按粒度分组的数据行
`series[].period`	string	周期标签（如 `2026-06-10` / `2026-06`）
`series[].values`	map	`{<metric>: {value, prev, pct, unit, is_ratio}}`；`prev`/`pct` 无同比时为 null
`meta`	Meta	`{currency, tz_offset, source, data_basis, coverage_days}`

越界：AIGENT_QUERY_RANGE_TOO_LARGE（>400 天，details{max_days,requested_days}）；粒度不支持：AIGENT_GRANULARITY_UNSUPPORTED{supported:[...]}。

1.2 维度拆分取数 `POST /pos/ai/v1/metrics:dimensions`

按渠道 / 支付 / 来源 / 会员维拆分（源 report_daily_statistics 预聚合列；维度不可用时按门店 available:false）。

Input

字段	类型	必填	说明
`store_id`	string	✓	门店
`metric`	string	✓	单指标 key
`dimension`	enum	✓	`CHANNEL\|PAYMENT\|ORDER_SOURCE\|MEMBER_TYPE`
`date_from` / `date_to`	epoch ms	✓	区间（含头含尾）

Output

字段	类型	说明
`breakdown`	Item[]	各维度值切片
`breakdown[].dimension_value`	string	如 `DINING_ROOM`/`PAY_BY_CARD`
`breakdown[].value`	number	该切片指标值
`breakdown[].share`	number	占比 0–1
`meta`	Meta	同 §1.1

1.3 经营健康分级 `POST /pos/ai/v1/insights/health`

Input：store_id、date_from、date_to（≥14 天两期对比）

Output

字段	类型	说明
`grade`	enum	`EXCELLENT\|GOOD\|WARNING\|RISK`
`signals`	Item[]	`{metric, current, prev, pct, direction}`
`summary`	string	结论摘要
`meta`	Meta	含 `coverage_days`

1.4 Peer 对标 `POST /pos/ai/v1/insights/peer-benchmark`

Input：store_id、metric(如 avg_ticket)、date_from、date_to、peer_scope(AREA_CUISINE 默认)

Output

字段	类型	说明
`self_value`	number	本店值
`peer_median`	number	peer 中位
`peer_p25` / `peer_p75`	number	四分位
`percentile`	number	本店在 peer 中的分位 0–100
`peer_size`	int	peer 样本店数（<5 返 `AIGENT_INSUFFICIENT_DATA`）
`meta`	Meta	peer 口径（area×cuisine）

1.5 菜单工程四象限 `POST /pos/ai/v1/insights/menu-engineering`

Input：store_id、date_from、date_to（≥30 天明细）

Output

字段	类型	说明
`items`	Item[]	商品级
`items[].spu_id` / `spu_name`	—	商品
`items[].quadrant`	enum	`STAR\|PLOWHORSE\|PUZZLE\|DOG`
`items[].sold_qty`	int	销量
`items[].profit_index`	number	毛利指数
`meta`	Meta	—

1.6 滞销 / 死 SKU `POST /pos/ai/v1/insights/slow-movers`

Input：store_id、window_days(默 30)、threshold(默销量阈)

Output：items[]{spu_id, spu_name, sold_qty, last_sold_at, stock_num, status}、meta

1.7 时段×星期热度 `POST /pos/ai/v1/insights/time-heatmap`

源 main_order.create_time（唯一时刻源）。

Input：store_id、metric(order_count/income)、date_from、date_to（≥4 周）

Output

字段	类型	说明
`grid`	Cell[]	7×24
`grid[].weekday`	int	0–6
`grid[].hour`	int	0–23
`grid[].value`	number	指标值
`peak`	object	`{weekday, hour, value}`

1.8 会员 RFM 分层 `POST /pos/ai/v1/insights/member-rfm`

Input：store_id、date_from、date_to

Output

字段	类型	说明
`segments`	Seg[]	`{segment, member_count, share, avg_recency_days, avg_frequency, avg_monetary:Money}`
`meta`	Meta	`member_id` 填充率不足时返 `AIGENT_INSUFFICIENT_DATA`

1.9 会员构成总览 `GET /pos/ai/v1/member/overview`

Input（query）：store_id、date_from、date_to

Output：{total, new_in_period, returning, by_source:[{source_type,count,share}], trend:[{period,new_count}]}、meta{scope_note:MEMBER_IS_MER_SCOPED}

1.10 门店画像 `GET /pos/ai/v1/stores/{store_id}/profile`

Output

字段	类型	说明
`store_id` / `store_name`	—	基本
`cuisine`	string	菜系
`trading_area`	object	`{area_id, area_name}`
`geo`	object?	未审计字段为 null + `field_audit` 标记
`launch_date`	epoch ms?	同上

1.11 报表导出（异步作业，3 端点）

步骤	端点	Input	Output
创建草稿	`POST /pos/ai/v1/report/exports`	`store_id`、`metrics[]`、`date_from`、`date_to`、`format`(`CSV\|XLSX`)	`{draft_token, expires_at, estimated_rows}`
确认	`POST /pos/ai/v1/report/exports:confirm`	`draft_token`（幂等键）	`{job_id, status}`
查终态	`GET /pos/ai/v1/report/exports/{job_id}`	—	`{job_id, status, download_url?, error?}`，`status∈ACCEPTED\|PROCESSING\|DELIVERED\|FAILED`

越界：AIGENT_EXPORT_RANGE_TOO_LARGE（>90 天）；token 门店绑定不符：AIGENT_TOKEN_SCOPE_MISMATCH(403)。

1.12 能力自描述 `GET /pos/ai/v1/metrics/capabilities`

Input（query）：store_id（按店返可用维度/能力）

Output

字段	类型	说明
`metrics`	Item[]	`{key, label, unit, is_ratio}`
`supported_aggregations`	enum[]	—
`supported_granularities`	enum[]	—
`compare_bases`	enum[]	`WOW/MOM/YOY`
`dimensions`	Item[]	`{dimension, available, data_basis, fill_rate}`
`insights`	Item[]	`{key, available, data_basis}`
`limits`	object	`{bi_max_days, export_max_days}`
`currency` / `tz_offset`	—	—

§指标白名单（12 项，`metrics[]` 取值）

key	含义	单位	来源
`income`	净收入(成功额−退款额)	Money	`turnover−refund` 派生
`success_amount`	成功交易额	Money	`turnover` 直取
`success_count`	成功笔数	笔	`order_quantity`
`refund_amount`	退款额	Money	`refund` 直取
`refund_count`	退款笔数	笔	`main_order.order_status=refunded` 聚合
`fail_amount`	失败额	Money	废单/取消聚合
`fail_count`	失败笔数	笔	`blankout+cancel` 聚合
`settle_amount`	总结算额	Money	`turnover−refund` 派生
`order_count`	订单总数	笔	`order_quantity`
`refund_rate`	退款率	ratio	`refund/turnover`
`success_rate`	成功率	ratio	成功/(成功+失败)
`avg_ticket`	客单价	Money	`average_order_price` 直取

二、营销专家 API

2.1 活动类型目录 `GET /pos/ai/v1/meta/campaign-activity-types`

Output

字段	类型	说明
`types`	Type[]	`{type_code, label, description, discount_model}`
`types[].discount_model`	enum	`PERCENT_TO_PAY\|FIXED_AMOUNT_OFF\|FLASH_PRICE\|...`

类型码：FIXED_AMOUNT_OFF（定额减）/WHOLE_ORDER_PERCENT（整单折）/FLASH_SALE（秒杀）等，均带 legacy_code 过渡。

2.2 商品检索 `GET /pos/ai/v1/products`

Input（query）：store_id、spu_keyword、page、page_size

Output

字段	类型	说明
`items`	Item[]	`{spu_id, spu_name, price:Money, original_price:Money, stock_num}`
`page_meta`	PageMeta	—

2.3 活动预览 `POST /pos/ai/v1/campaigns:preview`

生成草稿 + 一次性 token（不落库）。

Input

字段	类型	必填	说明
`store_id`	string	✓	—
`activity_type`	enum	✓	见 §2.1
`activity_name`	string	✓	—
`date_start` / `date_end`	epoch ms	✓	活动期
`time_start` / `time_end`	epoch ms	—	每日时段；空=全天
`is_long_term`	bool	—	长期活动
`percent_to_pay`	int	条件	10–99（折扣类）
`amount_off`	Money	条件	定额减类
`flash_price`	Money	条件	秒杀类
`spu_ids`	string[]	条件	适用商品（秒杀/单品类）

Output

字段	类型	说明
`preview_token`	string	commit 幂等键
`expires_at`	epoch ms	TTL
`summary`	object	可读摘要（展示用）
`draft`	object	规范化后的活动草稿（机读原始字段，可回填编辑）

2.4 活动确认发布 `POST /pos/ai/v1/campaigns:commit`

Input

字段	类型	必填	说明
`preview_token`	string	✓	幂等：同 token TTL 内二次提交返同一 `campaign_id`
`draft`	object	—	编辑后回传（提供则以最新资源重校验）

Output：{campaign_id, status, published_at}

快照过期：AIGENT_PREVIEW_STALE（区别于 EXPIRED）；门店越权：AIGENT_TOKEN_SCOPE_MISMATCH(403)。

2.5 活动列表 `GET /pos/ai/v1/campaigns`

Input（query，含 §0.5 分页/排序/投影壳）

字段	类型	说明
`store_id`	string	✓
`statuses`	enum[]	多状态过滤
`keyword`	string	匹配活动名
`created_from` / `created_to`	epoch ms	创建时间区间
`ended_reason`	enum	结束原因过滤

Output

字段	类型	说明
`items`	Row[]	活动行
`items[].campaign_id` / `activity_name` / `activity_type` / `status`	—	基本
`items[].date_start` / `date_end` / `time_start` / `time_end`	epoch ms	机读原始值
`items[].is_long_term` / `is_all_day`	bool	显式布尔
`items[].enabled_actions`	enum[]	当前可执行动作（见 §2.7）
`items[].ended_reason`	enum?	已结束时
`page_meta`	PageMeta	—

2.6 活动详情 `GET /pos/ai/v1/campaigns/{id}`

Output：§2.5 行字段超集 + 明细

追加字段	类型	说明
`discount_detail`	object	`{discount_model, percent_to_pay?, amount_off?:Money, flash_price?:Money}`
`spus`	Item[]	适用商品 `{spu_id, spu_name, price:Money}`
`progress`	object?	秒杀类 `{sold, total, progress}`
`all_actions`	`[{action, endpoint, available, status}]`	机读可调对象

2.7 活动生命周期（4 端点）

动作	端点	Input	Output
暂停	`POST /pos/ai/v1/campaigns/{id}:pause`	`expected_status?`(CAS)	`{campaign_id, status}`
恢复	`POST /pos/ai/v1/campaigns/{id}:resume`	`expected_status?`	`{campaign_id, status}`
终止	`POST /pos/ai/v1/campaigns/{id}:terminate`	`expected_status?`	`{campaign_id, status}`（库存归还恰好一次）
撤回	`POST /pos/ai/v1/campaigns/{id}:withdraw`	`expected_status?`	`{campaign_id, status}`（PENDING/DRAFT 用）

状态前置不满足：AIGENT_STATE_CONFLICT(409，details{current_status, allowed_actions})；目标态已达成→幂等成功返当前状态。

2.8 会员标签操作（preview→commit）

步骤	端点	Input	Output
预览	`POST /pos/ai/v1/member/tags:preview`	`store_id`、`member_id`、`op`(`ADD\|REMOVE`)、`tag`	`{preview_token, expires_at, affected}`
确认	`POST /pos/ai/v1/member/tags:commit`	`preview_token`（幂等）	`{member_id, tags}`

2.9 会员查询

端点	Input（query）	Output
`GET /pos/ai/v1/member` 列表	`store_id`、`keyword`、§0.5 壳	`items[]{member_id, nickname, phone(脱敏), level, tags}`、`page_meta`
`GET /pos/ai/v1/member/{id}` 详情	—	上行超集 + `{join_at, source_type, recent_orders}`；手机/邮箱默认脱敏，`view=FULL`+平台身份才全量

附：端点清单一览

数据专家（14）：metrics:query · metrics:dimensions · insights/health · insights/peer-benchmark · insights/menu-engineering · insights/slow-movers · insights/time-heatmap · insights/member-rfm · member/overview · stores/{id}/profile · report/exports(创建) · report/exports:confirm · report/exports/{id} · metrics/capabilities

营销专家（13）：meta/campaign-activity-types · products · campaigns:preview · campaigns:commit · campaigns(列表) · campaigns/{id} · campaigns/{id}:pause · :resume · :terminate · :withdraw · member/tags:preview · member/tags:commit · member/member/{id}

nearboss 业务数据 API

0. 公共约定

0.1 响应信封 Envelope<T>（所有端点统一外壳）

0.2 Error

0.3 Money

0.4 PageMeta（分页响应共用）

0.5 分页/排序/投影请求壳（列表类端点共用入参）

一、数据专家 API

1.1 指标查询 POST /pos/ai/v1/metrics:query

1.2 维度拆分取数 POST /pos/ai/v1/metrics:dimensions

1.3 经营健康分级 POST /pos/ai/v1/insights/health

1.4 Peer 对标 POST /pos/ai/v1/insights/peer-benchmark

1.5 菜单工程四象限 POST /pos/ai/v1/insights/menu-engineering

1.6 滞销 / 死 SKU POST /pos/ai/v1/insights/slow-movers

1.7 时段×星期热度 POST /pos/ai/v1/insights/time-heatmap

1.8 会员 RFM 分层 POST /pos/ai/v1/insights/member-rfm

1.9 会员构成总览 GET /pos/ai/v1/member/overview

1.10 门店画像 GET /pos/ai/v1/stores/{store_id}/profile

1.11 报表导出（异步作业，3 端点）

1.12 能力自描述 GET /pos/ai/v1/metrics/capabilities

§指标白名单（12 项，metrics[] 取值）

二、营销专家 API

2.1 活动类型目录 GET /pos/ai/v1/meta/campaign-activity-types

2.2 商品检索 GET /pos/ai/v1/products

2.3 活动预览 POST /pos/ai/v1/campaigns:preview

2.4 活动确认发布 POST /pos/ai/v1/campaigns:commit

2.5 活动列表 GET /pos/ai/v1/campaigns

2.6 活动详情 GET /pos/ai/v1/campaigns/{id}

2.7 活动生命周期（4 端点）

2.8 会员标签操作（preview→commit）

2.9 会员查询

附：端点清单一览

0.1 响应信封 `Envelope<T>`（所有端点统一外壳）

0.2 `Error`

0.3 `Money`

0.4 `PageMeta`（分页响应共用）

1.1 指标查询 `POST /pos/ai/v1/metrics:query`

1.2 维度拆分取数 `POST /pos/ai/v1/metrics:dimensions`

1.3 经营健康分级 `POST /pos/ai/v1/insights/health`

1.4 Peer 对标 `POST /pos/ai/v1/insights/peer-benchmark`

1.5 菜单工程四象限 `POST /pos/ai/v1/insights/menu-engineering`

1.6 滞销 / 死 SKU `POST /pos/ai/v1/insights/slow-movers`

1.7 时段×星期热度 `POST /pos/ai/v1/insights/time-heatmap`

1.8 会员 RFM 分层 `POST /pos/ai/v1/insights/member-rfm`

1.9 会员构成总览 `GET /pos/ai/v1/member/overview`

1.10 门店画像 `GET /pos/ai/v1/stores/{store_id}/profile`

1.12 能力自描述 `GET /pos/ai/v1/metrics/capabilities`

§指标白名单（12 项，`metrics[]` 取值）

2.1 活动类型目录 `GET /pos/ai/v1/meta/campaign-activity-types`

2.2 商品检索 `GET /pos/ai/v1/products`

2.3 活动预览 `POST /pos/ai/v1/campaigns:preview`

2.4 活动确认发布 `POST /pos/ai/v1/campaigns:commit`

2.5 活动列表 `GET /pos/ai/v1/campaigns`

2.6 活动详情 `GET /pos/ai/v1/campaigns/{id}`