## 生成代码命令

```
flutter pub run build_runner build --delete-conflicting-outputs~
```

## 本地运行

项目使用 FVM Flutter 3.27.4。在 IDE 中选择启动模式即可，无需每次填写参数：

| 模式 | VS Code 启动项 | Android Studio 启动项 | 文件请求 |
| --- | --- | --- | --- |
| 新版签名 | `pj_supermarket_cloud（新版签名）` | `main.dart`，Additional run args 配置下述签名参数 | 读取本地配置，图片和上传携带签名 |
| 旧版兼容测试 | `pj_supermarket_cloud（旧版兼容，无配置）` | `main.dart（旧版兼容，无配置）` | 不读取配置文件，图片和上传不携带应用签名 |

直接运行以下命令也可启动。Debug 未传任何文件签名配置时，自动走旧版兼容测试模式：

```bash
fvm flutter run
```

旧版模式会在控制台打印 `[file-access] 旧版兼容测试模式`，不发起文件校时和签名续期。
即使同时提供签名配置，显式 `FILE_ACCESS_MODE=legacy` 也会保持旧版请求行为。
该模式仅用于 Debug；Profile/Release 仍需有效签名配置。配置不完整或密钥错误会报错。

新版签名模式读取 `.file-access/config.json`。该文件已被 Git 忽略，所有环境共用现有的一套配置。
换电脑或在 CI 构建时需要同步这份配置；准备方式见
[文件访问接入说明](../pj_service_cloud/docs/file-access/README.md)。

```bash
fvm flutter run --dart-define-from-file=.file-access/config.json
```

VS Code 的新版 Debug、Profile、Release 启动配置已包含签名参数。
Android Studio 在 `main.dart` 的 Run/Debug Configurations 中，将 Additional run args 设置为
`--dart-define-from-file=.file-access/config.json`。
这些参数在编译时生效，修改后需停止调试并重新运行。

## 旧版兼容验证

1. 选择“旧版兼容，无配置”，完全停止后重新启动，确认控制台显示旧版模式。
2. 使用未缓存的新图片，检查实际请求只有原始文件参数，没有 `appId/kid/ts/sign`。
   主屏、副屏、人脸图片下载均使用同一编译模式；已有图片缓存不代表服务器仍允许读取。
3. 在已部署文件校验的后端测试：`mode: enforce` 且 `legacy-dart.enabled: true` 时，
   符合 `Dart/<版本> (dart:io)` UA 的裸图片请求可走兼容；关闭兼容后应返回 403。
   后端 `observe` 模式仍会放行，不能用于确认拒绝行为。
4. 旧 Dart 兼容只放行图片；PDF、裸 APK、上传不会因 Dart UA 放行。
   服务端签发的 `package` 下载链接继续可用。切回“新版签名”后，验证图片和上传请求带签名。

此模式模拟旧版请求，旧 APK 在实际设备上的兼容性仍需用原安装包验证。

## flutter打包

```
fvm flutter build apk --dart-define-from-file=.file-access/config.json --build-name 2.2.0 --build-number 220
--build-name为版本号(展示)
--build-number为版本号(内部比较)
```

## 打印日志

```
adb -s 8d06b935c69accd4 logcat -v time -s flutter
```