ikooc / baidujiexi_app

# 百度解析助手
百度网盘直链解析助手的 Flutter 客户端（Android / Windows / iOS）。
App 不硬编码任何上游接口域名，启动时从远端配置接口拉取真实 API 地址，把用户粘贴的网盘分享链接解析为可直接下载的直链，再交给内置的 Gopeed 下载引擎进行多线程下载。
- Android：Gopeed 以 `libgopeed.aar` 形式内嵌，通过 MethodChannel 与 Dart 通信
- Windows：以子进程 `gopeed-rest.exe` 运行，通过本地 REST API 通信
> **反馈与交流**：使用中遇到问题、有功能建议，或想第一时间获取新版本，欢迎加入 QQ 群 **1125479685**。
> **下载安装**：Android 用户可直接从 Releases 下载已打包好的 APK（arm64-v8a）安装使用，无需自行编译。自行构建方法见「使用前端」，后端部署见「使用后端」。
---
## 功能概览
| 模块 | 说明 |
| --- | --- |
| 远端配置 | 启动时从 bootstrap 地址拉取 JSON 配置（API 地址、备用地址、`Origin`/`Referer`、默认模式、公告等），本地缓存以支持离线启动与多地址回退 |
| 直链解析 | 输入网盘分享链接（支持整段分享文本），调用远端接口以 SSE 流式返回解析进度与结果 |
| 多线程下载 | 内置 Gopeed 引擎，支持暂停 / 继续 / 删除 / 强制删除，单任务进度实时刷新 |
| 下载目录 | 默认 `/storage/emulated/0/Download/`，支持用户自定义目录并持久化，适配 Android 7–16 的存储权限差异 |
| 云端公告 | 首页展示后端下发的公告内容；内容为空时整块隐藏 |
| 主题 | Material 3，跟随系统亮色 / 暗色，并可手动切换 |
---
## 目录结构
 [code] 
---
## 使用前端
### 1. 环境与运行
环境要求：Flutter 3.x（Dart SDK `^3.12.2`）。
 [code] 
> App 启动时若拿不到后端配置，会退回本地缓存；首次启动需能访问 bootstrap 地址，否则停留在加载页。
### 2. 构建
 [code] 
产物位置：
- Android：`build/app/outputs/flutter-apk/app-release.apk`
- Windows：`build/windows/x64/runner/Release/`
### 3. 指定 bootstrap 地址
默认 bootstrap 地址定义在 remote_config.dart 的 `kDefaultBootstrapUrls`。可在构建时覆盖：
 [code] 
> 完整字段与后端部署方式见下文「使用后端」。
---
## 架构说明
### 1. 远端配置（`remote_config.dart`）
App 启动时按顺序请求 bootstrap 地址，直到拿到一份合法配置，并写入 `shared_preferences` 缓存；后续启动优先使用缓存，网络不可达时仍可工作。
`AppConfig` 字段：
| 字段 | 含义 |
| --- | --- |
| `apiBase` | 转换接口基础地址（无尾斜杠） |
| `siteOrigin` | 注入请求头 `Origin`，上游据此校验会话归属 |
| `referer` | 注入请求头 `Referer` |
| `fallbackBases` | 主地址失败时依次尝试的备用地址 |
| `defaultMode` | 默认转换模式：`web`（直链）/ `exe`（PC 下载器） |
| `configVersion` | 后端下发的版本号，用于识别缓存是否过期 |
| `announcement` | 首页公告文案，空字符串表示隐藏 |
| `extras` | 未被显式建模的其余键，原样保留，可用 `extra (key)` 读取 |
> 上游 `apiBase` 等网络配置由后端下发，更换上游接口地址无需重新发版；bootstrap 自身地址改变时，需要更新默认地址或构建参数并重新构建客户端。
### 2. 转换接口（`api_client.dart`）
上游已升级为「会话 → 行为认证 → 滑块验证码 → 转换」四步协议，客户端按同一顺序取齐凭据后再发起转换：
1. `GET /api/session` → `{ token, ttl, attest }`
 - 必须用 **GET**；
 - 新版响应不再直接下发 `secret`，而是带 `attest: 1`，需要再做第 2 步换取；
 - 会话按 `ttl` 缓存并预留 1 分钟安全边界。
2. `POST /api/session/attest` → `{ secret, ttl }`
 - 请求头带 `x-session-token`，body 为 `{ "fp": }`；
 - 与第 1 步的间隔需 ≥ 1600ms，过快会被判 `too-fast`，客户端退避后重试；
 - `secret` 仅用于本地签名，不上行。
3. `GET /api/captcha` → 曲线跟随滑块挑战
 - 挑战单次有效，每次转换都重新获取；答案恒为把滑块拖到最右端（`captchaAnswer = 283`），
 轨迹按引导曲线拟合，无需图像识别（见 `lib/core/captcha_solver.dart`）。
4. `POST /api/downloadConvertUrl`（SSE，`Accept: text/event-stream`）
 - 请求头：`Origin` / `Referer` / `User-Agent`，以及 `x-session-token`、`x-client-sign`；
 - body：`{ "link": , "mode": "web|exe", "captchaId", "captchaAnswer", "captchaTrail", "ref": }`；
 - `x-client-sign = clientSign(secret, link)`，**只对规范化后的链接字符串加签**（不是整个 JSON body）。
验证码被拒或会话 / 签名失效时，`convert()` 会刷新对应凭据并自动重试（最多 3 次）。
分享链接会被 `normalizeShareLink()` 规范化为 `https://pan.baidu.com/s/1 ?pwd= `。提取码可来自链接中的 `?pwd=`，也可来自粘贴文本里的 `提取码：xxxx`；签名必须覆盖这个规范化后的完整字符串。
SSE 事件逐步返回（`step` 字段）：`queue` / `ready` / `link_check` / `verify_pwd` / `file_list` / `import` / `wait_import` / `ba