docs: sync affCode auth API changes

docs/dev/api/API-01-用户系统.md

@@ -4,7 +4,7 @@
 
 > 图片字段约定：本文件中的 `avatar` 等图片类字段，后端当前返回的是老司机/CDN 绝对地址。H5 渲染前需先走媒体 helper 转成同源代理地址，不要直接把原始 URL 塞进 `<img src>`、`<video poster>`、canvas `new Image()` 或 CSS `background-image`。
 
-> 认证链路设备参数约定：为支持登录/注册埋点与设备归因，`AUTH-01/02/03/04` 建议客户端统一透传 `X-Device-ID` 和 `X-Platform`。其中 `X-Platform` 支持 `ios / android / h5 / web / pc`，后端会将 `web / pc` 统一按 `h5` 处理；`AUTH-07` 继续使用 Body 中的 `deviceId / deviceType`；`AUTH-08` 继续要求 Body 中传 `deviceId`。
+> 认证链路设备与归因参数约定：为支持登录/注册埋点、设备归因与推广归因，`AUTH-01/02/03/04` 建议客户端统一透传 `X-Device-ID` 和 `X-Platform`。其中 `X-Platform` 支持 `ios / android / h5 / web / pc`，后端会将 `web / pc` 统一按 `h5` 处理；`AUTH-01/02/07` 额外支持在 Body 中传可选 `affCode` JSON 字符串（形如 `{"dc":"渠道A","pc":"12345","channel":"landingA","traceId":"trace-xxx"}`），用于渠道/推广归因；`AUTH-01/02` 原有 `X-Track-Channel` 仍可继续透传，但在新实现中仅作为 `affCode.dc / affCode.channel` 都未提供时的 fallback；`AUTH-07` 继续使用 Body 中的 `deviceId / deviceType`，并可同时带 `affCode`；`AUTH-08` 继续要求 Body 中传 `deviceId`。
 
 ---
 
@@ -24,8 +24,9 @@
 4. 密码加密（bcrypt）
 5. 写入 `user` 表（含嵌套 profile、privacy_setting、notification_setting 默认值）
 6. 写入 `wallet` 表（初始 balance=0）
-7. 签发 JWT Token（access_token + refresh_token），写入 `user_device` 表；若请求 Header 带 `X-Device-ID`，则同时写入 `user_device.device_id`，`user_device.device_type` 取服务端现有设备识别结果（`X-Platform` → `User-Agent` → 默认 `h5`），其中 `X-Platform=web/pc` 会归并为 `h5`
-8. 返回用户信息和Token
+7. 如请求 Body 传 `affCode`，则解析其中的 `dc / pc / channel / traceId`：`dc` 优先作为渠道号，`channel` 次之，二者都没有时才回退使用 Header `X-Track-Channel`；`pc` 按推广 clickId 解释；`traceId` 用于注册埋点 `trace_id`
+8. 签发 JWT Token（access_token + refresh_token），写入 `user_device` 表；若请求 Header 带 `X-Device-ID`，则同时写入 `user_device.device_id`，`user_device.device_type` 取服务端现有设备识别结果（`X-Platform` → `User-Agent` → 默认 `h5`），其中 `X-Platform=web/pc` 会归并为 `h5`；注册成功埋点以及注册后自动补发的登录埋点会透传上一步归一化后的渠道值
+9. 返回用户信息和Token
 
 **请求参数（Body）：**
 
@@ -34,6 +35,7 @@
 | username | string | 是 | 用户名，2-20字符，中英文/数字/下划线，不允许纯数字，不区分大小写 |
 | password | string | 是 | 密码，≥8位，需含字母+数字 |
 | confirmPassword | string | 是 | 确认密码，需与password一致 |
+| affCode | string | 否 | 剪切板归因 JSON 字符串，支持字段 `dc / pc / channel / traceId`；`dc` 优先作为渠道号，`pc` 按推广 clickId 解释，`traceId` 仅影响注册埋点 `trace_id` |
 
 **请求 Header（可选）：**
 
@@ -41,12 +43,16 @@
 |------|------|------|------|
 | X-Device-ID | string | 否 | 客户端设备唯一标识；注册时若提供，后端会写入 `user_device.device_id` |
 | X-Platform | string | 否 | 设备平台标识：`ios / android / h5 / web / pc`；用于推断 `user_device.device_type` 和埋点 `device` |
+| X-Track-Channel | string | 否 | 渠道号/渠道标识；当 `affCode.dc` 与 `affCode.channel` 都未提供时，后端会回退使用该值作为注册成功埋点及注册后自动补发登录埋点的 `channel` |
 
 **设备字段说明：**
 - `device_type` 不通过 Body 显式传参，后端按现有请求识别逻辑推断：`X-Platform` → `User-Agent` → 默认 `h5`
 - `X-Platform` 支持 `ios / android / h5 / web / pc`，其中 `web / pc` 会统一按 `h5` 处理
 - 未显式传 `X-Platform` 时，后端仅通过 `User-Agent` 继续识别 `ios / android`；仍无法识别时默认写 `h5`
 - `X-Device-ID` 未提供时，`user_device.device_id` 置空
+- `affCode` 为可选 Body 字段，不影响注册主流程；解析失败时接口仍按正常注册逻辑执行，只忽略本次归因信息
+- `affCode` 的渠道优先级为 `dc > channel > X-Track-Channel`；其中 `pc` 按推广 clickId 解释，不再兼作邀请码语义
+- `X-Track-Channel` 为 Header fallback 字段，不走 Body；当前用于注册成功后的渠道埋点，不写入 `user_device` / `user` 等业务表
 - 设备类型无法识别时，按当前后端现有识别结果写入；本接口不新增单独的设备类型协议字段
 
 **响应数据：**
@@ -79,8 +85,9 @@
 5. 连续5次错误 → 更新 `user` 表 设置 login_locked_until = 当前时间+15分钟（更新）
 6. 密码正确 → 重置 login_fail_count=0，更新 last_login_at（更新 `user`）
 7. 踢旧设备：将 `user_device` 表 中该用户所有 is_active=1 的记录更新为 is_active=0（更新）
-8. 签发新 JWT Token，写入 `user_device` 表（写）；若请求 Header 带 `X-Device-ID`，后端会同时读取该值和当前设备识别结果，用于平台登录埋点上报
-9. 读取 user 嵌套的 profile 子文档，组装响应
+8. 如请求 Body 传 `affCode`，则解析其中的 `dc / pc / channel / traceId`：`dc` 优先作为渠道号，`channel` 次之，二者都没有时才回退使用 Header `X-Track-Channel`；`pc` 按推广 clickId 解释；`traceId` 在登录链路不新增响应字段，仅供归因上下文使用
+9. 签发新 JWT Token，写入 `user_device` 表（写）；若请求 Header 带 `X-Device-ID`，后端会同时读取该值和当前设备识别结果，用于平台登录埋点上报；登录成功埋点会透传上一步归一化后的渠道值
+10. 读取 user 嵌套的 profile 子文档，组装响应
 
 **请求参数（Body）：**
 
@@ -88,6 +95,7 @@
 |------|------|------|------|
 | account | string | 是 | 用户名 |
 | password | string | 是 | 密码 |
+| affCode | string | 否 | 剪切板归因 JSON 字符串，支持字段 `dc / pc / channel / traceId`；`dc` 优先作为渠道号，`pc` 按推广 clickId 解释 |
 
 **请求 Header（可选）：**
 
@@ -95,11 +103,15 @@
 |------|------|------|------|
 | X-Device-ID | string | 否 | 客户端设备唯一标识；登录时若提供，后端会用于平台登录埋点上报 |
 | X-Platform | string | 否 | 设备平台标识：`ios / android / h5 / web / pc`；用于平台登录埋点中的 `device` |
+| X-Track-Channel | string | 否 | 渠道号/渠道标识；当 `affCode.dc` 与 `affCode.channel` 都未提供时，后端会回退使用该值作为登录成功埋点的 `channel` |
 
 **设备字段说明：**
 - 登录接口会继续读取现有设备识别信息（`X-Platform` → `User-Agent` → 默认 `h5`），用于平台登录埋点中的 `device`
 - `X-Platform` 支持 `ios / android / h5 / web / pc`，其中 `web / pc` 会统一按 `h5` 处理
 - 未显式传 `X-Platform` 时，后端仅通过 `User-Agent` 继续识别 `ios / android`；仍无法识别时，平台埋点默认按 `H5` 上报
+- `affCode` 为可选 Body 字段，不影响登录主流程；解析失败时接口仍按正常登录逻辑执行，只忽略本次归因信息
+- `affCode` 的渠道优先级为 `dc > channel > X-Track-Channel`；其中 `pc` 按推广 clickId 解释
+- `X-Track-Channel` 为 Header fallback 字段，不走 Body；当前用于登录成功后的渠道埋点，不写入 `user_device` / `user` 等业务表
 - 本期登录链路不额外承诺把 `device_id / device_type` 回写到 `user_device`，当前仅用于下游平台上报
 
 **响应数据：**
@@ -303,8 +315,9 @@
    - 写入默认 `user_profile` / `user_privacy_setting` / `user_notification_setting`
    - 回读完整 `user` 行
 5. 签发 JWT Token（access_token + refresh_token，与正式用户同一把 secret 和 uid claim）
-6. 写入 `user_device` 表，带上 `device_id / device_type / device_name / app_version`
-7. 读取 `user_profile` 子资料组装响应
+6. 如请求 Body 传 `affCode`，则解析其中的 `dc / pc / channel / traceId`：`dc` 优先作为渠道号，`channel` 次之；`pc` 按推广 clickId 解释；首次创建游客账号时，`traceId` 会透传到游客注册埋点，后续复用老游客仅影响登录归因上下文
+7. 写入 `user_device` 表，带上 `device_id / device_type / device_name / app_version`
+8. 读取 `user_profile` 子资料组装响应
 
 **请求参数（Body）：**
 
@@ -314,11 +327,14 @@
 | deviceType | string | 否 | 设备平台：ios / android / web（≤16 字符） |
 | deviceName | string | 否 | 机型或浏览器标识（≤64 字符） |
 | appVersion | string | 否 | 客户端版本号（≤32 字符） |
+| affCode | string | 否 | 剪切板归因 JSON 字符串，支持字段 `dc / pc / channel / traceId`；`dc` 优先作为渠道号，`pc` 按推广 clickId 解释，`traceId` 仅在首次创建游客账号时影响注册埋点 `trace_id` |
 
 **设备字段说明：**
 - `deviceId` 为游客身份复用主键，必须稳定透传；同一设备重复调用会复用历史游客账号
 - `deviceType` 建议透传真实平台值；`web / pc` 会在后端埋点口径中统一按 `h5` 处理
 - `deviceName / appVersion` 主要用于设备排查与埋点维度，不影响游客账号复用规则
+- `affCode` 为可选 Body 字段；解析失败时接口仍按正常游客登录逻辑执行，只忽略本次归因信息
+- `affCode` 的渠道优先级为 `dc > channel`；`AUTH-07` 不依赖 `X-Track-Channel` 作为主传参
 
 **响应数据：** 结构同 AUTH-02 `AuthResp`
 

docs/dev/api/README.md

@@ -39,7 +39,9 @@
 - AUTH-08 游客升级为正式账号 — `POST /client/api/v1/auth/upgrade`
 - 认证链路设备参数约定：
   - `AUTH-01/02/03/04` 建议透传 `X-Device-ID` 与 `X-Platform`
-  - `AUTH-07` 使用 Body 中的 `deviceId / deviceType`
+  - `AUTH-01/02/07` 支持 Body 可选 `affCode` JSON：`{"dc":"渠道A","pc":"12345","channel":"landingA","traceId":"trace-xxx"}`
+  - `AUTH-01/02` 的渠道优先级为 `affCode.dc > affCode.channel > X-Track-Channel`，其中 `pc` 按推广 `clickId` 解释
+  - `AUTH-07` 使用 Body 中的 `deviceId / deviceType`，并可同时带 `affCode`
   - `AUTH-08` 使用 Body 中的 `deviceId`
 - USER-01 获取当前用户信息 — `GET /client/api/v1/users/me`
 - USER-02 修改个人资料 — `PUT /client/api/v1/users/me`