智价云小程序 API 接口设计 V1.0

定稿日期：2026-06-27
与桌面端共用后端 · Base URL 示例：https://api.proprice.kailin.com.cn/v1
关联 PRD：PRD-小程序-V1.0.md

1. 通用约定

1.1 请求头

Header	说明
`Authorization`	`Bearer {access_token}`，除登录/回调外必填
`X-Client`	固定 `mini_program`
`X-Client-Version`	小程序版本号，如 `1.0.0`
`Content-Type`	`application/json`

1.2 响应格式

{
  "code": 0,
  "message": "ok",
  "data": {}
}

code	含义
0	成功
40001	参数错误
40101	未登录 / Token 过期
40301	无权限（如体验用户访问超限历史）
40401	资源不存在
42901	请求过于频繁
50001	服务器错误

1.3 分页

列表接口统一参数：

参数	类型	说明
`page`	int	页码，从 1 开始，默认 1
`page_size`	int	每页条数，默认 20，最大 50

响应 data 结构：

{
  "items": [],
  "total": 100,
  "page": 1,
  "page_size": 20,
  "has_more": true
}

2. 数据实体

2.1 User（扩展）

在 PRD §10 基础上扩展：

字段	类型	说明
`id`	string	用户 ID
`phone`	string	手机号（脱敏返回）
`pharmacy_name`	string	药店名称
`region`	object	`{ province, city, district }`
`license_status`	enum	`pending` / `approved` / `rejected`
`license_reject_reason`	string?	驳回原因
`member_type`	enum	`trial` / `paid` / `expired`
`trial_end_at`	datetime?	体验到期时间
`member_expire_at`	datetime?	会员到期时间
`invite_code`	string	个人邀请码
`wx_openid`	string	微信 openid（内部）
`wx_unionid`	string?	微信 unionid（内部）
`created_at`	datetime	注册时间

2.2 UserGateStatus（聚合，非表）

/users/me 返回的门禁摘要（与主 PRD §3.4 一致，各端共用）：

字段	类型	说明
`can_query_on_desktop`	bool	执照已通过且绑平台 ≥1 时为 true
`license_status`	enum	执照状态
`platform_bound_count`	int	已绑定平台数
`gate_messages`	string[]	待完成事项（引导完成注册/执照/绑平台）

上述门禁仅影响桌面查价等等价能力；不用于裁剪小程序历史/采购接口返回。

2.3 BusinessLicense（新增）

字段	类型	说明
`id`	string	执照记录 ID
`user_id`	string	用户 ID
`image_url`	string	执照图片 URL（私有存储，需签名访问）
`status`	enum	`pending` / `approved` / `rejected`
`reject_reason`	string?	驳回原因
`submitted_at`	datetime	提交时间
`reviewed_at`	datetime?	审核时间
`source_client`	enum	`mini_program` / `windows` / `android`
`reviewer_id`	string?	运营审核人（Admin）

审核通过/驳回由 Admin 操作台调用内部接口，与桌面端上传共用队列。

2.4 QueryLog（扩展）

字段	类型	说明
`id`	string	query_id
`user_id`	string	用户 ID
`keyword`	string	搜索关键词
`queried_at`	datetime	查询时间
`source_client`	enum	`windows` / `android` / `mini_program`
`result_count`	int	命中 SKU 数
`lowest_platform`	string	最低价平台
`lowest_price`	decimal	参考最低价
`snapshot`	QuerySnapshot	完整快照 JSON
`related_intent_ids`	string[]	关联跳转购买 ID

QuerySnapshot 结构：

{
  "items": [
    {
      "platform": "药帮忙",
      "platform_id": "yaobangmang",
      "price": 8.50,
      "spec": "0.25g×24粒",
      "manufacturer": "石药集团",
      "approval_number": "国药准字H13020961",
      "expiry": "2027-06",
      "moq": "10盒",
      "stock_status": "in_stock",
      "is_lowest": true,
      "external_url": "https://..."
    }
  ]
}

2.5 PurchaseIntent（新增）

字段	类型	说明
`id`	string	intent_id
`user_id`	string	用户 ID
`query_id`	string?	关联 QueryLog
`drug_name`	string	药品名称
`spec`	string	规格
`manufacturer`	string?	厂家
`platform`	string	药师帮 / 药帮忙 / 1药城
`platform_id`	string	平台标识
`reference_price`	decimal	跳转时参考价
`clicked_at`	datetime	跳转时间
`source_client`	enum	产生端
`external_url`	string?	跳转 URL（内部存储，小程序不返回）

2.6 ProcurementLedger（V1.1 新增）

字段	类型	说明
`id`	string	ledger_id
`user_id`	string	用户 ID
`intent_id`	string?	关联 PurchaseIntent
`query_id`	string?	关联 QueryLog
`drug_name`	string	药品名称
`spec`	string	规格
`qty`	decimal	数量
`unit_price`	decimal	单价
`total`	decimal	总价
`platform`	string?	平台
`order_note`	string?	备注
`status`	enum	`ordered` / `received`
`created_at`	datetime	录入时间

2.7 Order（扩展）

字段	类型	说明
`id`	string	订单 ID
`order_no`	string	业务订单号
`user_id`	string	用户 ID
`package_type`	enum	`monthly` / `quarterly` / `yearly`
`amount`	decimal	应付金额（元）
`pay_channel`	enum	`wechat_mp` / `wechat_qr` / `alipay`
`source_client`	enum	`mini_program` / `windows` / `android`
`status`	enum	`pending` / `paid` / `failed` / `closed`
`paid_at`	datetime?	支付时间
`member_expire_at`	datetime?	开通后会员到期
`created_at`	datetime	创建时间

2.8 MembershipQuota（聚合）

/users/me 返回配额摘要：

字段	类型	说明
`daily_query_used`	int	桌面今日已用查询次数
`daily_query_limit`	int	桌面每日上限（体验 20，会员 -1 表示不限）
`watchlist_used`	int	本月已关注品种数
`watchlist_limit`	int	关注上限

小程序历史/采购参考无 history_visible_* 配额字段；列表接口不对体验用户做裁剪。

3. 认证接口

3.1 小程序登录

POST /auth/mp/login

请求：

{
  "code": "wx.login 返回的 code",
  "phone_code": "getPhoneNumber 返回的 code"
}

响应 data：

{
  "access_token": "eyJ...",
  "expires_in": 7200,
  "refresh_token": "rf_...",
  "is_registered": true,
  "user": { /* User 摘要，is_registered=true 时返回 */ }
}

场景	行为
手机号已注册	绑定/更新 `wx_openid`，返回 token + user
手机号未注册	`is_registered: false`，前端跳转 `mp-register`

3.2 新用户注册

POST /auth/register

{
  "invite_code": "PX8K2M",
  "pharmacy_name": "康宁大药房",
  "region": {
    "province": "广东省",
    "city": "广州市",
    "district": "天河区"
  }
}

需已登录（微信授权 + 手机号已绑定）。成功后创建 User，license_status: null（未上传），返回更新后的 user。

3.3 刷新 Token

POST /auth/refresh

{ "refresh_token": "rf_..." }

3.4 退出登录

POST /auth/logout

清除服务端 session（可选）；小程序端清除本地 token。

4. 用户接口

4.1 获取当前用户

GET /users/me

响应 data：

{
  "user": { /* User */ },
  "gate": { /* UserGateStatus */ },
  "quota": { /* MembershipQuota */ },
  "platform_bindings": [
    {
      "platform_id": "yaobangmang",
      "platform_name": "药帮忙",
      "status": "bound",
      "last_validated_at": "2026-06-27T10:00:00Z"
    }
  ]
}

不返回平台账号密码。

4.2 首页概览统计

GET /users/me/dashboard

响应 data：

{
  "today_query_count": 8,
  "today_purchase_intent_count": 3,
  "total_query_count": 156,
  "recent_queries": [ /* QueryLog 摘要，最多 3 条 */ ]
}

5. 营业执照接口

5.1 获取执照状态

GET /licenses/current

响应 data：

{
  "status": "pending",
  "reject_reason": null,
  "submitted_at": "2026-06-27T15:30:00Z",
  "reviewed_at": null,
  "image_url": "https://...signed...",
  "source_client": "mini_program"
}

status	说明
`null` / 404	未上传，前端跳转 `mp-license-upload`
`pending`	审核中
`approved`	已通过
`rejected`	已驳回，含 `reject_reason`

5.2 上传营业执照

POST /licenses/upload

Content-Type: multipart/form-data

字段	类型	说明
`file`	file	JPG/PNG，≤ 5MB

响应 data：

{
  "id": "lic_abc",
  "status": "pending",
  "submitted_at": "2026-06-27T15:30:00Z"
}

行为：

新上传或驳回后重传：创建新记录或更新，status → pending
同步更新 User.license_status → pending
审核中不可重复提交（返回 40903）

5.3 获取执照图片（签名 URL）

GET /licenses/current/image-url

返回短期有效的 signed URL，供小程序预览已提交执照。

6. 平台绑定接口

与桌面端共用 PlatformBinding 实体；任一端绑定/解绑，各端同步。

6.1 平台列表

GET /platform-bindings

响应 data.items[]：

{
  "platform_id": "yaobangmang",
  "platform_name": "药帮忙",
  "status": "bound",
  "account_masked": "138****5678",
  "last_validated_at": "2026-06-27T10:00:00Z"
}

未绑定的平台也返回，status: "unbound"。

6.2 绑定平台

POST /platform-bindings

{
  "platform_id": "yaobangmang",
  "account": "user@example.com",
  "password": "******",
  "source_client": "mini_program"
}

密码加密传输，服务端加密存储；响应不含明文密码。

6.3 解绑平台

DELETE /platform-bindings/{platform_id}

至少保留 0 个绑定；若解绑后导致 can_query_on_desktop=false，与主 PRD 一致。

6.4 验证绑定

POST /platform-bindings/{platform_id}/validate

触发凭证有效性校验，更新 last_validated_at。

7. 查询历史接口

7.1 查询历史列表

GET /queries

参数	类型	说明
`keyword`	string?	关键词搜索
`days`	int?	可选时间筛选：7 / 30 / 90（用户主动筛选，非会员限制）
`source_client`	string?	来源端筛选

响应 data.items[] 摘要字段：

{
  "id": "q_abc123",
  "keyword": "阿莫西林胶囊",
  "queried_at": "2026-06-27T14:32:00Z",
  "source_client": "windows",
  "result_count": 3,
  "lowest_platform": "药帮忙",
  "lowest_price": 8.50
}

不做会员级裁剪：体验用户与付费会员返回相同全量数据（分页仍按 page / page_size）。

7.2 查询快照详情

GET /queries/{id}

响应 data：完整 QueryLog + snapshot + related_intents[]

8. 采购参考接口

8.1 跳转购买记录列表

GET /purchase-intents

参数	类型	说明
`keyword`	string?	药品名搜索
`platform_id`	string?	平台筛选
`days`	int?	可选时间筛选（用户主动筛选，非会员限制）

不做会员级裁剪：体验用户与付费会员返回相同全量数据。

响应 data.items[]：

{
  "id": "pi_xyz789",
  "query_id": "q_abc123",
  "drug_name": "阿莫西林胶囊",
  "spec": "0.25g×24粒",
  "manufacturer": "石药集团",
  "platform": "药帮忙",
  "platform_id": "yaobangmang",
  "reference_price": 8.50,
  "clicked_at": "2026-06-27T14:35:00Z",
  "source_client": "windows"
}

8.2 跳转购买详情

GET /purchase-intents/{id}

含关联 query_summary（若有 query_id）。

8.3 写入跳转记录（桌面/Android 调用，小程序只读）

POST /purchase-intents

小程序 MVP 不暴露此接口；由 Windows/Android 在点击「去购买」时调用。

{
  "query_id": "q_abc123",
  "drug_name": "阿莫西林胶囊",
  "spec": "0.25g×24粒",
  "manufacturer": "石药集团",
  "platform_id": "yaobangmang",
  "reference_price": 8.50,
  "source_client": "windows",
  "external_url": "https://..."
}

8.4 写入查询快照（桌面/Android 调用）

POST /queries

小程序 MVP 不暴露写接口。

{
  "keyword": "阿莫西林胶囊",
  "source_client": "windows",
  "result_count": 3,
  "lowest_platform": "药帮忙",
  "lowest_price": 8.50,
  "snapshot": { "items": [ /* ... */ ] }
}

8. 手动采购台账（V1.1）

8.1 列表

GET /procurement-ledgers

仅付费会员可用；体验用户返回 40301。

8.2 创建

POST /procurement-ledgers

{
  "intent_id": "pi_xyz789",
  "query_id": "q_abc123",
  "drug_name": "阿莫西林胶囊",
  "spec": "0.25g×24粒",
  "qty": 10,
  "unit_price": 8.50,
  "total": 85.00,
  "platform": "药帮忙",
  "order_note": "6月补货",
  "status": "ordered"
}

8.3 更新 / 删除

PATCH /procurement-ledgers/{id}
DELETE /procurement-ledgers/{id}

9. 会员与支付接口

9.1 获取套餐列表

GET /membership/plans

响应 data.plans[]：

{
  "package_type": "yearly",
  "name": "年卡会员",
  "price": 899.00,
  "original_price": 999.00,
  "duration_days": 365,
  "badge": "最划算",
  "features": ["不限查询", "1999关注/月"]
}

9.2 创建会员订单

POST /membership/orders

{
  "package_type": "yearly",
  "source_client": "mini_program"
}

响应 data：

{
  "order_id": "ord_123",
  "order_no": "202606271430001",
  "amount": 899.00,
  "status": "pending",
  "wechat_pay": {
    "timeStamp": "1719492600",
    "nonceStr": "abc123",
    "package": "prepay_id=wx...",
    "signType": "RSA",
    "paySign": "..."
  }
}

小程序调用 wx.requestPayment(wechat_pay)。

9.3 查询订单状态

GET /membership/orders/{order_no}

用于支付后轮询：

{
  "order_no": "202606271430001",
  "status": "paid",
  "paid_at": "2026-06-27T14:30:05Z",
  "member_expire_at": "2027-06-27T14:30:05Z"
}

9.4 微信支付回调

POST /payments/wechat/notify

微信服务器回调，验签后更新 Order 状态及 User 会员字段。不对小程序暴露。

10. 邀请与体验券

10.1 邀请统计

GET /invites/stats

{
  "invite_code": "PX8K2M",
  "invited_count": 5,
  "activated_count": 3,
  "total_reward_days": 21,
  "records": [
    {
      "invitee_phone_masked": "138****1234",
      "status": "activated",
      "reward_days": 7,
      "activated_at": "2026-06-20T10:00:00Z"
    }
  ]
}

10.2 体验券核销

POST /coupons/redeem

{ "code": "TRIAL-ABCD-1234" }

成功响应：

{
  "days_added": 15,
  "trial_end_at": "2026-07-12T00:00:00Z",
  "member_type": "trial"
}

11. 内容与配置

11.1 帮助与 FAQ

GET /content/help

返回 FAQ 列表、合规文案、桌面下载链接。

11.2 桌面下载链接

GET /content/download

{
  "windows_url": "https://proprice.kailin.com.cn/download/windows",
  "official_site_url": "https://proprice.kailin.com.cn",
  "mini_program_appid": "wx...",
  "version": "1.0.0",
  "release_notes": "..."
}

12. 错误码补充

code	message 示例	场景
40302	~~体验用户历史记录超出可见范围~~	已废弃：历史不做会员裁剪
40303	请升级会员后使用采购台账	V1.1 台账
40304	~~请先上传营业执照~~	已废弃：小程序历史/采购不因执照状态拦截
40402	用户未注册	登录后业务接口
40901	体验券已使用或无效	核销失败
40902	订单已支付或已关闭	重复支付
40903	营业执照审核中，请勿重复提交	重复上传
41301	图片超过 5MB 或格式不支持	执照上传

13. 接口清单汇总

方法	路径	调用端	MVP
POST	`/auth/mp/login`	小程序	✓
POST	`/auth/register`	小程序	✓
POST	`/auth/refresh`	小程序	✓
GET	`/users/me`	小程序	✓
GET	`/users/me/dashboard`	小程序	✓
GET	`/licenses/current`	小程序	✓
POST	`/licenses/upload`	小程序	✓
GET	`/licenses/current/image-url`	小程序	✓
GET	`/platform-bindings`	小程序	✓
POST	`/platform-bindings`	小程序	✓
DELETE	`/platform-bindings/{platform_id}`	小程序	✓
POST	`/platform-bindings/{platform_id}/validate`	小程序	✓
GET	`/queries`	小程序	✓
GET	`/queries/{id}`	小程序	✓
POST	`/queries`	桌面/Android	✓
GET	`/purchase-intents`	小程序	✓
GET	`/purchase-intents/{id}`	小程序	✓
POST	`/purchase-intents`	桌面/Android	✓
GET	`/membership/plans`	小程序	✓
POST	`/membership/orders`	小程序	✓
GET	`/membership/orders/{order_no}`	小程序	✓
POST	`/payments/wechat/notify`	微信服务器	✓
GET	`/invites/stats`	小程序	✓
POST	`/coupons/redeem`	小程序	✓
GET	`/content/help`	小程序	✓
GET	`/content/download`	小程序	✓
GET	`/procurement-ledgers`	小程序	V1.1
POST	`/procurement-ledgers`	小程序	V1.1

14. 数据库变更建议

-- User 扩展
ALTER TABLE users ADD COLUMN wx_openid VARCHAR(64) NULL;
ALTER TABLE users ADD COLUMN wx_unionid VARCHAR(64) NULL;
CREATE UNIQUE INDEX idx_users_wx_openid ON users(wx_openid);

-- BusinessLicense 新表
CREATE TABLE business_licenses (
  id VARCHAR(32) PRIMARY KEY,
  user_id VARCHAR(32) NOT NULL,
  image_url TEXT NOT NULL,
  status VARCHAR(16) NOT NULL DEFAULT 'pending',
  reject_reason TEXT NULL,
  submitted_at TIMESTAMP NOT NULL,
  reviewed_at TIMESTAMP NULL,
  source_client VARCHAR(32) NOT NULL,
  reviewer_id VARCHAR(32) NULL,
  INDEX idx_bl_user_status (user_id, status),
  INDEX idx_bl_pending (status, submitted_at)
);

-- QueryLog 扩展
ALTER TABLE query_logs ADD COLUMN source_client VARCHAR(32) NOT NULL DEFAULT 'windows';
ALTER TABLE query_logs ADD COLUMN result_count INT NOT NULL DEFAULT 0;
ALTER TABLE query_logs ADD COLUMN lowest_platform VARCHAR(32) NULL;
ALTER TABLE query_logs ADD COLUMN lowest_price DECIMAL(10,2) NULL;
ALTER TABLE query_logs ADD COLUMN snapshot JSON NOT NULL;

-- PurchaseIntent 新表
CREATE TABLE purchase_intents (
  id VARCHAR(32) PRIMARY KEY,
  user_id VARCHAR(32) NOT NULL,
  query_id VARCHAR(32) NULL,
  drug_name VARCHAR(128) NOT NULL,
  spec VARCHAR(64) NOT NULL,
  manufacturer VARCHAR(128) NULL,
  platform_id VARCHAR(32) NOT NULL,
  reference_price DECIMAL(10,2) NOT NULL,
  clicked_at TIMESTAMP NOT NULL,
  source_client VARCHAR(32) NOT NULL,
  external_url TEXT NULL,
  INDEX idx_pi_user_clicked (user_id, clicked_at DESC),
  INDEX idx_pi_query (query_id)
);

-- Order 扩展
ALTER TABLE orders ADD COLUMN source_client VARCHAR(32) NOT NULL DEFAULT 'windows';

API-小程序.md 19 KB 고유링크 히스토리 Raw

智价云小程序 API 接口设计 V1.0

1. 通用约定

1.1 请求头

1.2 响应格式

1.3 分页

2. 数据实体

2.1 User（扩展）

2.2 UserGateStatus（聚合，非表）

2.3 BusinessLicense（新增）

2.4 QueryLog（扩展）

2.5 PurchaseIntent（新增）

2.6 ProcurementLedger（V1.1 新增）

2.7 Order（扩展）

2.8 MembershipQuota（聚合）

3. 认证接口

3.1 小程序登录

3.2 新用户注册

3.3 刷新 Token

3.4 退出登录

4. 用户接口

4.1 获取当前用户

4.2 首页概览统计

5. 营业执照接口

5.1 获取执照状态

5.2 上传营业执照

5.3 获取执照图片（签名 URL）

6. 平台绑定接口

6.1 平台列表

6.2 绑定平台

6.3 解绑平台

6.4 验证绑定

7. 查询历史接口

7.1 查询历史列表

7.2 查询快照详情

8. 采购参考接口

8.1 跳转购买记录列表

8.2 跳转购买详情

8.3 写入跳转记录（桌面/Android 调用，小程序只读）

8.4 写入查询快照（桌面/Android 调用）

8. 手动采购台账（V1.1）

8.1 列表

8.2 创建

8.3 更新 / 删除

9. 会员与支付接口

9.1 获取套餐列表

9.2 创建会员订单

9.3 查询订单状态

9.4 微信支付回调

10. 邀请与体验券

10.1 邀请统计

10.2 体验券核销

11. 内容与配置

11.1 帮助与 FAQ

11.2 桌面下载链接

12. 错误码补充

13. 接口清单汇总

14. 数据库变更建议

API-小程序.md 19 KB

고유링크 히스토리 Raw