添加 README

2026-06-26 06:07:01 +00:00
parent df6e9ab9e9
commit 84b9e8e66f
1 changed files with 525 additions and 0 deletions
@@ -0,0 +1,525 @@
+# YMhut Box 中文项目说明
+
+YMhut Box 是一个以 C#、.NET 和 WinUI 3 为核心的 Windows 原生工具箱项目。当前仓库同时保留了新版 WinUI 桌面端、核心工具逻辑、测试项目、辅助进程、统一管理服务、旧版 Electron 项目以及更新/反馈相关服务代码。
+
+当前版本信息来自 `version.json`：
+
+- 版本号：`2.0.7`
+- 构建号：`05`
+- 发布通道：`stable`
+
+## 项目定位
+
+本项目用于构建 YMhut Box 桌面工具箱，主要目标是把原有 Web/Electron 工具箱迁移到原生 Windows 桌面体验，并配套提供更新、反馈、资源管理和服务端管理能力。
+
+核心能力包括：
+
+- WinUI 3 桌面壳、页面、窗口和托盘体验。
+- C#/.NET 核心工具目录、工具执行、设置、日志、反馈、下载和更新逻辑。
+- WebView2 内嵌页面，用于工具页、结果页、启动动画和 3D/可视化内容。
+- 独立 Worker、插件宿主和下载宿主进程。
+- MSTest 单元测试。
+- MSIX 和传统 EXE 安装包构建流程。
+- Go 版本统一管理服务，兼容旧版更新 JSON、下载目录和反馈接口。
+- 旧版 Electron 项目保留，便于历史对照和迁移。
+
+## 技术栈
+
+桌面端：
+
+- C# / .NET 10
+- WinUI 3
+- Windows App SDK
+- WebView2
+- Microsoft.Extensions.DependencyInjection
+- SQLite
+- MSTest
+
+服务端：
+
+- Go
+- SQLite，部分路径支持 MySQL 配置
+- Vue 前端管理台和门户页
+- Rust WASM 辅助模块
+
+旧版客户端：
+
+- Electron
+- Node.js
+- HTML/CSS/JavaScript
+
+## 仓库结构
+
+```text
+.
+|-- src/
+|   |-- box-winUI/                 # WinUI 3 桌面应用
+|   |-- YMhut.Box.Core/            # 核心业务逻辑、工具系统、设置、日志、反馈、更新
+|   |-- YMhut.Box.Tests/           # MSTest 测试项目
+|   |-- YMhut.Box.Worker/          # 工具执行 Worker 进程
+|   |-- YMhut.Box.PluginHost/      # 插件宿主进程
+|   `-- YMhut.Box.DownloadHost/    # 下载宿主进程
+|-- assets/                        # 图标、字体、图片、本地数据、太阳系纹理源素材
+|-- server/
+|   |-- unified-management/        # 统一管理服务，整合更新和反馈能力
+|   |-- update/                    # 旧更新服务 Go 实现
+|   `-- feedback-mailer/           # 旧反馈工单服务
+|-- box-old/                       # 旧版 Electron 工具箱
+|-- installer/                     # Inno Setup 安装脚本
+|-- scripts/                       # 构建脚本
+|-- docs/                          # 架构、贡献、迁移、插件文档
+|-- update-notice/                 # 更新公告 JSON
+|-- 新增工具文档/                  # 新增工具接口/需求说明
+|-- build.bat                      # Windows 构建入口
+|-- YMhut.Box.Native.sln           # Visual Studio 解决方案
+|-- Directory.Build.props          # 统一版本注入
+|-- NuGet.Config                   # NuGet 配置
+|-- version.json                   # 项目版本源
+`-- README.md                      # 英文简要说明
+```
+
+## 解决方案项目
+
+`YMhut.Box.Native.sln` 包含以下项目：
+
+- `YMhut.Box.Core`：核心库，目标框架 `net10.0`。
+- `YMhut.Box.WinUI`：桌面主程序，目标框架 `net10.0-windows10.0.19041.0`。
+- `YMhut.Box.Tests`：测试项目，目标框架 `net10.0`。
+- `YMhut.Box.Worker`：独立工具执行进程。
+- `YMhut.Box.PluginHost`：插件宿主进程。
+- `YMhut.Box.DownloadHost`：下载宿主进程。
+
+## 桌面端说明
+
+主程序目录是 `src/box-winUI/`。
+
+主要内容：
+
+- `App.xaml`、`App.xaml.cs`：应用入口和生命周期。
+- `MainWindow.xaml`、`MainWindow.xaml.cs`：主窗口。
+- `Views/`：主页面、设置页、工具箱页、媒体页、浏览器页、日志页、插件页等。
+- `Views/Tools/`：具体工具页面、工具注册表、工具页面基类和生成工具页。
+- `Services/`：下载、更新、托盘、启动、插件、WebView2、窗口状态等服务。
+- `Controls/`：天气、指标图表、信息条等自定义控件。
+- `Assets/`：桌面端图标、启动页、工具页 Web 资源、太阳系/地球 3D 资源。
+- `Strings/zh-CN`、`Strings/en-US`：中英文资源文件。
+
+Release 构建时：
+
+- 运行时标识为 `win-x64`。
+- 使用 MSIX 包类型。
+- 关闭 Appx 签名，由构建脚本处理本地证书和输出。
+- 会复制 Worker、PluginHost、DownloadHost 输出到主程序输出目录。
+- 会复制内置 WebView2 静态资源和工具数据。
+
+## 核心库说明
+
+核心库目录是 `src/YMhut.Box.Core/`。
+
+主要模块：
+
+- `Api/`：API 端点和远程接口管理。
+- `App/`：应用路径、安装布局、运行时布局策略、开源参考资料。
+- `Data/`：本地参考数据加载。
+- `DevEnvironments/`：开发环境配置模型。
+- `Downloads/`：下载队列、下载模型、直接下载校验。
+- `Feedback/`：反馈码、反馈提交、反馈包加密、反馈记录。
+- `Logging/`：JSON、SQLite、弹性日志服务和日志展示本地化。
+- `Media/`：远程媒体目录、媒体解析、音量模型。
+- `Net/`：HTTP 服务和重定向解析。
+- `Plugins/`：内置插件、插件注册、插件状态和插件宿主协议。
+- `Settings/`：应用设置、语言、置顶工具、协议文档。
+- `SolarSystem/`：太阳系星历模型和服务。
+- `Startup/`：启动检查、安装完整性检查和启动初始化管线。
+- `System/`：硬件信息和系统指标。
+- `Tools/`：工具目录、工具执行、结果渲染、隐私清理、Worker 协议和布局计算。
+- `Updates/`：更新模型、版本比较、更新接口策略。
+
+## 测试
+
+测试项目在 `src/YMhut.Box.Tests/`。
+
+测试覆盖方向包括：
+
+- 设置读写和协议接受。
+- 下载、开发环境、反馈服务。
+- 安装布局、日志、媒体解析。
+- 插件、工具目录、工具执行和 Worker。
+- 远程工具排序、结果体验、Web payload 序列化。
+- 敏感文本、启动检查、更新版本比较。
+
+常用测试命令：
+
+```powershell
+dotnet restore YMhut.Box.Native.sln --configfile NuGet.Config --ignore-failed-sources
+dotnet test src\YMhut.Box.Tests\YMhut.Box.Tests.csproj -c Debug --no-restore
+```
+
+## 构建
+
+推荐使用根目录的 `build.bat`：
+
+```powershell
+build.bat --target=publish
+build.bat --target=msix
+build.bat --target=exe
+build.bat --target=both
+```
+
+可选参数：
+
+```powershell
+build.bat --target=both --configuration=Release --platform=x64
+build.bat --target=both --skip-tests
+build.bat --target=both --skip-exe
+build.bat --target=exe --skip-msix
+```
+
+构建脚本实际入口是：
+
+```powershell
+scripts\build-winui.ps1
+```
+
+主要输出目录：
+
+- `build/winui/publish/`：发布输出。
+- `build/winui/msix-stage/`：MSIX 临时目录。
+- `build/winui/logs/`：构建日志。
+- `latest/`：最新构建结果。
+- `installer_output/`：安装包、证书、更新信息。
+- `server/update/public/downloads/`：可被更新服务使用的下载包目录。
+
+这些输出目录通常不提交到 Git。
+
+## 发布和更新
+
+构建脚本会使用以下默认地址生成下载和更新信息：
+
+- 下载基础地址：`https://update.ymhut.cn/downloads/`
+- 更新信息基础地址：`https://update.ymhut.cn/update-info/`
+
+可通过环境变量覆盖：
+
+```powershell
+$env:YMHUT_DOWNLOAD_BASE_URI="https://example.com/downloads/"
+$env:YMHUT_UPDATE_BASE_URI="https://example.com/update-info/"
+```
+
+更新公告文件位于 `update-notice/`，用于维护不同版本的更新说明。
+
+## 服务端
+
+### 统一管理服务
+
+目录：
+
+```text
+server/unified-management/
+```
+
+它用于整合旧 `server/update` 和 `server/feedback-mailer` 的能力。
+
+主要能力：
+
+- Go 后端，默认 SQLite。
+- 可选 MySQL 配置。
+- 兼容旧路由：`update-info.json`、`tool-status.json`、`media-types.json`、`modules.json`、下载文件和反馈接口。
+- 提供 `/api/client/bootstrap` 客户端发现接口。
+- 管理员登录、验证码、HttpOnly session cookie、CSRF 检查。
+- 媒体源和数据源健康检查。
+- Vue 管理台、门户页和 Rust WASM 辅助模块。
+
+运行：
+
+```powershell
+cd server\unified-management
+go mod tidy
+go run main.go
+```
+
+或：
+
+```powershell
+go run .\cmd\unified-management
+```
+
+测试：
+
+```powershell
+go test ./...
+```
+
+默认监听地址：
+
+```text
+:33550
+```
+
+常用环境变量：
+
+- `YMHUT_LISTEN`：监听地址。
+- `PORT`：端口，作为监听地址的简写来源。
+- `YMHUT_BASE_URL`：公开服务地址。
+- `YMHUT_DB_PROVIDER`：`sqlite` 或 `mysql`。
+- `YMHUT_SQLITE_PATH`：SQLite 数据库路径。
+- `YMHUT_MYSQL_DSN`：MySQL DSN。
+- `YMHUT_UPDATE_PUBLIC_DIR`：旧更新服务 public 目录。
+- `YMHUT_DOWNLOADS_DIR`：下载包目录。
+- `YMHUT_SOURCE_CHECK_SECONDS`：源健康检查间隔。
+
+前端目录：
+
+- `web/admin`：Vue 管理台。
+- `web/portal`：Vue 公共门户。
+- `web/setup`：初始化/设置页面。
+- `web/wasm`：Rust WASM 辅助模块。
+
+前端构建示例：
+
+```powershell
+cd server\unified-management\web\admin
+npm install
+npm run build
+
+cd ..\portal
+npm install
+npm run build
+```
+
+发布二进制：
+
+```powershell
+cd server\unified-management
+.\scripts\build-release.ps1 -Version 0.1.0
+```
+
+输出目录为 `server/unified-management/dist-release/`，该目录不提交。
+
+### 更新服务
+
+目录：
+
+```text
+server/update/
+```
+
+该目录保留旧更新服务的 Go 实现，包括：
+
+- 下载中心页面。
+- JSON API。
+- 下载文件目录。
+- 管理后台。
+- 路由配置。
+- 用户和认证模型。
+- 静态资源和视图模板。
+
+注意：`server/update/public/downloads/` 存放安装包和 MSIX 等大文件，已在 `.gitignore` 中排除。
+
+### 反馈服务
+
+目录：
+
+```text
+server/feedback-mailer/
+```
+
+该目录保留反馈工单服务，包括：
+
+- Go 后端。
+- SQLite 数据。
+- 管理前端。
+- 反馈包处理。
+- 旧客户端兼容接口。
+
+注意：`config.json`、生成的可执行文件和 `storage/` 运行态目录已在 `.gitignore` 中排除。
+
+## 旧版项目
+
+旧版 Electron 项目保留在：
+
+```text
+box-old/
+```
+
+它包含：
+
+- Electron 主进程和 preload。
+- 旧版 Web UI。
+- 旧版工具实现。
+- 旧版工具状态和更新信息。
+- 旧构建脚本和安装配置。
+
+该目录主要用于历史保留、迁移参考和功能对照。
+
+## 资源
+
+资源目录：
+
+```text
+assets/
+```
+
+主要内容：
+
+- `icons/`：应用图标。
+- `images/`：图片资源。
+- `fonts/`：字体资源。
+- `data/`：本地数据，如行政区划、三国杀皮肤配置、参考数据。
+- `source-textures/solar/`：太阳系纹理源文件。
+
+桌面端运行时还会从 `src/box-winUI/Assets/` 加载应用内静态资源，包括：
+
+- 启动画面。
+- 工具页 Web 资源。
+- 工具结果页 Web 资源。
+- home globe 和太阳系可视化资源。
+
+## Git 和 Gitea 推送
+
+当前远端仓库地址：
+
+```text
+http://admin_gitea@git.ymhut.cn/admin_gitea/YMhut-box-C-.git
+```
+
+常用提交流程：
+
+```powershell
+git status
+git add .
+git commit -m "提交说明"
+git push
+```
+
+查看远端：
+
+```powershell
+git remote -v
+```
+
+如果提示需要登录，请使用 Gitea 账号登录。不要把密码写进远端 URL，也不要把密码写进文档或提交记录。
+
+如果 Git 使用了错误的缓存凭据，可以清理该站点凭据后重新推送：
+
+```powershell
+@"
+protocol=http
+host=git.ymhut.cn
+
+"@ | git credential reject
+
+git push
+```
+
+## 不应提交的内容
+
+`.gitignore` 已排除常见缓存、构建产物、运行态数据和大安装包。
+
+主要包括：
+
+- `.cache/`
+- `.codex/`
+- `.codex_state/`
+- `.agents/`
+- `.tmp/`
+- `.idea/`
+- `.vs/`
+- `build/`
+- `latest/`
+- `installer_output/`
+- `Release/`
+- `node_modules/`
+- `dist/`
+- `bin/`
+- `obj/`
+- `src/box-winUI/AppPackages/`
+- `server/update/build/`
+- `server/update/public/downloads/`
+- `server/unified-management/dist-release/`
+- `server/unified-management/storage/`
+- `server/feedback-mailer/storage/`
+- `server/feedback-mailer/config.json`
+
+如果执行 `git status --ignored` 看到这些路径前面是 `!!`，表示它们已被忽略，这是正常现象。
+
+## 常见状态说明
+
+`git status` 显示：
+
+```text
+Your branch is up to date with 'origin/main'.
+```
+
+表示本地分支和远端分支同步。
+
+显示：
+
+```text
+Changes not staged for commit
+```
+
+表示有文件已修改，但还没有执行 `git add`。
+
+显示：
+
+```text
+LF will be replaced by CRLF
+```
+
+这是 Windows 换行提示，不是错误。它表示 Git 可能在工作区把 LF 换行转换成 CRLF。
+
+显示：
+
+```text
+Everything up-to-date
+```
+
+表示没有新的本地提交需要推送。
+
+## 本地开发建议
+
+推荐流程：
+
+```powershell
+git pull
+dotnet restore YMhut.Box.Native.sln --configfile NuGet.Config --ignore-failed-sources
+dotnet build src\box-winUI\YMhut.Box.WinUI.csproj -c Debug -p:Platform=x64 --no-restore
+dotnet test src\YMhut.Box.Tests\YMhut.Box.Tests.csproj -c Debug --no-restore
+```
+
+服务端开发：
+
+```powershell
+cd server\unified-management
+go test ./...
+go run main.go
+```
+
+前端管理台开发：
+
+```powershell
+cd server\unified-management\web\admin
+npm install
+npm run dev
+```
+
+门户页开发：
+
+```powershell
+cd server\unified-management\web\portal
+npm install
+npm run dev
+```
+
+## 维护注意事项
+
+- 修改版本号时优先更新 `version.json`，构建时会通过 `Directory.Build.props` 注入程序集版本。
+- 提交前先看 `git status`，确认没有缓存、构建产物和本地数据库混入。
+- 发布安装包、MSIX、下载包建议走构建脚本输出目录，不直接手动放入源码提交。
+- 服务端默认账号、数据库路径、生产密钥和密码不要写入仓库。
+- 大文件如果确实需要进入仓库，建议分批提交和推送，避免 HTTP 413。
+
+## 许可证
+
+仓库包含 `LICENSE`，当前为 GNU General Public License v3.0 文本。