# 后端接口对接规范

## 1. 目标

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

核心原则：

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

---

## 2. 当前前端项目事实

当前 Flutter 项目路径：

```text
/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`。

当前本机后端仓库路径：

```text
/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/`：后端辅助资料或报告，按需只读参考。

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

说明：

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

---

## 4. 后端代码只读红线

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

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

允许的只读命令示例：

```text
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：

```text
{
  "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. 接口事实记录模板

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

```text
### 接口名称

- 业务板块：
- 后端来源：
  - 接口文档 / 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 或占位实现。
- 前端需要新增接口、合并接口或调整响应字段。
- 当前前端需要真实接口，但后端尚未提供可用契约。

建议记录格式：

```text
- 【待后端确认｜业务板块｜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/`