Dev latest

.github/workflows/ci.yml

@@ -11,7 +11,8 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.9", "3.10", "3.11"]
+        # 与 pyproject.toml 中 python = "^3.10" 一致 / Match Poetry python constraint
+        python-version: ["3.10", "3.11", "3.12"]
 
     steps:
     - uses: actions/checkout@v4
@@ -37,6 +38,19 @@ jobs:
     - name: 安装依赖
       run: poetry install --no-interaction --no-root
 
+    - name: 设置 Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: "20"
+        cache: "npm"
+        cache-dependency-path: web/analysis-ui/package-lock.json
+
+    - name: 构建星空解算控制台前端
+      run: |
+        cd web/analysis-ui
+        npm ci
+        npm run build
+
     - name: 代码格式检查 (Black)
       run: poetry run black --check ogscope tests
 
@@ -56,6 +70,7 @@ jobs:
         file: ./coverage.xml
         flags: unittests
         name: codecov-umbrella
+        fail_ci_if_error: false  # 无 CODECOV_TOKEN 的 fork 等场景不阻断 CI / Do not fail CI without token
 
   lint:
     runs-on: ubuntu-latest
@@ -65,7 +80,7 @@ jobs:
     - name: 设置 Python
       uses: actions/setup-python@v4
       with:
-        python-version: "3.9"
+        python-version: "3.10"
 
     - name: 安装 Poetry
       uses: snok/install-poetry@v1

.github/workflows/release.yml

@@ -14,7 +14,7 @@ jobs:
     - name: 设置 Python
       uses: actions/setup-python@v4
       with:
-        python-version: "3.9"
+        python-version: "3.10"
 
     - name: 安装 Poetry
       uses: snok/install-poetry@v1

.gitignore

@@ -37,6 +37,11 @@ env.bak/
 venv.bak/
 .python-version
 
+# ====================
+# Node (星图解算实验室前端 / Analysis lab UI)
+# ====================
+web/analysis-ui/node_modules/
+
 # ====================
 # Poetry
 # ====================
@@ -143,6 +148,9 @@ captured_images/
 *.fits
 *.fit
 
+# Tetra3 图案库（体积大，本地或部署时放入 / Large pattern DB; copy on deploy）
+data/plate_solve/default_database.npz
+
 # 星表数据（太大，不提交）
 star_catalogs/*.dat
 star_catalogs/*.bin

CLAUDE.md

@@ -15,6 +15,7 @@ OGScope 是一个基于 Orange Pi Zero 2W 的电子极轴镜系统，用于天
 - **日志**: Loguru
 - **测试**: Pytest
 - **代码质量**: Black, Ruff, MyPy
+- **星空解算控制台前端**: `web/analysis-ui`（Vite + React + Tailwind），构建输出 `web/static/analysis-lab/`；本地执行 `cd web/analysis-ui && npm install && npm run build`；同步到开发板见 `scripts/sync_dev_board.sh`（环境变量 `OGSCOPE_DEV_HOST`、`OGSCOPE_DEV_PATH` 等）。i18n 见 `web/static/i18n/analysis.zh.json` / `analysis.en.json`。
 
 ## 开发环境
 

data/analysis/presets/official/default_widefield.json

@@ -0,0 +1,13 @@
+{
+  "id": "default_widefield",
+  "name": "默认广角 / Default widefield",
+  "scope": "official",
+  "params": {
+    "fov_estimate": 16.0,
+    "fov_max_error": 5.0,
+    "solve_timeout_ms": 8000,
+    "hint_ra_deg": 45.0,
+    "hint_dec_deg": 80.0
+  },
+  "created_at": "2026-01-01T00:00:00+00:00"
+}

data/plate_solve/README.md

@@ -0,0 +1,5 @@
+# Plate solve 数据目录 / Plate solve data directory
+
+请将 `default_database.npz`（Tetra3 图案库）放在此目录，或通过 `OGSCOPE_SOLVER_TETRA_DATABASE_PATH` 指定绝对路径。
+
+详细说明见 [docs/development/plate-solve-data.md](../../docs/development/plate-solve-data.md)。

docs/development/README.md

@@ -9,6 +9,61 @@
 当前推荐流程为：**本地编辑代码 -> 上传到开发板 -> 使用 `systemd` 重启服务验证**。  
 该流程与实际硬件运行环境一致，适合涉及相机与系统库依赖的场景。
 
+## 0. 部署速查（爱好者复刻）
+
+本节与 **§1–§11** 的关系：**只列最常用命令与检查项**；Poetry/PEP 668、镜像选项、卸载与排错原理见后文对应章节。
+
+### 0.1 系统要求
+
+- 单板：**ARM**（`aarch64` 或 `armhf`），如 Raspberry Pi / Orange Pi  
+- 系统：**Debian/apt** 系镜像（与 `picamera2`/`libcamera` 文档一致；脚本会读 `/etc/os-release`，见 **§1.4**）  
+- Python：**3.10+**（以 `pyproject.toml` 为准）  
+- 网络：首次安装需拉取依赖；浏览器访问 Web 需可达设备 **TCP 8000**（按需防火墙放行）
+
+### 0.2 首次安装
+
+```bash
+cd /path/to/OGScope
+chmod +x scripts/install.sh
+./scripts/install.sh
+```
+
+说明摘要：默认 `poetry install --only main`；国内网络可 **`export OGSCOPE_MIRROR=cn`**；低配板可 **`OGSCOPE_APT_SLOW=1`**。完整选项见 **§1.4**。安装后：`sudo systemctl start ogscope`。
+
+### 0.3 星图解算数据
+
+将 **`default_database.npz`** 放到 **`data/plate_solve/`**（不随仓库分发）。放置与配置见 [plate-solve-data.md](plate-solve-data.md)。
+
+### 0.4 日常更新
+
+```bash
+cd /path/to/OGScope
+chmod +x scripts/board-update.sh
+# 可选：OGSCOPE_GIT_PULL=1  OGSCOPE_MIRROR=cn
+./scripts/board-update.sh
+```
+
+详情见 **§6.2**。
+
+### 0.5 卸载与健康检查
+
+- 卸载服务与 `.venv`：见 **§6.3**（`scripts/uninstall.sh`）  
+- 健康检查与日志：
+
+```bash
+curl -s http://127.0.0.1:8000/health
+sudo systemctl status ogscope
+sudo journalctl -u ogscope -f
+```
+
+### 0.6 常见故障（简表）
+
+| 现象 | 处理方向 |
+|------|----------|
+| `ImportError: picamera2` | 用 `apt` 装相机栈；venv 由 `install.sh` 配置（**§1.2、§3**） |
+| PEP 668 / 系统 pip 被拒 | 只用项目 `.venv`，勿在系统 Python 上混装（**§1.2**） |
+| 服务无法启动 | 查 `WorkingDirectory`、`ExecStart`、`journalctl`（**§10**） |
+
 ## 1. Python 版本与项目依赖
 
 ### 1.1 Python 版本基线
@@ -17,7 +72,13 @@
 - 建议开发板使用 Python 3.10 及以上版本
 - 若其他文档出现 `3.9+`，应视为历史描述
 
-### 1.2 安装 Poetry 与 Python 依赖
+### 1.2 Poetry、PEP 668 与虚拟环境（必读）
+
+- **必须使用 Poetry 创建的项目内虚拟环境**（`.venv`），**禁止**全局设置 `virtualenvs.create false` 后在系统 Python 上混装依赖；否则易触发 **PEP 668**（发行版保护系统 site-packages，`pip`/`poetry` 无法改写系统包）。
+- 开发板推荐由 `scripts/install.sh` 统一写入：`virtualenvs.create true`、`virtualenvs.in-project true`，并尽量启用 **`virtualenvs.options.system-site-packages true`**，使 venv 能解析通过 `apt` 安装的 `picamera2` 等系统包。
+- **生产/板端**默认仅安装运行时依赖：`poetry install --only main`（脚本默认）。若需 pytest、类型检查等，在开发机或板上设置 `OGSCOPE_INSTALL_DEV=1` 后重装。
+
+### 1.3 安装 Poetry 与 Python 依赖
 
 ```bash
 # 进入项目目录
@@ -27,18 +88,26 @@ cd /path/to/OGScope
 curl -sSL https://install.python-poetry.org | python3 -
 export PATH="$HOME/.local/bin:$PATH"
 
-# 安装项目依赖
+# 开发机：完整依赖（含 dev）
 poetry install
+
+# 开发板（手动维护时）：仅运行时依赖，与 install.sh 默认一致
+# poetry install --no-interaction --only main
 ```
 
-### 1.3 使用安装脚本（推荐首次部署）
+### 1.4 使用安装脚本（推荐首次部署）
 
 仓库提供 `scripts/install.sh`，用于在开发板执行一次性环境准备。脚本会：
 
+- 读取 `/etc/os-release` 识别发行版，**仅支持 Debian/Ubuntu 系**（含 **Raspberry Pi OS**、Orange Pi Debian 等）；非该系将退出，避免误改软件源
 - 安装系统依赖与 Poetry
-- 安装项目 Python 依赖
+- 配置 Poetry 使用项目 `.venv` 与 `system-site-packages`（Poetry 版本支持时）
+- 默认执行 `poetry install --only main`（设 `OGSCOPE_INSTALL_DEV=1` 可装 dev）
+- 可选 `OGSCOPE_APT_SLOW=1`：分批 `apt` 并在批次间暂停，减轻低配板内存压力
+- **`OGSCOPE_MIRROR`**：`auto`（默认，按 `LANG`/`LC_*` 与系统时区启发）、`cn`（中国大陆镜像：apt 清华源 + PyPI 清华）、`international`（不替换 apt，PyPI 走默认）。在国内但语言为英文时，请显式 `export OGSCOPE_MIRROR=cn`。
+- 创建 `logs`、`uploads`、`data/plate_solve` 等目录
 - 生成/更新 `systemd` 服务（`ogscope.service`）
-- 注入 `PYTHONPATH` 与 `LD_LIBRARY_PATH`
+- 注入 `PYTHONPATH` 与 `LD_LIBRARY_PATH`（按实际存在的路径）
 - 启用服务开机自启
 
 执行方式：
@@ -49,10 +118,10 @@ chmod +x scripts/install.sh
 ./scripts/install.sh
 ```
 
-### 1.4 依赖维护建议
+### 1.5 依赖维护建议
 
 - 保持 `poetry.lock` 与仓库同步
-- 每次上传较大改动后，执行一次 `poetry install`
+- 每次上传较大改动后，在板上执行 `./scripts/board-update.sh`，或手动 `poetry install --only main` 后 `sudo systemctl restart ogscope`
 - 服务运行时优先使用固定虚拟环境解释器（见第 5 节）
 
 ## 2. 系统环境依赖（重点）
@@ -82,6 +151,8 @@ sudo apt install -y \
 - 这些系统路径默认不一定在 Poetry 虚拟环境的 `sys.path` 中
 - 结果是：服务运行于虚拟环境时，可能找不到 `picamera2` 等系统包
 
+**与 `system-site-packages` 的关系**：启用后，venv 的 `sys.path` 会包含系统 site-packages，一般即可 `import picamera2`；`systemd` 里仍保留 `PYTHONPATH`，用于覆盖不同发行版下 `/usr/local/lib/python3.x/dist-packages` 等路径，二者叠加不冲突。
+
 因此在服务配置中显式注入 `PYTHONPATH`，将系统 Python 包路径加入解释器搜索路径，例如：
 
 ```ini
@@ -107,6 +178,12 @@ Environment=LD_LIBRARY_PATH=/usr/lib/aarch64-linux-gnu
 - `scripts/install.sh`
   - 作用：安装依赖并生成 service
   - 状态：安装辅助脚本，不是运行时自动调用入口
+- `scripts/board-update.sh`
+  - 作用：已安装环境下的增量更新（可选 `OGSCOPE_GIT_PULL=1` 执行 `git pull`、`poetry install`、重启 `ogscope`）
+  - 状态：日常部署推荐入口
+- `scripts/uninstall.sh`
+  - 作用：停止并移除 `ogscope` systemd 单元、可选删除 `.venv`；默认保留 `logs/`、`data/` 等；需确认（交互输入 `YES` 或 `OGSCOPE_UNINSTALL_CONFIRM=1`）
+  - 状态：卸载辅助脚本；不卸载系统 apt 包与全局 Poetry
 - `scripts/start_debug_console.sh`
   - 作用：手动设置 `PYTHONPATH`/`LD_LIBRARY_PATH` 后前台启动
   - 状态：手动调试辅助脚本，不是默认生产启动链路
@@ -162,14 +239,24 @@ sudo systemctl status ogscope
 
 ### 6.2 日常代码更新（推荐）
 
-代码更新后（`git pull` 或手动上传）执行以下流程：
+代码更新后（`git pull` 或手动上传）可一键执行（镜像策略与 `install.sh` 相同，通过 `OGSCOPE_MIRROR` 控制）：
+
+```bash
+cd /path/to/OGScope
+chmod +x scripts/board-update.sh
+# 若需先拉取远端代码（仅 git 仓库）：OGSCOPE_GIT_PULL=1 ./scripts/board-update.sh
+# 中国大陆：OGSCOPE_MIRROR=cn ./scripts/board-update.sh
+./scripts/board-update.sh
+```
+
+或手动执行：
 
 ```bash
 # 进入项目目录
 cd /path/to/OGScope
 
-# 同步依赖（有 pyproject.toml/poetry.lock 变更时必须执行）
-poetry install
+# 同步依赖（有 pyproject.toml/poetry.lock 变更时必须执行；板端建议仅 main）
+poetry install --no-interaction --only main
 
 # 重启服务使新代码生效
 sudo systemctl restart ogscope
@@ -184,6 +271,49 @@ sudo journalctl -u ogscope -f
 - 若仅前端模板/静态文件变更，通常不需要 `poetry install`
 - 若服务文件配置有改动，需先 `sudo systemctl daemon-reload`
 
+### 6.3 卸载服务与本地环境（`scripts/uninstall.sh`）
+
+在需要**移除 systemd 服务**、清理项目内 **`.venv`**，或换目录重装时使用 `scripts/uninstall.sh`。脚本**不会**卸载系统已通过 `apt` 安装的包（如 `python3-picamera2`），也**不会**卸载用户级全局 **Poetry**；仅处理 OGScope 服务单元与项目目录内可选内容。
+
+**会执行的操作 / What it does**
+
+- `systemctl stop` / `disable` `ogscope`
+- 删除 `/etc/systemd/system/ogscope.service`（若存在），并 `daemon-reload`
+- 默认删除项目根目录下的 **`.venv`**（可用环境变量保留，见下）
+
+**默认保留 / Kept by default**
+
+- `logs/`、`uploads/`、`data/`（含 `data/plate_solve` 等）；若需一并删除，须显式开启（见下）
+
+**环境变量 / Environment**
+
+| 变量 | 含义 |
+|------|------|
+| `OGSCOPE_UNINSTALL_CONFIRM=1` | **非交互场景必须设置**（如 CI、脚本），否则脚本在非 TTY 下直接退出 |
+| `OGSCOPE_UNINSTALL_KEEP_VENV=1` | 保留 `.venv`，不删除虚拟环境 |
+| `OGSCOPE_UNINSTALL_REMOVE_DATA=1` | **危险**：删除 `logs/`、`uploads/`、`data/`（含星库等用户数据） |
+
+**交互确认 / Interactive**：在终端前台运行时，若未设置 `OGSCOPE_UNINSTALL_CONFIRM=1`，需输入全大写 **`YES`** 才会继续。
+
+```bash
+cd /path/to/OGScope
+chmod +x scripts/uninstall.sh
+
+# 交互：按提示输入 YES
+./scripts/uninstall.sh
+
+# 非交互：确认后执行
+OGSCOPE_UNINSTALL_CONFIRM=1 ./scripts/uninstall.sh
+
+# 保留虚拟环境，仅移除服务
+OGSCOPE_UNINSTALL_CONFIRM=1 OGSCOPE_UNINSTALL_KEEP_VENV=1 ./scripts/uninstall.sh
+
+# 同时删除日志与数据目录（慎用）
+OGSCOPE_UNINSTALL_CONFIRM=1 OGSCOPE_UNINSTALL_REMOVE_DATA=1 ./scripts/uninstall.sh
+```
+
+卸载后若需再次部署，重新执行 `./scripts/install.sh` 即可。
+
 ## 7. PyCharm 远程开发（当前实践）
 
 当前采用的是 **“本地 IDE 编辑 + 手动部署到开发板”** 模式，而不是由 IDE 直接接管远程运行。
@@ -273,11 +403,12 @@ router.include_router(new_router, tags=["NewModule - 新模块"])
 - `PYTHONPATH` 是否包含系统 `dist-packages`
 - `LD_LIBRARY_PATH` 是否包含 `libcamera` 相关库路径
 - 最近代码上传是否完整，依赖是否已重新安装
+- **`No module named 'scipy'`**：`board-update.sh` / `install.sh` 会在 `poetry install` 后校验并自动 `--no-cache` 重试与 pip 补装；若仍失败，删除 `.venv` 后执行 `OGSCOPE_MIRROR=cn ./scripts/board-update.sh`（或重装 `./scripts/install.sh`）
 
 ## 11. 常用命令速查
 
 ```bash
-# 安装/更新依赖
+# 安装/更新依赖（开发机）；板端可用 ./scripts/board-update.sh
 poetry install
 
 # 前台手动启动（调试时）
@@ -287,4 +418,8 @@ poetry run python -m ogscope.main
 sudo systemctl restart ogscope
 sudo systemctl status ogscope
 sudo journalctl -u ogscope -f
+
+# 卸载服务与 .venv（详见 §6.3；需确认或 OGSCOPE_UNINSTALL_CONFIRM=1）
+# ./scripts/uninstall.sh
+# OGSCOPE_UNINSTALL_CONFIRM=1 ./scripts/uninstall.sh
 ```