Initial project implementation

2026-04-28 10:44:45 +08:00
commit 60527e935f
41 changed files with 7378 additions and 0 deletions
@@ -0,0 +1,401 @@
+# Sentinel Orbit Downloader
+
+一个本地可用的 Sentinel-1 数据与精密轨道下载工具，支持：
+
+- 按行政区和时间范围检索 Sentinel-1
+- 下载原始 Sentinel-1 产品
+- 下载匹配的精密轨道/恢复轨道 `.EOF`
+- 用 SQLite 管理项目、任务、场景和下载记录
+- 通过本地 Web 页面完成日常操作
+
+当前项目面向 Windows 本机使用场景，已经包含一键启动脚本。
+
+## 当前能力
+
+已实现：
+
+- 行政区 GeoJSON 导入 SQLite
+- 按行政区检索 Sentinel-1 场景
+- 原始 Sentinel-1 产品下载
+- 精密轨道 `.EOF` 下载
+- 项目管理
+- 任务列表、任务详情、事件日志
+- 任务删除与清空
+- Earthdata 凭据本地保存
+
+暂未实现：
+
+- GeoTIFF / `.tif` 处理与导出
+- 后处理流水线
+
+也就是说，现在项目专注于“检索 + 下载原始数据 + 下载轨道”。
+
+## 目录
+
+- 项目根目录：`C:\Users\16216\Desktop\Code\sentinel-orbit-downloader`
+- 默认数据库：`.s1dl\app.db`
+- 默认本地数据目录：`.local-data\`
+- 行政区源文件：`全国行政区.geojson`
+
+## 环境要求
+
+- Windows
+- Python 3.11 - 3.13
+- `uv`
+- 网络可访问 ASF / Earthdata
+
+## 快速开始
+
+### 1. 一键启动
+
+直接双击：
+
+- `Start-SentinelUI.cmd`
+
+它会自动：
+
+1. 检查 `uv`
+2. 执行 `uv sync`
+3. 启动本地服务
+4. 打开浏览器
+
+停止服务时双击：
+
+- `Stop-SentinelUI.cmd`
+
+启动脚本优先尝试这些端口：
+
+- `8011`
+- `8010`
+- `8012`
+- `8013`
+- `8014`
+
+如果端口已被占用，会自动换到下一个可用端口。
+
+### 2. 手动启动
+
+```powershell
+cd C:\Users\16216\Desktop\Code\sentinel-orbit-downloader
+uv sync
+$env:S1DL_API_PORT="8011"
+uv run s1-web
+```
+
+打开页面：
+
+```text
+http://127.0.0.1:8011/
+```
+
+Swagger 文档：
+
+```text
+http://127.0.0.1:8011/docs
+```
+
+## 首次使用流程
+
+### 1. 导入行政区
+
+项目根目录下已经放了：
+
+- `全国行政区.geojson`
+
+在页面中点击：
+
+- `导入行政区`
+
+也可以用命令行：
+
+```powershell
+uv run s1-dl regions import
+```
+
+### 2. 创建项目
+
+建议先建一个本地项目，例如：
+
+- 项目名称：`牡丹江 Sentinel-1 数据`
+- 数据根目录：`.local-data\mudanjiang`
+
+### 3. 配置 Earthdata
+
+下载原始 Sentinel-1 产品必须有 NASA Earthdata 账号。
+
+页面中可填写：
+
+- `Earthdata 用户名`
+- `Earthdata 密码`
+
+然后点击：
+
+- `保存凭据`
+
+保存后：
+
+- 用户名和密码会写入本地 SQLite
+- 密码不是明文保存
+- 密码使用当前 Windows 用户的 DPAPI 加密
+
+如果不想保存，也可以每次手填。
+
+### 4. Earthdata 首次授权 ASF
+
+很多第一次下载失败，不是用户名密码错，而是没有授权 ASF 应用访问 Earthdata。
+
+如果任务日志出现类似错误：
+
+```text
+Pre authorization required for this application
+```
+
+请先在浏览器登录 Earthdata，然后打开下面链接完成授权：
+
+```text
+https://urs.earthdata.nasa.gov/approve_app?client_id=BO_n7nTIlMljdvU6kRRB3g
+```
+
+这是一次性的关键步骤。
+
+### 5. 检索并下载
+
+页面典型流程：
+
+1. 搜索行政区，例如 `牡丹江`
+2. 选择时间范围
+3. 选择产品级别，如 `SLC`
+4. 点击 `发起检索`
+5. 选中任务
+6. 选择下载参数
+7. 点击 `启动下载`
+
+如果只想补精密轨道，不下载原始产品：
+
+- 把 `跳过产品` 设为 `是`
+
+## 页面功能说明
+
+### 环境配置
+
+- 导入行政区 GeoJSON
+- 查看服务状态
+
+### 项目
+
+- 创建项目
+- 刷新项目列表
+
+### 行政区选择
+
+- 按名称或 `adcode` 搜索
+- 查看行政区范围框和中心点
+
+### 检索参数
+
+支持：
+
+- 开始日期 / 结束日期
+- 产品级别
+- 波束模式
+- 轨道方向
+- 极化
+- 相对轨道号
+- 最大结果数
+- 使用原始行政区边界
+
+### 下载参数
+
+支持：
+
+- 数据目录
+- 轨道目录
+- 跳过产品
+- 跳过轨道
+- 并发数
+- 忽略轨道失败
+- Earthdata 凭据保存 / 清除
+
+### 任务区
+
+支持：
+
+- 刷新任务
+- 刷新详情
+- 删除选中任务
+- 清空当前项目的非运行任务
+
+## 输出结构
+
+典型输出目录如下：
+
+```text
+.local-data\mudanjiang\
+  data\        # Sentinel-1 原始产品
+  orbits\      # AUX_POEORB / AUX_RESORB EOF 文件
+  manifest.csv
+```
+
+数据库中还会保存：
+
+- 项目信息
+- 搜索任务
+- 场景清单
+- 下载记录
+- 任务事件日志
+
+## 命令行用法
+
+### 同步环境
+
+```powershell
+uv sync
+```
+
+### 导入行政区
+
+```powershell
+uv run s1-dl regions import
+```
+
+### 搜索行政区
+
+```powershell
+uv run s1-dl regions search 牡丹江
+```
+
+### 创建项目
+
+```powershell
+uv run s1-dl projects create `
+  --name "牡丹江 Sentinel-1 数据" `
+  --data-root ".local-data\mudanjiang" `
+  --description "Mudanjiang Sentinel-1 scenes and orbits"
+```
+
+### 按行政区检索
+
+牡丹江市 `adcode`：
+
+- `231000`
+
+```powershell
+uv run s1-dl search `
+  --project-id 1 `
+  --region-adcode 231000 `
+  --start 2024-01-01 `
+  --end 2024-03-01 `
+  --processing-level SLC `
+  --max-results 20 `
+  --manifest ".local-data\mudanjiang\manifest.csv"
+```
+
+### 直接下载
+
+```powershell
+uv run s1-dl download `
+  --project-id 1 `
+  --region-adcode 231000 `
+  --start 2024-01-01 `
+  --end 2024-03-01 `
+  --processing-level SLC `
+  --out ".local-data\mudanjiang-run" `
+  --processes 2
+```
+
+### 只补轨道
+
+```powershell
+uv run s1-dl orbits `
+  --data-dir ".local-data\mudanjiang\data" `
+  --out ".local-data\mudanjiang\orbits"
+```
+
+## 常见问题
+
+### 1. 页面里任务全是 failed
+
+先看任务事件日志。
+
+常见原因有两个：
+
+#### 原因 A：没填 Earthdata 用户名和密码
+
+如果下载原始 Sentinel-1 产品，必须提供 Earthdata 凭据。
+
+解决：
+
+- 页面填写用户名密码
+- 或保存到本地配置
+- 或设置环境变量 `EARTHDATA_USER` / `EARTHDATA_PASS`
+
+#### 原因 B：Earthdata 没授权 ASF
+
+如果日志里有：
+
+```text
+Pre authorization required for this application
+```
+
+按前文的授权链接先批准 ASF 应用。
+
+### 2. 为什么检索成功，但下载失败
+
+因为检索 ASF 元数据不一定要求完整的下载授权；真正下载原始产品时才会触发 Earthdata 登录和授权校验。
+
+### 3. 只想下载轨道，不想下载原始产品
+
+页面里把：
+
+- `跳过产品`
+
+设成：
+
+- `是`
+
+### 4. 保存 Earthdata 凭据是否明文
+
+不是。
+
+当前实现：
+
+- 用户名保存在本地 SQLite
+- 密码经过 Windows DPAPI 加密后保存
+
+### 5. 为什么不支持 `.tif`
+
+当前项目只管原始 Sentinel-1 产品和轨道文件。
+
+还没有做：
+
+- 解压
+- 预处理
+- GeoTIFF 导出
+
+## 开发与维护
+
+### 主要入口
+
+- Web API: `src/sentinel_orbit_downloader/api/app.py`
+- Web 页面: `src/sentinel_orbit_downloader/web/`
+- 下载管理: `src/sentinel_orbit_downloader/services/download_manager.py`
+- 项目/任务存储: `src/sentinel_orbit_downloader/services/project_store.py`
+- Earthdata 本地设置: `src/sentinel_orbit_downloader/services/settings_store.py`
+
+### 本地脚本
+
+- `Start-SentinelUI.cmd`
+- `Start-SentinelUI.ps1`
+- `Stop-SentinelUI.cmd`
+- `Stop-SentinelUI.ps1`
+
+## 说明
+
+这个项目当前阶段的目标很明确：
+
+- 把“按区域检索 Sentinel-1”
+- “下载原始数据”
+- “下载精密轨道”
+- “管理任务记录”
+
+这四件事先稳定做好。