本篇汇总通用客户端（Vue 等）接入时需要特别留意的约定项。这些设计源于 API 最初的小程序背景，通用客户端可以完全忽略其中的小程序专属字段，但依赖 Cookie 的少数链路与URL 形态需要按本篇说明处理。

一、dou.* 扩展字段与 link_user_center

部分接口的 data 中会出现 dou 命名空间字段和 link_user_center 字段：

{
  "code": "OK",
  "data": {
    "title": "会员中心",
    "welcome": "欢迎回来",
    "link_user_center": "...",
    "if_connect_plugin": false,
    "dou": {
      "user": { "...": "会员资料" },
      "auth": { "is_login": true, "is_vip": false, "is_work": false, "is_distribution": false },
      "vip": { },
      "work": { },
      "distribution": { }
    }
  }
}

通用客户端的处理原则：dou.* 是附加信息，不是必需数据。账号信息以 data.user（登录类接口）或各业务接口自身的数据字段为准；dou.auth 里的布尔位（登录/会员/员工/分销）可选择性采用。

二、Cookie 会话依赖（结算链路）

大部分接口是无状态令牌鉴权，但有少数链路在服务端使用 Cookie 会话（Session）暂存中间状态：

浏览器端接入结算时：

1. 服务端 CORS 配置中 credentials 必须为 true（且白名单不可用 *）；
2. 前端 axios 实例设 withCredentials: true；
3. 同域名部署（如前后端同站）时浏览器自动携带 Cookie，无额外配置。

非浏览器客户端（App、小程序）本身有 Cookie 容器，正常处理响应 Set-Cookie 即可。

三、微信登录为小程序专用

user/weixin/* 系列接口（login、get_phone、pay）依赖微信小程序运行环境（code 换 session_key、解密用户信息），仅系统自带小程序可用。通用 Web 客户端请使用：

• 账号密码登录：user/login_post；
• 手机验证码登录：user/login_phone_post；
• 站内安装的第三方登录插件（user/sns*，见《会员接口》）。

四、URL 形态约定

接口响应中出现的页面链接类字段（如 jump_url、邮件里的重置链接、link_user_center）在服务端渲染时的形态取决于调用端：

通用客户端应自行拼装前端路由，不要把服务端返回的 URL 直接用于浏览器跳转判断（除 jump_url 这类明确语义为"去哪儿登录"的字段外）。

五、路由命名与版本策略

所有 API 路由名统一带 api. 前缀（如 api.user.login_post），为将来的 API 版本化预留命名空间。当前没有 /v2 之类的路径版本段——若未来出现不兼容变更：

• 会以新增路由（不同路径或不同 action 名）的方式引入，旧路由保持可用一段时间；
• 新增 code 业务码同样只追加、不改名（见《错误码与限流》）；
• 客户端自身的版本迭代请以本文档的接口契约为准做兼容性测试。

六、工作端接口的 work_required 策略

标注 work_required 的接口（主要集中在各模块的 /work 子控制器，如 order/work、product/work）除要求登录外，还要求当前账号绑定员工身份：

• 未登录 → 401 UNAUTHORIZED；
• 已登录但非员工 → 403 FORBIDDEN（message 提示无工作端权限）。

工作端接口面向"员工在工作台处理业务"（跟进、核销、审核等），通用 C 端客户端一般不需要接入；小程序端对接前提是该账号已在后台绑定员工。详见《工作端接口》。

七、兼容性承诺小结

如需申请新接口或反馈文档与实现不一致，请附上 request_id 与接口路径联系服务端维护者。