宠医 App 接口文档

一、通用约定

错误码一览

共 37 个。客户端按 code 分支，不要把 message 当条件—— 文案会随版本调整，code 不会。

场景	code	HTTP	含义
认证与会话	TOKEN_MISSING	401	没有携带 Bearer 令牌
	TOKEN_INVALID	401	令牌无效、已撤销或已过期，需要重新登录
	INVALID_CREDENTIALS	401	账号或密码不正确
	ACCOUNT_DISABLED	403	账号已被停用（App 端表现为不可用，需联系管理员）
	IDENTIFIER_TAKEN	409	注册时手机号或邮箱已存在
权限与角色	FORBIDDEN	403	资源不属于当前账号（例如操作别人店铺的商品、删别人的记录）
	MERCHANT_ONLY	403	账号角色不是 merchant，App 只给买家视角
	MERCHANT_NOT_APPLIED	403	还没有提交商户入驻申请
	MERCHANT_NOT_APPROVED	403	入驻仍在审核或未通过，details 带 status 与 auditNote
	ALREADY_MERCHANT	409	当前账号已经是入驻商户，无需重复申请
	APPLICATION_PENDING	409	已有一份在审或已通过的入驻申请
资源不存在	NOT_FOUND	404	资源不存在或已删除
	PRODUCT_NOT_FOUND	404	商品不存在或已下架
	ANIMAL_NOT_FOUND	404	找不到该动物档案（不属于当前账号也算）
	SYMPTOM_NOT_FOUND	404	症状 key 不在目录里，需重新拉 /symptoms
	POST_NOT_FOUND	404	动态不存在或已删除
	UNKNOWN_RECORD_TYPE	404	通用删除的 key 不在白名单内
问诊流程	NO_SYMPTOM	422	一句话描述与症状都没给（或给的 key 都不在目录里），details.allowed 是可用 key
	STEP_FINISHED	409	结构化问题已答完，下一步应提交 redFlag
	INVALID_OPTION	422	回答不在问题给出的 options 里，details.options 是可选值
	CONSULT_FINISHED	422	本次问诊已结束，补充信息要走 /refine
	NOT_DONE	409	还没出报告，不能补充信息
	REPORT_NOT_READY	409	还没有生成报告，无法写入病例档案
	NOT_INTERVIEW	409	当前不是追问阶段，不需要回答追问
	NO_PENDING_QUESTION	409	当前没有待回答的追问
	NOT_CLARIFY	409	当前不在澄清阶段，应按 state 继续
	ANIMAL_REQUIRED	422	这次问诊没有关联动物档案，无法归档
商城与购物车	MEDICATION_CHECK_REQUIRED	409	处方 / 需核对的兽药不能直接加入购物车，先走 /medications/check
	OUT_OF_STOCK	409	该商品暂时缺货
	PRODUCT_UNAVAILABLE	409	商品当前不可购买（下架、审核中或被驳回）
	CART_EMPTY	422	购物车是空的，不能结算
状态机与业务冲突	INVALID_TRANSITION	409	状态机不允许的流转（未发货就签收、出售中直接删除、有售后未处理时再提售后）
	SELF_APPLICATION	422	不能申请自己发布的送养信息
	IMAGE_IN_USE	409	图片已被商品引用，不能直接删除
上传	UPLOAD_FAILED	422	图片保存失败（超过 2MB、格式不支持或磁盘错误）
	PHOTO_STORE_FAILED	422	动物档案照片保存失败
通用	VALIDATION_FAILED	422	字段校验未通过，details 内含字段级错误

二、角色与 App 界面分流

网站有五种账号角色，但 App 只承载其中两种工作界面。登录后先用 GET /users/me 的 appShell 决定落地界面，再用 capabilities 决定「我的」页面显示什么入口。

角色	App 界面	说明
guest	访客	可浏览公开内容、症状目录、商品、公开领养与医院、静态危险信号；发起问诊、下单、发布信息时再引导登录。
user	买家视角	网站全部顾客侧功能：问诊、方案、商城、档案、健康监测、救助领养、寄养、日程、寻宠、互助、检查、医院、核验、费用、疗效、共同照护、困难支持、通知。
merchant	商户工作台	底部导航换成「经营 / 商品 / 订单 / 售后 / 货款」，同时保留「切到买家视角」；买家侧数据与普通用户完全相同。
reviewer	无	审核工作台（/review）是平台内部运营工具，只在 Web 端提供。App 登录后提示「请使用 Web 端」。
admin	无	后台管理（/admin）含角色、配置、症状题库、提现打款等高风险操作，只在 Web 端提供。

商户入驻路径：POST /merchant-applications → 平台在 Web 端审核 → 通过后账号角色升级为 merchant 并绑定 merchant_id → 重新登录后 appShell 变成 merchant。不需要重新注册，买家数据（问诊、订单、档案）全部保留。

三、快速开始

1. 注册并拿到令牌

curl -X POST https://www.chongyi.org/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"nickname":"小护","identifier":"[email protected]","password":"your-password"}'

{
  "data": {
    "accessToken": "chongyi_9f2c...",
    "tokenType": "Bearer",
    "expiresAt": "2026-11-27T08:39:38+00:00",
    "user": {
      "id": 2, "nickname": "小护", "role": "user", "roleLabel": "普通用户",
      "appShell": "user",
      "capabilities": {"isMerchant": false, "canEnterConsole": false, "canReview": false, "isAdmin": false, "webOnly": false},
      "merchant": null
    }
  }
}

2. 建立动物档案

curl -X POST https://www.chongyi.org/api/v1/animals \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"团团","species":"猫","age":"2岁","weightKg":4.1,"sex":"公"}'

3. 走完一次问诊

# ① 拉症状目录（App 的症状多选面板与「本题库共几题」）
GET https://www.chongyi.org/api/v1/symptoms?species=cat

# ② 开始：一句话描述 + 勾选的症状，服务端合并成同一份事实
#    （旧协议仍可用：{"category":"cat_gi01"} 只在没有 symptomText / symptoms 时生效）
POST https://www.chongyi.org/api/v1/consultations   {"symptomText":"三天前开始呕吐，今天没吃东西","symptoms":["cat_gi01"]}

# ③ 逐题回答结构化关键问题，options 来自返回的 question.options
POST https://www.chongyi.org/api/v1/consultations/12/answers   {"value":"有，明显干呕"}

# ④ 答完后提交危险信号（可多选），进入模型追问
POST https://www.chongyi.org/api/v1/consultations/12/complete  {"redFlags":[]}

# ⑤ 若返回的 interview 不为空：继续回答追问，直到返回报告
POST https://www.chongyi.org/api/v1/consultations/12/interviews   {"value":"6小时内1次"}

# ⑥ 报告出来后写入病例档案
POST https://www.chongyi.org/api/v1/consultations/12/save-record

问诊深度和 Web 完全一致：结构化关键问题（3—4 题）+ 模型按问答库挑的追问， 正常病例合计 8—16 题。每次 state 里的 questionsAsked / questionsTotal 可以用来显示「已问 N 题 / 本题库 M 题」； interview 为空且 reportReady=true 时，报告已经生成。

4. 报告结构（结论先行，不可为 null）

{
  "data": {
    "id": 207,
    "triageLevel": "NEEDS_EXAM",
    "triage": {
      "level": "NEEDS_EXAM",
      "rule_level": "NEEDS_EXAM",
      "ai_level": "HOME_OBSERVATION",
      "overridden": true,          // 模型判轻、规则判重 → 服务端上调
      "reason_codes": ["VOMIT_REPEAT"],
      "unknowns": ["…"]
    },
    "decision": {
      "level": "today",   // home / today / now
      "headline": "先按胃肠刺激处理，24 小时内复评",
      "reason": "…",
      "recheck_at": "24 小时内",
      "hospital": {"level": "…", "reason": "…"}
    },
    "diagnosis": {
      "primary": {
        "name": "进食过快 / 食物不耐受",
        "confidence": "medium",
        "mechanism": "进食过快导致胃部过度扩张…",
        "goal": "48 小时内不再加重",
        "plan": [{"label": "现在", "text": "少量多餐"}, {"label": "24—48 小时内", "text": "逐步恢复正常饮食"}],
        "evidence": [{"why": "呕吐与进食即刻相关", "answer": "进食即刻"}],
        "against": [{"why": "无毛球相关问题", "answer": "…"}],
        "confirm": "观察呕吐频率和内容变化",
        "urgency": "home"
      },
      "confidence": "medium",
      "headline": "…",
      "ranked": ["…"],
      "alternatives": ["…"],
      "tests": ["…"],
      "coverage": ["每条事实都被解释"],
      "red_flags": ["持续呕吐"],
      "confidence_reason": "…"
    },
    "immediate_care": {"do": ["…"], "avoid": ["…"]},
    "medication_review": {
      "status": "NOT_NEEDED",       // NEEDED / NOT_NEEDED
      "headline": "不用止吐药，先调整饮食",
      "rationale": "…",
      "drugs": [{"name": "…", "dose": "按体重换算", "route": "…", "frequency": "…", "duration": "…", "rx": false}],
      "items": ["小碗"],
      "when": "如持续呕吐再考虑",
      "avoid": ["人用药物"]
    },
    "assessment": {"summary": "…", "evidence": ["…"], "uncertainty": "…", "level_note": "…"},
    "monitoring": {"observe": ["饮水与进食"], "recheck_at": "24 小时", "escalate_if": ["持续呕吐"]},
    "treatment": {"goal": "…", "review": ["…"], "confirm": ["…"]},
    "differential": [{"condition": "…", "for": ["…"], "against": ["…"]}],
    "relations": {"type": "single", "coexisting": [], "unexplained": [], "evidence_level": "…"},
    "recommended_exams": [],
    "hospital_assistance": {"show": false, "reason": null},
    "clinic_only": ["需要静脉输液：…（这一项线上做不到）"],
    "meta": {
      "knowledge_version": "…", "rules_version": "…", "model_version": "…",
      "questions_asked": 9, "interview_rounds": 2, "revision_of": null,
      "ai": {"source": "llm", "model": "宠医模型 V3", "escalated": true}
    }
  }
}

平台不做机构推荐：报告里不会出现「建议就诊 / 推荐医院」这类出口， 线上做不到的操作（输液、导尿、影像、化验、手术）统一放在 clinic_only， 客户端把它渲染在处置段末尾，说明「哪几项线上做不到、为什么」。 分级只升不降——模型判轻而规则判重时，服务端会把结论改回重的那一级并置 triage.overridden=true。

5. 商户工作台（appShell = merchant）

# 首屏：待办 + 商品分布 + 钱包摘要
GET https://www.chongyi.org/api/v1/merchant/overview

# 发布商品（action=draft 存草稿；不带就是直接送审）
POST https://www.chongyi.org/api/v1/merchant/products
{"name":"术后康复护具","category":"护理器具","spec":"S/M/L","price":45,"stock":30,"shipFee":6,"action":"draft"}

# 上架（仓库中直接上架；草稿 / 被驳回转为待审核）
POST https://www.chongyi.org/api/v1/merchant/products/11/status   {"action":"online"}

# 发货
POST https://www.chongyi.org/api/v1/merchant/orders/CHONGYI-607FA5E8/ship
{"expressCompany":"顺丰速运","expressNo":"SF123456789"}

# 处理售后
POST https://www.chongyi.org/api/v1/merchant/aftersales/1/handle   {"decision":"approve","note":"外包装破损，同意部分退款"}

# 提现
POST https://www.chongyi.org/api/v1/merchant/wallet/withdraw
{"amount":40,"bankName":"招商银行","accountName":"周店主","cardNo":"6225 8800 1234 5678"}

四、App 版本与升级

App 启动时先打一次 GET /app/version：用户可能还没登录、甚至连接口目录都还拉不动， 也必须能问到「我是不是该升级了」，所以它是公开端点。客户端不要自己比版本号， 服务端已经把结论算好（updateAvailable / forceUpdate / supported），照着执行即可。

阈值全部存在 settings 表的 group='app' 分组，后台「站点设置」改完即时生效， 不需要发版。forceBelow 留空或为 0 表示不启用强制升级；latest 误填成低于 minimum 时， 服务端自动按 minimum 处理，避免要求客户端「升级到一个比现在还旧的版本」。

GET https://www.chongyi.org/api/v1/app/version?platform=android&version=1.0.1&code=1

{
  "data": {
    "platform": "android",
    "current":   {"version": "1.0.1", "code": 1},
    "latest":    {"version": "1.1.0", "code": 2},
    "minimum":   {"version": "1.0.1", "code": 1},
    "forceBelow": {"version": "", "code": 0},
    "downloadUrl": "https://www.chongyi.org/download/",       // 落地页，浏览器打开
    "apkUrl": "",                                // 安装包直链，有值才走内置下载
    "apkSha256": "", "apkBytes": 0,              // 完整性校验与进度条总量，0 / 空表示未知
    "updateTitle": "发现新版本 1.1.0",
    "updateNotes": ["统一品牌视觉与口号。"],
    "updateAvailable": true, "forceUpdate": false, "supported": true,
    "message": "发现新版本 1.1.0，建议更新。",
    "checkedAt": "2026-11-01T12:00:00+00:00"
  }
}

platform 只接受 android / ios，未知值按 android 处理： 宁可按安卓给结果，也不要让老客户端在升级这一步收到错误。

五、端点清单

认证与会话 · 6 个

方法	路径	用途	权限	说明
POST	/auth/register	注册并签发访问令牌	公开	nickname 2—24 位；identifier 为手机号或邮箱；password 需含字母与数字；默认角色 user
POST	/auth/login	登录并签发访问令牌	公开	返回 accessToken（默认 30 天）与 user.appShell，App 据此决定进买家界面还是商户界面
POST	/auth/refresh	轮换令牌（旧的立即失效）	令牌	临近过期前续期，避免长期令牌被复制后一直可用
POST	/auth/logout	撤销当前令牌	令牌	服务端删除摘要即生效
GET	/users/me	账号资料 + 角色能力 + 动物列表	令牌	含 role / roleLabel / appShell / capabilities / merchant / unreadNotifications
PATCH	/users/me	修改昵称与低打扰模式	令牌	criticalOnly=true 仅接收关键通知

App 版本与升级 · 1 个

方法	路径	用途	权限	说明
GET	/app/version	App 版本校验（最新 / 最低可用 / 强制升级基线）	公开	启动时调用一次；返回 updateAvailable / forceUpdate / supported 三个结论，客户端只照着执行，不自己比版本

元数据与公开内容 · 7 个

方法	路径	用途	权限	说明
GET	/meta	版本、症状分类、导航、商户枚举	公开	客户端启动调用一次并缓存；appNav 已剔除审核与后台入口
GET	/public/emergency-guide	静态危险信号与禁止事项	公开	不做任何 AI 调用，访客可用
GET	/public/adoptions	公开待领养列表	公开	只含城市 / 片区，无电话与详细地址
GET	/public/hospitals	已审核合作医院	公开	未通过审核的机构不会出现
GET	/search	服务 + 商品 + 领养联合搜索	公开	q 为空时返回全部服务入口
GET	/symptoms	症状目录（按物种 + 系统分组）	公开	支持 q 搜索与 group 过滤；meta.questionTotal 即「本题库共几题」
GET	/symptoms/{key}	单个症状的完整题库与处置知识	公开	key 形如 cat_gi01 / dog_ur01；含追问脚本、危险信号、clinic_only

动物档案与健康记录 · 13 个

方法	路径	用途	权限	说明
GET	/animals	我的动物档案	令牌	含 isCurrent 标识，同一账号仅一个当前档案
POST	/animals	新建动物档案	令牌	weightKg 允许为空（未知）
GET	/animals/{id}	单个档案 + 记录计数	令牌	资源级授权
PATCH	/animals/{id}	修改档案	令牌	只提交需要变更的字段
DELETE	/animals/{id}	归档档案	令牌	连带清理病例档案与照片，历史问诊保留
POST	/animals/{id}/select	设为当前动物	令牌	问诊与观察默认挂到当前动物
POST	/animals/{id}/photo	上传档案照片	令牌	multipart，单张 ≤2MB
GET	/animals/{id}/observations	观察记录（游标分页）	令牌	对应网站「健康监测」
POST	/animals/{id}/observations	记录一次观察	令牌	category + detail；含水、食、精神、排尿等
GET	/animals/{id}/timeline	观察与问诊合并时间线	令牌	按时间倒序
GET	/animals/{id}/records	病例档案列表	令牌	一问诊一份，重新判断时覆盖同一份
DELETE	/medical-records/{record}	删除一份病例档案	令牌	只删档案，不删问诊会话
DELETE	/records/{key}/{id}	通用删除（观察 / 任务 / 寄养 / 台账 …）	令牌	key 白名单；只能删本人记录；App 端删除是终态的（Web 才有一步撤销）

免费问诊 · 13 个

方法	路径	用途	权限	说明
GET	/consultations	我的问诊会话列表	令牌	游标分页
POST	/consultations	创建问诊会话	令牌	症状来源三选一也可叠加：symptomText（≤600 字自然语言）/ symptoms[] / category（旧协议，仅前两者为空时生效）；都没有返回 422 NO_SYMPTOM
GET	/consultations/{id}	当前步骤 / 待答问题 / 追问	令牌	断点续答靠这个接口，state 里有 questionsAsked / questionsTotal
POST	/consultations/{id}/answers	回答当前结构化问题	令牌	value 必须在 options 内
POST	/consultations/{id}/back	回到上一步	令牌	第一步时删除草稿
POST	/consultations/{id}/complete	提交危险信号并生成报告	令牌	redFlags 可多选；非空即进入高危分支
POST	/consultations/{id}/interviews	回答模型追问（找病因）	令牌	一轮 1—3 题；返回 interview 为空表示追问结束
POST	/consultations/{id}/clarifications	对话式澄清（危险信号之后）	令牌	不参与分级，只影响报告里「更倾向哪条病因」的标注
POST	/consultations/{id}/messages	自由描述补充	令牌	只做补充与危险信号兜底，不替代选项
POST	/consultations/{id}/refine	补充信息后重新判断	令牌	生成新一版报告，旧报告保留（meta.revision_of）
POST	/consultations/{id}/discard	退出本次问诊	令牌	草稿直接丢弃；已出报告的只退出不删档
POST	/consultations/{id}/save-record	把本次结论写入病例档案	令牌	一问诊一份，重复调用覆盖
GET	/consultations/{id}/report	读取已生成的报告	令牌	结论先行五段；clinic_only 为线上做不到的操作

用药安全 · 3 个

方法	路径	用途	权限	说明
POST	/medications/check	药物适用性核对	令牌	返回 status 与 cautions；不返回剂量
GET	/medications/reviews	我的用药核对记录	令牌	对应网站「购药商城 › 用药核对」
GET	/drugs/search	按名称 / 通用名 / 规格搜索药品	公开	含 prescription 标记，处方药不能直接下单

商城与订单 · 15 个

方法	路径	用途	权限	说明
GET	/products	商品列表	公开	q / category / merchant / sort；只返回出售中的商品
GET	/products/{code}	商品详情	公开	code 为稳定业务编码，不是自增 ID
GET	/cart/summary	购物车件数	可选令牌	未登录返回 0，登录后返回角标数据
GET	/cart	购物车内容（按商户分组）	令牌	金额由服务端重算，不信任客户端
POST	/cart/items	加入购物车	令牌	规范字段是 code（productCode 为兼容别名）；处方商品返回 409 MEDICATION_CHECK_REQUIRED
PATCH	/cart/items/{productId}	修改数量	令牌	qty=0 等于移除
DELETE	/cart/items/{productId}	移除商品	令牌
DELETE	/cart	清空购物车	令牌
GET	/orders	我的订单	令牌	游标分页；一次结算按商户拆成多笔子订单
POST	/orders	创建订单	令牌	支持 Idempotency-Key；事务内扣库存，任一缺货整体回滚
GET	/orders/{code}	订单详情	令牌	含 items、timeline 与 actions 布尔块
POST	/orders/{code}/pay	模拟支付	令牌	演示环境不真实扣款；成功后进入托管待结算
POST	/orders/{code}/confirm	确认收货	令牌	售后期满后货款结算给商户
POST	/orders/{code}/aftersale	申请售后	令牌	type=refund|return|complaint；有未关闭售后时不能再提
GET	/aftersales	我的售后记录	令牌	含处理结果与商户回复

救助领养 · 6 个

方法	路径	用途	权限	说明
GET	/adoptions	我发布的送养信息	令牌	含申请数量与状态
POST	/adoptions	发布送养信息	令牌	holderPhone / holderAddress 受保护，不进入公开列表
GET	/adoptions/{id}	送养详情	令牌	仅发布者或已通过审核的申请人可见联系方式
POST	/adoptions/{id}/apply	提交领养申请	令牌	状态从「待人工审核」开始，不能自我通过
GET	/adoption-applications	我提交或待我处理的申请	令牌	canReview 标识处理权限
POST	/adoption-applications/{id}/review	审核 / 交接	令牌	decision=approve|reject|handover

爱心寄养 · 4 个

方法	路径	用途	权限	说明
GET	/fosters/offers	我登记的寄养位	令牌	含物种、天数、隔离条件
POST	/fosters/offers	登记寄养位	令牌	species / days / isolate
GET	/fosters/requests	我的寄养需求	令牌
POST	/fosters/requests	创建寄养需求	令牌	健康状态与隔离需求必须写清楚

医院与检查 · 5 个

方法	路径	用途	权限	说明
GET	/hospitals/nearby	附近已审核医院	令牌	无结果时返回 mapFallback 提示，不阻断急诊
GET	/hospital/applications	我提交的机构入驻申请	令牌	含审核状态与驳回原因
POST	/hospital/applications	医院申请入驻	令牌	进入人工审核，未通过不会出现在合作名录
GET	/exams/bookings	我的检查申请	令牌	对应网站「低价检查」
POST	/exams/bookings	提交检查申请	令牌	急症不得等待未来名额

照护日程与协作 · 8 个

方法	路径	用途	权限	说明
GET	/tasks	照护任务	令牌	todo / progress / done
POST	/tasks	新建任务	令牌	可指定 animalId
PATCH	/tasks/{id}	修改任务状态 / 标题	令牌
DELETE	/tasks/{id}	删除任务	令牌
GET	/team/tasks	共同照护任务	令牌	对应网站「共同照护」
POST	/team/tasks	新增协作任务	令牌	person + task + animalLabel
GET	/supplies	物资台账	令牌
POST	/supplies	登记物资去向	令牌	item + count + usage

社区与台账 · 13 个

方法	路径	用途	权限	说明
GET	/lost-reports	寻宠记录	令牌
POST	/lost-reports	发布寻宠信息	令牌	只写区域，不写门牌
POST	/lost-reports/{id}/found	标记已找回	令牌
GET	/aid-requests	公益互助需求	令牌	对应网站「公益互助」
POST	/aid-requests	发布互助需求	令牌	kind 见表单定义；不代收款项
GET	/support-requests	困难支持记录	令牌	不需要身份材料
POST	/support-requests	匿名求助	令牌	只填城区，可留空联系方式
GET	/quotes	费用报价记录	令牌	对应网站「费用透明」
POST	/quotes	添加报价	令牌	provider + item + amount
GET	/assessments	诊疗核验记录	令牌	对应网站「方案核验」
POST	/assessments	记录核验	令牌	六问清单在 /meta 之外固定，见网站 copy
GET	/outcomes	疗效时间线	令牌	对应网站「疗效反馈」
POST	/outcomes	记录疗效	令牌	result 为四选一枚举

交流社区 · 7 个

方法	路径	用途	权限	说明
GET	/feed	社区动态流（游标分页）	可选令牌	按 feed_at 倒序；带令牌才回 liked / canDelete；与网站 /feed 同一份数据
GET	/feed/{id}	动态详情 + 回复列表	可选令牌	comments 为回复数组；likeCount / commentCount 为计数
POST	/feed	发布动态	令牌	body ≤500 字；可只发图；media 传 /feed/media 拿到的 path
POST	/feed/media	上传一张配图（先传后挂）	令牌	multipart file；单张 ≤2MB；返回 path 给发帖时回传
POST	/feed/{id}/like	点赞 / 取消点赞（幂等切换）	令牌	同一接口按当前状态决定方向；返回 liked + likeCount
POST	/feed/{id}/comment	回复动态	令牌	body ≤200 字；meta.commentCount 为最新计数
DELETE	/feed/{id}	删除动态	令牌	作者 / 管理员 / 审核员可删；软删且 App 端不可撤销

个人主页 · 2 个

方法	路径	用途	权限	说明
GET	/users/{id}	用户主页：公开资料 + 宠物 + 活跃 + 四类公开信息	可选令牌	不含过敏史 / 既往病史 / 病例 / 问诊；领养不回联系人姓名电话地址
GET	/users/{id}/posts	该用户的动态流（游标分页）	可选令牌	主页下拉加载用

通知 · 4 个

方法	路径	用途	权限	说明
GET	/notifications	通知列表	令牌	meta.unread 为未读数
POST	/notifications/{id}/read	标记单条已读	令牌
POST	/notifications/read-all	全部标记已读	令牌
DELETE	/notifications/{id}	删除单条通知	令牌

商户入驻申请（买家侧） · 2 个

方法	路径	用途	权限	说明
GET	/merchant-applications	我提交过的入驻申请	令牌	含 status / auditNote 与 capabilities.canApply
POST	/merchant-applications	提交入驻申请	令牌	一个账号同时只能有一份在审或已通过的申请；通过后角色升级为 merchant

商户工作台 · 经营概览 · 1 个

方法	路径	用途	权限	说明
GET	/merchant/overview	店铺状态、待办数量、商品分布、钱包摘要	商户	首屏一次拉齐；待办含待发货、待处理售后、待审核商品

商户工作台 · 商品 · 7 个

方法	路径	用途	权限	说明
GET	/merchant/products	商品列表（按状态标签页）	商户	tab=all|on_sale|warehouse|pending|rejected|draft；支持 q 与 category
GET	/merchant/products/{id}	单个商品详情	商户	只能读自己店铺的商品
POST	/merchant/products	发布商品	商户	action=draft 存草稿，否则直接进待审核；库存与规格必填
PATCH	/merchant/products/{id}	修改商品	商户	action=submit 时草稿才真正送审；移除的图片会被清理
POST	/merchant/products/{id}/status	上架 / 下架	商户	action=online|offline；出售中才能下架，仓库中上架不再送审
DELETE	/merchant/products/{id}	删除商品	商户	出售中不能删，必须先下架；连带清理图片与购物车引用
POST	/merchant/products/batch	批量上架 / 下架 / 删除	商户	ids 最多 100 条，返回 done 与逐条 skipped 原因

商户工作台 · 主图 · 2 个

方法	路径	用途	权限	说明
POST	/merchant/media	上传一张主图	商户	multipart；JPG/PNG/WebP，≤2MB；单商品上限 5 张
DELETE	/merchant/media	删除一张未绑定的主图	商户	已被商品引用的图片返回 409

商户工作台 · 订单 · 3 个

方法	路径	用途	权限	说明
GET	/merchant/orders	店铺订单	商户	status 支持 pending_shipment 聚合待发货；返回 actions.canShip / canDeliver
POST	/merchant/orders/{code}/ship	发货	商户	expressCompany + expressNo；买家会收到通知，货款仍托管
POST	/merchant/orders/{code}/deliver	标记签收	商户	只有已发货的订单可以标记；售后期满后结算

商户工作台 · 售后 · 2 个

方法	路径	用途	权限	说明
GET	/merchant/aftersales	店铺售后单	商户	status 默认 pending；meta.counts 给标签页角标
POST	/merchant/aftersales/{id}/handle	同意退款 / 拒绝	商户	decision=approve|reject；同意退货退款会回补库存

商户工作台 · 货款 · 2 个

方法	路径	用途	权限	说明
GET	/merchant/wallet	可提现余额、待结算、流水、提现记录	商户	打开时顺手结算到期订单；待结算不落库，实时汇总
POST	/merchant/wallet/withdraw	提交提现	商户	提交即从余额扣出进入「打款中」，驳回时退回

六、网站页面 ↔ App ↔ 端点对照

下表是「网站有的功能，App 也要有」的验收口径。左边是网站路由（config/huta.nav 的 key）， 中间是 App 里的入口，右边是它调用的端点。

网站页面	App 入口	主要端点
/ 首页	首页	/meta · /animals · /consultations · /notifications
/consult 免费问诊	问诊	/symptoms · /consultations/* · /medications/check
/plan 诊疗方案	处理方案	/consultations/{id}/report · /consultations/{id}/refine
/shop 购药商城	购药	/products · /cart/* · /orders/* · /aftersales
/records 健康监测	健康监测	/animals/{id}/observations · /animals/{id}/timeline · /animals/{id}/records
/profile 动物档案	宠物档案	/animals/* · /animals/{id}/photo · /animals/{id}/select
/rescue 救助领养	流浪救助 / 领养	/adoptions/* · /adoption-applications · /public/adoptions
/foster 爱心寄养	爱心寄养	/fosters/offers · /fosters/requests
/schedule 照护日程	照护日程	/tasks · /tasks/{id}
/lost 走失寻找	寻宠	/lost-reports · /lost-reports/{id}/found
/mutual 公益互助	邻里互助	/aid-requests · /supplies
/diagnostics 低价检查	低价检查	/exams/bookings
/hospitals 爱心医院	爱心医院	/hospitals/nearby · /public/hospitals · /hospital/applications
/opinion 方案核验	方案核验	/assessments
/cost 费用透明	费用透明	/quotes
/outcomes 疗效反馈	疗效反馈	/outcomes
/team 共同照护	共同照护	/team/tasks
/support 困难支持	困难支持	/support-requests
/notifications 消息通知	消息	/notifications/*
/more 更多服务	全部服务	/meta.appNav · /search
/download App 下载	它自己	人读的下载落地页，读 settings 的 app 分组；App 侧对应 /app/version
/merchant 商家工作台	商户工作台	/merchant/overview · /merchant/products · /merchant/orders · /merchant/aftersales · /merchant/wallet
/merchant/products 商品管理	商户 › 商品	/merchant/products/* · /merchant/media
/merchant/orders 订单管理	商户 › 订单	/merchant/orders · /merchant/orders/{code}/ship · /deliver
/merchant/aftersales 售后	商户 › 售后	/merchant/aftersales · /handle
/merchant/wallet 货款提现	商户 › 货款	/merchant/wallet · /merchant/wallet/withdraw
/review 审核工作台	不提供	审核角色只在 Web 端工作，App 无入口
/hospital-admin 医院审核台	不提供	同上，属于审核工具
/admin 后台管理	不提供	角色、配置、题库、提现打款等高风险操作只在 Web 端

七、安全与合规约束

问诊分级	只由服务端规则引擎决定；客户端不得自行降级。triage.level 与预算、是否下单完全无关。
用药	/medications/check 不返回剂量。剂量属于处方行为，只能来自问诊报告里的 medication.drugs[]（按体重换算）。
领养隐私	公开列表与 /public/adoptions 永远不含电话与详细地址；联系方式仅在审核通过后返回。
医院标识	只有审核通过的机构可显示「合作 / 已审核」；名录为空时必须引导用户用公开地图找急诊，不能因为没名录就不救。
商户数据边界	商户只能读写 merchant_id 等于自己的商品、订单、售后与货款；跨店铺请求返回 403 FORBIDDEN。
提现	提交即从可提现余额扣出并进入「打款中」，驳回时退回——防止等待打款期间重复提现。打款动作只在 Web 后台由管理员执行。
令牌存储	App 端必须使用 Keychain / Keystore；服务端只存 sha256 摘要。
删除语义	Web 删除后可一步撤销（会话级）；App 的 DELETE /records/{key}/{id} 是终态的，客户端必须先做二次确认。