OG-star-tech · YihuiLu · Apr 6, 2026 · Oct 22, 2025 · Oct 23, 2025 · Oct 23, 2025
diff --git a/.github/workflows/ci.yml b/.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

diff --git a/.github/workflows/release.yml b/.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

diff --git a/.gitignore b/.gitignore
@@ -37,10 +37,15 @@ env.bak/
 venv.bak/
 .python-version
 
+# ====================
+# Node (星图解算实验室前端 / Analysis lab UI)
+# ====================
+web/analysis-ui/node_modules/
+
 # ====================
 # Poetry
 # ====================
-poetry.lock  # 在开发机和 Orange Pi 上可能不一致，建议忽略
+poetry.lock  # 在开发机与树莓派上可能不一致，建议忽略
 .poetry/
 
 # ====================
@@ -92,6 +97,12 @@ logs/
 *.sqlite3
 *.db-shm
 *.db-wal
+!data/catalog/stars.db
+data/catalog/raw/*
+data/catalog/index/*
+data/catalog/meta/*
+!data/catalog/meta/manifest.json
+!data/catalog/README.md
 
 # ====================
 # 配置文件（敏感信息）
@@ -137,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

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -4,17 +4,18 @@
 
 ## 项目概述
 
-OGScope 是一个基于 Orange Pi Zero 2W 的电子极轴镜系统，用于天文摄影中的精确极轴校准。
+OGScope 是一个基于 Raspberry Pi Zero 2W 的电子极轴镜系统，用于天文摄影中的精确极轴校准。
 
 ## 技术栈
 
-- **硬件**: Orange Pi Zero 2W, IMX327 相机, 2.4寸 SPI LCD
+- **硬件**: Raspberry Pi Zero 2W, IMX327 相机, 2.4寸 SPI LCD
 - **语言**: Python 3.9+
 - **包管理**: Poetry
 - **Web 框架**: FastAPI + Uvicorn
 - **日志**: 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`。
 
 ## 开发环境
 
@@ -59,6 +60,7 @@ ogscope/
 - 类型提示: 使用 Python 类型注解
 - 文档字符串: Google 风格
 - 导入顺序: 标准库 → 第三方库 → 本地模块
+- 注释规范: 以后新增或修改注释必须使用中英文双语（中文 / English）
 
 ## 测试标记
 
@@ -67,16 +69,6 @@ ogscope/
 - `@pytest.mark.hardware`: 需要实际硬件的测试
 - `@pytest.mark.slow`: 运行较慢的测试
 
-## 配置管理
-
-- 默认配置: `default_config.json`
-- 环境变量: `.env` (从 `.env.example` 复制)
-- 运行时配置: `ogscope/config.py` (Pydantic Settings)
-
-## 参考项目
-
-- **PiFinder**: 板块求解寻星器架构参考
-- **OpenMV Polar Scope**: 极轴镜算法参考
 
 ## 注意事项
 
@@ -101,12 +93,12 @@ ogscope/
 - **虚拟环境**: Poetry 管理
 
 ### 部署配置
-- **生产环境**: Orange Pi Zero 2W 开发板
+- **生产环境**: Raspberry Pi Zero 2W 开发板
 - **测试环境**: [与生产环境相同]
 - **虚拟环境目录**: [用户自定义]
 
 ### 系统服务配置
-项目已配置为系统服务，服务配置文件位于 `/etc/systemd/system/ogscope.service`：
+在开发板运行时项目已配置为系统服务，服务配置文件位于 `/etc/systemd/system/ogscope.service`：
 
 ```ini
 [Unit]
@@ -129,6 +121,15 @@ RestartSec=3
 WantedBy=multi-user.target
 ```
 
+在本地运行时，使用虚拟环境，因为有些硬件只能在开发板上调用，所以本地只是代码编写，远程测试
+
+### WiFi 与网络（NetworkManager）
+
+- **唯一详解**见 [`docs/development/wifi-nm.md`](docs/development/wifi-nm.md)：热点默认密码、`network.env`、`/debug/system`、Web API、sudoers（`ogscope-wifi` / `ogscope-nmcli`）等。
+- **开机引导**：`ogscope-network-boot.service`（root oneshot，`Before=ogscope.service`）在冷启动时若 STA 长时间无可用 IPv4 则切 **AP**，不依赖 Python 进程。
+- **运行时 STA 回滚**：用户通过 Web/API 切 STA 成功后，应用内按 `wifi_sta_rollback_*` 超时无 IPv4 再切回 AP；与开机引导**分工不同、不冲突**（先 boot 完成再启动 `ogscope`）。
+- 二者均可能最终执行「切 AP」，行为**幂等**；不建议删除运行时回滚，否则仅冷启动有保障，**运行中**切 STA 失败后需手动恢复。
+
 **重要说明**：
 - 系统库（如 `libcamera`、`picamera2`）安装在系统环境中，通过 `PYTHONPATH` 环境变量注入到虚拟环境
 - `LD_LIBRARY_PATH` 确保系统库的链接库路径正确
@@ -137,7 +138,7 @@ WantedBy=multi-user.target
 ### 常用命令
 ```bash
 # 连接服务器
-ssh [用户名]@[服务器地址] -p [端口]
+ssh [ogstartech]@[192.168.31.16] -p [22]
 
 # 部署到服务器
 # 使用 git clone 或手动上传
@@ -159,20 +160,51 @@ python -m ogscope.main
 
 ## Git 工作流
 
-目前还没上传到Git
 - 主分支: `main` (稳定版本)
 - 开发分支: `dev` (开发版本)
 - 功能分支: `feature/xxx`
 - 修复分支: `fix/xxx`
 
-提交信息格式:
+### 提交信息格式
+**必须使用中英文双语提交信息**，格式如下：
 ```
-feat: 添加新功能
-fix: 修复bug
-docs: 更新文档
-style: 代码格式调整
-refactor: 重构代码
-test: 添加测试
-chore: 构建/工具变更
+中文描述 / English description
+
+- 中文详细说明 / English detailed explanation
+- 中文变更内容 / English change content
 ```
 
+示例：
+```
+修复相机接口500错误 / Fix camera API 500 error
+
+- 添加缺失的方法实现 / Add missing method implementations
+- 重新组织服务类结构 / Reorganize service class structure
+```
+
+### 提交类型前缀
+```
+feat: 添加新功能 / Add new feature
+fix: 修复bug / Fix bug
+docs: 更新文档 / Update documentation
+style: 代码格式调整 / Code style changes
+refactor: 重构代码 / Refactor code
+test: 添加测试 / Add tests
+chore: 构建/工具变更 / Build/tool changes
+```
+
+## 开发板调试配置
+
+### 开发板连接信息
+- **IP地址**: 192.168.31.16
+- **用户名**: ogstartech
+- **端口**: 22
+- **连接方式**: SSH
+
+### 调试工作流程
+1. **代码修改后必须上传**: 修改或新建的代码必须先上传到开发板
+2. **不要遗漏文件**: 确保所有相关文件都已上传
+3. **服务重启**: 项目以系统服务方式运行，修改后需要重启服务
+4. **调试前确认**: 如果有不明白的地方，先询问用户再开始工作
+
+
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -8,7 +8,7 @@
 
 如果你发现了 bug，请：
 
-1. 在 [Issues](https://github.com/your-username/OGScope/issues) 页面搜索是否已有相关问题
+1. 在 [Issues](https://github.com/OG-star-tech/OGScope/issues) 页面搜索是否已有相关问题
 2. 如果没有，创建新 Issue，包含：
    - 详细的问题描述
    - 复现步骤
@@ -27,7 +27,7 @@
 1. **Fork 项目**
    ```bash
    # 在 GitHub 上点击 Fork 按钮
-   git clone https://github.com/your-username/OGScope.git
+   git clone https://github.com/OG-star-tech/OGScope.git
    cd OGScope
    ```
 
@@ -129,7 +129,7 @@
 如果你在贡献过程中遇到问题：
 
 - 查看 [开发文档](docs/development/README.md)
-- 在 [Discussions](https://github.com/your-username/OGScope/discussions) 提问
+- 在 [Discussions](https://github.com/OG-star-tech/OGScope/discussions) 提问
 - 联系维护者
 
 感谢你的贡献！🎉

diff --git a/Makefile b/Makefile
@@ -54,8 +54,8 @@ lock:  ## 锁定依赖版本
 build:  ## 构建包
 	poetry build
 
-deploy:  ## 部署到 Orange Pi（需要配置 SSH）
-	@echo "同步代码到 Orange Pi..."
+deploy:  ## 部署到 Raspberry Pi（需要配置 SSH 主机别名）
+	@echo "同步代码到 Raspberry Pi..."
 	rsync -avz --exclude '.git' --exclude '__pycache__' --exclude '*.pyc' \
 		--exclude '.venv' --exclude 'PiFinder-release' \
 		. orangepi:~/OGScope/
@@ -69,7 +69,7 @@ logs:  ## 查看日志
 status:  ## 查看服务状态
 	ssh orangepi "sudo systemctl status ogscope"
 
-ssh:  ## SSH 到 Orange Pi
+ssh:  ## SSH 到 Raspberry Pi（主机名见 Makefile 中 rsync 目标）
 	ssh orangepi
 
 docs:  ## 生成文档（如果使用 Sphinx）