aslan-flutter/md/后端接口对接规范.md

后端接口对接规范

1. 目标

本文档用于 Aslan Flutter 项目后续与后端接口对接时统一协作边界、接口事实来源、前端落地位置、记录格式和问题流转方式。

核心原则：

• 前端可以只读查看后端代码、接口文档和契约，用于理解接口、字段、错误码、鉴权和业务边界。
• 前端绝对不能修改后端仓库中的任何代码、文档、配置、生成文件、SQL、资源或测试。
• 如果发现后端接口、字段、错误码或业务逻辑需要调整，只能整理建议和证据，由用户协调后端处理。
• 对接接口时禁止本地假数据兜底；接口报错、空数据、权限失败、字段缺失都必须按真实状态处理，不能用本地 mock 数据伪装成接口成功。

---

2. 当前前端项目事实

当前 Flutter 项目路径：

/Users/pinpaibu/flutter_code/aslan-flutter

项目名与包：

• 应用名：Aslan
• Flutter package import 前缀：package:aslan/...
• 当前配置入口：lib/chatvibe_core/config/app_config.dart
• 当前默认配置：Variant1Config
• 当前 API Host：https://api.atuchat.com/
• 当前图片 Host：https://img.atuchat.com/

主要前端分层：

• lib/chatvibe_core/：配置、常量、路由、通用工具。
• lib/chatvibe_data/：数据层实现、本地存储、网络请求、仓库实现。
• lib/chatvibe_domain/：仓库接口、请求模型、响应模型和领域模型。
• lib/chatvibe_features/：按业务功能组织的页面、状态和交互逻辑。
• lib/chatvibe_managers/：跨页面复用的管理器。
• lib/chatvibe_ui/：公共 UI 组件、主题和通用 widgets。
• local_packages/：项目内维护的本地 Flutter 插件，不能随意替换为 pub.dev 原版。

---

3. 后端代码位置

服务端代码项目名称：likei-services。

当前本机后端仓库路径：

/Users/pinpaibu/server_code/likei-services

已确认的后端结构：

• rc-gateway/：服务网关，客户端接口对接优先看这里。
• rc-auth/：认证服务。
• rc-service/rc-service-wallet/：钱包服务。
• rc-service/rc-service-live/：直播 / 语音房相关服务。
• rc-service/rc-service-order/：订单服务。
• rc-service/rc-service-other/：其他业务服务。
• rc-service/rc-service-external/：外部能力对接服务。
• rc-service/rc-service-console/：后台运营服务。
• rc-service/rc-inner-api/：内部服务 API / DTO 契约。
• rc-common-business/：通用业务组件、DTO、MQ、核心能力。
• rc-register/：注册配置中心。
• rc-scheduling/：调度中心。
• rc-service-game/：游戏服务。
• claude/、reports/：后端辅助资料或报告，按需只读参考。

后端仓库类型：Java / Maven 多模块服务

说明：

• 后端代码仅用于接口 API 参考。
• 不要修改服务端任何代码。
• 如果服务端需要增加接口或者存在 bug，只能提出建议和证据。

---

4. 后端代码只读红线

后续任何前端线程、AI 或开发者，进入后端路径时必须遵守：

• 只允许查看、搜索、摘录和分析后端代码。
• 禁止创建、修改、删除、移动、格式化后端仓库中的任何文件。
• 禁止对后端仓库使用 apply_patch、编辑器保存、sed -i、重定向写文件、脚本生成、批量替换等写入方式。
• 禁止运行会改动后端仓库文件的命令，例如格式化、依赖整理、代码生成、数据库迁移生成、OpenAPI 生成、mock 生成。
• 默认不在后端仓库执行构建、测试、启动、Docker、Makefile 或脚本命令；如果确实需要运行，必须先说明目的、可能产生的文件影响，并得到用户明确允许。
• 禁止提交、暂存、切分支、rebase、merge、pull、push 后端仓库。
• 禁止把前端对接需要的临时标记写入后端代码注释或文档。

允许的只读命令示例：

ls
find
rg
sed -n
git status --short
git diff --stat
git show
git grep

如果命令可能产生缓存、日志、生成文件或配置变更，默认视为禁止。

---

5. 接口事实参考顺序

对接某个接口前，必须按以下顺序确认事实：

1. 先看后端接口文档或 OpenAPI，确认 HTTP path、method、请求体、响应体、鉴权要求和错误码描述。
2. 再看后端实际路由注册和 handler/controller，确认当前线上实现、参数解析、响应 envelope 和鉴权行为。
3. 如接口由内部服务 API、DTO、Feign/RPC 或其它内部契约支撑，再看对应契约，确认字段语义、枚举、默认值和跨服务约束。
4. 必要时查看后端 service/domain/storage 代码，只为理解业务规则和字段来源，不直接照搬内部实现到前端。
5. 最后再查看业务说明文档，用于确认流程边界、当前限制和后续计划。

当接口文档、handler、契约、业务文档之间不一致时：

• 以当前后端 handler/controller 实现作为“现状事实”记录。
• 同时把不一致点写入“待后端确认事项”。
• 前端不得自行修改后端文档或代码来消除不一致。

---

6. 当前 Flutter 网络层约定

网络入口：

• 全局请求实例：lib/chatvibe_data/sources/remote/net/network_client.dart 中的 http
• 通用请求基类：lib/chatvibe_data/sources/remote/net/api.dart 中的 BaseNetworkClient
• Dio 基础配置：connectTimeout = 12s，receiveTimeout = 15s
• 额外超时拦截：TimeOutInterceptor.globalTimeoutSeconds = 15

基础 URL：

• NetworkClient.init() 设置 dio.options.baseUrl = ATGlobalConfig.apiHost
• ApiInterceptor.onRequest() 每次请求会重新写入 options.baseUrl = ATGlobalConfig.apiHost
• ATGlobalConfig.apiHost 来自 AppConfig.current.apiHost

请求头：

• req-lang：当前语言。
• req-imei：设备 ID。
• req-app-intel：版本、build、机型、系统版本、渠道。
• req-client：Android 或 iOS。
• req-sys-origin：origin 与 originChild。
• Authorization：当本地 token 非空时发送 Bearer <token>。
• Req-Atyou：当前固定为 true。

响应 envelope：

{
  "status": bool,
  "errorCode": int?,
  "errorCodeName": string?,
  "errorMsg": string?,
  "body": any,
  "time": number?
}

响应处理规则：

• status == true 才视为业务成功。
• body 由调用方传入的 fromJson 解析为领域响应模型。
• status == false 会通过 DioException 进入错误流程。
• 业务错误码集中参考 lib/chatvibe_data/models/enum/at_erro_code.dart。
• 不能在 UI 层直接解析后端 envelope；应在网络层、仓库层或 manager/provider 中处理。

特别注意：

• 当前仓库实现中，许多实际请求 path 是加密或映射后的字符串，真实业务接口名通常写在方法注释里，例如 ///auth/account/login。
• 后续记录接口时，必须同时记录“业务接口名”和“当前实际请求 path”。
• 如果需要新增接口，不要猜测加密 path 或随意复用旧 path，必须先确认后端契约和当前前端映射方式。

---

7. 前端对接落地流程

每次对接新接口时，按以下步骤执行：

1. 确认当前线程负责的业务板块，不能越界顺手处理其它模块。
2. 只读查看后端接口文档、实际 handler/controller、契约和相关业务说明。
3. 在前端记录接口事实：业务接口名、当前实际请求 path、method、auth、request、response、错误码、后端证据文件。
4. 按当前项目分层落地：
   • lib/chatvibe_data/sources/remote/net/：只维护通用网络能力、拦截器和响应 envelope。
   • lib/chatvibe_domain/models/req/：新增或调整请求模型。
   • lib/chatvibe_domain/models/res/：新增或调整响应模型。
   • lib/chatvibe_domain/repositories/：声明业务仓库接口方法。
   • lib/chatvibe_data/sources/repositories/：实现仓库接口并调用 http.get/post/put/delete。
   • lib/chatvibe_managers/ 或 lib/chatvibe_features/<feature>/：编排页面流程、加载态、错误态和状态更新。
   • lib/chatvibe_ui/：只做通用 UI 组件，不放接口解析逻辑。
5. 接口错误、空数据、鉴权失败、字段缺失必须展示真实状态或走既有错误流程，禁止本地假数据兜底。
6. 如发现后端需要调整，写入“待后端确认事项”，明确“建议后端处理”，前端不改后端。

---

8. 本地假数据与兜底红线

对接真实接口时禁止：

• 接口报错后返回本地固定列表、固定对象或 mock JSON，让页面看起来正常。
• 字段缺失时在仓库层硬编码业务假值来绕过问题。
• 后端未返回权限、余额、身份、房间状态等关键字段时，前端自行推断并继续提交后续业务请求。
• 将调试用 mock、临时测试数据、接口样例数据留在正式逻辑中。
• 为了避免页面空态，把接口失败当作空列表成功。

允许：

• UI 展示空态、错误态、重试按钮、toast 或既有错误弹窗。
• 在开发调试环境中使用明确隔离的 mock，但不得进入正式接口对接逻辑。
• 对非关键展示字段使用产品确认过的展示默认值，例如空昵称展示 --；这不等同于业务数据兜底。

---

9. 接口事实记录模板

后续每个正式接入的接口，建议按以下格式记录在对应业务文档或本文件的接口记录区：

### 接口名称

- 业务板块：
- 后端来源：
  - 接口文档 / OpenAPI：
  - Handler / Controller：
  - Proto / RPC / Service：
- 业务接口名：
- 当前实际请求 path：
- Method：
- Auth：
- Request：
- Response body：
- 业务错误码：
- 前端落地位置：
  - repository interface：
  - repository impl：
  - request model：
  - response model：
  - manager / provider / feature logic：
  - page / widget：
- 是否存在本地假数据兜底：否
- 待后端确认：
- 当前状态：未接入 / 接入中 / 已接入 / 等后端确认

---

10. 后端问题建议流转

如果前端对接时发现以下情况，不修改后端，只记录建议：

• 接口文档与实际 handler/controller 实现不一致。
• 字段缺失、字段含义不清、枚举值不完整。
• 错误码无法支撑前端区分提示。
• 接口返回结构不适合前端稳定渲染。
• 鉴权、幂等、分页、排序、时间单位、空态规则不明确。
• 后端当前只支持 mock 或占位实现。
• 前端需要新增接口、合并接口或调整响应字段。
• 当前前端需要真实接口，但后端尚未提供可用契约。

建议记录格式：

- 【待后端确认｜业务板块｜YYYY-MM-DD HH:mm CST】
  问题：
  证据：
  前端影响：
  建议后端处理：

所有建议由用户协调后端团队处理；前端线程只负责说明影响、提供证据和调整前端对接方案。

---

11. 验证要求

接口对接完成后，至少给出以下验证：

• 静态检查：按改动范围运行 flutter analyze 或说明无法运行的原因。
• 模型解析：确认成功响应、空 body、字段缺失、错误响应不会导致非预期崩溃。
• 业务路径：验证页面正常加载、刷新、分页、提交、失败提示等主路径。
• 鉴权路径：验证未登录、token 失效或权限不足时走既有登录/错误流程。
• 回归范围：说明本次改动是否影响同仓库其它方法、共享模型、网络拦截器或全局错误处理。

如果是 bug 修复线程，还必须先说明 Root Cause，得到用户确认后再改代码，并坚持最小改动。

---

12. 当前可优先参考的前端文件

对接接口时，前端优先查看：

• lib/chatvibe_data/sources/remote/net/network_client.dart
• lib/chatvibe_data/sources/remote/net/api.dart
• lib/chatvibe_data/sources/remote/net/at_logger.dart
• lib/chatvibe_data/models/enum/at_erro_code.dart
• lib/chatvibe_core/constants/at_global_config.dart
• lib/chatvibe_core/config/app_config.dart
• lib/chatvibe_core/config/configs/variant1_config.dart
• lib/chatvibe_domain/repositories/
• lib/chatvibe_data/sources/repositories/
• lib/chatvibe_domain/models/req/
• lib/chatvibe_domain/models/res/

后端优先查看：

• /Users/pinpaibu/server_code/likei-services/README.md
• /Users/pinpaibu/server_code/likei-services/rc-gateway/
• /Users/pinpaibu/server_code/likei-services/rc-auth/
• /Users/pinpaibu/server_code/likei-services/rc-service/
• /Users/pinpaibu/server_code/likei-services/rc-common-business/
• /Users/pinpaibu/server_code/likei-services/rc-service/rc-inner-api/