# OA岛 **Repository Path**: callmenz/island-oa ## Basic Information - **Project Name**: OA岛 - **Description**: 参照项目winisland - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-10-12 - **Last Updated**: 2026-10-12 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 供应链 OA 提醒小助手 · 灵动岛 给使用 **TeamFace** 内核的 OA 系统(提示中心 / 待办)使用的桌面提醒工具。定时获取未读消息与待办,在屏幕顶部的灵动岛中显示数量、消息列表和新消息通知。 **技术栈**:.NET 10、[Windows App SDK](https://learn.microsoft.com/windows/apps/windows-app-sdk/) 2.3(WinUI 3)。界面与交互结构参考 [WinLand](https://github.com/luolangaga/WinLand),按 OA 业务裁剪为单一「OA」内容源。 配置、状态和日志位于 `%APPDATA%\oa-widget\`,可通过 `OA_WIDGET_HOME` 指定独立目录。 > 仓库里**不含任何具体部署的地址与账号**:OA 服务器地址、账号与密码都在「设置 → 账号」里填(分别落在 `config.json` 的 `base` / `account` / `password`,密码经 DPAPI 加密)。首次运行会直接打开设置页要求填写。 ## 灵动岛交互 | 操作或状态 | 行为 | |---|---| | 收起 | 170×44 DIP 胶囊,显示未读数与轮询状态 | | 悬停 | 展开消息中心(480×430),移出后收起;可在设置中关闭「悬停展开」 | | 关闭悬停展开后单击 | 展开/收起常驻消息中心,点岛体以外区域收起 | | 触控单击 | 展开并常驻(触摸没有悬停),点岛外收起 | | 中键 / 双击(有临时通知时)| 关闭当前临时通知 | | 新消息 | 岛体切换为临时通知条;免打扰期间自动通知不弹出,手动操作结果照常显示 | | 展开态内容 | 「立即检查」「打开 OA」「全部已读」「设置」「收起」 | | 右键 | 岛体与展开面均可打开同一菜单:立即检查、打开消息中心、打开 OA、检查更新…、设置…、暂停/继续轮询、非工作时间免打扰、开机自启、查看日志、退出 | | 托盘图标 | 双击打开设置;右键打开同一菜单 | 岛体、消息中心与临时通知共用一个窗口。窗口预留固定透明画布,动画只改变岛体尺寸,避免原生窗口反复调整尺寸造成残影;Win32 圆角裁剪让透明画布上的点击穿透到桌面,全屏应用时按设置隐藏或缩为屏幕边缘的小色条。 开着「无待审批时收成小色条」时,岛体不会凭空消失:它收成岛体自己边上的一条小色条(顶部模式在岛体上沿、底部模式在岛体下沿,都在任务栏上方),鼠标靠近就临时现身、离开再收回,来了新待审批或新消息照常回来。 ## 外观与位置 设置页可调:主题(跟随系统 / 深 / 浅)、灵动岛外观(Apple / Fluent)、系统材质(Acrylic / Mica)、位置(顶部 / 底部)、水平对齐、目标显示器、顶部/底部/水平偏移、缩放(50%–200%)、悬停展开、无待审批时收成小色条,以及全屏应用时的行为(照常显示 / 贴边小色条 / 完全隐藏;锁屏不算全屏应用)。外观与位置保存在 `island-settings.json`。 ## 版本更新 从 `gitee.com/callmenz/island-oa` 的 release 拉版本号,只下载**全量更新包**(约 0.9MB)原地替换程序自身文件后自动重启。 - **入口**:「设置 → 关于」有版本、检查按钮、更新说明与「下载并更新」;托盘与右键菜单有「检查更新…」(发现新版时直接写成「发现新版本 x.y.z」)。默认启动约 15 秒后自动查一次,最多 6 小时一次,可在「关于」页关掉;发现新版只在岛上提一句,不自动下载。 - **更新包里没有依赖**:它只含本应用自己的 7 个文件(exe / dll / pri / deps.json / runtimeconfig.json / Assets),.NET 运行时与 Windows App SDK 载荷(170MB 发布目录里占 167MB)由安装包提供,不重复下载。 - **依赖基线**:安装目录里的 `update-baseline.txt` 记着"已装的是哪套依赖"。更新包声明自己要求的基线,两者不一致就拒绝更新并引导走完整安装包 —— 否则换了应用层会因为缺程序集起不来。基线含依赖层文件的指纹,所以将来新增/升级任何 NuGet 依赖都会被这条闸挡住。 - **校验**:HTTPS + 包内 `update.json` 逐文件 sha256 + 对照 release 说明里的 SHA256 表(打包脚本自动写入),任一项不符就拒绝落地。 - **落地方式**:不需要额外的更新器进程 —— 实测运行中的 exe 与已加载的程序集都能改名,所以本进程把旧文件改名成 `.old` 让位、写新文件,然后带 `--after-update` 重启自己(新实例会等旧进程交出单实例闸门)。任何一步失败都会把改过名的还原回去;下次启动会清掉 `.old` 与暂存目录。 - **首次过渡**:3.0.1 及更早的安装没有 `update-baseline.txt`,客户端会退一步只比 .NET 运行时的大版本(对得上就放行)。从 3.0.2 起基线齐全。 ## 非工作时间免打扰 在设置或右键菜单开启「非工作时间免打扰」,默认关闭。 - 夏季默认 `05-01` 开始,工作时间 `08:00-18:00`;冬季默认 `10-01` 开始,工作时间 `08:30-17:30`。日期和时间可修改,按本机日期切换,支持季节跨年。 - 午休可设置为 `12:00-14:00` 等时段,留空关闭。时间段不跨午夜,包含开始、不包含结束;季节起始日期不能相同或使用 `02-29`。 - 休息日、工作时间外和午休期间暂停自动登录、刷新、新消息弹窗与声音。岛体保留最后数量,显示「免打扰」,悬停可查看原因。 -「立即检查」仅本次绕过免打扰,包含会话失效后的必要重试;「全部已读」仍可手动执行。手动暂停及登录锁定保护继续生效。 - 上班、午休结束、系统时间变化或关闭免打扰后,重新判断作息并及时恢复刷新。请求跨过下班/午休边界时不再发出自动通知。 - 已在岛内显示的自动通知会在进入免打扰时撤下,手动请求结果仍可显示。 工作日历与服务端采用同一规则:内置 2025/2026 安排,法定节假日静默,周末调休补班照常。开启免打扰后后台同步今年和明年安排;数据超过 24 小时才更新,失败最多每 6 小时重试,也可在设置中手动同步。 在线数据来自 [NateScarlet/holiday-cn](https://github.com/NateScarlet/holiday-cn),依次尝试 GitHub 与 jsDelivr。失败时使用本地缓存,部分年份失败保留该年份旧数据,未覆盖年份暂按周一至周五判断。 优先级:内置安排 → `holidays_sync.json` 在线缓存 → `holidays.json` 手动覆盖。手动文件修改后自动重新加载,例如: ```json { "2026": { "holidays": ["10-08"], "workdays": ["10-10"] } } ``` ## 代码结构 ```text OaWidget.sln src/ OaWidget.Core/ UI 无关的核心层 OaClient.cs / Poller.cs OA 协议、轮询、重登与登录保护 AppConfig.cs / Dpapi.cs 配置、状态、密码 DndPolicy.cs 作息策略 WorkdayCalendar.cs 节假日与调休日历 MessageFormat.cs 消息行格式化 Update/ 检查更新(Gitee release)、更新包校验与原地替换 OaWidget.WinUI/ WinUI 3 灵动岛(当前桌面实现) Program.cs / App.xaml(.cs) CLI、单实例闸门与 WinUI 启动 Shell/DesktopApplication.cs 轮询事件、内容派发、托盘与右键菜单、设置与退出 Island/ IslandWindow.xaml(.cs) 岛窗口:常驻内容、临时通知、展开队列、形变与原生输入 IslandStyle.cs 配色、圆角、材质与缩放 IslandBackdrop.cs 背景材质 EdgeStripWindow.cs 小色条(全屏避让 / 无待审批收起共用) MessageView.cs 临时通知条 Views/OaContent.cs 胶囊与消息中心内容(未读 / 待办 / 列表 / 操作) Settings/SettingsWindow.cs 账号、作息、外观、关于与更新等设置页 Core/ Win32.cs 原生样式、置顶自愈、任务栏、全屏检测、输入会话 DisplayResolver.cs 显示器几何(工作区/外框/DPI) IslandApi.cs / IslandService.cs 内容接入层与 UI 线程派发 SettingsService.cs island-settings.json 读写 SystemTheme.cs / TransparentBackdrop.cs 主题与透明背景 SingleInstance.cs / TrayIcon.cs / InputSession.cs / HostLogger.cs Diagnostics/Snapshot.cs 离线冒烟截图 tests/ OaWidget.Dnd.Tests/ 免打扰与轮询回归 installer/ Inno Setup 安装配置(自包含发布) ``` 未读数使用网关 `data.totalRows`,展示列表来自 `data.dataList`,列表受分页限制时仍显示真实总数。全部已读调用 `POST /custom-gateway/imChat/markAllAssistantRead`;签名、登录加密、DPAPI 与状态指纹的核心协议未改变。 账号、DPAPI 密码、token、消息去重状态、轮询间隔、消息来源、主题、免打扰和工作日历继续使用原 `config.json`;旧 `ball_x` / `ball_y` / `ball_dock` 键保留以兼容旧版本,灵动岛自身的位置与外观改由 `island-settings.json` 保存。 > `src/OaWidget.Wpf/` 是上一代的悬浮球 WPF 实现,已不参与 `OaWidget.sln` 构建,仅作历史参考保留。 ## 构建、验证和运行 需要 Windows 与 .NET 10 SDK。发布程序自包含 .NET 运行时与 Windows App SDK,目标机器无需另装运行时。 ```powershell dotnet build OaWidget.sln -c Release # 离线回归,不读取用户凭据、不访问 OA 或在线日历 dotnet run --project tests/OaWidget.Dnd.Tests -c Release # 启动正常 GUI:会读取现有配置并按作息轮询 dotnet run --project src/OaWidget.WinUI # 离线窗口冒烟(不加载用户配置、不创建轮询器、不写自启注册),截图写入独立临时目录 dotnet run --project src/OaWidget.WinUI -c Release -- --smoke # 自包含发布,产物目录与安装脚本约定一致 dotnet publish src/OaWidget.WinUI/OaWidget.WinUI.csproj -c Release -r win-x64 ` --self-contained true -o publish/供应链OA提醒小助手 ``` | 参数 | 用途 | |---|---| | 无参数 | 正常 GUI;首次运行弹出账号设置 | | `--selftest-local` | 既有签名与登录报文本地回验 | | `--selftest` | 网络、登录与消息/待办自检,会真实登录 | | `--smoke` | 离线窗口冒烟:紧凑 / 展开 / 通知 / 免打扰撤回 / 设置 / 关于页,自动退出 | | `--after-update` | 应用内更新后由程序自己拉起:等旧进程交出单实例闸门,别被判成多开 | | `--help` | 命令行帮助 | | 环境变量 | 用途 | |---|---| | `OA_WIDGET_HOME` | 配置、状态与日志目录,默认 `%APPDATA%\oa-widget`;`--smoke` 时自动指向临时目录 | | `OA_WIDGET_PORT` | 单实例锁端口,默认 `47832` | | `GITEE_TOKEN` | 仅 `installer/build.ps1 -Publish` 用;私人令牌只从环境变量读,绝不写进仓库或脚本 | 冒烟测试检查岛体紧凑/展开尺寸、固定原生窗口画布、通知展示与免打扰撤回、手动通知保留、收起、设置页、关于页的更新检查、底部落位,以及无待审批收起为小色条与全屏避让色条(顶部/底部两种位置:色条在屏幕内、不压任务栏、鼠标靠近现身、离开收回、色条缩放生效),并把截图写入 `OA_WIDGET_HOME`,本地产物不进入 Git。 ## 发布 ```powershell # 1. 改版本号(csproj / setup.iss / build.ps1 三处) # 2. 提交 # 3. 打包(本地产出两个文件 + 校验值) powershell -File installer\build.ps1 -Version 3.0.7 # 4. 发布到 Gitee(建 release、上传安装包与更新包、把 SHA256 表写进说明) $env:GITEE_TOKEN = "<私人令牌>" powershell -File installer\build.ps1 -Version 3.0.7 -Publish -NotesFile installer\release-notes.md ``` `installer\output\` 每次产出三样: | 产物 | 用途 | |---|---| | `…-<版本>-<架构>-setup.exe` | 完整安装包(含 .NET 运行时与 Windows App SDK),首次安装与跨运行环境升级用 | | `…-<版本>-<架构>-update.zip` | 全量更新包,应用内更新用;只含应用层 7 个文件,包内 `update.json` 带逐文件 sha256 与依赖基线 | | `SHA256SUMS-<版本>-<架构>.txt` | 上面两个的哈希;`-Publish` 时自动写进 release 说明,客户端据此核对 | 发布前建议把更新说明写在 `installer\release-notes.md`(纯文本/markdown 都行,客户端按纯文本显示);不写就只写一句版本号。注意客户端**要求 release 说明里有 SHA256 表**才会做哈希核对(表由 `-Publish` 自动追加,手工建 release 时要自己贴上)。