# Yumi Flutter 后端接口对接规范

> 适用仓库：`yumi-flutter`  
> 后端代码：`yumi-java` + `yumi-golang`  
> 最后核对：2026-07-10

## 1. 目标与适用范围

本文档用于统一 Yumi Flutter 与 Java、Go 后端的接口对接方式，覆盖接口事实来源、路由归属、前端分层、响应解析、鉴权、错误处理、验证和问题流转。

核心原则：

- 先查代码和配置，再实现；禁止根据页面或旧模型猜测后端契约。
- Flutter 线程对两个后端仓库仅有只读权限，发现后端问题只记录证据和建议。
- 所有业务 HTTP 请求必须经过项目现有网络层，页面不直接解析原始响应。
- 接口失败时禁止使用本地假数据、硬编码列表或伪造成功结果还原页面。
- Bug 修复必须先说明 Root Cause 和影响面，经确认后再做最小改动并提供验证证据。

---

## 2. 仓库位置与责任边界

### 2.1 Flutter 客户端

```text
/Users/pinpaibu/flutter_code/yumi-flutter
```

当前技术和分层事实：

- 网络：Dio，统一客户端为 `lib/shared/data_sources/sources/remote/net/network_client.dart`。
- 响应封装：`ResponseData<T>`。
- 仓储接口：`lib/shared/business_logic/repositories/`。
- 仓储实现：`lib/shared/data_sources/sources/repositories/`。
- 请求/响应模型：`lib/shared/business_logic/models/req/` 与 `res/`。
- 功能模块：`lib/modules/`；独立功能也可在模块内保留 `data/api/repository/models` 边界，例如 `lib/modules/room_game/data/`。
- 页面状态：Provider + ChangeNotifier，全局管理器在 `lib/services/`。
- 路由：Fluro，入口为 `lib/main.dart`。

### 2.2 Java 后端

```text
/Users/pinpaibu/server_code/yumi-java
```

客户端相关的主要边界：

- `rc-gateway/`：Spring Cloud Gateway，是 Flutter 默认 HTTP 入口。
- `nacos_config/rc-gateway/application.yml`：外部路径到 Java/Go 服务的路由事实。
- `rc-auth/`：登录凭证和内部 Token 校验。
- `rc-service/rc-service-other/`：用户、配置、礼物、任务、房间外围等大量 App 业务。
- `rc-service/rc-service-live/`：语音房在线、麦位等实时业务。
- `rc-service/rc-service-wallet/`：钱包、余额、流水。
- `rc-service/rc-service-order/`：订单与支付。
- `rc-service/rc-service-external/`：文件、短信、IM/TRTC 等外部能力。
- `rc-service/rc-inner-api/`：Java 服务内部 Feign 契约，Flutter 不直接调用。

Java `README.md` 可用于快速定位模块，但其端口和模块说明可能滞后；联调时必须以 Gateway/Nacos 路由和当前 Controller 为准。

### 2.3 Go 后端

```text
/Users/pinpaibu/server_code/yumi-golang
```

当前主要边界：

- `cmd/api/`：HTTP API 启动和依赖装配。
- `cmd/consumer/`：事件消费入口。
- `internal/router/`：Gin 路由、请求绑定、鉴权中间件和统一响应。
- `internal/service/<module>/`：按业务模块拆分的业务逻辑。
- `internal/integration/`：Go 调用 Java 服务的网关封装。
- `internal/common/`：`AppError`、`AuthUser` 等跨模块类型。
- `internal/model/` 与 `migrations/`：表映射和数据库迁移。
- `internal/config/config.go`：运行配置与 Java 下游地址。

Go 本地 HTTP 默认监听 `:2900`，但 Flutter 默认仍应通过 Java Gateway 访问，不应在业务代码中硬编码内部端口。

---

## 3. 后端仓库只读红线

在 Flutter 对接任务中，`yumi-java` 和 `yumi-golang` 一律视为只读证据源。

允许：

- 使用 `rg`、`find`、`sed -n`、`git status --short`、`git diff`、`git show` 查看和搜索。
- 读取路由、Controller/Handler、DTO、Service、错误码、配置和测试。
- 在 Flutter 文档中记录后端证据路径和待确认事项。

禁止：

- 在后端仓库创建、修改、删除、移动或格式化任何代码、文档、配置、SQL、生成文件和测试。
- 运行会产生文件的命令，如 `gofmt -w`、`goimports -w`、`go mod tidy`、Maven 打包、代码生成、数据库迁移。
- 默认启动后端、Docker、消费者、定时任务或执行后端测试；确有必要时必须先说明作用和文件/数据影响，并得到用户明确授权。
- 在后端仓库执行暂存、提交、切分支、合并、拉取或推送。
- 把调试标记或前端待办写入后端源码。

---

## 4. 实际请求拓扑与路由归属

### 4.1 默认链路

```text
Flutter
  -> Java Gateway（API_HOST）
     -> Java auth / external / order / wallet / live / other
     -> Go API
        -> MySQL / Redis / MQ
        -> Java 内部服务（鉴权、用户、钱包、奖励等）
```

Flutter 默认基地址由 `SCVariant1Config.apiHost` 提供，可通过编译参数覆盖：

```bash
flutter run --dart-define=API_HOST=https://example-gateway/
```

不得在 Repository、Manager 或 Widget 中硬编码生产/测试域名。

### 4.2 Java Gateway 路由要点

以 `yumi-java/nacos_config/rc-gateway/application.yml` 为准，当前关键对外路径如下：

| Flutter 请求路径 | Gateway 处理 | 实际归属 |
| --- | --- | --- |
| `/auth/**` | 去掉 `/auth` | Java auth |
| `/external/**` | 去掉 `/external` | Java external |
| `/order/**` | 去掉 `/order` | Java order |
| `/wallet/**` | 去掉 `/wallet` | Java wallet |
| `/live/**` | 去掉 `/live` | Java live |
| `/go/**` | 去掉 `/go` | Go API |
| `/app/game/**` | 保留原路径 | Go API |
| 未匹配的普通路径 | 默认转发 | Java other |
| 带 `Req-Likei: true` 的加密路由 | `ForwardRoute` 解析后转发 | 由解析结果决定 |

Gateway 还对部分活动、回调和后台路径做了专用路由；对接具体接口时必须搜索完整 path，不能只根据前缀推断服务归属。

### 4.3 Go 路径的两种对接形式

- 经 Gateway 的 `/go` 路由：Flutter 请求 `/go/app/vip/status`，Go 实际接收 `/app/vip/status`。
- Gateway 专用路由：例如 Flutter 请求 `/app/game/providers`，Go 仍接收 `/app/game/providers`。

除已有调试边界外，新增 App 接口优先使用同一 `API_HOST` 经 Gateway 访问。项目已有两个可选直连覆盖：

- `VIP_API_HOST`：VIP Go API 调试。
- `GAME_API_HOST`：房间游戏 Go API 调试。

仅在确认需要绕过 Gateway 联调时使用；不得为单个页面随意新增直连域名。

---

## 5. 接口事实参考顺序

当前两个后端仓库没有可覆盖全部 App 接口的统一 OpenAPI 契约，因此必须以可执行代码和当前路由配置为主证据。

### 5.1 先确定请求归属

1. 在 `nacos_config/rc-gateway/application.yml` 搜索完整 path 或前缀。
2. 判断请求是否会 `StripPrefix`，记录 Flutter path 与下游 path。
3. 确认该路由是否在 `gateway.ignorePaths` 中；“忽略 Gateway 鉴权”不等于“业务无需鉴权”，还要继续检查下游实现。

### 5.2 Java 接口

按以下顺序核对：

1. `*-adapter/src/main/java/**/**RestController.java`：`@RequestMapping` + `@Get/Post/Put/DeleteMapping` 确认 method/path。
2. Controller 方法参数：确认 query/path/form/json、`@Validated` 和必填规则。
3. `*-client` / `*-inner` 中的 Command、CO、DTO、Enum：确认字段名、类型、枚举和响应数据。
4. `*-application` 中对应 Service：确认业务条件、空值和错误分支。
5. 错误码枚举、`ApiException` 和统一响应框架：确认业务失败语义。
6. 最后查看相关测试和 README/docs，用于补充流程，不用于覆盖当前代码。

### 5.3 Go 接口

按以下顺序核对：

1. `internal/router/<module>_routes.go`：确认 method/path、鉴权中间件、query/path/body 绑定。
2. `internal/service/<module>/types.go` 及对应业务文件：确认请求/响应字段、默认值、业务规则和 `AppError`。
3. `internal/integration/`：如业务依赖 Java，确认实际下游 endpoint、Header 和数值转换。
4. `internal/model/`、`migrations/` 和 `internal/config/`：仅用于理解字段来源、持久化和运行限制。
5. `*_test.go`：核对边界值和已固化行为。

### 5.4 证据冲突时

- Gateway 配置决定外部请求实际到达哪个服务。
- 当前 Router/Controller 实现决定 method、path 和参数接收方式。
- 当前 Service/DTO 实现决定业务语义和字段。
- README、注释、历史文档和 Flutter 旧模型只是补充证据。
- 冲突时以当前可到达的执行代码作为“现状事实”，同时记录“待后端确认”，Flutter 不自行改后端消除差异。

---

## 6. 已确认的网络契约

### 6.1 请求 Header

`ApiInterceptor` 会统一补充：

- `Authorization: Bearer <token>`（本地存在 Token 时）
- `req-lang`
- `req-imei`
- `req-app-intel`
- `req-client`
- `req-sys-origin`
- `Host`
- 已确认的加密路由才会添加 `Req-Likei: true`

对接时不得在 Widget/Manager 重复手工组装这些公共 Header，也不得在代码或日志中写死 Token、密钥或完整鉴权数据。

Go App 路由的 `authMiddleware` 会读取 Bearer Token，并调用 Java auth 校验凭证；因此 Go 接口鉴权仍与 Java 登录态一致。

### 6.2 Java/Go 兼容响应

Flutter `ResponseData<T>` 当前兼容两类字段：

```json
{
  "status": true,
  "errorCode": 0,
  "errorCodeName": "",
  "errorMsg": "success",
  "body": {},
  "time": 0
}
```

以及：

```json
{
  "code": 200,
  "message": "OK",
  "data": {}
}
```

Go `writeOK` / `writeError` 会同时输出 `status/errorCode/errorMsg/body` 与 `code/message/data` 两套兼容字段。Flutter 解析规则为：

- 数据优先读取 `body`，不存在时读取 `data`。
- 优先用 `status` 判定成败；缺失时，`code == 0` 或 `code == 200` 视为成功。
- 错误码读取 `errorCode` 或 `code`，错误信息读取 `errorMsg` 或 `message`。
- HTTP 200 不代表业务成功，仍必须检查 envelope。
- HTTP 4xx/5xx 与业务失败都必须进入明确错误状态。

新接口不得在页面层再实现一套 envelope 判定逻辑。

### 6.3 空响应

- 只有后端契约明确表示成功无数据时，才允许使用可空泛型和 `allowNullBody: true`。
- 不得用 `false`、`0`、空字符串或空列表掩盖本应返回对象的契约问题。
- 列表本身合法为空时，空列表是真实业务结果，不是接口失败的替代值。

### 6.4 路径与加密路由

- 旧接口在 Repository 中仍可能使用哈希形式的路由键，`network_client.dart` 会用 `_localRouteOverrides` 转为已知明文 path。
- 新对接优先使用后端路由中已确认的明文 path，不复制或自行生成哈希。
- 若线上 Gateway 明确要求加密路由，必须先获得后端路由键/转发规则并在网络层集中处理，页面层不得设置 `Req-Likei`。

---

## 7. Flutter 对接落地规范

### 7.1 分层责任

```text
Widget / Page
  -> Provider / ChangeNotifier / Manager
     -> Repository abstraction
        -> Repository implementation / feature Api
           -> NetworkClient
              -> Java Gateway -> Java or Go
```

- `Widget / Page`：只负责渲染、交互与发出意图；不直接调 Dio，不解析 JSON。
- `Provider / ChangeNotifier / Manager`：编排加载、成功、空态和错误状态，调用 Repository，不处理原始 envelope。
- `Repository abstraction`：定义业务语义明确的方法和返回类型。
- `Repository implementation / feature Api`：定义 method/path/query/body，调用 `http.get/post/put/delete`，完成 model 映射。
- `NetworkClient`：统一 base URL、Header、Token、超时、envelope 和通用错误处理。

对现有模块增加接口时，优先延续该模块的已有分层，不为单个接口引入第二套网络或状态管理方案。

### 7.2 Model 与字段

- 字段命名、类型、可空性、枚举值和时间单位必须有后端证据。
- 后端 `int64/Long` 字段如可能以数字或数字字符串返回，只能在 Model 解析边界做兼容，不得在 Widget 中反复转换。
- 时间字段必须明确是秒、毫秒还是 ISO-8601，禁止通过数值长度猜测。
- 金额、金币和比例必须确认单位与精度，不得在 UI 层暗中乘除。
- 枚举未知值应有安全的“未知/不支持”分支，但不得把未知值伪装成某个已知业务类型。
- 不在 Model 中根据页面需求虚构后端未返回的业务字段。

### 7.3 请求参数

- GET 查询使用 `queryParams`，path variable 只用已确认的 URL 片段。
- JSON 请求使用 `data`，参数命名与后端契约一致。
- 文件上传使用 `FormData`/`MultipartFile`，必须同时确认表单字段名、MIME、扩展名、大小上限和超时。
- 幂等写操作的 key 由调用方在一次用户意图开始时创建，同一次超时重试必须复用；不得在每次底层请求时重新生成。
- 分页必须记录是 cursor、page/size 还是 lastId，不得混用。

### 7.4 错误和登录态

- 网络层负责超时、HTTP 错误、通用业务错误和当前登录态校验。
- Manager/Provider 只负责将错误转为页面可表达的错误状态，必要时提供重试入口。
- Widget 不得看 `errorCode` 决定登出，不得自行重试鉴权失败。
- 不得把服务端内部堆栈、SQL、密钥、完整 Token 或敏感请求体输出到生产日志。
- 同一页面需要部分容错时，必须先定义每个数据源的独立成功/失败语义，不能用本地假数据补齐失败部分。

---

## 8. 严禁本地数据兜底

接口错误、超时、解析失败或返回不完整时，禁止：

- 返回内置 mock 列表、本地 JSON、调试 assets 或硬编码对象。
- 把异常转换为空列表、`false`、`0` 或“成功”，使页面误以为接口已成功。
- 因为新接口不可用而静默切换到语义不同的旧接口。
- 用占位数据触发下游支付、送礼、发奖、扣费、房间状态或其他写操作。

允许的仅是产品明确设计的本地能力，例如：

- 加载骨架、空态插图、错误提示和重试按钮，但不得表示为服务端真实数据。
- 明确定义的离线缓存，但必须保留“旧数据/离线”语义，不能覆盖本次请求失败事实。
- 纯 UI 预览和单元测试中的 Fake/Fixture，必须与生产请求路径隔离。

---

## 9. 标准对接流程

1. 明确本次业务范围，不顺手改无关模块。
2. 在 Flutter 中搜索现有接口、Model、Manager 和测试，确认已有状态和兼容要求。
3. 查 Java Gateway 路由，确定请求归属和外部 path。
4. 按第 5 节读取 Java 或 Go 的 Router/Controller、DTO/Service、错误和测试。
5. 先写一份接口事实记录，至少包含 method/path/auth/request/response/error/evidence。
6. 说明改动对现有路由、网络层、登录态、模型和页面的影响；若为 Bug，先提供 Root Cause 并等待用户确认。
7. 在 Flutter 做能解决问题的最小变更，不重构无关代码。
8. 增加 Model/envelope/分页/错误分支的针对性测试。
9. 按第 11 节执行验证，并记录真实 API 联调结果。
10. 如后端需要调整，只记录待确认项和证据，由用户协调后端处理。

---

## 10. 接口事实记录模板

```text
### 接口名称

- 业务模块：
- 调用链路：Flutter -> Java Gateway -> Java / Go -> 下游
- Flutter Method / Path：
- 下游 Method / Path：
- Gateway 路由处理：保留路径 / StripPrefix / 加密转发
- Auth：无 / Bearer / 其他
- Request：
  - path：
  - query：
  - header：
  - body/form：
- Response body/data：
- 空值与默认值：
- 业务错误码：
- 时间/金额/分页/幂等语义：
- 后端证据：
  - Gateway：
  - Router / Controller：
  - DTO / Service：
  - Test / Doc：
- Flutter 落地：
  - repository/api：
  - model：
  - manager/provider：
  - view：
  - test：
- 待后端确认：
- 当前状态：未对接 / 对接中 / 已对接 / 等后端
```

---

## 11. 验证规范

### 11.1 静态与自动化验证

只格式化本次改动的 Dart 文件，然后执行：

```bash
flutter analyze
flutter test
```

网络 envelope 或通用解析改动至少运行：

```bash
flutter test test/network_response_data_test.dart
```

业务 Model 改动应运行或新增对应 `*_test.dart`；不能只依赖 Widget 手工观察。

### 11.2 真实接口联调

至少验证：

1. 实际请求 method/path 与 Gateway 转发后 path 正确。
2. 需鉴权接口携带当前 Bearer Token，无 Token/失效 Token 进入错误态。
3. 成功、真实空数据、业务失败、HTTP 失败、超时、解析失败各至少覆盖相关分支。
4. 重复点击、翻页、刷新和页面销毁不会产生重复写入或过期状态覆盖。
5. 接口失败时页面不出现本地假数据，也不把失败当作空数据。
6. 错误信息可理解、可重试，且日志不包含敏感信息。

### 11.3 回归影响

每次交付要明确说明：

- 是否修改公共 `NetworkClient`、`ResponseData`、公共 Header 或 Token 处理。
- 是否影响旧哈希路由、明文路由或 base URL override。
- 是否影响其他共用 Model、Repository、Provider 或实时消息。
- 针对上述影响执行了哪些测试，结果是什么。

---

## 12. 后端问题流转

出现以下情况时，Flutter 不修改后端：

- Gateway 路由与 Router/Controller 不一致。
- Java/Go 响应字段、可空性、数值类型或枚举不一致。
- HTTP 状态码、`errorCode/code` 和业务语义不能支持前端分支。
- 鉴权、幂等、分页、排序、时区、时间单位或金额单位不清晰。
- Go 路由存在但 Java Gateway 没有可到达转发。
- 后端仅有占位实现、返回 mock，或所需下游能力未上线。

记录模板：

```text
- 【待后端确认｜业务模块｜YYYY-MM-DD HH:mm CST】
  问题：
  现象：
  证据：
    - Gateway：
    - Java / Go：
    - Flutter：
  Root Cause 判断：
  前端影响：
  建议后端处理：
  联调验收条件：
```

---

## 13. 文档维护要求

- 本文档记录稳定规则；具体接口事实应写入对应业务文档，避免把本文档变成无法维护的接口大全。
- 引用后端证据时写明仓库和相对路径，必要时补充类/函数名，不复制大段实现。
- 不在文档中记录真实 Token、密码、密钥、DSN、云服务凭证或内网敏感信息。
- 后端路由或响应契约变更后，同步更新相关业务接口记录和验证日期。
- 文档中的“已对接”必须同时满足：Flutter 代码已落地、自动化验证通过、真实接口联调通过、不存在本地假数据兜底。