docs: 添加 README 索引、CONVENTIONS 协定与 CI

2026-10-16 18:59:55 +08:00
parent 7740f341a7
commit 72747071d0
4 changed files with 112 additions and 0 deletions
@@ -0,0 +1,30 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  python:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        tool: [sar-gf3-l1a2l2, s1-orbit-downloader]
+    defaults:
+      run:
+        working-directory: python/${{ matrix.tool }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: 编译检查
+        run: python -m compileall -q src
+      - name: Ruff（仅报错类规则）
+        run: pip install ruff && ruff check --select E9,F63,F7,F82 src
+      - name: 安装
+        run: pip install .
+      - name: 测试
+        run: |
+          if [ -d tests ]; then pip install pytest && pytest -q; else echo "无测试"; fi
@@ -0,0 +1,5 @@
+__pycache__/
+*.py[cod]
+.venv/
+*.egg-info/
+/build/
@@ -0,0 +1,57 @@
+# Harmon 代码协定
+
+适用于 git.rsharmon.cn/Harmon 下的所有仓库（GitHub HarmonRS 为镜像）。新代码必须遵守，旧代码在修改时逐步对齐。
+
+## 1. 仓库命名
+- 全小写，短横线连接：`领域-数据源-功能`，如 `sar-lt1-dinsar`、`sar-gf3-l1a2l2`、`s1-orbit-downloader`。
+- 常用前缀：`sar`（雷达通用）、`lt1`（陆探1号）、`gf3`（高分3号）、`s1`（Sentinel-1）、`opt`（光学）。
+- 禁止下划线、大写、`-v2`/`-new`/`-final` 之类的版本后缀（版本靠 tag）。
+- 主力项目（系统/服务）独立成仓库；小工具、脚本统一放进 `rs-toolkit`。
+
+## 2. rs-toolkit 目录结构
+```
+rs-toolkit/
+  idl/<工具名>/       # IDL/ENVI 脚本
+  python/<工具名>/    # 每个工具是独立的 Python 包
+  go/<工具名>/        # 如有
+  README.md           # 工具索引：一行说明 + 安装/运行方式
+  CONVENTIONS.md
+```
+- 工具目录名同样遵守第 1 条命名规则。
+- 工具之间不互相 import；共用代码再考虑抽成 `python/rs-common/`。
+- 新增工具时同步更新根 README 索引。
+
+## 3. 分支与提交
+- 默认分支 `main`，始终保持可用；功能在 `feat/xxx`、`fix/xxx` 分支上开发，通过 PR 合并。
+- 提交信息采用 Conventional Commits：`<type>(<scope>): <说明>`
+  - type：`feat` `fix` `refactor` `docs` `test` `chore` `ci` `perf`
+  - scope：rs-toolkit 中写工具名，如 `fix(sar-gf3-l1a2l2): 跳过损坏的压缩包`
+- 一个提交只做一件事；不提交生成物、数据、密钥。
+- 发布打 tag：主项目 `vX.Y.Z`；toolkit 内工具 `<工具名>-vX.Y.Z`。
+
+## 4. Python
+- 一律 `pyproject.toml` + `src/` 布局：`src/<包名>/`，包名为目录名的下划线形式。
+- 声明 `requires-python`、依赖下限，命令行入口写在 `[project.scripts]`。
+- 安装方式（无需拷脚本）：
+  `pip install "git+https://git.rsharmon.cn/Harmon/rs-toolkit.git#subdirectory=python/<工具名>"`
+- 代码用 `ruff` 检查与格式化；测试放 `tests/`，用 `pytest`。
+- 路径、账号等配置不写死在代码里，走命令行参数/配置文件/环境变量。
+
+## 5. IDL / ENVI
+- 文件名小写下划线（IDL 惯例），一个 `.pro` 一个主过程，过程名与文件名一致。
+- 文件头注释写明：用途、输入输出、依赖的 ENVI/SARscape 版本、作者与日期。
+- 输入输出路径作为参数传入，不写死；批处理入口统一命名 `batch_*.pro`。
+- `.sav` 等编译产物如必须入库，标记为 binary（.gitattributes）。
+
+## 6. README 要求
+每个仓库/工具目录必须有 README，至少包含：
+1. 一句话说明做什么；2. 环境与依赖；3. 安装；4. 最小运行示例；5. 输入/输出说明；6. 已知限制。
+
+## 7. CI
+- 每个仓库在 `.gitea/workflows/` 下配置 CI，PR 和推送 main 时触发。
+- Python：ruff + 编译检查 + pytest（有测试时）；Rust：`cargo fmt --check`、`cargo clippy -D warnings`、`cargo test`；Go：`go vet`、`go test`。
+- `main` 开分支保护：CI 通过后才能合并。AI 生成的代码同样必须过 CI。
+
+## 8. 其他
+- 文本统一 UTF-8、LF（Windows `.cmd/.bat` 除外）。
+- 大于 10MB 的二进制/数据不入库，放 release 或 NAS。
@@ -0,0 +1,20 @@
+# rs-toolkit
+
+遥感（SAR/InSAR）常用小工具与脚本合集。规范见 [CONVENTIONS.md](CONVENTIONS.md)。
+
+| 工具 | 语言 | 说明 | 原仓库 |
+|---|---|---|---|
+| [idl/sar-lt1-dinsar](idl/sar-lt1-dinsar) | IDL | 陆探1号 ENVI/SARscape D-InSAR 批处理流水线 | lutan1-envi-idl-dinsar-pipeline |
+| [python/sar-gf3-l1a2l2](python/sar-gf3-l1a2l2) | Python | 高分3号 L1A → L2 处理流水线（含 SARscape Go 封装） | GF3_L1A_To_L2_pipeline |
+| [python/s1-orbit-downloader](python/s1-orbit-downloader) | Python | Sentinel-1 影像与精密轨道查询下载（CLI + Web UI） | sentinel-orbit-downloader |
+
+## 安装 Python 工具
+
+```bash
+pip install "git+https://git.rsharmon.cn/Harmon/rs-toolkit.git#subdirectory=python/sar-gf3-l1a2l2"
+pip install "git+https://git.rsharmon.cn/Harmon/rs-toolkit.git#subdirectory=python/s1-orbit-downloader"
+```
+
+IDL 工具直接在 ENVI/IDL 中打开对应目录下的 `.pro`，用法见各目录 README。
+
+各工具的提交历史均已保留（`git log -- <目录>`）。