feat(mobile): api client, session storage and contract-aligned models

P3 计划 Task 2(apps/mobile):

- core/config.dart:API_BASE/VIEWER_BASE 经 --dart-define 覆盖,缺省
  10.0.2.2 模拟器宿主回环;viewer 相册链接构造 {VIEWER_BASE}/a/{token}。
- core/error_codes.dart:errors.ts 17 码 1:1 镜像(含注释),另设 4 个
  客户端本地伪码(NETWORK_ERROR/NETWORK_TIMEOUT/CANCELLED/HTTP_ERROR)。
- core/api_client.dart:dio 封装——Bearer 注入(登录端点豁免)、401
  驱逐(清会话 + onUnauthorized 回调去重,App 壳注册跳 /login)、
  DioException/错误体 {code,message,requestId} 归一 AppException、
  通用游标分页助手;auth/albums/members/categories/admin/uploads/photos
  全端点方法;riverpod provider 出口。
- core/session_store.dart:SessionStore 抽象 + flutter_secure_storage
  实现(token/expiresAt/account 三键,encode/decode 纯函数可测)。
- features/{auth,albums,uploads,photos}/models.dart:手写 fromJson/
  toJson,逐字段对齐 openapi.yaml(类注释标注契约 schema/operationId);
  locale 按字符串透传(zh-CN 标识符不兼容),业务枚举 Dart 化并在
  未知值 fail-fast。
- 测试 66 项:17 码表驱动 + 网络/超时/取消 + 兜底映射、游标边界
  (含 CursorPageMeta 不变式违约容错)、模型往返(fixture 转写自
  openapi.yaml schema 与 api e2e 断言,来源在测试头注释)、拦截器
  行为(手写 FakeAdapter:Bearer 注入/401 驱逐/登录豁免/并发去重/
  尽力而为 logout/refresh 滑动续期)。flutter analyze 零告警。

Co-Authored-By: Claude Code <noreply@anthropic.com>
This commit is contained in:
浅念
2026-09-19 00:40:02 +08:00
parent 8bc50e07ef
commit f975321b67
18 changed files with 3430 additions and 0 deletions
+26
View File
@@ -0,0 +1,26 @@
/// 环境入口配置(P3 计划 Task 2)。
///
/// 值经 `--dart-define=KEY=value` 覆盖;缺省指向 Android 模拟器宿主回环
/// (10.0.2.2 = 模拟器内看到的宿主机 localhost,见计划「模拟器网络回环」
/// 偏差登记)。`String.fromEnvironment` 为编译期常量,不可运行时切换。
class ApiConfig {
const ApiConfig._();
/// cn-api 基地址(不含 `/v1` 前缀——契约 servers.url 为 `/v1`,
/// 由 [ApiClient] 统一拼接到各端点路径)。
static const String baseUrl = String.fromEnvironment(
'API_BASE',
defaultValue: 'http://10.0.2.2:8080',
);
/// viewer 观众端基地址(Task 4 分享二维码链接用)。
static const String viewerBase = String.fromEnvironment(
'VIEWER_BASE',
defaultValue: 'http://10.0.2.2:5175',
);
/// 观众端相册链接:`{VIEWER_BASE}/a/{token}`(Task 4 qr 分享用,
/// viewer 路由约定)。
static String viewerAlbumUrl(String publicToken) =>
'$viewerBase/a/$publicToken';
}