release: 发布 v0.2.0

本次发布聚焦降低误报风险、规范发布产物和重构仓库文档。主要变更： - 删除开机自启功能，移除 Windows 启动项注册表写入逻辑。 - 新增标准应用清单，声明应用以普通用户权限运行。 - 新增 framework-dependent 发布脚本，保持发布包不内置 .NET 运行时。 - 禁用单文件、自解压、裁剪和 ReadyToRun 发布方式，保持产物结构透明。 - 将发布资产命名规范化为 omni-notify-v0.2.0-win-x64.zip。 - 重写文档结构：README.md 面向用户，docs/development.md 面向开发者。 - 删除过时且内容重复的 PRD.md 与 docs/usage.md。验证： - dotnet build .\OmniNotify.csproj -c Release 构建通过。 - 发布脚本成功生成 v0.2.0 win-x64 压缩包。 - 发布目录未包含 coreclr.dll、hostfxr.dll、hostpolicy.dll 等 .NET 运行时文件。
2026-05-20 12:53:24 +08:00
parent 09b68ada48
commit 21fd8eaf55
12 changed files with 443 additions and 122 deletions
--- a/docs/development.md
+++ b/docs/development.md
@@ -0,0 +1,189 @@
+# Omni-Notify 开发者文档
+
+本文档面向需要构建、修改、审查或发布 Omni-Notify 的开发者。最终用户安装和使用说明请见 [README.md](../README.md)。
+
+## 技术栈
+
+- .NET 8
+- WPF
+- Windows Forms `NotifyIcon`
+- Built-in `HttpListener`
+- JSON 本地持久化
+
+项目不依赖第三方 NuGet 包。
+
+## 项目结构
+
+| 文件 | 责任 |
+| --- | --- |
+| `App.xaml.cs` | 应用生命周期、单实例互斥、托盘入口、本地 HTTP 服务启动 |
+| `MainWindow.xaml` | 主控制面板 UI |
+| `MainWindow.xaml.cs` | 频道管理、历史筛选、全局设置保存 |
+| `Models.cs` | 应用状态、频道、弹窗样式、历史记录、输入消息模型 |
+| `Services.cs` | 状态持久化、消息路由、限流熔断、本地 HTTP 接收服务 |
+| `PopupCoordinator.cs` | 弹窗队列、堆叠、替换和位置计算 |
+| `PopupWindow.xaml` | 单个弹窗窗口 UI |
+| `PopupWindow.xaml.cs` | 弹窗动画、生命周期和正文溢出处理 |
+| `app.manifest` | Windows 应用清单，声明普通用户权限运行 |
+| `scripts/package-release.ps1` | 标准发布脚本 |
+
+## 本地构建
+
+```powershell
+dotnet build .\OmniNotify.csproj -c Release
+```
+
+目标框架：
+
+```xml
+net8.0-windows
+```
+
+应用类型为 WPF 桌面应用，输出为 `WinExe`。
+
+## 本地运行
+
+```powershell
+dotnet run --project .\OmniNotify.csproj
+```
+
+默认监听：
+
+```text
+http://127.0.0.1:19845/
+```
+
+通知接口：
+
+```text
+POST http://127.0.0.1:19845/notify
+```
+
+请求体：
+
+```json
+{
+  "channel": "default",
+  "title": "Build finished",
+  "body": "The nightly job completed successfully."
+}
+```
+
+## 状态持久化
+
+状态文件路径：
+
+```text
+%LOCALAPPDATA%\OmniNotify\state.json
+```
+
+保存内容包括：
+
+- 全局设置
+- 频道列表和频道样式
+- 历史记录
+
+`AppStore.Save` 会在写入前清理超出保留天数和数量限制的历史记录。
+
+## 消息处理流程
+
+1. `LocalHttpServer` 接收本地 HTTP 请求。
+2. 请求体反序列化为 `IncomingMessage`。
+3. `NotificationRouter.Receive` 进入 UI Dispatcher。
+4. 检查熔断状态和每秒消息上限。
+5. 按 `channel` 严格匹配频道。
+6. 根据免打扰状态决定是否弹窗。
+7. 写入历史记录。
+8. `PopupCoordinator` 按频道样式显示弹窗。
+
+未知频道不会弹窗，会记录为 `IllegalChannel`。
+
+## 发布包
+
+生成 v0.2.0 Windows x64 发布包：
+
+```powershell
+.\scripts\package-release.ps1 -Version 0.2.0
+```
+
+默认产物：
+
+```text
+artifacts\omni-notify-v0.2.0-win-x64.zip
+```
+
+脚本参数：
+
+| 参数 | 默认值 | 说明 |
+| --- | --- | --- |
+| `Configuration` | `Release` | 构建配置 |
+| `Version` | `0.2.0` | 应用版本和产物版本 |
+| `RuntimeIdentifier` | `win-x64` | 目标运行时标识 |
+
+## 发布策略
+
+当前发布策略刻意保持透明、标准和低风险：
+
+- `SelfContained=false`
+- `PublishSingleFile=false`
+- `PublishTrimmed=false`
+- `PublishReadyToRun=false`
+- `--self-contained false`
+- 不使用混淆器
+- 不使用 UPX
+- 不使用自解压启动器
+- 不请求管理员权限
+
+发布脚本会检查产物目录中是否出现以下 .NET 运行时文件：
+
+- `coreclr.dll`
+- `clrjit.dll`
+- `hostfxr.dll`
+- `hostpolicy.dll`
+
+如果出现这些文件，脚本会失败，避免误发布自包含运行时包。
+
+## 安全敏感行为约束
+
+v0.2.0 已删除开机自启功能。代码中不应重新引入以下行为，除非经过明确产品决策：
+
+- 写入 `HKCU\Software\Microsoft\Windows\CurrentVersion\Run`
+- 创建计划任务实现自启动
+- 后台下载或执行外部程序
+- 全局键盘/鼠标钩子
+- 注入、提权、隐藏进程或绕过安全产品
+
+应用保留的本地监听服务仅绑定 `127.0.0.1`，不应改为 `0.0.0.0` 或局域网地址，除非同时补充认证和明确的安全设计。
+
+## 版本与 Git
+
+发布新版本时：
+
+1. 更新 `OmniNotify.csproj` 中的 `Version`、`FileVersion`、`AssemblyVersion`。
+2. 更新 `app.manifest` 中的 `assemblyIdentity version`。
+3. 更新文档中的示例版本号。
+4. 运行发布脚本生成 zip。
+5. 验证发布目录不包含 .NET 运行时文件。
+6. 提交代码。
+7. 创建 tag，例如 `v0.2.0`。
+8. 推送分支和 tag。
+
+建议 tag 命名：
+
+```text
+vMAJOR.MINOR.PATCH
+```
+
+建议发布资产命名：
+
+```text
+omni-notify-vMAJOR.MINOR.PATCH-win-x64.zip
+```
+
+## v0.2.0 发布摘要
+
+- 删除开机自启功能及相关注册表写入逻辑。
+- 新增标准应用清单，声明普通用户权限运行。
+- 新增 framework-dependent 发布脚本。
+- 发布包改为 `omni-notify-v0.2.0-win-x64.zip`。
+- README 改为用户文档，开发信息迁入本文档。