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>

lib/app/app.dart

@@ -1,10 +1,20 @@
 import 'package:flutter/material.dart';
+import 'package:patbond_flutter/core/network/api_client.dart';
+import 'package:patbond_flutter/core/network/token_refresher.dart';
 import 'package:patbond_flutter/core/theme/app_theme.dart';
+import 'package:patbond_flutter/features/auth/auth_repository.dart';
+import 'package:patbond_flutter/features/auth/login_page.dart';
+import 'package:patbond_flutter/features/auth/session_manager.dart';
+import 'package:patbond_flutter/features/auth/splash_page.dart';
 import 'package:patbond_flutter/features/main/main_shell_page.dart';
 import 'package:patbond_flutter/state/app_state.dart';
 
 class App extends StatefulWidget {
-  const App({super.key});
+  const App({super.key, this.sessionManager, this.authRepository});
+
+  /// 测试注入口；生产默认走安全存储 + 真实 API。
+  final SessionManager? sessionManager;
+  final AuthRepository? authRepository;
 
   @override
   State<App> createState() => _AppState();
@@ -12,26 +22,80 @@ class App extends StatefulWidget {
 
 class _AppState extends State<App> {
   late final AppState appState;
+  late final SessionManager sessionManager;
+  late final AuthRepository authRepository;
 
   @override
   void initState() {
     super.initState();
     appState = AppState()..load();
+    sessionManager =
+        widget.sessionManager ??
+        SessionManager(store: const SecureTokenStore());
+    authRepository = widget.authRepository ?? _buildRepository();
+  }
+
+  AuthRepository _buildRepository() {
+    final dio = buildPatbondDio(session: sessionManager);
+    final refresher = TokenRefresher(dio: dio, session: sessionManager);
+    final api = ApiClient(
+      dio: dio,
+      session: sessionManager,
+      refresher: refresher,
+    );
+    return ApiAuthRepository(
+      api: api,
+      session: sessionManager,
+      refresher: refresher,
+    );
   }
 
   @override
   void dispose() {
     appState.dispose();
+    if (widget.sessionManager == null) sessionManager.dispose();
     super.dispose();
   }
 
+  Widget _homeForStatus() {
+    switch (sessionManager.status) {
+      case AuthStatus.unknown:
+        return SplashPage(
+          key: const ValueKey('splash'),
+          authRepository: authRepository,
+          sessionManager: sessionManager,
+        );
+      case AuthStatus.unauthenticated:
+        return LoginPage(
+          key: const ValueKey('login'),
+          authRepository: authRepository,
+        );
+      case AuthStatus.authenticated:
+        return MainShellPage(
+          key: const ValueKey('shell'),
+          appState: appState,
+          onLogout: authRepository.logout,
+        );
+    }
+  }
+
   @override
   Widget build(BuildContext context) {
     return MaterialApp(
       title: 'Patbond',
       debugShowCheckedModeBanner: false,
       theme: buildAppTheme(),
-      home: MainShellPage(appState: appState),
+      home: ListenableBuilder(
+        listenable: sessionManager,
+        builder: (context, _) {
+          // 认证状态切换统一 300ms 淡入淡出（Splash ↔ 登录 ↔ 主壳，
+          // BrandMark 同构保证品牌区过渡对位，组装稿 §7）。
+          return AnimatedSwitcher(
+            duration: const Duration(milliseconds: 300),
+            child: _homeForStatus(),
+          );
+        },
+      ),
     );
   }
 }

lib/core/navigation/fade_route.dart

@@ -0,0 +1,13 @@
+import 'package:flutter/material.dart';
+
+/// 统一页面切换：300ms 淡入淡出（12 号组装稿 §7 流程约束）。
+Route<T> fadePageRoute<T>(Widget page) {
+  return PageRouteBuilder<T>(
+    transitionDuration: const Duration(milliseconds: 300),
+    reverseTransitionDuration: const Duration(milliseconds: 300),
+    pageBuilder: (context, animation, secondaryAnimation) => page,
+    transitionsBuilder: (context, animation, secondaryAnimation, child) {
+      return FadeTransition(opacity: animation, child: child);
+    },
+  );
+}

lib/core/network/api_client.dart

@@ -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);
+  }
+}

lib/core/network/api_envelope.dart

@@ -0,0 +1,20 @@
+/// 服务端统一响应信封 `{code, message, data}` 的解析结果。
+class ApiEnvelope {
+  const ApiEnvelope({required this.code, required this.message, this.data});
+
+  final int code;
+  final String message;
+  final Object? data;
+
+  /// 从响应体解析信封；结构不符（非 JSON 对象 / 无 int code）返回 null。
+  static ApiEnvelope? tryParse(Object? body) {
+    if (body is! Map) return null;
+    final code = body['code'];
+    if (code is! int) return null;
+    return ApiEnvelope(
+      code: code,
+      message: body['message'] is String ? body['message'] as String : '',
+      data: body['data'],
+    );
+  }
+}

lib/core/network/api_exception.dart

@@ -0,0 +1,59 @@
+/// 服务端错误信封 `{code, message, data}` 的业务码常量（接口契约冻结稿）。
+abstract final class ApiCodes {
+  static const ok = 0;
+
+  /// 参数错误。
+  static const paramError = 40000;
+
+  /// 用户名或密码错误。
+  static const badCredentials = 40100;
+
+  /// access token 无效或过期。
+  static const accessTokenInvalid = 40101;
+
+  /// refresh token 已失效。
+  static const refreshTokenInvalid = 40102;
+
+  /// 用户名重复。
+  static const usernameTaken = 40900;
+
+  /// 手机号重复。
+  static const phoneTaken = 40901;
+}
+
+/// API 调用的类型化异常。页面按类型映射为三层错误呈现
+/// （字段级 / 表单横幅 / SnackBar，见 12 号组装稿 §4），
+/// 服务端原始 message 一律不直接透出给用户。
+sealed class ApiException implements Exception {
+  const ApiException(this.message);
+
+  /// 服务端返回的原始 message（仅用于日志排查，不上屏）。
+  final String message;
+
+  @override
+  String toString() => '$runtimeType: $message';
+}
+
+/// 系统错误：超时、断网、5xx、响应无法解析。归瞬态层（SnackBar + 重试）。
+final class ApiNetworkException extends ApiException {
+  const ApiNetworkException([super.message = '网络或服务不可用']);
+}
+
+/// 业务错误：错误信封 code != 0（40000/40100/40900/40901 等）。
+final class ApiBusinessException extends ApiException {
+  const ApiBusinessException({required this.code, required String message})
+    : super(message);
+
+  final int code;
+}
+
+/// 限流（HTTP 429）：映射为横幅「尝试次数过多，请稍后再试」。
+final class ApiRateLimitException extends ApiException {
+  const ApiRateLimitException([super.message = '请求过于频繁']);
+}
+
+/// 会话已失效：refresh token 失效（40102）或刷新重放后仍 401。
+/// 抛出前本地会话已被清除，应用会自动回到登录页。
+final class SessionExpiredException extends ApiException {
+  const SessionExpiredException([super.message = '会话已失效']);
+}

lib/core/network/token_refresher.dart

@@ -0,0 +1,66 @@
+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/features/auth/auth_models.dart';
+import 'package:patbond_flutter/features/auth/session_manager.dart';
+
+/// 单飞（single-flight）token 刷新器。
+///
+/// 并发触发的多个 401/40101 只发出一次 `POST /auth/refresh`，
+/// 其余调用共享同一个进行中的刷新结果。
+///
+/// 清会话纪律（12 号组装稿 §7）：只有服务端明确判定 refresh 失效
+/// （40102 或 HTTP 401）才清除本地会话；网络失败、5xx 一律保留 token。
+class TokenRefresher {
+  TokenRefresher({required this._dio, required this._session});
+
+  final Dio _dio;
+  final SessionManager _session;
+
+  Future<void>? _inflight;
+
+  /// 刷新并轮换 token。成功后新 token 已写入 [SessionManager]。
+  ///
+  /// 抛出 [SessionExpiredException]（会话已被清除）或
+  /// [ApiNetworkException]（token 保留，可重试）。
+  Future<void> refresh() {
+    return _inflight ??= _doRefresh().whenComplete(() => _inflight = null);
+  }
+
+  Future<void> _doRefresh() async {
+    await _session.loadFromStorage();
+    final refreshToken = _session.refreshToken;
+    if (refreshToken == null) {
+      await _session.clearSession();
+      throw const SessionExpiredException('本地无 refresh token');
+    }
+
+    final Response<Object?> response;
+    try {
+      response = await _dio.post<Object?>(
+        '/api/v1/auth/refresh',
+        data: {'refreshToken': refreshToken},
+      );
+    } on DioException catch (error) {
+      throw ApiNetworkException('刷新请求失败：${error.type.name}');
+    }
+
+    final envelope = ApiEnvelope.tryParse(response.data);
+    if (response.statusCode == 401 ||
+        envelope?.code == ApiCodes.refreshTokenInvalid) {
+      await _session.clearSession();
+      throw const SessionExpiredException('refresh token 已失效');
+    }
+    if (envelope != null &&
+        envelope.code == ApiCodes.ok &&
+        envelope.data is Map<String, dynamic>) {
+      await _session.updateTokens(
+        AuthTokens.fromJson(envelope.data! as Map<String, dynamic>),
+      );
+      return;
+    }
+    throw ApiNetworkException(
+      '刷新响应异常：HTTP ${response.statusCode}，code ${envelope?.code}',
+    );
+  }
+}

lib/core/theme/app_theme.dart

@@ -160,6 +160,7 @@ ThemeData buildAppTheme() {
         borderSide: BorderSide(color: AppColors.error, width: 1.5),
       ),
       errorStyle: TextStyle(color: AppColors.error, fontSize: 12),
+      helperStyle: TextStyle(color: AppColors.muted, fontSize: 12),
     ),
     snackBarTheme: const SnackBarThemeData(
       behavior: SnackBarBehavior.floating,

lib/features/auth/auth_models.dart

@@ -0,0 +1,57 @@
+/// 认证接口的响应模型（接口契约冻结稿，字段名与后端一致）。
+class AuthTokens {
+  const AuthTokens({
+    required this.userId,
+    required this.tokenType,
+    required this.accessToken,
+    required this.accessTokenExpiresAt,
+    required this.refreshToken,
+    required this.refreshTokenExpiresAt,
+  });
+
+  factory AuthTokens.fromJson(Map<String, dynamic> json) {
+    return AuthTokens(
+      userId: json['userId'] as String,
+      tokenType: json['tokenType'] as String,
+      accessToken: json['accessToken'] as String,
+      accessTokenExpiresAt: DateTime.parse(
+        json['accessTokenExpiresAt'] as String,
+      ),
+      refreshToken: json['refreshToken'] as String,
+      refreshTokenExpiresAt: DateTime.parse(
+        json['refreshTokenExpiresAt'] as String,
+      ),
+    );
+  }
+
+  final String userId;
+  final String tokenType;
+  final String accessToken;
+  final DateTime accessTokenExpiresAt;
+  final String refreshToken;
+  final DateTime refreshTokenExpiresAt;
+}
+
+/// `GET /api/v1/me` 的用户资料。
+class UserProfile {
+  const UserProfile({
+    required this.userId,
+    required this.username,
+    required this.phone,
+    required this.createdAt,
+  });
+
+  factory UserProfile.fromJson(Map<String, dynamic> json) {
+    return UserProfile(
+      userId: json['userId'] as String,
+      username: json['username'] as String,
+      phone: json['phone'] as String,
+      createdAt: DateTime.parse(json['createdAt'] as String),
+    );
+  }
+
+  final String userId;
+  final String username;
+  final String phone;
+  final DateTime createdAt;
+}

lib/features/auth/auth_repository.dart

@@ -0,0 +1,111 @@
+import 'package:patbond_flutter/core/network/api_client.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/auth_models.dart';
+import 'package:patbond_flutter/features/auth/session_manager.dart';
+import 'package:uuid/uuid.dart';
+
+/// Splash 会话恢复的裁决结果。状态切换由 Splash 在最短停留时间后执行。
+enum SessionRestoreResult { authenticated, noSession }
+
+/// 认证仓库接口（页面依赖此抽象，widget 测试注入假实现）。
+abstract class AuthRepository {
+  Future<void> login({required String username, required String password});
+
+  Future<void> register({
+    required String username,
+    required String phone,
+    required String password,
+  });
+
+  /// 撤销当前会话并清除本地凭证。服务端调用失败也保证本地清除。
+  Future<void> logout();
+
+  /// 启动恢复：本地有 refresh token 则静默刷新。
+  /// 网络失败抛 [ApiNetworkException]（token 保留）；
+  /// refresh 失效抛 [SessionExpiredException]（会话已清）。
+  Future<SessionRestoreResult> restoreSession();
+
+  Future<UserProfile> me();
+}
+
+class ApiAuthRepository implements AuthRepository {
+  ApiAuthRepository({
+    required this._api,
+    required this._session,
+    required this._refresher,
+    this._uuid = const Uuid(),
+  });
+
+  final ApiClient _api;
+  final SessionManager _session;
+  final TokenRefresher _refresher;
+  final Uuid _uuid;
+
+  @override
+  Future<void> login({
+    required String username,
+    required String password,
+  }) async {
+    final data = await _api.request(
+      '/api/v1/auth/login',
+      body: {'username': username, 'password': password},
+    );
+    await _session.saveSession(
+      AuthTokens.fromJson(data! as Map<String, dynamic>),
+    );
+  }
+
+  @override
+  Future<void> register({
+    required String username,
+    required String phone,
+    required String password,
+  }) async {
+    final data = await _api.request(
+      '/api/v1/auth/register',
+      body: {'username': username, 'phone': phone, 'password': password},
+      // 每次提交一个幂等键；token 刷新后的自动重放沿用同一个键。
+      headers: {'Idempotency-Key': _uuid.v4()},
+    );
+    await _session.saveSession(
+      AuthTokens.fromJson(data! as Map<String, dynamic>),
+    );
+  }
+
+  @override
+  Future<void> logout() async {
+    final refreshToken = _session.refreshToken;
+    try {
+      await _api.request(
+        '/api/v1/auth/logout',
+        body: {'refreshToken': refreshToken},
+        requiresAuth: true,
+      );
+    } on ApiException {
+      // 服务端撤销失败不阻塞本地登出；refresh 侧最终会自然过期。
+    } finally {
+      await _session.clearSession();
+    }
+  }
+
+  @override
+  Future<SessionRestoreResult> restoreSession() async {
+    await _session.loadFromStorage();
+    if (_session.refreshToken == null) {
+      return SessionRestoreResult.noSession;
+    }
+    await _refresher.refresh();
+    return SessionRestoreResult.authenticated;
+  }
+
+  @override
+  Future<UserProfile> me() async {
+    final data = await _api.request(
+      '/api/v1/me',
+      method: 'GET',
+      requiresAuth: true,
+    );
+    return UserProfile.fromJson(data! as Map<String, dynamic>);
+  }
+}

lib/features/auth/login_page.dart

@@ -0,0 +1,221 @@
+import 'package:flutter/material.dart';
+import 'package:flutter/semantics.dart';
+import 'package:flutter/services.dart';
+import 'package:patbond_flutter/core/navigation/fade_route.dart';
+import 'package:patbond_flutter/core/network/api_exception.dart';
+import 'package:patbond_flutter/core/theme/app_theme.dart';
+import 'package:patbond_flutter/core/widgets/app_text_field.dart';
+import 'package:patbond_flutter/core/widgets/auth_scaffold.dart';
+import 'package:patbond_flutter/core/widgets/brand_mark.dart';
+import 'package:patbond_flutter/core/widgets/inline_error_banner.dart';
+import 'package:patbond_flutter/core/widgets/primary_button.dart';
+import 'package:patbond_flutter/features/auth/auth_repository.dart';
+import 'package:patbond_flutter/features/auth/register_page.dart';
+
+enum _Field { account, password }
+
+/// 登录页（12 号组装稿 §5）。登录成功后由认证状态机切入主壳。
+class LoginPage extends StatefulWidget {
+  const LoginPage({required this.authRepository, super.key});
+
+  final AuthRepository authRepository;
+
+  @override
+  State<LoginPage> createState() => _LoginPageState();
+}
+
+class _LoginPageState extends State<LoginPage> {
+  final _accountCtrl = TextEditingController();
+  final _passwordCtrl = TextEditingController();
+  String? _accountError;
+  String? _passwordError;
+  String? _formError;
+  bool _submitting = false;
+
+  @override
+  void dispose() {
+    _accountCtrl.dispose();
+    _passwordCtrl.dispose();
+    super.dispose();
+  }
+
+  String? _validateAccount() =>
+      _accountCtrl.text.trim().isEmpty ? '请输入用户名或手机号' : null;
+
+  String? _validatePassword() =>
+      _passwordCtrl.text.trim().isEmpty ? '请输入密码' : null;
+
+  void _validateAccountOnBlur() {
+    if (!mounted) return;
+    setState(() => _accountError = _validateAccount());
+  }
+
+  void _validatePasswordOnBlur() {
+    if (!mounted) return;
+    setState(() => _passwordError = _validatePassword());
+  }
+
+  /// 字段变更即清除本字段错误与表单级横幅。
+  void _clearErrors({required _Field field}) {
+    if (_formError == null &&
+        (field == _Field.account ? _accountError : _passwordError) == null) {
+      return;
+    }
+    setState(() {
+      _formError = null;
+      if (field == _Field.account) _accountError = null;
+      if (field == _Field.password) _passwordError = null;
+    });
+  }
+
+  void _showFormError(String message) {
+    setState(() => _formError = message);
+    SemanticsService.sendAnnouncement(
+      View.of(context),
+      message,
+      TextDirection.ltr,
+    );
+  }
+
+  void _showNetworkSnackBar() {
+    ScaffoldMessenger.of(context).showSnackBar(
+      SnackBar(
+        content: const Text('网络异常，请检查网络后重试'),
+        action: SnackBarAction(label: '重试', onPressed: _submit),
+      ),
+    );
+  }
+
+  Future<void> _submit() async {
+    if (_submitting) return;
+    final accountError = _validateAccount();
+    final passwordError = _validatePassword();
+    if (accountError != null || passwordError != null) {
+      setState(() {
+        _accountError = accountError;
+        _passwordError = passwordError;
+      });
+      return;
+    }
+    setState(() {
+      _submitting = true;
+      _formError = null;
+    });
+    try {
+      await widget.authRepository.login(
+        username: _accountCtrl.text.trim(),
+        password: _passwordCtrl.text.trim(),
+      );
+      TextInput.finishAutofillContext();
+      // 认证状态机随 saveSession 切换，根路由 300ms fade 进主壳。
+    } on ApiBusinessException catch (error) {
+      if (!mounted) return;
+      _showFormError(
+        error.code == ApiCodes.badCredentials ? '用户名或密码错误' : '登录失败，请稍后重试',
+      );
+    } on ApiRateLimitException {
+      if (!mounted) return;
+      _showFormError('尝试次数过多，请稍后再试');
+    } on ApiNetworkException {
+      if (!mounted) return;
+      _showNetworkSnackBar();
+    } on SessionExpiredException {
+      // 登录请求不带会话，理论不可达；静默留在登录页。
+    } finally {
+      if (mounted) setState(() => _submitting = false);
+    }
+  }
+
+  void _goRegister() {
+    Navigator.of(context).push(
+      fadePageRoute<void>(RegisterPage(authRepository: widget.authRepository)),
+    );
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return AuthScaffold(
+      child: AutofillGroup(
+        child: Column(
+          // AuthScaffold 内禁用 Spacer，垂直居中用 mainAxisAlignment（§4 总则）。
+          mainAxisAlignment: MainAxisAlignment.center,
+          children: [
+            const SizedBox(height: 48),
+            const BrandMark(),
+            const SizedBox(height: 48),
+            Focus(
+              onFocusChange: (hasFocus) {
+                if (!hasFocus) _validateAccountOnBlur();
+              },
+              child: AppTextField(
+                label: '用户名 / 手机号',
+                controller: _accountCtrl,
+                prefixIcon: Icons.person_outline_rounded,
+                errorText: _accountError,
+                enabled: !_submitting,
+                keyboardType: TextInputType.text,
+                textInputAction: TextInputAction.next,
+                autofillHints: const [AutofillHints.username],
+                onChanged: (_) => _clearErrors(field: _Field.account),
+              ),
+            ),
+            const SizedBox(height: 16),
+            Focus(
+              onFocusChange: (hasFocus) {
+                if (!hasFocus) _validatePasswordOnBlur();
+              },
+              child: AppTextField(
+                label: '密码',
+                controller: _passwordCtrl,
+                prefixIcon: Icons.lock_outline_rounded,
+                obscurable: true,
+                errorText: _passwordError,
+                enabled: !_submitting,
+                textInputAction: TextInputAction.done,
+                autofillHints: const [AutofillHints.password],
+                onChanged: (_) => _clearErrors(field: _Field.password),
+                onSubmitted: (_) => _submit(),
+              ),
+            ),
+            if (_formError != null) ...[
+              const SizedBox(height: 16),
+              InlineErrorBanner(message: _formError!),
+            ],
+            const SizedBox(height: 24),
+            PrimaryButton(
+              label: '登录',
+              isLoading: _submitting,
+              onPressed: _submit,
+            ),
+            const SizedBox(height: 16),
+            Row(
+              mainAxisAlignment: MainAxisAlignment.center,
+              children: [
+                const Text(
+                  '还没有账号？',
+                  style: TextStyle(color: AppColors.muted, fontSize: 14),
+                ),
+                TextButton(
+                  style: TextButton.styleFrom(
+                    foregroundColor: AppColors.primaryStrong,
+                    minimumSize: const Size(44, 44),
+                    padding: const EdgeInsets.symmetric(horizontal: 8),
+                    textStyle: const TextStyle(
+                      fontSize: 14,
+                      fontWeight: FontWeight.w700,
+                    ),
+                  ),
+                  onPressed: _submitting ? null : _goRegister,
+                  child: const Text('立即注册'),
+                ),
+              ],
+            ),
+            const SizedBox(height: 24),
+            // 协议行：v1 协议页未就绪，整行不渲染（组装稿 §5）。
+            // 预留区（短信验证码/第三方登录）：不渲染任何占位（ADR-004）。
+          ],
+        ),
+      ),
+    );
+  }
+}

lib/features/auth/register_page.dart

@@ -0,0 +1,318 @@
+import 'package:flutter/material.dart';
+import 'package:flutter/semantics.dart';
+import 'package:flutter/services.dart';
+import 'package:patbond_flutter/core/network/api_exception.dart';
+import 'package:patbond_flutter/core/theme/app_theme.dart';
+import 'package:patbond_flutter/core/widgets/app_text_field.dart';
+import 'package:patbond_flutter/core/widgets/auth_scaffold.dart';
+import 'package:patbond_flutter/core/widgets/inline_error_banner.dart';
+import 'package:patbond_flutter/core/widgets/primary_button.dart';
+import 'package:patbond_flutter/features/auth/auth_repository.dart';
+
+enum _Field { username, phone, password, confirm }
+
+/// 注册页（12 号组装稿 §6）。字段按 ADR-004：用户名 + 手机号 + 密码 + 确认密码；
+/// 短信验证码行与第三方登录预留区一律不渲染。注册成功即建立会话直接进首页。
+class RegisterPage extends StatefulWidget {
+  const RegisterPage({required this.authRepository, super.key});
+
+  final AuthRepository authRepository;
+
+  @override
+  State<RegisterPage> createState() => _RegisterPageState();
+}
+
+class _RegisterPageState extends State<RegisterPage> {
+  static final _usernamePattern = RegExp(r'^[A-Za-z][A-Za-z0-9_]{2,19}$');
+  static final _phonePattern = RegExp(r'^1\d{10}$');
+
+  final _usernameCtrl = TextEditingController();
+  final _phoneCtrl = TextEditingController();
+  final _passwordCtrl = TextEditingController();
+  final _confirmCtrl = TextEditingController();
+  String? _usernameError;
+  String? _phoneError;
+  String? _passwordError;
+  String? _confirmError;
+  String? _formError;
+  bool _submitting = false;
+
+  @override
+  void dispose() {
+    _usernameCtrl.dispose();
+    _phoneCtrl.dispose();
+    _passwordCtrl.dispose();
+    _confirmCtrl.dispose();
+    super.dispose();
+  }
+
+  String? _validateUsernameValue() {
+    final value = _usernameCtrl.text.trim();
+    if (value.isEmpty) return '请输入用户名';
+    if (!_usernamePattern.hasMatch(value)) {
+      return '用户名需 3–20 位，字母开头，可含数字和下划线';
+    }
+    return null;
+  }
+
+  String? _validatePhoneValue() {
+    final value = _phoneCtrl.text.trim();
+    if (value.isEmpty) return '请输入手机号';
+    if (!_phonePattern.hasMatch(value)) return '请输入正确的 11 位手机号';
+    return null;
+  }
+
+  String? _validatePasswordValue() {
+    final value = _passwordCtrl.text;
+    final lengthOk = value.length >= 8 && value.length <= 32;
+    final hasLetter = value.contains(RegExp('[A-Za-z]'));
+    final hasDigit = value.contains(RegExp('[0-9]'));
+    if (!lengthOk || !hasLetter || !hasDigit) {
+      return '密码需 8–32 位，且同时包含字母和数字';
+    }
+    return null;
+  }
+
+  String? _validateConfirmValue() =>
+      _confirmCtrl.text == _passwordCtrl.text ? null : '两次输入的密码不一致';
+
+  void _validateOnBlur(_Field field) {
+    if (!mounted) return;
+    setState(() {
+      switch (field) {
+        case _Field.username:
+          _usernameError = _validateUsernameValue();
+        case _Field.phone:
+          _phoneError = _validatePhoneValue();
+        case _Field.password:
+          _passwordError = _validatePasswordValue();
+        case _Field.confirm:
+          _confirmError = _validateConfirmValue();
+      }
+    });
+  }
+
+  /// 字段变更清除本字段错误与横幅；密码变更时若确认密码已有值，
+  /// 同步重校验一致性（组装稿 §6）。
+  void _clearError(_Field field) {
+    setState(() {
+      _formError = null;
+      switch (field) {
+        case _Field.username:
+          _usernameError = null;
+        case _Field.phone:
+          _phoneError = null;
+        case _Field.password:
+          _passwordError = null;
+          if (_confirmCtrl.text.isNotEmpty) {
+            _confirmError = _validateConfirmValue();
+          }
+        case _Field.confirm:
+          _confirmError = null;
+      }
+    });
+  }
+
+  void _showFormError(String message) {
+    setState(() => _formError = message);
+    SemanticsService.sendAnnouncement(
+      View.of(context),
+      message,
+      TextDirection.ltr,
+    );
+  }
+
+  Future<void> _submit() async {
+    if (_submitting) return;
+    final usernameError = _validateUsernameValue();
+    final phoneError = _validatePhoneValue();
+    final passwordError = _validatePasswordValue();
+    final confirmError = _validateConfirmValue();
+    if (usernameError != null ||
+        phoneError != null ||
+        passwordError != null ||
+        confirmError != null) {
+      setState(() {
+        _usernameError = usernameError;
+        _phoneError = phoneError;
+        _passwordError = passwordError;
+        _confirmError = confirmError;
+      });
+      return;
+    }
+    setState(() {
+      _submitting = true;
+      _formError = null;
+    });
+    try {
+      await widget.authRepository.register(
+        username: _usernameCtrl.text.trim(),
+        phone: _phoneCtrl.text.trim(),
+        password: _passwordCtrl.text,
+      );
+      TextInput.finishAutofillContext();
+      if (!mounted) return;
+      // 会话已建立，根路由切主壳；弹掉注册页露出新首页，不回登录页。
+      Navigator.of(context).popUntil((route) => route.isFirst);
+    } on ApiBusinessException catch (error) {
+      if (!mounted) return;
+      switch (error.code) {
+        case ApiCodes.usernameTaken:
+          setState(() => _usernameError = '该用户名已被使用');
+        case ApiCodes.phoneTaken:
+          setState(() => _phoneError = '该手机号已注册，可直接登录');
+        default:
+          _showFormError('注册失败，请稍后重试');
+      }
+    } on ApiRateLimitException {
+      if (!mounted) return;
+      _showFormError('尝试次数过多，请稍后再试');
+    } on ApiNetworkException {
+      if (!mounted) return;
+      ScaffoldMessenger.of(context).showSnackBar(
+        SnackBar(
+          content: const Text('网络异常，请检查网络后重试'),
+          action: SnackBarAction(label: '重试', onPressed: _submit),
+        ),
+      );
+    } on SessionExpiredException {
+      // 注册请求不带会话，理论不可达。
+    } finally {
+      if (mounted) setState(() => _submitting = false);
+    }
+  }
+
+  Widget _blurValidated(_Field field, Widget child) {
+    return Focus(
+      onFocusChange: (hasFocus) {
+        if (!hasFocus) _validateOnBlur(field);
+      },
+      child: child,
+    );
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return AuthScaffold(
+      appBar: AppBar(
+        backgroundColor: Colors.transparent,
+        elevation: 0,
+        scrolledUnderElevation: 0,
+        foregroundColor: AppColors.ink,
+      ),
+      child: AutofillGroup(
+        child: Column(
+          crossAxisAlignment: CrossAxisAlignment.start,
+          children: [
+            const SizedBox(height: 8),
+            Text('创建账号', style: Theme.of(context).textTheme.headlineSmall),
+            const SizedBox(height: 8),
+            Text(
+              '加入 Patbond，记录毛孩子的每一天',
+              style: Theme.of(context).textTheme.bodySmall,
+            ),
+            const SizedBox(height: 32),
+            _blurValidated(
+              _Field.username,
+              AppTextField(
+                label: '用户名',
+                controller: _usernameCtrl,
+                prefixIcon: Icons.person_outline_rounded,
+                errorText: _usernameError,
+                enabled: !_submitting,
+                textInputAction: TextInputAction.next,
+                autofillHints: const [AutofillHints.newUsername],
+                onChanged: (_) => _clearError(_Field.username),
+              ),
+            ),
+            const SizedBox(height: 16),
+            _blurValidated(
+              _Field.phone,
+              AppTextField(
+                label: '手机号',
+                controller: _phoneCtrl,
+                prefixIcon: Icons.phone_iphone_rounded,
+                errorText: _phoneError,
+                enabled: !_submitting,
+                keyboardType: TextInputType.phone,
+                textInputAction: TextInputAction.next,
+                autofillHints: const [AutofillHints.telephoneNumber],
+                onChanged: (_) => _clearError(_Field.phone),
+              ),
+            ),
+            const SizedBox(height: 16),
+            _blurValidated(
+              _Field.password,
+              AppTextField(
+                label: '密码',
+                controller: _passwordCtrl,
+                prefixIcon: Icons.lock_outline_rounded,
+                obscurable: true,
+                errorText: _passwordError,
+                helperText: '密码 8–32 位，需包含字母和数字',
+                enabled: !_submitting,
+                textInputAction: TextInputAction.next,
+                autofillHints: const [AutofillHints.newPassword],
+                onChanged: (_) => _clearError(_Field.password),
+              ),
+            ),
+            const SizedBox(height: 16),
+            _blurValidated(
+              _Field.confirm,
+              AppTextField(
+                label: '确认密码',
+                controller: _confirmCtrl,
+                prefixIcon: Icons.lock_outline_rounded,
+                obscurable: true,
+                errorText: _confirmError,
+                enabled: !_submitting,
+                textInputAction: TextInputAction.done,
+                autofillHints: const [AutofillHints.newPassword],
+                onChanged: (_) => _clearError(_Field.confirm),
+                onSubmitted: (_) => _submit(),
+              ),
+            ),
+            if (_formError != null) ...[
+              const SizedBox(height: 16),
+              InlineErrorBanner(message: _formError!),
+            ],
+            const SizedBox(height: 32),
+            PrimaryButton(
+              label: '注册',
+              isLoading: _submitting,
+              onPressed: _submit,
+            ),
+            const SizedBox(height: 16),
+            Center(
+              child: Row(
+                mainAxisSize: MainAxisSize.min,
+                children: [
+                  const Text(
+                    '已有账号？',
+                    style: TextStyle(color: AppColors.muted, fontSize: 14),
+                  ),
+                  TextButton(
+                    style: TextButton.styleFrom(
+                      foregroundColor: AppColors.primaryStrong,
+                      minimumSize: const Size(44, 44),
+                      padding: const EdgeInsets.symmetric(horizontal: 8),
+                      textStyle: const TextStyle(
+                        fontSize: 14,
+                        fontWeight: FontWeight.w700,
+                      ),
+                    ),
+                    onPressed: _submitting
+                        ? null
+                        : () => Navigator.of(context).pop(),
+                    child: const Text('直接登录'),
+                  ),
+                ],
+              ),
+            ),
+            const SizedBox(height: 24),
+          ],
+        ),
+      ),
+    );
+  }
+}

lib/features/auth/session_manager.dart

@@ -0,0 +1,159 @@
+import 'package:flutter/foundation.dart';
+import 'package:flutter_secure_storage/flutter_secure_storage.dart';
+import 'package:patbond_flutter/features/auth/auth_models.dart';
+import 'package:uuid/uuid.dart';
+
+/// 认证状态机：unknown（启动恢复中，停留 Splash）→ authenticated / unauthenticated。
+enum AuthStatus { unknown, authenticated, unauthenticated }
+
+/// token 持久化抽象。生产实现走系统安全存储（Keychain / Keystore），
+/// 测试注入内存实现。token 绝不写入 SharedPreferences（开发计划 §4.2）。
+abstract class TokenStore {
+  Future<String?> read(String key);
+  Future<void> write(String key, String value);
+  Future<void> delete(String key);
+}
+
+/// 基于 flutter_secure_storage 的生产实现。
+class SecureTokenStore implements TokenStore {
+  const SecureTokenStore([this._storage = const FlutterSecureStorage()]);
+
+  final FlutterSecureStorage _storage;
+
+  @override
+  Future<String?> read(String key) => _storage.read(key: key);
+
+  @override
+  Future<void> write(String key, String value) =>
+      _storage.write(key: key, value: value);
+
+  @override
+  Future<void> delete(String key) => _storage.delete(key: key);
+}
+
+/// 会话管理：token 的内存副本 + 安全存储持久化 + 认证状态广播。
+///
+/// 状态变更只通过 [saveSession]（登录/注册成功）、[markAuthenticated] /
+/// [markUnauthenticated]（Splash 恢复裁决）与 [clearSession]（登出/会话失效）。
+/// TokenRefresher 轮换 token 用 [updateTokens]，不改状态——
+/// Splash 需要在最短停留时间后才切页（12 号组装稿 §7）。
+class SessionManager extends ChangeNotifier {
+  SessionManager({required this._store, this._uuid = const Uuid()});
+
+  static const _accessTokenKey = 'patbond_access_token';
+  static const _refreshTokenKey = 'patbond_refresh_token';
+  static const _accessExpiresKey = 'patbond_access_token_expires_at';
+  static const _refreshExpiresKey = 'patbond_refresh_token_expires_at';
+  static const _userIdKey = 'patbond_user_id';
+  static const _deviceIdKey = 'patbond_device_id';
+
+  final TokenStore _store;
+  final Uuid _uuid;
+
+  AuthStatus _status = AuthStatus.unknown;
+  String? _accessToken;
+  String? _refreshToken;
+  String? _userId;
+  String? _deviceId;
+  bool _loaded = false;
+
+  AuthStatus get status => _status;
+  String? get accessToken => _accessToken;
+  String? get refreshToken => _refreshToken;
+  String? get userId => _userId;
+
+  /// 设备标识：首次生成 UUID 并持久化，跨会话稳定。
+  String? get deviceId => _deviceId;
+
+  /// 从安全存储载入 token 到内存（幂等）。存储读取失败按无会话处理，
+  /// 不阻塞启动。
+  Future<void> loadFromStorage() async {
+    if (_loaded) return;
+    _accessToken = await _readOrNull(_accessTokenKey);
+    _refreshToken = await _readOrNull(_refreshTokenKey);
+    _userId = await _readOrNull(_userIdKey);
+    _deviceId = await _readOrNull(_deviceIdKey);
+    if (_deviceId == null) {
+      _deviceId = _uuid.v4();
+      await _writeQuietly(_deviceIdKey, _deviceId!);
+    }
+    _loaded = true;
+  }
+
+  /// 登录/注册成功：持久化整套 token 并进入已认证态。
+  Future<void> saveSession(AuthTokens tokens) async {
+    await updateTokens(tokens);
+    _status = AuthStatus.authenticated;
+    notifyListeners();
+  }
+
+  /// 仅写入/轮换 token，不改变认证状态（刷新流程用）。
+  Future<void> updateTokens(AuthTokens tokens) async {
+    _accessToken = tokens.accessToken;
+    _refreshToken = tokens.refreshToken;
+    _userId = tokens.userId;
+    _loaded = true;
+    await _writeQuietly(_accessTokenKey, tokens.accessToken);
+    await _writeQuietly(_refreshTokenKey, tokens.refreshToken);
+    await _writeQuietly(
+      _accessExpiresKey,
+      tokens.accessTokenExpiresAt.toIso8601String(),
+    );
+    await _writeQuietly(
+      _refreshExpiresKey,
+      tokens.refreshTokenExpiresAt.toIso8601String(),
+    );
+    await _writeQuietly(_userIdKey, tokens.userId);
+  }
+
+  /// Splash 恢复成功后的显式切态。
+  void markAuthenticated() {
+    _status = AuthStatus.authenticated;
+    notifyListeners();
+  }
+
+  /// 无本地会话或用户选择改用账号登录。
+  void markUnauthenticated() {
+    _status = AuthStatus.unauthenticated;
+    notifyListeners();
+  }
+
+  /// 清除会话（登出 / refresh 失效）。设备标识保留。
+  Future<void> clearSession() async {
+    _accessToken = null;
+    _refreshToken = null;
+    _userId = null;
+    _status = AuthStatus.unauthenticated;
+    notifyListeners();
+    for (final key in const [
+      _accessTokenKey,
+      _refreshTokenKey,
+      _accessExpiresKey,
+      _refreshExpiresKey,
+      _userIdKey,
+    ]) {
+      try {
+        await _store.delete(key);
+      } catch (error) {
+        debugPrint('清除会话存储失败（$key）：$error');
+      }
+    }
+  }
+
+  Future<String?> _readOrNull(String key) async {
+    try {
+      return await _store.read(key);
+    } catch (error) {
+      debugPrint('读取安全存储失败（$key）：$error');
+      return null;
+    }
+  }
+
+  Future<void> _writeQuietly(String key, String value) async {
+    try {
+      await _store.write(key, value);
+    } catch (error) {
+      debugPrint('写入安全存储失败（$key）：$error');
+    }
+  }
+}

lib/features/auth/splash_page.dart

@@ -0,0 +1,147 @@
+import 'dart:async';
+
+import 'package:flutter/material.dart';
+import 'package:patbond_flutter/core/network/api_exception.dart';
+import 'package:patbond_flutter/core/theme/app_theme.dart';
+import 'package:patbond_flutter/core/widgets/brand_mark.dart';
+import 'package:patbond_flutter/features/auth/auth_repository.dart';
+import 'package:patbond_flutter/features/auth/session_manager.dart';
+
+enum _SplashState { checking, failed }
+
+/// 启动 Splash（12 号组装稿 §7）：静默恢复会话。
+///
+/// 流程约束：最短停留 500ms；刷新超时 5s；spinner 等待超过 300ms 才出现；
+/// 网络失败不清除本地 refresh token（只有服务端明确 401/40102 才清）。
+class SplashPage extends StatefulWidget {
+  const SplashPage({
+    required this.authRepository,
+    required this.sessionManager,
+    super.key,
+  });
+
+  final AuthRepository authRepository;
+  final SessionManager sessionManager;
+
+  @override
+  State<SplashPage> createState() => _SplashPageState();
+}
+
+class _SplashPageState extends State<SplashPage> {
+  _SplashState _state = _SplashState.checking;
+  bool _showSpinner = false;
+  Timer? _spinnerTimer;
+
+  @override
+  void initState() {
+    super.initState();
+    _restore();
+  }
+
+  @override
+  void dispose() {
+    _spinnerTimer?.cancel();
+    super.dispose();
+  }
+
+  Future<void> _restore() async {
+    _spinnerTimer?.cancel();
+    _spinnerTimer = Timer(const Duration(milliseconds: 300), () {
+      if (mounted) setState(() => _showSpinner = true);
+    });
+    final minStay = Future<void>.delayed(const Duration(milliseconds: 500));
+    try {
+      final result = await widget.authRepository.restoreSession().timeout(
+        const Duration(seconds: 5),
+      );
+      await minStay;
+      if (!mounted) return;
+      switch (result) {
+        case SessionRestoreResult.authenticated:
+          widget.sessionManager.markAuthenticated();
+        case SessionRestoreResult.noSession:
+          widget.sessionManager.markUnauthenticated();
+      }
+    } on SessionExpiredException {
+      // refresh 已被服务端判失效，会话已清、状态机已切换，无需处理。
+    } catch (_) {
+      // 网络失败 / 超时：token 保留，转错误态供重试。
+      await minStay;
+      if (!mounted) return;
+      setState(() {
+        _state = _SplashState.failed;
+        _showSpinner = false;
+      });
+    }
+  }
+
+  void _retryRefresh() {
+    setState(() {
+      _state = _SplashState.checking;
+      _showSpinner = false;
+    });
+    _restore();
+  }
+
+  Future<void> _clearCredentialsAndGoLogin() async {
+    // 逃生通道：放弃本地凭证，改用账号登录。
+    await widget.sessionManager.clearSession();
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      backgroundColor: AppColors.canvas,
+      body: Center(
+        child: _state == _SplashState.checking
+            ? Column(
+                mainAxisSize: MainAxisSize.min,
+                children: [
+                  const BrandMark(),
+                  const SizedBox(height: 32),
+                  // 占位保高度，spinner 出现时不跳动。
+                  SizedBox.square(
+                    dimension: 20,
+                    child: _showSpinner
+                        ? const CircularProgressIndicator(
+                            strokeWidth: 2.5,
+                            color: AppColors.primary,
+                          )
+                        : null,
+                  ),
+                ],
+              )
+            : Column(
+                mainAxisSize: MainAxisSize.min,
+                children: [
+                  const BrandMark(),
+                  const SizedBox(height: 24),
+                  const Text(
+                    '网络连接失败，无法恢复登录',
+                    style: TextStyle(color: AppColors.ink, fontSize: 14),
+                  ),
+                  const SizedBox(height: 16),
+                  OutlinedButton(
+                    style: OutlinedButton.styleFrom(
+                      minimumSize: const Size(120, 44),
+                      foregroundColor: AppColors.primaryStrong,
+                      side: const BorderSide(color: AppColors.border),
+                    ),
+                    onPressed: _retryRefresh,
+                    child: const Text('重试'),
+                  ),
+                  const SizedBox(height: 8),
+                  TextButton(
+                    style: TextButton.styleFrom(
+                      foregroundColor: AppColors.primaryStrong,
+                      minimumSize: const Size(44, 44),
+                    ),
+                    onPressed: _clearCredentialsAndGoLogin,
+                    child: const Text('改用账号登录'),
+                  ),
+                ],
+              ),
+      ),
+    );
+  }
+}

lib/features/home/home_page.dart

@@ -619,7 +619,10 @@ class _PromoCard extends StatelessWidget {
     return Container(
       padding: const EdgeInsets.all(20),
       decoration: BoxDecoration(
-        gradient: AppColors.brandGradient,
+        // 深端在左承载白字（4.5:1 达标）；brandGradient 不承载正文文字（FIX-1）。
+        gradient: const LinearGradient(
+          colors: [AppColors.primaryStrong, AppColors.primary],
+        ),
         borderRadius: BorderRadius.circular(26),
       ),
       child: Row(

lib/features/main/main_shell_page.dart

@@ -11,10 +11,13 @@ import 'package:patbond_flutter/state/app_state.dart';
 import 'package:patbond_flutter/widgets/common.dart';
 
 class MainShellPage extends StatefulWidget {
-  const MainShellPage({required this.appState, super.key});
+  const MainShellPage({required this.appState, super.key, this.onLogout});
 
   final AppState appState;
 
+  /// 退出登录：调 logout 接口并清会话，认证状态机自动回登录页。
+  final Future<void> Function()? onLogout;
+
   @override
   State<MainShellPage> createState() => _MainShellPageState();
 }
@@ -77,7 +80,7 @@ class _MainShellPageState extends State<MainShellPage> {
             showPersonal: showPersonalServices,
             locationWeather: widget.appState.locationWeather,
           ),
-          ProfilePage(appState: widget.appState),
+          ProfilePage(appState: widget.appState, onLogout: widget.onLogout),
         ];
 
         return Scaffold(

lib/features/profile/profile_page.dart

@@ -5,10 +5,13 @@ import 'package:patbond_flutter/state/app_state.dart';
 import 'package:patbond_flutter/widgets/common.dart';
 
 class ProfilePage extends StatelessWidget {
-  const ProfilePage({required this.appState, super.key});
+  const ProfilePage({required this.appState, super.key, this.onLogout});
 
   final AppState appState;
 
+  /// 真实退出登录入口；未接线时保持演示提示。
+  final Future<void> Function()? onLogout;
+
   static const menuItems = [
     (Icons.assignment_outlined, '我的预约订单', '查看进行中与历史服务'),
     (Icons.bookmarks_outlined, '我的收藏与草稿', '已保存的宠物作品与攻略'),
@@ -133,7 +136,7 @@ class ProfilePage extends StatelessWidget {
         ),
         const SizedBox(height: 10),
         TextButton(
-          onPressed: () => showDemoMessage(context, '退出登录'),
+          onPressed: onLogout ?? () => showDemoMessage(context, '退出登录'),
           child: const Text('切换账号或退出登录'),
         ),
       ],