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>
This commit is contained in:
2026-09-04 11:52:51 +08:00
parent ee77361b92
commit 8d890c0424
30 changed files with 2306 additions and 9 deletions
+111
View File
@@ -0,0 +1,111 @@
import 'package:dio/dio.dart';
import 'package:flutter_test/flutter_test.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';
import '../../helpers/auth_test_helpers.dart';
void main() {
late SessionManager session;
late Dio dio;
late FakeHttpAdapter adapter;
late TokenRefresher refresher;
Future<void> setUpWith(
Future<ResponseBody> Function(RequestOptions) handler, {
bool seedTokens = true,
}) async {
session = SessionManager(store: InMemoryTokenStore());
if (seedTokens) {
await session.updateTokens(
sampleTokens(access: 'old-access', refresh: 'old-refresh'),
);
}
dio = Dio(BaseOptions(validateStatus: (_) => true));
adapter = FakeHttpAdapter(handler);
dio.httpClientAdapter = adapter;
refresher = TokenRefresher(dio: dio, session: session);
}
test('并发触发只发出一次刷新请求(单飞),并轮换 token', () async {
await setUpWith((options) async {
await Future<void>.delayed(const Duration(milliseconds: 20));
return jsonResponse(
200,
okEnvelope(tokenDataJson(access: 'new-access', refresh: 'new-refresh')),
);
});
await Future.wait([refresher.refresh(), refresher.refresh()]);
expect(adapter.requests, hasLength(1));
expect(adapter.requests.single.path, '/api/v1/auth/refresh');
expect(adapter.requests.single.data, {'refreshToken': 'old-refresh'});
expect(session.accessToken, 'new-access');
expect(session.refreshToken, 'new-refresh');
});
test('40102 清除会话并抛 SessionExpiredException', () async {
await setUpWith(
(options) async =>
jsonResponse(401, errorEnvelope(40102, 'refresh token 已失效')),
);
await expectLater(
refresher.refresh(),
throwsA(isA<SessionExpiredException>()),
);
expect(session.accessToken, isNull);
expect(session.refreshToken, isNull);
expect(session.status, AuthStatus.unauthenticated);
});
test('网络失败不清除本地 token,抛 ApiNetworkException', () async {
await setUpWith((options) async {
throw DioException(
requestOptions: options,
type: DioExceptionType.connectionTimeout,
);
});
await expectLater(refresher.refresh(), throwsA(isA<ApiNetworkException>()));
expect(session.refreshToken, 'old-refresh');
expect(session.accessToken, 'old-access');
});
test('上一次刷新结束后单飞复位,可再次刷新', () async {
var calls = 0;
await setUpWith((options) async {
calls += 1;
if (calls == 1) {
throw DioException(
requestOptions: options,
type: DioExceptionType.connectionError,
);
}
return jsonResponse(
200,
okEnvelope(tokenDataJson(access: 'a2', refresh: 'r2')),
);
});
await expectLater(refresher.refresh(), throwsA(isA<ApiNetworkException>()));
await refresher.refresh();
expect(calls, 2);
expect(session.refreshToken, 'r2');
});
test('本地无 refresh token 时直接判会话失效', () async {
await setUpWith(
(options) async => jsonResponse(200, okEnvelope(tokenDataJson())),
seedTokens: false,
);
await expectLater(
refresher.refresh(),
throwsA(isA<SessionExpiredException>()),
);
expect(adapter.requests, isEmpty);
});
}
@@ -0,0 +1,216 @@
import 'package:dio/dio.dart';
import 'package:flutter_test/flutter_test.dart';
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_repository.dart';
import 'package:patbond_flutter/features/auth/session_manager.dart';
import '../../helpers/auth_test_helpers.dart';
void main() {
late SessionManager session;
late FakeHttpAdapter adapter;
late ApiAuthRepository repository;
Future<void> setUpWith(
Future<ResponseBody> Function(RequestOptions) handler, {
bool seedTokens = false,
}) async {
session = SessionManager(store: InMemoryTokenStore());
if (seedTokens) {
await session.updateTokens(
sampleTokens(access: 'old-access', refresh: 'old-refresh'),
);
}
final dio = buildPatbondDio(session: session, baseUrl: 'http://test.local');
adapter = FakeHttpAdapter(handler);
dio.httpClientAdapter = adapter;
final refresher = TokenRefresher(dio: dio, session: session);
repository = ApiAuthRepository(
api: ApiClient(dio: dio, session: session, refresher: refresher),
session: session,
refresher: refresher,
);
}
test('登录成功:按契约发请求并把 token 存入会话', () async {
await setUpWith(
(options) async => jsonResponse(
200,
okEnvelope(tokenDataJson(access: 'a1', refresh: 'r1')),
),
);
await repository.login(username: 'gunnar', password: 'passw0rd');
final request = adapter.requests.single;
expect(request.path, '/api/v1/auth/login');
expect(request.method, 'POST');
expect(request.data, {'username': 'gunnar', 'password': 'passw0rd'});
expect(session.accessToken, 'a1');
expect(session.refreshToken, 'r1');
expect(session.userId, 'user-1');
expect(session.status, AuthStatus.authenticated);
});
test('登录 40100:抛业务异常且不建立会话', () async {
await setUpWith(
(options) async => jsonResponse(401, errorEnvelope(40100, '用户名或密码错误')),
);
await expectLater(
repository.login(username: 'gunnar', password: 'wrong'),
throwsA(
isA<ApiBusinessException>().having(
(e) => e.code,
'code',
ApiCodes.badCredentials,
),
),
);
expect(session.status, AuthStatus.unknown);
expect(session.accessToken, isNull);
});
test('注册:携带 Idempotency-Key40900 映射为业务异常', () async {
await setUpWith(
(options) async => jsonResponse(409, errorEnvelope(40900, '用户名重复')),
);
await expectLater(
repository.register(
username: 'gunnar',
phone: '13800138000',
password: 'passw0rd',
),
throwsA(
isA<ApiBusinessException>().having(
(e) => e.code,
'code',
ApiCodes.usernameTaken,
),
),
);
final request = adapter.requests.single;
expect(request.path, '/api/v1/auth/register');
expect(request.data, {
'username': 'gunnar',
'phone': '13800138000',
'password': 'passw0rd',
});
expect(request.headers['Idempotency-Key'], isNotEmpty);
});
test('鉴权请求 40101:单飞刷新后重放一次并携带新 token', () async {
await setUpWith(seedTokens: true, (options) async {
if (options.path == '/api/v1/me') {
final auth = options.headers['Authorization'];
if (auth == 'Bearer old-access') {
return jsonResponse(401, errorEnvelope(40101, 'access token 过期'));
}
return jsonResponse(
200,
okEnvelope({
'userId': 'user-1',
'username': 'gunnar',
'phone': '13800138000',
'createdAt': '2026-09-01T10:00:00+08:00',
}),
);
}
return jsonResponse(
200,
okEnvelope(tokenDataJson(access: 'new-access', refresh: 'new-refresh')),
);
});
final profile = await repository.me();
expect(profile.username, 'gunnar');
expect(adapter.requests.map((r) => r.path).toList(), [
'/api/v1/me',
'/api/v1/auth/refresh',
'/api/v1/me',
]);
expect(adapter.requests.last.headers['Authorization'], 'Bearer new-access');
});
test('刷新后重放仍 401:清会话并抛 SessionExpiredException', () async {
await setUpWith(seedTokens: true, (options) async {
if (options.path == '/api/v1/me') {
return jsonResponse(401, errorEnvelope(40101, 'access token 无效'));
}
return jsonResponse(200, okEnvelope(tokenDataJson()));
});
await expectLater(repository.me(), throwsA(isA<SessionExpiredException>()));
expect(session.refreshToken, isNull);
expect(session.status, AuthStatus.unauthenticated);
});
test('登出:服务端网络失败也保证本地会话清除', () async {
await setUpWith(seedTokens: true, (options) async {
throw DioException(
requestOptions: options,
type: DioExceptionType.connectionError,
);
});
session.markAuthenticated();
await repository.logout();
expect(session.accessToken, isNull);
expect(session.refreshToken, isNull);
expect(session.status, AuthStatus.unauthenticated);
});
test('会话恢复:无 refresh token 返回 noSession,不发请求', () async {
await setUpWith(
(options) async => jsonResponse(200, okEnvelope(tokenDataJson())),
);
final result = await repository.restoreSession();
expect(result, SessionRestoreResult.noSession);
expect(adapter.requests, isEmpty);
});
test('会话恢复:有 refresh token 时静默刷新并返回 authenticated', () async {
await setUpWith(
seedTokens: true,
(options) async => jsonResponse(
200,
okEnvelope(tokenDataJson(access: 'a2', refresh: 'r2')),
),
);
final result = await repository.restoreSession();
expect(result, SessionRestoreResult.authenticated);
expect(adapter.requests.single.path, '/api/v1/auth/refresh');
expect(session.accessToken, 'a2');
});
test('5xx 归为系统错误 ApiNetworkException', () async {
await setUpWith(
(options) async => jsonResponse(500, {'error': 'Internal Server Error'}),
);
await expectLater(
repository.login(username: 'gunnar', password: 'passw0rd'),
throwsA(isA<ApiNetworkException>()),
);
});
test('HTTP 429 映射为 ApiRateLimitException', () async {
await setUpWith(
(options) async => jsonResponse(429, errorEnvelope(42900, '限流')),
);
await expectLater(
repository.login(username: 'gunnar', password: 'passw0rd'),
throwsA(isA<ApiRateLimitException>()),
);
});
}
+99
View File
@@ -0,0 +1,99 @@
import 'dart:async';
import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.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/inline_error_banner.dart';
import 'package:patbond_flutter/features/auth/auth_repository.dart';
import 'package:patbond_flutter/features/auth/login_page.dart';
import '../../helpers/auth_test_helpers.dart';
void main() {
Future<void> pumpLogin(WidgetTester tester, AuthRepository repository) {
return tester.pumpWidget(
MaterialApp(
theme: buildAppTheme(),
home: LoginPage(authRepository: repository),
),
);
}
Future<void> fillValidInput(WidgetTester tester) async {
await tester.enterText(find.byType(TextFormField).at(0), 'gunnar');
await tester.enterText(find.byType(TextFormField).at(1), 'passw0rd');
}
testWidgets('初始态:品牌区、两个输入框、登录按钮与注册链接,无错误无 loading', (tester) async {
await pumpLogin(tester, FakeAuthRepository());
expect(find.text('Patbond'), findsOneWidget);
expect(find.text('用户名 / 手机号'), findsOneWidget);
expect(find.text('密码'), findsOneWidget);
expect(find.text('登录'), findsOneWidget);
expect(find.text('立即注册'), findsOneWidget);
expect(find.byType(InlineErrorBanner), findsNothing);
expect(find.byType(CircularProgressIndicator), findsNothing);
});
testWidgets('loading 态:按钮转圈、字段禁用、注册链接不可点', (tester) async {
final completer = Completer<void>();
final repository = FakeAuthRepository(loginHandler: () => completer.future);
await pumpLogin(tester, repository);
await fillValidInput(tester);
await tester.tap(find.text('登录'));
await tester.pump();
expect(find.byType(CircularProgressIndicator), findsOneWidget);
final fields = tester.widgetList<TextFormField>(find.byType(TextFormField));
expect(fields.every((field) => field.enabled == false), isTrue);
final registerLink = tester.widget<TextButton>(
find.widgetWithText(TextButton, '立即注册'),
);
expect(registerLink.onPressed, isNull);
completer.complete();
await tester.pumpAndSettle();
expect(find.byType(CircularProgressIndicator), findsNothing);
});
testWidgets('字段错误态:空表单提交显示两条字段级错误,输入即清除', (tester) async {
final repository = FakeAuthRepository();
await pumpLogin(tester, repository);
await tester.tap(find.text('登录'));
await tester.pump();
expect(find.text('请输入用户名或手机号'), findsOneWidget);
expect(find.text('请输入密码'), findsOneWidget);
expect(repository.loginCalls, 0);
await tester.enterText(find.byType(TextFormField).at(0), 'g');
await tester.pump();
expect(find.text('请输入用户名或手机号'), findsNothing);
expect(find.text('请输入密码'), findsOneWidget);
});
testWidgets('横幅错误态:40100 显示「用户名或密码错误」,任一字段输入即清除', (tester) async {
final repository = FakeAuthRepository(
loginHandler: () => Future.error(
const ApiBusinessException(code: ApiCodes.badCredentials, message: ''),
),
);
await pumpLogin(tester, repository);
await fillValidInput(tester);
await tester.tap(find.text('登录'));
await tester.pumpAndSettle();
expect(find.byType(InlineErrorBanner), findsOneWidget);
expect(find.text('用户名或密码错误'), findsOneWidget);
expect(repository.loginCalls, 1);
await tester.enterText(find.byType(TextFormField).at(1), 'changed1');
await tester.pump();
expect(find.byType(InlineErrorBanner), findsNothing);
});
}
@@ -0,0 +1,78 @@
import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:patbond_flutter/core/theme/app_theme.dart';
import 'package:patbond_flutter/features/auth/register_page.dart';
import '../../helpers/auth_test_helpers.dart';
void main() {
Future<void> pumpRegister(
WidgetTester tester,
FakeAuthRepository repository,
) {
return tester.pumpWidget(
MaterialApp(
theme: buildAppTheme(),
home: RegisterPage(authRepository: repository),
),
);
}
testWidgets('渲染四个字段与 helperText,不渲染任何预留区', (tester) async {
await pumpRegister(tester, FakeAuthRepository());
expect(find.text('创建账号'), findsOneWidget);
expect(find.byType(TextFormField), findsNWidgets(4));
expect(find.text('密码 832 位,需包含字母和数字'), findsOneWidget);
// ADR-004:短信验证码与第三方登录预留区不渲染。
expect(find.textContaining('验证码'), findsNothing);
expect(find.text('注册'), findsOneWidget);
expect(find.text('直接登录'), findsOneWidget);
});
testWidgets('空表单提交:非空校验拦截,不发请求', (tester) async {
final repository = FakeAuthRepository();
await pumpRegister(tester, repository);
await tester.tap(find.text('注册'));
await tester.pump();
expect(find.text('请输入用户名'), findsOneWidget);
expect(find.text('请输入手机号'), findsOneWidget);
expect(find.text('密码需 8–32 位,且同时包含字母和数字'), findsOneWidget);
expect(repository.registerCalls, 0);
});
testWidgets('格式校验:用户名/手机号/密码/确认密码逐项报错', (tester) async {
final repository = FakeAuthRepository();
await pumpRegister(tester, repository);
await tester.enterText(find.byType(TextFormField).at(0), '1abc');
await tester.enterText(find.byType(TextFormField).at(1), '23800138000');
await tester.enterText(find.byType(TextFormField).at(2), 'abcdefgh');
await tester.enterText(find.byType(TextFormField).at(3), 'abcdefg1');
await tester.tap(find.text('注册'));
await tester.pump();
expect(find.text('用户名需 3–20 位,字母开头,可含数字和下划线'), findsOneWidget);
expect(find.text('请输入正确的 11 位手机号'), findsOneWidget);
expect(find.text('密码需 8–32 位,且同时包含字母和数字'), findsOneWidget);
expect(find.text('两次输入的密码不一致'), findsOneWidget);
expect(repository.registerCalls, 0);
});
testWidgets('全部合法:提交调用注册接口', (tester) async {
final repository = FakeAuthRepository();
await pumpRegister(tester, repository);
await tester.enterText(find.byType(TextFormField).at(0), 'gunnar');
await tester.enterText(find.byType(TextFormField).at(1), '13800138000');
await tester.enterText(find.byType(TextFormField).at(2), 'passw0rd');
await tester.enterText(find.byType(TextFormField).at(3), 'passw0rd');
await tester.tap(find.text('注册'));
await tester.pumpAndSettle();
expect(repository.registerCalls, 1);
expect(find.text('两次输入的密码不一致'), findsNothing);
});
}
+128
View File
@@ -0,0 +1,128 @@
import 'dart:convert';
import 'dart:typed_data';
import 'package:dio/dio.dart';
import 'package:patbond_flutter/features/auth/auth_models.dart';
import 'package:patbond_flutter/features/auth/auth_repository.dart';
import 'package:patbond_flutter/features/auth/session_manager.dart';
/// 测试用内存 token 存储。
class InMemoryTokenStore implements TokenStore {
final Map<String, String> values = {};
@override
Future<String?> read(String key) async => values[key];
@override
Future<void> write(String key, String value) async => values[key] = value;
@override
Future<void> delete(String key) async => values.remove(key);
}
/// 测试用假认证仓库:各方法可注入行为,默认成功空实现。
class FakeAuthRepository implements AuthRepository {
FakeAuthRepository({
this.loginHandler,
this.registerHandler,
this.restoreHandler,
});
final Future<void> Function()? loginHandler;
final Future<void> Function()? registerHandler;
final Future<SessionRestoreResult> Function()? restoreHandler;
int loginCalls = 0;
int registerCalls = 0;
int logoutCalls = 0;
@override
Future<void> login({required String username, required String password}) {
loginCalls += 1;
return loginHandler?.call() ?? Future.value();
}
@override
Future<void> register({
required String username,
required String phone,
required String password,
}) {
registerCalls += 1;
return registerHandler?.call() ?? Future.value();
}
@override
Future<void> logout() async {
logoutCalls += 1;
}
@override
Future<SessionRestoreResult> restoreSession() {
return restoreHandler?.call() ??
Future.value(SessionRestoreResult.noSession);
}
@override
Future<UserProfile> me() async => throw UnimplementedError();
}
/// mock dio:用假 HttpClientAdapter 返回预设响应并记录请求。
class FakeHttpAdapter implements HttpClientAdapter {
FakeHttpAdapter(this.handler);
final Future<ResponseBody> Function(RequestOptions options) handler;
final List<RequestOptions> requests = [];
@override
Future<ResponseBody> fetch(
RequestOptions options,
Stream<Uint8List>? requestStream,
Future<void>? cancelFuture,
) {
requests.add(options);
return handler(options);
}
@override
void close({bool force = false}) {}
}
ResponseBody jsonResponse(int statusCode, Map<String, Object?> body) {
return ResponseBody.fromString(
jsonEncode(body),
statusCode,
headers: {
Headers.contentTypeHeader: [Headers.jsonContentType],
},
);
}
Map<String, Object?> okEnvelope(Map<String, Object?> data) => {
'code': 0,
'message': 'ok',
'data': data,
};
Map<String, Object?> errorEnvelope(int code, [String message = 'error']) => {
'code': code,
'message': message,
'data': null,
};
Map<String, dynamic> tokenDataJson({
String access = 'access-1',
String refresh = 'refresh-1',
}) => {
'userId': 'user-1',
'tokenType': 'Bearer',
'accessToken': access,
'accessTokenExpiresAt': '2026-09-04T13:00:00+08:00',
'refreshToken': refresh,
'refreshTokenExpiresAt': '2026-10-04T12:00:00+08:00',
};
AuthTokens sampleTokens({
String access = 'access-0',
String refresh = 'refresh-0',
}) => AuthTokens.fromJson(tokenDataJson(access: access, refresh: refresh));
+8 -1
View File
@@ -1,12 +1,19 @@
import 'package:flutter_test/flutter_test.dart';
import 'package:patbond_flutter/app/app.dart';
import 'package:patbond_flutter/features/auth/session_manager.dart';
import 'package:shared_preferences/shared_preferences.dart';
import 'helpers/auth_test_helpers.dart';
void main() {
testWidgets('Patbond renders the main navigation', (tester) async {
SharedPreferences.setMockInitialValues({});
final session = SessionManager(store: InMemoryTokenStore())
..markAuthenticated();
await tester.pumpWidget(const App());
await tester.pumpWidget(
App(sessionManager: session, authRepository: FakeAuthRepository()),
);
await tester.pumpAndSettle();
expect(find.text('Patbond'), findsWidgets);