refactor(client): 网络层由官方 http 换成 dio（对外行为不变）

为什么：权威文档（AGENTS.md / CODING_STANDARDS.md）强制网络层用 dio，差异清单 A 组第 1 题
用户裁定选 A；原来用官方 http 是在无文档状态下按口头要求选的。

- ApiClient 改用 dio + BaseOptions（validateStatus 恒真、8s 超时、ResponseType.bytes 自行 UTF-8 解码）
- 新增 AuthHeaderInterceptor（Authorization / X-Device-Id）与 EnvelopeInterceptor
  （解包 {code,message,data} + 错误码映射 + 401 判定）
- 401 → 刷新 → 重发一次在 ApiClient 里编排，刻意不放在拦截器内重发：dio 的排队拦截器
  在回调里再发请求会自锁
- 接口层（auth_api/catalog_api）签名、全部 controller/logic/page 未改动
- 测试：新增假 dio adapter 替代 MockClient，断言口径一条未改；用例名改为 should_<期望>_when_<条件>；
  新增 api_client_test（解包/错误映射/请求头/查询参数/跳过重试）与 live_auth_test（真实后端 POST 链路）
- pubspec：加 dio、移除已无引用的 http
- 实测：dart analyze lib test 零告警；flutter test 155 全过；真实联调（8081）GET/POST 链路均通

test/auth/auth_controller_test.dart

@@ -1,8 +1,6 @@
 import 'dart:convert';
 
 import 'package:flutter_test/flutter_test.dart';
-import 'package:http/http.dart' as http;
-import 'package:http/testing.dart';
 import 'package:shared_preferences_platform_interface/in_memory_shared_preferences_async.dart';
 import 'package:shared_preferences_platform_interface/shared_preferences_async_platform_interface.dart';
 
@@ -12,23 +10,18 @@ import 'package:nontonki/core/data/remote/auth_api.dart';
 import 'package:nontonki/core/data/services/auth_controller.dart';
 import 'package:nontonki/core/data/services/auth_session_store.dart';
 
-/// 用假的 http.Client 覆盖三条关键路径：注册成功、401 → 刷新 → 重试、刷新失败 → 清会话。
+import '../support/fake_http_adapter.dart';
+
+/// 用假的 dio adapter 覆盖四条关键路径：注册成功、401 → 刷新 → 重试、刷新失败 → 清会话、登出。
+///
+/// 网络层从 http 换成 dio 后，这里的**断言口径一条没变**，只是注入方式从
+/// `http.testing.MockClient` 换成 `FakeHttpAdapter`。
 void main() {
   setUp(() {
     SharedPreferencesAsyncPlatform.instance =
         InMemorySharedPreferencesAsync.empty();
   });
 
-  /// http.Response(String) 默认按 Latin-1 编码，中文消息会直接抛
-  /// "Contains invalid characters" —— 统一用 UTF-8 字节构造。
-  http.Response jsonResponse(String body, [int statusCode = 200]) {
-    return http.Response.bytes(
-      utf8.encode(body),
-      statusCode,
-      headers: const {'content-type': 'application/json; charset=utf-8'},
-    );
-  }
-
   String tokenBody({
     required String accessToken,
     required String refreshToken,
@@ -48,12 +41,12 @@ void main() {
 
   ApiClient clientWith(
     AuthController Function() auth, {
-    required MockClient httpClient,
+    required FakeHttpAdapter adapter,
   }) {
     final store = AuthSessionStore();
     return ApiClient(
       baseUrl: 'http://127.0.0.1:8081',
-      client: httpClient,
+      adapter: adapter,
       accessTokenReader: () => auth().accessToken,
       tokenRefresher: () => auth().refresh(),
       onUnauthorized: () => auth().clear(),
@@ -61,16 +54,19 @@ void main() {
     );
   }
 
-  test('register stores session and exposes signed-in state', () async {
+  test('should store the session and expose a signed-in state when register succeeds', () async {
     late AuthController auth;
-    final mock = MockClient((request) async {
-      expect(request.url.path, '/app/auth/register');
-      expect(request.headers['X-Device-Id'], isNotEmpty);
-      expect(request.headers.containsKey('Authorization'), isFalse);
-      return jsonResponse(tokenBody(accessToken: 'a1', refreshToken: 'r1'));
+    final adapter = FakeHttpAdapter((options) async {
+      expect(options.uri.path, '/app/auth/register');
+      expect(options.headers['X-Device-Id'], isNotEmpty);
+      expect(options.headers.containsKey('Authorization'), isFalse);
+      return FakeHttpResponse(tokenBody(accessToken: 'a1', refreshToken: 'r1'));
     });
     final store = AuthSessionStore();
-    auth = AuthController(AuthApi(clientWith(() => auth, httpClient: mock)), store);
+    auth = AuthController(
+      AuthApi(clientWith(() => auth, adapter: adapter)),
+      store,
+    );
 
     expect(auth.isSignedIn, isFalse);
     await auth.register(email: 'a@b.com', password: 'abcd1234');
@@ -81,72 +77,89 @@ void main() {
     expect((await AuthSessionStore().read())?.refreshToken, 'r1');
   });
 
-  test('401 triggers refresh once and retries with the new token', () async {
+  test('should refresh once and retry with the new token when a response carries code 401', () async {
     var calls = 0;
     late AuthController auth;
-    final mock = MockClient((request) async {
+    final adapter = FakeHttpAdapter((options) async {
       calls++;
-      if (request.url.path == '/app/auth/refresh') {
-        return jsonResponse(tokenBody(accessToken: 'a2', refreshToken: 'r2'));
+      if (options.uri.path == '/app/auth/refresh') {
+        return FakeHttpResponse(tokenBody(accessToken: 'a2', refreshToken: 'r2'));
       }
-      if (request.url.path != '/app/me') {
+      if (options.uri.path != '/app/me') {
         // 注册等其它请求：直接发第一版令牌
-        return jsonResponse(tokenBody(accessToken: 'a1', refreshToken: 'r1'));
+        return FakeHttpResponse(tokenBody(accessToken: 'a1', refreshToken: 'r1'));
       }
-      final token = request.headers['Authorization'];
+      final token = options.headers['Authorization'];
       if (token == 'Bearer a1') {
-        return jsonResponse(
+        return FakeHttpResponse(
           jsonEncode({'code': 401, 'message': '未登录或登录已过期', 'data': null}),
         );
       }
       expect(token, 'Bearer a2');
-      return jsonResponse(jsonEncode({'code': 0, 'message': 'ok', 'data': {'hit': true}}));
+      return FakeHttpResponse(
+        jsonEncode({
+          'code': 0,
+          'message': 'ok',
+          'data': {'hit': true},
+        }),
+      );
     });
     final store = AuthSessionStore();
-    auth = AuthController(AuthApi(clientWith(() => auth, httpClient: mock)), store);
+    auth = AuthController(
+      AuthApi(clientWith(() => auth, adapter: adapter)),
+      store,
+    );
     await auth.register(email: 'a@b.com', password: 'abcd1234');
     calls = 0;
 
-    final api = clientWith(() => auth, httpClient: mock);
+    final api = clientWith(() => auth, adapter: adapter);
     final data = await api.get('/app/me');
     expect((data as Map)['hit'], isTrue);
     expect(calls, 3); // 原请求(401) + 刷新 + 重试
     expect(auth.accessToken, 'a2');
   });
 
-  test('refresh failure clears the session (401 handling)', () async {
+  test('should clear the session when the refresh itself fails', () async {
     late AuthController auth;
-    final mock = MockClient((request) async {
-      if (request.url.path == '/app/auth/refresh') {
-        return jsonResponse(jsonEncode({'code': 401, 'message': '登录已过期', 'data': null}));
+    final adapter = FakeHttpAdapter((options) async {
+      if (options.uri.path == '/app/auth/refresh') {
+        return FakeHttpResponse(
+          jsonEncode({'code': 401, 'message': '登录已过期', 'data': null}),
+        );
       }
-      if (request.url.path == '/app/auth/register') {
-        return jsonResponse(tokenBody(accessToken: 'a1', refreshToken: 'r1'));
+      if (options.uri.path == '/app/auth/register') {
+        return FakeHttpResponse(tokenBody(accessToken: 'a1', refreshToken: 'r1'));
       }
-      return jsonResponse(
+      return FakeHttpResponse(
         jsonEncode({'code': 401, 'message': '未登录或登录已过期', 'data': null}),
       );
     });
     final store = AuthSessionStore();
-    auth = AuthController(AuthApi(clientWith(() => auth, httpClient: mock)), store);
+    auth = AuthController(
+      AuthApi(clientWith(() => auth, adapter: adapter)),
+      store,
+    );
     await auth.register(email: 'a@b.com', password: 'abcd1234');
 
-    final api = clientWith(() => auth, httpClient: mock);
+    final api = clientWith(() => auth, adapter: adapter);
     await expectLater(api.get('/app/me'), throwsA(isA<ApiException>()));
     expect(auth.isSignedIn, isFalse);
     expect(await AuthSessionStore().read(), isNull);
   });
 
-  test('signOut clears local session even if the server call fails', () async {
+  test('should clear the local session when sign out hits a server error', () async {
     late AuthController auth;
-    final mock = MockClient((request) async {
-      if (request.url.path == '/app/auth/logout') {
-        return jsonResponse('{}', 500);
+    final adapter = FakeHttpAdapter((options) async {
+      if (options.uri.path == '/app/auth/logout') {
+        return FakeHttpResponse('{}', 500);
       }
-      return jsonResponse(tokenBody(accessToken: 'a1', refreshToken: 'r1'));
+      return FakeHttpResponse(tokenBody(accessToken: 'a1', refreshToken: 'r1'));
     });
     final store = AuthSessionStore();
-    auth = AuthController(AuthApi(clientWith(() => auth, httpClient: mock)), store);
+    auth = AuthController(
+      AuthApi(clientWith(() => auth, adapter: adapter)),
+      store,
+    );
     await auth.register(email: 'a@b.com', password: 'abcd1234');
 
     await auth.signOut();

test/auth/auth_page_test.dart

@@ -1,7 +1,5 @@
 import 'package:flutter/material.dart';
 import 'package:flutter_test/flutter_test.dart';
-import 'package:http/http.dart' as http;
-import 'package:http/testing.dart';
 import 'package:provider/provider.dart';
 import 'package:shared_preferences_platform_interface/in_memory_shared_preferences_async.dart';
 import 'package:shared_preferences_platform_interface/shared_preferences_async_platform_interface.dart';
@@ -13,6 +11,8 @@ import 'package:nontonki/core/data/services/auth_session_store.dart';
 import 'package:nontonki/l10n/app_localizations.dart';
 import 'package:nontonki/pages/auth/auth_view.dart';
 
+import '../support/fake_http_adapter.dart';
+
 /// 登录/注册页的可读证据：校验提示 + 登录/注册切换 + 未登录时不会去发请求。
 void main() {
   setUp(() {
@@ -26,7 +26,7 @@ void main() {
         // 这个测试不联网：请求一律 500，正好用于验证"本地校验没过就不发请求"
         ApiClient(
           baseUrl: 'http://127.0.0.1:1',
-          client: MockClient((_) async => http.Response('{}', 500)),
+          adapter: FakeHttpAdapter((_) async => FakeHttpResponse('{}', 500)),
         ),
       ),
       AuthSessionStore(),
@@ -45,7 +45,7 @@ void main() {
     await tester.pumpAndSettle();
   }
 
-  testWidgets('empty form shows the email error and stays on the page', (tester) async {
+  testWidgets('should show the email error and stay on the page when the form is empty', (tester) async {
     await pumpAuthPage(tester);
 
     expect(find.text('Welcome back'), findsOneWidget);
@@ -57,7 +57,7 @@ void main() {
     expect(find.text('Welcome back'), findsOneWidget);
   });
 
-  testWidgets('weak password is rejected locally', (tester) async {
+  testWidgets('should reject a weak password locally when only letters are typed', (tester) async {
     await pumpAuthPage(tester);
 
     await tester.enterText(find.byType(TextField).first, 'a@b.com');
@@ -68,7 +68,7 @@ void main() {
     expect(find.text('Password needs both letters and numbers'), findsOneWidget);
   });
 
-  testWidgets('switch link flips between sign in and sign up', (tester) async {
+  testWidgets('should flip between sign in and sign up when the switch link is tapped', (tester) async {
     await pumpAuthPage(tester);
     expect(find.text('Welcome back'), findsOneWidget);
 

test/core/api_client_test.dart

@@ -0,0 +1,107 @@
+// Author: fruit.com.cn
+
+import 'dart:convert';
+
+import 'package:flutter_test/flutter_test.dart';
+
+import 'package:nontonki/core/data/remote/api_client.dart';
+
+import '../support/fake_http_adapter.dart';
+
+/// 网络层换 dio 之后，把「对外契约」逐条钉住：解包、错误码映射、请求头、查询参数、跳过重试。
+void main() {
+  String envelope(Object? data, {int code = 0, String message = 'ok'}) {
+    return jsonEncode({'code': code, 'message': message, 'data': data});
+  }
+
+  test('should return the data field when the envelope code is zero', () async {
+    final adapter = FakeHttpAdapter(
+      (_) async => FakeHttpResponse(envelope({'id': 7})),
+    );
+    final client = ApiClient(baseUrl: 'http://127.0.0.1:8081', adapter: adapter);
+
+    final data = await client.get('/app/dramas/7');
+    expect((data as Map)['id'], 7);
+  });
+
+  test('should throw an ApiException carrying the server message when the envelope code is not zero', () async {
+    final adapter = FakeHttpAdapter(
+      (_) async => FakeHttpResponse(
+        envelope(null, code: 40001, message: '邮箱格式不正确'),
+      ),
+    );
+    final client = ApiClient(baseUrl: 'http://127.0.0.1:8081', adapter: adapter);
+
+    await expectLater(
+      client.post('/app/auth/register', body: {'target': 'bad'}),
+      throwsA(
+        isA<ApiException>()
+            .having((e) => e.code, 'code', 40001)
+            .having((e) => e.message, 'message', '邮箱格式不正确'),
+      ),
+    );
+  });
+
+  test('should map a body without envelope to an ApiException carrying the http status', () async {
+    final adapter = FakeHttpAdapter((_) async => FakeHttpResponse('oops', 502));
+    final client = ApiClient(baseUrl: 'http://127.0.0.1:8081', adapter: adapter);
+
+    await expectLater(
+      client.get('/app/home/feed'),
+      throwsA(
+        isA<ApiException>().having((e) => e.code, 'code', 502),
+      ),
+    );
+  });
+
+  test('should send the bearer token and the device header when both are available', () async {
+    final adapter = FakeHttpAdapter((_) async => FakeHttpResponse(envelope(null)));
+    final client = ApiClient(
+      baseUrl: 'http://127.0.0.1:8081',
+      adapter: adapter,
+      accessTokenReader: () => 'token-1',
+      deviceIdReader: () async => 'device-9',
+    );
+
+    await client.get('/app/me');
+
+    final request = adapter.requests.single;
+    expect(request.headers['Authorization'], 'Bearer token-1');
+    expect(request.headers['X-Device-Id'], 'device-9');
+    expect(request.headers['Accept'], 'application/json');
+  });
+
+  test('should put the query map into the request uri', () async {
+    final adapter = FakeHttpAdapter((_) async => FakeHttpResponse(envelope(null)));
+    final client = ApiClient(baseUrl: 'http://127.0.0.1:8081', adapter: adapter);
+
+    await client.get('/app/search', query: {'keyword': '短剧', 'page': '2'});
+
+    final uri = adapter.requests.single.uri;
+    expect(uri.path, '/app/search');
+    expect(uri.queryParameters['keyword'], '短剧');
+    expect(uri.queryParameters['page'], '2');
+  });
+
+  test('should not refresh the token when the call opts out of auth retry', () async {
+    var refreshed = false;
+    final adapter = FakeHttpAdapter(
+      (_) async => FakeHttpResponse(envelope(null, code: 401, message: '登录已过期')),
+    );
+    final client = ApiClient(
+      baseUrl: 'http://127.0.0.1:8081',
+      adapter: adapter,
+      tokenRefresher: () async {
+        refreshed = true;
+        return true;
+      },
+    );
+
+    await expectLater(
+      client.post('/app/auth/refresh', body: {'refreshToken': 'r1'}, skipAuthRetry: true),
+      throwsA(isA<ApiException>().having((e) => e.code, 'code', 401)),
+    );
+    expect(refreshed, isFalse);
+    expect(adapter.requests, hasLength(1));
+  });
+}

test/integration/live_auth_test.dart

@@ -0,0 +1,34 @@
+// Author: fruit.com.cn
+
+import 'package:flutter_test/flutter_test.dart';
+
+import 'package:nontonki/core/data/remote/api_client.dart';
+import 'package:nontonki/core/data/remote/auth_api.dart';
+
+/// 联调测试：直连本机客户端接口服务（8081）验证 **POST + JSON body + 错误码映射**。
+///
+/// 特意用"不存在的邮箱"登录：既能走完整的 POST 链路，又不会在库里留下测试数据。
+/// 服务没启动时自动跳过，不影响日常 `flutter test`。
+void main() {
+  final client = ApiClient(baseUrl: 'http://127.0.0.1:8081');
+  final api = AuthApi(client);
+
+  tearDownAll(client.close);
+
+  test('should surface a business error when signing in with an unknown email', () async {
+    try {
+      await api.login(
+        email: 'no-such-user-for-dio-check@example.com',
+        password: 'abcd1234',
+        deviceId: 'dio-check-device',
+      );
+      fail('不存在的邮箱不应该登录成功');
+    } on ApiException catch (error) {
+      // 关键点：错误码来自响应体（不是 HTTP 状态码），说明统一解包生效
+      expect(error.code, isNot(0));
+      expect(error.message, isNotEmpty);
+    } catch (_) {
+      markTestSkipped('客户端接口服务未启动，已跳过联调测试');
+    }
+  });
+}

test/support/fake_http_adapter.dart

@@ -0,0 +1,46 @@
+// Author: fruit.com.cn
+
+import 'dart:convert';
+import 'dart:typed_data';
+
+import 'package:dio/dio.dart';
+
+/// 假响应：[body] 会按 UTF-8 编码成字节，[statusCode] 默认 200。
+class FakeHttpResponse {
+  FakeHttpResponse(this.body, [this.statusCode = 200]);
+
+  final String body;
+  final int statusCode;
+}
+
+/// dio 的测试替身：把请求交给回调处理，全程不联网。
+///
+/// 顺带记录每个收到的请求，测试可以直接断言"发了几次、带了什么头"。
+class FakeHttpAdapter implements HttpClientAdapter {
+  FakeHttpAdapter(this.handler);
+
+  final Future<FakeHttpResponse> Function(RequestOptions options) handler;
+
+  /// 按顺序记录收到的请求，用于断言请求次数与请求头。
+  final List<RequestOptions> requests = [];
+
+  @override
+  Future<ResponseBody> fetch(
+    RequestOptions options,
+    Stream<Uint8List>? requestStream,
+    Future<void>? cancelFuture,
+  ) async {
+    requests.add(options);
+    final response = await handler(options);
+    return ResponseBody.fromBytes(
+      utf8.encode(response.body),
+      response.statusCode,
+      headers: const {
+        'content-type': ['application/json; charset=utf-8'],
+      },
+    );
+  }
+
+  @override
+  void close({bool force = false}) {}
+}