Dev latest

.github/workflows/ci.yml

@@ -43,11 +43,11 @@ jobs:
       with:
         node-version: "20"
         cache: "npm"
-        cache-dependency-path: web/analysis-ui/package-lock.json
+        cache-dependency-path: web/spa/package-lock.json
 
     - name: 构建星空解算控制台前端
       run: |
-        cd web/analysis-ui
+        cd web/spa
         npm ci
         npm run build
 

.gitignore

@@ -40,7 +40,7 @@ venv.bak/
 # ====================
 # Node (星图解算实验室前端 / Analysis lab UI)
 # ====================
-web/analysis-ui/node_modules/
+web/spa/node_modules/
 
 # ====================
 # Poetry
@@ -73,6 +73,13 @@ poetry.lock  # 在开发机与树莓派上可能不一致，建议忽略
 .pytest_cache/
 .coverage
 .coverage.*
+# macOS/复制等可能产生「.coverage 2」等带空格副本 / Spaced duplicates from copy tools
+.coverage *
+# 同上：构建目录内「file 2.js」「page 2.html」等误副本 / Duplicate-named build artifacts
+**/* 2.js
+**/* 3.js
+**/* 2.html
+**/* 3.html
 htmlcov/
 .tox/
 .nox/

CLAUDE.md

@@ -1,11 +1,13 @@
-# CLAUDE.md
+# [CLAUDE.md](http://CLAUDE.md)
 
 本文件为 Claude AI 助手提供项目上下文指导
 
 ## 项目概述
 
 OGScope 是一个基于 Raspberry Pi Zero 2W 的电子极轴镜系统，用于天文摄影中的精确极轴校准。
 
+人类可读文档按主题分组（入门、板上运维、API/契约、跨仓、工具）见 [docs/README.md](docs/README.md)（[English](docs/README_EN.md)）；下文仅保留 AI 常用要点与路径。
+
 ## 技术栈
 
 - **硬件**: Raspberry Pi Zero 2W, IMX327 相机, 2.4寸 SPI LCD
@@ -15,7 +17,7 @@ OGScope 是一个基于 Raspberry 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`。
+- **Web 前端（Vite SPA 源码）**: 目录 `[web/spa](web/spa)`（Vite + React + Tailwind）。`npm run build` 产出到 `**web/static/analysis-lab/`**（`base: /static/analysis-lab/`）：`**home.html**` 对应用户首页 `/`，`**index.html` / `system.html` / `camera.html**` 对应 `/debug/analysis`、`/debug`、`/debug/camera`。`**npm run build:home**`（随 `npm run build` 执行）用 Tailwind 生成 HUD 用 `hud-home.bundle.css`（扫描 `[web/spa/src/apps/home/homeHudBody.html](web/spa/src/apps/home/homeHudBody.html)`）。首页在 React 中挂载后仍加载既有 `[web/static/js/](web/static/js/)` 相机与解算脚本链。纯改首页可 `cd web/spa && npm run dev:home`；改调试台用 `npm run dev:tools` 或默认 `npm run dev`。同步开发板见 `scripts/sync_dev_board.sh`。i18n 与调试 SPA 共用 `[web/static/i18n/](web/static/i18n/)`（别名 `@i18n`）。**已移除 Jinja2 模板**，不再使用 `web/templates`。
 
 ## 开发环境
 
@@ -27,30 +29,37 @@ OGScope 是一个基于 Raspberry Pi Zero 2W 的电子极轴镜系统，用于
 
 ```
 ogscope/
-├── core/          # 核心功能：相机、图像处理、板块求解
-├── hardware/      # 硬件接口：相机驱动、显示驱动
-├── web/           # FastAPI Web 服务
-├── ui/            # SPI 屏幕界面
-├── algorithms/    # 天文算法
-├── data/          # 数据管理
-├── indi/          # INDI 集成（Phase 3）
-└── utils/         # 工具函数
+├── core/           # 标准契约编排 / Core contract orchestration
+├── domain/         # 领域服务 / Domain services
+├── web/            # FastAPI 入口与路由 / FastAPI entry and routes
+├── platform/       # 平台与基础设施 / Platform & infrastructure
+│   ├── hardware/       # 设备驱动（相机、GPIO、WiFi 等）/ Device drivers
+│   ├── hardware_plane/ # 共享硬件平面（契约、编排）/ Shared hardware plane
+│   ├── adapters/       # 边界适配 / Boundary adapters
+│   ├── ui/             # SPI 屏幕界面（预留）/ SPI UI (placeholder)
+│   └── indi/           # INDI 集成（Phase 3，预留）/ INDI integration (placeholder)
+├── algorithms/     # 天文与图像算法 / Astronomy & image algorithms
+├── data/           # 数据与目录约定 / Data layout
+└── utils/          # 通用工具 / Utilities
 ```
 
 ## 开发阶段
 
 ### Phase 1 - MVP (当前)
+
 - ✅ 项目结构搭建
 - 🔄 基础相机功能
 - 🔄 Web 界面和 API
 - 🔄 简单极轴校准算法
 
 ### Phase 2 - 完整功能
+
 - ⏳ SPI 屏幕支持
 - ⏳ 高级板块求解
 - ⏳ 移动 App
 
 ### Phase 3 - 生态集成
+
 - ⏳ INDI 驱动
 - ⏳ 赤道仪控制
 
@@ -69,7 +78,6 @@ ogscope/
 - `@pytest.mark.hardware`: 需要实际硬件的测试
 - `@pytest.mark.slow`: 运行较慢的测试
 
-
 ## 注意事项
 
 - 避免在代码中硬编码路径，使用配置系统
@@ -80,24 +88,28 @@ ogscope/
 ## 项目配置信息
 
 ### 服务器连接信息
+
 - **服务器地址**: [配置为环境变量]
 - **服务器项目目录**: [配置为环境变量]
 - **连接方式**: SSH
 - **用户名**: [配置为环境变量]
 - **端口**: [配置为环境变量]
 
 ### 开发环境配置
+
 - **本地项目路径**: [用户自定义]
 - **Python 版本**: 3.9+
 - **包管理器**: Poetry
 - **虚拟环境**: Poetry 管理
 
 ### 部署配置
+
 - **生产环境**: Raspberry Pi Zero 2W 开发板
 - **测试环境**: [与生产环境相同]
 - **虚拟环境目录**: [用户自定义]
 
 ### 系统服务配置
+
 在开发板运行时项目已配置为系统服务，服务配置文件位于 `/etc/systemd/system/ogscope.service`：
 
 ```ini
@@ -125,17 +137,19 @@ 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`）等。
+- **唯一详解**见 [docs/development/wifi-nm.md](docs/development/wifi-nm.md)（English: [wifi-nm_EN.md](docs/development/wifi-nm_EN.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`）。
+- **运行时 STA 回滚**：用户通过 Web/API 切 STA 成功后，应用内按 `wifi_sta_rollback_`* 超时无 IPv4 再切回 AP；与开机引导**分工不同、不冲突**（先 boot 完成再启动 `ogscope`）。
 - 二者均可能最终执行「切 AP」，行为**幂等**；不建议删除运行时回滚，否则仅冷启动有保障，**运行中**切 STA 失败后需手动恢复。
 
 **重要说明**：
+
 - 系统库（如 `libcamera`、`picamera2`）安装在系统环境中，通过 `PYTHONPATH` 环境变量注入到虚拟环境
 - `LD_LIBRARY_PATH` 确保系统库的链接库路径正确
 - 服务使用虚拟环境运行，但可以访问系统安装的相机驱动库
 
 ### 常用命令
+
 ```bash
 # 连接服务器
 ssh [ogstartech]@[192.168.31.16] -p [22]
@@ -166,7 +180,9 @@ python -m ogscope.main
 - 修复分支: `fix/xxx`
 
 ### 提交信息格式
+
 **必须使用中英文双语提交信息**，格式如下：
+
 ```
 中文描述 / English description
 
@@ -175,6 +191,7 @@ python -m ogscope.main
 ```
 
 示例：
+
 ```
 修复相机接口500错误 / Fix camera API 500 error
 
@@ -183,6 +200,7 @@ python -m ogscope.main
 ```
 
 ### 提交类型前缀
+
 ```
 feat: 添加新功能 / Add new feature
 fix: 修复bug / Fix bug
@@ -196,15 +214,32 @@ chore: 构建/工具变更 / Build/tool changes
 ## 开发板调试配置
 
 ### 开发板连接信息
+
 - **IP地址**: 192.168.31.16
 - **用户名**: ogstartech
 - **端口**: 22
 - **连接方式**: SSH
 
 ### 调试工作流程
+
 1. **代码修改后必须上传**: 修改或新建的代码必须先上传到开发板
 2. **不要遗漏文件**: 确保所有相关文件都已上传
 3. **服务重启**: 项目以系统服务方式运行，修改后需要重启服务
 4. **调试前确认**: 如果有不明白的地方，先询问用户再开始工作
 
+## 跨仓协同开发（OGScope x ZenitScope）
+
+- OGScope 在联动中是 **核心能力提供方**；ZenitScope 是 **上层调用方**。
+- OGScope 对外稳定契约为 `"/api/core/v1/*"`；内部开发接口为 `"/api/dev/*"`。
+- 任何跨仓需求按以下顺序执行：
+  1. 更新契约文档/兼容矩阵
+  2. 修改 OGScope 核心实现与测试
+  3. 同步 ZenitScope 适配层与上层逻辑
+  4. 双仓测试通过后再提交
+- 禁止在 OGScope 中重新引入旧路径：`/api/debug/`*、`/api/analysis/*`、`/api/system/*`。
+- 联动开发详细流程见 [docs/development/CROSS_PROJECT_COLLAB.md](docs/development/CROSS_PROJECT_COLLAB.md)（English: [CROSS_PROJECT_COLLAB_EN.md](docs/development/CROSS_PROJECT_COLLAB_EN.md)）。
+- Cursor 联动建议：
+  - 同一会话挂载双项目根（OGScope + ZenitScope）
+  - 指令中明确“分别在两个仓执行改动、测试、提交”
+  - 每次提交前先核对当前仓 `git status` 与 `git remote -v`
 

CONTRIBUTING.md

@@ -1,5 +1,7 @@
 # 贡献指南
 
+中文 | [English](CONTRIBUTING_EN.md)
+
 感谢你对 OGScope 项目的关注！我们欢迎任何形式的贡献。
 
 ## 如何贡献
@@ -54,14 +56,19 @@
    poetry run ruff check ogscope tests
    poetry run mypy ogscope
    ```
+   同时建议按 [Architecture Quick Checklist](docs/development/ARCHITECTURE_QUICK_CHECKLIST.md)（[English](docs/development/ARCHITECTURE_QUICK_CHECKLIST_EN.md)）做一次提交前自检，尤其是 API/架构改动。
 
 6. **提交更改**
    ```bash
    git add .
-   git commit -m "feat: add your feature"
+   git commit
    ```
 
-   提交信息格式：
+   提交信息格式（建议中英文双语）：
+   - 标题：`中文一句话 / English one-liner`
+   - 正文：按要点写 1~3 条中文/英文对应说明
+
+   提交类型前缀：
    - `feat:` 新功能
    - `fix:` Bug 修复
    - `docs:` 文档更新
@@ -101,6 +108,16 @@
 - 测试覆盖率应保持在 80% 以上
 - 使用合适的测试标记（unit/integration/hardware）
 
+### API 改动防误提规范（重要）
+
+- 标准契约固定在 `"/api/core/v1/*"`。
+- 开发接口固定在 `"/api/dev/*"`，不要再引入 `"/api/debug/*"`、`"/api/analysis/*"`、`"/api/system/*"` 旧路径。
+- `routes.py` 仅保留 HTTP 适配逻辑，业务逻辑下沉到 `domain/*` 与 `core/application/*`。
+- API 相关改动需同步更新：
+  - `docs/contracts/core-rest-v1.md`、`docs/contracts/core-rest-v1_EN.md`
+  - `docs/contracts/dev-rest-v1.md`、`docs/contracts/dev-rest-v1_EN.md`
+  - `docs/contracts/core-compatibility-matrix.md`（段内中英）
+
 ## 开发流程
 
 1. **选择 Issue**: 从 Issues 列表中选择要解决的问题
@@ -128,7 +145,7 @@
 
 如果你在贡献过程中遇到问题：
 
-- 查看 [开发文档](docs/development/README.md)
+- 查看 [文档索引](docs/README.md)（[English](docs/README_EN.md)）与 [开发文档](docs/development/README.md)
 - 在 [Discussions](https://github.com/OG-star-tech/OGScope/discussions) 提问
 - 联系维护者
 

CONTRIBUTING_EN.md

@@ -0,0 +1,107 @@
+# Contributing to OGScope
+
+English | [中文](CONTRIBUTING.md)
+
+Thank you for your interest in OGScope. We welcome contributions of all kinds.
+
+## How to contribute
+
+### Reporting bugs
+
+1. Search [Issues](https://github.com/OG-star-tech/OGScope/issues) for duplicates.
+2. If none, open a new issue with:
+   - Clear description
+   - Steps to reproduce
+   - Expected vs actual behavior
+   - Environment (OS, Python version, etc.)
+   - Logs or screenshots if relevant
+
+### Feature requests
+
+1. Open an issue describing the use case.
+2. Wait for maintainer feedback before large work.
+
+### Code contributions
+
+1. **Fork** the repository and clone your fork.
+2. **Branch**: `git checkout -b feature/your-feature-name`
+3. **Dev dependencies**:
+   ```bash
+   poetry install
+   poetry run pre-commit install
+   ```
+4. **Implement** following project style; add tests; update docs.
+5. **Validate**:
+   ```bash
+   poetry run pytest
+   poetry run black ogscope tests
+   poetry run ruff check ogscope tests
+   poetry run mypy ogscope
+   ```
+   For API/architecture changes, also run through [Architecture Quick Checklist](docs/development/ARCHITECTURE_QUICK_CHECKLIST_EN.md).
+6. **Commit** with bilingual messages when possible:
+   - Title: `Chinese one-liner / English one-liner`
+   - Body: a few paired bullets
+   - Prefixes: `feat:`, `fix:`, `docs:`, `style:`, `refactor:`, `test:`, `chore:`
+7. **Push** and open a **Pull Request** using the template.
+
+## Style
+
+### Python
+
+- **Black** formatting (88 columns)
+- **Ruff** linting
+- Type hints (**MyPy**)
+- **PEP 8** baseline
+
+### Documentation
+
+- Markdown
+- Full-width punctuation for Chinese text (except inside English fragments)
+- Runnable code samples
+
+### Tests
+
+- New features need tests
+- Aim for meaningful coverage on touched code
+- Use markers: `unit` / `integration` / `hardware`
+
+### API change policy (important)
+
+- Stable contract: `"/api/core/v1/*"`.
+- Developer APIs: `"/api/dev/*"` only—do not bring back `"/api/debug/*"`, `"/api/analysis/*"`, `"/api/system/*"`.
+- `routes.py` is HTTP-only; logic belongs in `domain/*` and `core/application/*`.
+- Update contract docs together with code:
+  - `docs/contracts/core-rest-v1.md` / `docs/contracts/core-rest-v1_EN.md`
+  - `docs/contracts/dev-rest-v1.md` / `docs/contracts/dev-rest-v1_EN.md`
+  - `docs/contracts/core-compatibility-matrix.md` (inline bilingual)
+
+## Workflow
+
+1. Pick or file an issue  
+2. Develop and test locally  
+3. Open a PR  
+4. Review  
+5. Merge
+
+## Review expectations
+
+- Correct behavior
+- Style compliance
+- Adequate tests
+- Docs updated
+- Breaking changes called out with migration notes
+
+## Community
+
+- Be respectful
+- Give constructive feedback
+- Help newcomers
+
+## Getting help
+
+- [Documentation index](docs/README_EN.md) | [中文](docs/README.md)
+- [Development docs (中文)](docs/development/README.md) / [English](docs/development/README_EN.md)
+- [GitHub Discussions](https://github.com/OG-star-tech/OGScope/discussions)
+
+Thank you for contributing.