feat: 落地登录纵切——网络层、认证会话与登录/注册/Splash 三页（ADR-003/ADR-004）

- 新增 lib/core/network/：ApiClient（dio 封装，错误信封→类型化异常，base URL 经 --dart-define=PATBOND_API_BASE_URL 注入）、AuthInterceptor（Bearer + 设备标识）、TokenRefresher（单飞刷新，401/40101 重放一次，仅 40102/再 401 清会话） - 新增 lib/features/auth/：SessionManager（token 只进 flutter_secure_storage）、AuthRepository（login/register/refresh/logout/me，注册带 Idempotency-Key）、Splash（500ms 最短停留/5s 超时/错误态重试+改用账号登录）、登录页与注册页（照 12 号组装稿，错误三层映射，预留区不渲染） - App 根组件改为认证状态机驱动（Splash↔登录↔主壳 300ms fade）；个人中心退出登录接入真实 logout - 顺带修复：FIX-1 促销卡渐变改 [primaryStrong, primary]、FIX-2 补 helperStyle: muted、README dart format 命令补 --output=none - 新增依赖：dio ^5.11.1、flutter_secure_storage ^11.0.0、uuid ^4.6.0 - 门禁：dart format（0 changed）/ flutter analyze（No issues）/ flutter test（30 passed，其中新增 23：TokenRefresher 5 + AuthRepository 10 + 登录页 4 + 注册页 4） Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-09-04 11:52:51 +08:00
parent ee77361b92
commit 8d890c0424
30 changed files with 2306 additions and 9 deletions
@@ -0,0 +1,149 @@
+import 'package:dio/dio.dart';
+import 'package:patbond_flutter/core/network/api_envelope.dart';
+import 'package:patbond_flutter/core/network/api_exception.dart';
+import 'package:patbond_flutter/core/network/token_refresher.dart';
+import 'package:patbond_flutter/features/auth/session_manager.dart';
+
+/// API 基地址：`--dart-define=PATBOND_API_BASE_URL=...` 注入，默认本机后端。
+const String patbondApiBaseUrl = String.fromEnvironment(
+  'PATBOND_API_BASE_URL',
+  defaultValue: 'http://127.0.0.1:8081',
+);
+
+/// 构建全局共用的 Dio 实例。
+///
+/// `validateStatus` 放行所有状态码：错误信封由 [ApiClient] 统一解析成
+/// 类型化异常，不依赖 dio 的 4xx/5xx 抛错路径。
+Dio buildPatbondDio({required SessionManager session, String? baseUrl}) {
+  final dio = Dio(
+    BaseOptions(
+      baseUrl: baseUrl ?? patbondApiBaseUrl,
+      connectTimeout: const Duration(seconds: 5),
+      sendTimeout: const Duration(seconds: 10),
+      receiveTimeout: const Duration(seconds: 10),
+      contentType: Headers.jsonContentType,
+      validateStatus: (_) => true,
+    ),
+  );
+  dio.interceptors.add(AuthInterceptor(session));
+  return dio;
+}
+
+/// 鉴权拦截器：对标记 [ApiClient.requiresAuthExtra] 的请求附加
+/// `Authorization: Bearer`，并统一携带设备标识。
+class AuthInterceptor extends Interceptor {
+  AuthInterceptor(this._session);
+
+  final SessionManager _session;
+
+  @override
+  void onRequest(RequestOptions options, RequestInterceptorHandler handler) {
+    final deviceId = _session.deviceId;
+    if (deviceId != null) {
+      options.headers['X-Device-Id'] = deviceId;
+    }
+    if (options.extra[ApiClient.requiresAuthExtra] == true) {
+      final token = _session.accessToken;
+      if (token != null) {
+        options.headers['Authorization'] = 'Bearer $token';
+      }
+    }
+    handler.next(options);
+  }
+}
+
+/// HTTP 客户端封装：错误信封 → 类型化异常，401/40101 → 刷新后重放一次。
+class ApiClient {
+  ApiClient({
+    required this._dio,
+    required this._session,
+    required this._refresher,
+  });
+
+  /// RequestOptions.extra 标记：该请求需要 Bearer 鉴权。
+  static const requiresAuthExtra = 'patbond.requiresAuth';
+
+  final Dio _dio;
+  final SessionManager _session;
+  final TokenRefresher _refresher;
+
+  /// 发起请求并返回信封中的 `data`。
+  ///
+  /// 鉴权请求遇 HTTP 401 或 code 40101 时：经单飞刷新后原样重放一次；
+  /// 重放仍失败则清会话并抛 [SessionExpiredException]。
+  Future<Object?> request(
+    String path, {
+    String method = 'POST',
+    Object? body,
+    Map<String, Object?>? headers,
+    bool requiresAuth = false,
+  }) async {
+    var response = await _send(
+      path,
+      method: method,
+      body: body,
+      headers: headers,
+      requiresAuth: requiresAuth,
+    );
+
+    if (requiresAuth && _isAuthFailure(response)) {
+      await _refresher.refresh();
+      response = await _send(
+        path,
+        method: method,
+        body: body,
+        headers: headers,
+        requiresAuth: requiresAuth,
+      );
+      if (_isAuthFailure(response)) {
+        await _session.clearSession();
+        throw const SessionExpiredException('刷新后重放仍未通过鉴权');
+      }
+    }
+
+    return _unwrap(response);
+  }
+
+  Future<Response<Object?>> _send(
+    String path, {
+    required String method,
+    required bool requiresAuth,
+    Object? body,
+    Map<String, Object?>? headers,
+  }) async {
+    try {
+      return await _dio.request<Object?>(
+        path,
+        data: body,
+        options: Options(
+          method: method,
+          headers: headers,
+          extra: {requiresAuthExtra: requiresAuth},
+        ),
+      );
+    } on DioException catch (error) {
+      throw ApiNetworkException('请求失败：${error.type.name}');
+    }
+  }
+
+  bool _isAuthFailure(Response<Object?> response) {
+    if (response.statusCode == 401) return true;
+    return ApiEnvelope.tryParse(response.data)?.code ==
+        ApiCodes.accessTokenInvalid;
+  }
+
+  Object? _unwrap(Response<Object?> response) {
+    final status = response.statusCode ?? 0;
+    if (status == 429) {
+      throw const ApiRateLimitException();
+    }
+    final envelope = ApiEnvelope.tryParse(response.data);
+    if (envelope == null || status >= 500) {
+      throw ApiNetworkException('响应异常：HTTP $status');
+    }
+    if (envelope.code == ApiCodes.ok) {
+      return envelope.data;
+    }
+    throw ApiBusinessException(code: envelope.code, message: envelope.message);
+  }
+}