patbond-flutter/lib/core/network/api_exception.dart

/// 服务端错误信封 `{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;

  /// 登录失败次数过多，账号临时锁定（HTTP 423，见 openapi.yaml）。
  static const loginLocked = 42300;

  // ------ pets 域（契约 v1.2.0 冻结，M2 第二波定型 8 个）------

  /// 对可见宠物无相应操作权限（viewer 写记录、caregiver/viewer 改档案）。
  static const petAccessDenied = 40300;

  /// 宠物不存在 / 已软删 / 与调用者无关系（防枚举，三种情况响应一致）。
  static const petNotFound = 40401;

  /// 记录不存在或记录所属宠物对调用者不可见（记录级防枚举）。
  static const recordNotFound = 40402;

  /// 乐观锁版本冲突（提交的 version 已过期；提醒的条件更新守卫落空同码）。
  static const versionConflict = 40902;

  /// 芯片号已被登记（跨用户唯一）。
  static const microchipTaken = 40903;

  /// 同宠物同疫苗同系列同剂次的非 cancelled 疫苗记录已存在。
  static const vaccinationDoseExists = 40904;

  /// 疫苗状态机 / 状态-日期规则违反（HTTP 422）。
  static const vaccinationRuleViolation = 42201;

  /// 提醒状态机 / completed-completedAt 一致性违反（HTTP 422）。
  static const careReminderRuleViolation = 42202;

  // ------ community / media 域（契约 v1.3.0 冻结，M3 第二波定型 9 个）------

  /// 对可见帖子/评论无相应操作权限（改删他人已发布帖、删他人可见评论）。
  static const postAccessDenied = 40301;

  /// 帖子不存在 / 已软删 / hidden/archived（含作者）/ 他人 draft
  /// （防枚举，全部情况响应一致；互动路径上含作者本人草稿）。
  static const postNotFound = 40403;

  /// 评论不存在、已删或所属帖子不可见（防枚举合并）。
  static const commentNotFound = 40404;

  /// media asset 不存在、非本人所有或已删（防枚举合并）。
  static const mediaNotFound = 40405;

  /// 目标用户不存在或已注销（合并不泄露成因）。
  static const communityUserNotFound = 40406;

  /// 同 Idempotency-Key 不同 payload（规范化 request_hash 不符）。
  static const idempotencyKeyMismatch = 40905;

  /// 引用了本人所有但非 ready（uploading/failed）状态的 asset（HTTP 422）。
  static const mediaNotReady = 42203;

  /// 自关注（仅 PUT；自取关走 DELETE 的 200 幂等 no-op）。
  static const selfFollow = 42204;

  /// 上传状态不允许确认（非 uploading 态或对象校验未通过，HTTP 422）。
  static const mediaUploadStateInvalid = 42205;
}

/// 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 等）。
/// 领域层可按错误码细分子类型（见 features/pets/pet_exceptions.dart）。
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 = '会话已失效']);
}