conti-retail-app/SCAFFOLD-NOTES.md

# 脚手架落地记录：偏离文档的地方

这份文件是给 `conti-docs` 的**回写清单**。搭这个骨架的过程中，文档里有一部分
内容无法照抄——有的是版本过期，有的是两篇文档互相矛盾，有的是照抄会直接编译
不过。每一条的裁决都记在下面，代码里对应位置也留了注释。

**本次没有改动 `conti-docs` 仓库的任何文件。** 更新 01 / 03 / 07 / 12 / 14 四篇
文档时以这份清单为准。

日期：2026-08-17。工具链：Flutter 3.44.9 / Dart 3.12.2 / Melos 8.2.2。

---

## A. 版本纠错

文档 03 写的 riverpod 版本已经过期，但**不能直接升到 pub.dev 上的最新版**：

| 包 | 文档 | 最新 | 本仓库实际 | 为什么不是最新 |
|---|---|---|---|---|
| `riverpod_annotation` | `^3.4.2` | 4.0.6 | **4.0.3** | 见下 |
| `riverpod_generator` | `^3.4.2` | 4.0.8 | **4.0.4** | 见下 |
| `flutter_riverpod` | `^3.4.2` | 3.4.2 | **3.3.2** | 见下 |

**约束来自 `flutter_test`**：它 pin 了 `test_api 0.7.11`，而 riverpod 4.0.6+ 要
`analyzer 13.x`，两者的解析结果冲突。往上升之前先确认这条链路，光看 pub.dev 的
最新版会浪费半天。

`build_runner 2.15.1` / `analyzer 12.1.0` 是被上面这条连带定死的。

其余 22 个包与文档一致。

## B. `riverpod_lint` 不再走 `custom_lint`

文档 03/14 要求装 `custom_lint`、在 `analysis_options.yaml` 里写
`analyzer: plugins: - custom_lint`、CI 里单独跑 `dart run custom_lint`。

**实测 `riverpod_lint 3.1.8` 的依赖里没有 `custom_lint`**，它依赖
`analysis_server_plugin`。官方 changelog：

> 3.1.0 — `riverpod_lint` is no-longer implemented using `custom_lint`, but
> instead `analysis_server_plugin`

因此本仓库：

- `analysis_options.yaml` 用**顶层** `plugins:` 映射，不是 `analyzer.plugins`；
- 所有 `dev_dependencies` 里没有 `custom_lint`；
- CI 里没有 `dart run custom_lint` 这一步，lint 由 `flutter analyze` 直接执行。

**顺带解决了 01 和 14 关于「custom_lint 装根还是装每个包」的长期矛盾**——这个
问题不存在了。

## C. 新增了一个文档里没有的包：`core_foundation`

这是本次唯一的结构性增补。理由是文档现有的依赖规则**自相矛盾**，不加就无法
同时满足：

- 文档 12 把 `sealed AppException` 放在 `core_network`。但这个体系里有
  `StorageException`（`core_storage` 要用）和 `UnauthorizedException`
  （`core_auth` 要用），而 01 明令 `core_storage`/`core_auth` **不许**依赖
  `core_network`。
- `AppEnv` 被 `core_network`（baseUrl）、`core_auth`（TokenRefresher）、
  `core_webview`（域名白名单）、`core_logging`（日志级别）同时需要。放进任何
  一个现有 `core_*` 都会造出非法依赖边或循环。

方案：`packages/core_foundation` 是一个**叶子包**，只依赖 `flutter_riverpod`，
内容是 `AppEnv` + `AppException` 体系 + `NetworkErrorKind` + `ApiCode` +
`NativeErrorCode`。所有 `core_*` / `feature_*` 都可以依赖它；`native_*` **不**
依赖（保住 01 那条「native_* 只依赖 Flutter SDK 和 Pigeon 产物」）。

叶子包不可能形成循环，01「core_* 之间不互相依赖」的立法目的（防循环）不受损。

`PageQuery` / `PageResult` 按文档 02 留在 `core_network`。

## D. `native_*` 无法抛 `AppException`

文档 07 写「原生异常不外泄，统一转成 AppException 体系」，但 `native_*` 不许
依赖任何 `core_*`（含 `core_foundation`）。

裁决：`native_scan` 抛包内自定义的 `NativeScanException`（纯 Dart 无依赖），
**映射到 `NativeException` 的动作放在调用方**（feature_scan / core_webview 的
bridge handler）。文档 07 的 `NativeCapabilityException` /
`UnsupportedPlatformException` 收敛成文档 12 的 `NativeException(code, message)`。

## E. 逐条冲突裁决

| # | 冲突 | 裁决 |
|---|---|---|
| 1 | `BusinessException` 构造签名：05 用具名，12 用位置参数 | 按 **12**（定义类的那篇），05 的拦截器代码相应调整 |
| 2 | 05 的 `HttpException` 不在 12 的 sealed 体系里，且与 `dart:io` 同名 | 改用 12 的 `ServerException` |
| 3 | `NetworkErrorKind` 被 12 的 `present()` 用了但从未声明 | 在 core_foundation 声明；`ErrorMappingInterceptor` 负责填 |
| 4 | `UnauthorizedException` / `RequestCancelledException` / `StorageException` 无构造函数，父类却要求位置参数 | 各补 `const` 构造 + 默认文案 |
| 5 | **`PreconditionException` 不在 12 的 `present()` switch 里** | 补分支。sealed 穷尽，不补**编译不过** |
| 6 | `AppException.bridgeCode` 被 core_webview 用了但未定义 | 在 `AppException` 上加 getter，子类 override。码表待与 F6 对齐 |
| 7 | 05 的拦截器顺序正文与附录不一致 | 按**附录**：Header → Log → Auth → ApiResult → ErrorMapping |
| 8 | 06 有两个 `readAccessToken` 实现 | 用带 try/catch 兜底那版：读失败按未登录处理 + `clear()`，绝不让异常逃进启动流程 |
| 9 | `currentStoreIdProvider` 返回非空且会 throw（11），但 05 的 `HeaderInterceptor` 写 `if (storeId != null)` | 提供**两个** provider：`currentStoreIdProvider`（非空，业务用）和 `currentStoreIdOrNullProvider`（可空，基础设施用） |
| 10 | melos 脚本名 `pigeon`（01）vs `gen:pigeon`（14） | 统一 `gen:pigeon` |
| 11 | `analyze` 脚本 01 无 `--fatal-infos`，14 的 CI 有 | 脚本里加上 |
| 12 | melos 脚本里 `flutter` vs `fvm flutter` | 用裸 `flutter`（按 01），版本靠 `.fvmrc` + PATH 保证 |
| 13 | 02 的 `PageResult.hasMore` 计算逻辑有误 | 用后端返回的 `hasMore`，不在客户端算 |
| 14 | 02 正文说 `data/repository_impl/`，示例写 `data/repository/` | 统一 `data/repository/` |
| 15 | `Analytics` 接口：13 正文说 `login()`/`logout()`，代码块用 `identify()`/`reset()` | 按代码块 |

## F. 本次范围调整

- **Drift / 本地数据库暂缓**。骨架阶段没有任何业务表，`core_storage` 现在只有
  KV 一档（`Prefs`）。文档 06 的表结构、迁移策略、`{storeId, orderId}` 联合主键
  规则仍然有效，等第一张业务表落地时按 06 建。
  > 顺带：melos 8.x 和 `drift_dev` 有一个 `cli_util` 的版本冲突，接 Drift 时会
  > 撞上，先有个心理准备。
- **原生 Kotlin/Swift 实现不做**。`native_scan` 的 Pigeon 接口和 Dart 侧齐了，
  原生侧是 `flutter create` 的模板 + TODO。
- **不做 lefthook**、不做 `git init` / 首次提交（按需求）。
- **i18n 只做结构预留**：`app/l10n.yaml` + 一个 `app_zh.arb`，文案还写在 Widget
  里。理由见 conti-docs README 的待补充清单——等 30 个页面都写死中文再抽，成本
  是现在的几十倍。

## G. 依赖反转（"端口"）模式

**这是本次落地里最值得回写文档的一条。** 文档里有若干处伪代码违反了 01 自己
定的依赖规则：

| 文档处 | 想做的事 | 为什么不行 |
|---|---|---|
| 11 `SessionNotifier` | 调 `authRepository.login()` | core_auth 不许依赖 core_network / feature_* |
| 11 切店第 6 步 | `goRouterProvider.go('/home')` | core_auth 不许依赖 core_router |
| 11 切店级联 | 清 WebView cookie | core_auth 不许依赖 core_webview |
| 05 `HeaderInterceptor` | 读 `deviceIdProvider` | core_network 不许依赖 core_storage |
| 05 `ApiResultInterceptor` | 收一个 `AppLogger` | core_network 不许依赖 core_logging |
| 10 H5 换票 | 发 `/h5/launch` 请求 | core_webview 不许依赖 core_network |
| 04 未知菜单编码 | 上报埋点 | core_router 不许依赖 core_analytics |

统一解法：**包内只声明"我需要什么"，不声明"谁来满足"**。

```dart
// core_auth/lib/src/session_ports.dart
abstract interface class SessionRemote { Future<UserContext> fetchCurrentUser(); ... }

final Provider<SessionRemote> sessionRemoteProvider = Provider<SessionRemote>(
  (Ref ref) => throw UnimplementedError('sessionRemoteProvider 必须在 bootstrap() 里 override'),
);
```

```dart
// app/lib/bootstrap.dart —— 唯一知道所有包的地方
sessionRemoteProvider.overrideWith((Ref ref) => ref.watch(authRepositoryProvider)),
```

现有的端口文件：

- `core_auth/lib/src/session_ports.dart` — `SessionRemote` / `SessionScopedStore`
  / `SessionObserver`
- `core_network/lib/src/ports.dart` — `ClientInfo` / `ApiLogSink`
- `core_router/lib/src/ports.dart` — `appRoutesProvider` /
  `navigatorObserversProvider` / `RouteReporter`
- `core_webview/lib/src/h5_launch.dart` — `H5LaunchRepository`

代价要说清楚：**这些 override 是运行期才炸的，编译器不管**。新增一个端口就要
同时在 `bootstrap()` 里接上。默认值给不给有讲究——`appEnvProvider` /
`sessionRemoteProvider` 故意不给（忘了接必须立刻炸），`apiLogSinkProvider` /
`sessionObserversProvider` 给空实现（忘了接只是没日志，不影响功能）。

切店后回工作台那一条，实现成了 `goRouterProvider` 里的一个 `ref.listen`：

```dart
if (before is SessionActive && after is SessionActive &&
    before.store.storeId != after.store.storeId) {
  router.go(AppRoutes.home);   // go 而不是 push：替换整个栈
}
```

方向反过来了（core_router 观察 core_auth，而不是 core_auth 调 core_router），
符合允许的依赖边。

## H. Pub Workspace 让「包边界靠编译器强制」这句话不成立

**这条建议直接回写进 01。** 01 的立论是「违反分包规则的代码根本写不出来，
因为 pubspec 里没声明就 import 不到」。在 Pub Workspace 下**这是错的**：所有
成员包共用根目录一份 `.dart_tool/package_config.json`，任何成员都能解析到任何
其他成员，不管 pubspec 里写没写。

实测（在 `feature_home/lib/src/` 放一个 import `feature_auth` 的文件，
`feature_home/pubspec.yaml` 里**不**声明这条依赖）：

```
flutter test                  → All tests passed!        编译通过，跑得起来
flutter analyze --fatal-infos → info: depend_on_referenced_packages   ✗
```

只有一条 **info**级 lint。结论：

> **`--fatal-infos` 是这套包边界唯一的强制点。** 它没了，边界当天失效，且
> 没有任何别的信号——不会编译失败，测试还是绿的。

所以 §E 第 11 条（`analyze` 脚本要不要加 `--fatal-infos`）不是风格问题，是
**这套架构成不成立的问题**，01 和 14 都应该按这个高度重写那一段。相应地，
`depend_on_referenced_packages` 不允许在任何包的 `analysis_options.yaml` 里被
ignore，建议在 14 的 CI 门禁一节里单列。

（改用 path dependency 而不是 workspace 可以拿回编译期强制，代价是失去统一
版本解析——不建议为此推翻 workspace，把 `--fatal-infos` 守住即可。）

## I. 写代码时踩到的坑（Riverpod 3 / flutter_test）

不属于文档偏离，但会反复咬人，记在这里：

1. **`AsyncValue.valueOrNull` 没了**，用 `.value`。
2. **`copyWithPrevious` 是 internal**，用了会报 `invalid_use_of_internal_member`。
3. **`Override` 类型不公开导出**。`overrides: [...]` 不要写类型参数。
4. **riverpod_generator 4.x 只剥 `Notifier` 后缀**：`SessionNotifier` →
   `sessionProvider`，但 `LoginController` → `loginControllerProvider`。
5. **所有 provider 默认 autoDispose**。测试里 `container.read` 之后没有监听者，
   状态立刻被回收；要 `container.listen(p, (_, _) {})` 顶住。
6. **`ProviderObserver` 是 `base` 类**，子类必须标 `final` / `base` / `sealed`。
7. **`testWidgets` 跑在 fake async 区里**：里面 `await` 一个真实的 Future
   （比如 `container.refresh(p.future)`）**永远不会完成**，会挂到 10 分钟超时。
   碰真 provider 生命周期必须包一层 `await tester.runAsync(() async { ... })`。
8. **`ProviderContainer` + 异步 provider**：同步 `read` 拿到的是 loading 态，
   要先 `await container.read(p.future)`。
9. Pigeon 生成的 `@HostApi` 是**具体类**不是接口，测试替身要 `extends` 不是
   `implements`。
10. 局部变量别叫 `fail`——会遮蔽 `flutter_test` 的 `fail()`。