Pancake

面向教室大屏与触控设备的 Windows 班级作业看板。

Pancake 将时间、日期、天气、教室噪音和各科作业集中在一块适合远距离阅读的深色看板中。它使用 WinUI 3 构建，支持鼠标、触控笔与触摸操作，并为教室大屏提供默认全屏展示。

✨ 功能

• 大屏展示：实时显示时钟、日期、天气、噪音水平与今日作业。
• 看板编辑：新增、重命名、移动、缩放和删除科目磁贴。
• 布局模式：分屏、仅作业、仅时钟和自由布局；分屏可拖动分隔条调整两区大小，拖至两端切换单区。
• 网格布局：磁贴默认吸附到 48 px 网格，设置中可调整网格大小；无限作业板支持滚动、平移和缩放，靠近画布边缘时继续扩展。
• 对齐辅助：关闭网格时，拖动磁贴会吸附作业区域中轴以及其他磁贴的边缘、中心线，并显示辅助线；导出排版也使用同一规则。
• 项目管理：顶栏在查看和编辑模式下均可切换最近项目；项目名后显示科目数量，文件菜单支持新建、重命名、删除、导入、保存和图片导出。
• 作业文件：将布局、配色、富文本、图片和可编辑笔迹打包为 .pch，导入后可以继续修改并保存回原文件。
• 作业内容：在磁贴内直接编辑，支持字体、加粗、斜体、下划线、文字颜色和高光，并可添加图片。
• 图片附件：图片框按原图比例显示；点击图片后显示选中框及下方的裁切、旋转控件，拖动中央移动图片，拖动四角等比缩放。
• 手写标注：编辑页底栏第一个图标开启全局画笔，弹出的画笔栏提供颜色、粗细、橡皮擦及按磁贴或全部清空；缩放磁贴不会缩放已有笔迹。
• 图片导出：支持常用比例和自定义尺寸，可调整背景、色系、标题、磁贴位置和等比缩放，输出不含时钟与编辑工具的 PNG。
• 磁贴主题：每个科目可独立更换主题色。
• 编辑保护：进入编辑前创建快照，底栏倒数第二个按钮放弃修改并先询问确认，最后一个按钮保存本轮修改。
• 噪音检测：通过麦克风实时估算环境音量，支持检测间隔、输入设备、吵闹阈值、提示音音量和目标音量校准。
• 天气信息：按小米天气接口文档读取当前温度和天气状态，内置 2566 个可按名称搜索的地区。
• 本地数据：所有项目持续自动保存到可执行文件旁的 data 目录，加入项目的图片会复制到对应项目资源目录。
• 内置字体：界面与新文字默认使用 HarmonyOS Sans，功能图标使用随程序分发的 Fluent System Icons。
• 自动更新：默认从 GitHub Release 检查更新，也可选择 Gitee；支持 ZIP、7z 与分卷更新包，确认后保存项目、校验解压、退出覆盖并重新启动，保留项目和软件配置，覆盖失败会尝试恢复旧文件。
• 显示设置：支持深色、浅色和跟随系统主题，以及全屏和窗口模式。
• 自适应布局：窄窗口下自动切换为上下排列。

🖥️ 使用方式

程序默认以全屏展示模式启动。查看模式下，浮动工具栏按编辑看板、设置、全屏切换排列；编辑模式仍以画笔开头、放弃和保存结尾。工具栏默认位于底部居中，可在外观设置中调整位置、大小、圆角、边距和按钮名称显示。

查看和编辑模式下，左上角都会显示当前项目与文件菜单。进入编辑模式后可以：

1. 拖动磁贴顶部来移动磁贴；关闭网格后，靠近作业板中轴或其他磁贴对齐位置时会自动吸附并显示蓝色辅助线。
2. 拖动四条边或四个角来调整磁贴大小，或点击底栏自动排列图标整理全部磁贴。
3. 直接修改科目名和作业文字，或添加图片；点击图片后可拖动中央移动、拖动四角等比缩放，并可裁切、旋转、复位和删除。
4. 点击作业文字，在顶栏设置字体、加粗、斜体、下划线、文字颜色和高光；有选区时只修改选区，没有选区时设置后续输入格式。
5. 点击底栏第一个画笔图标后在任意磁贴书写；一笔归属起笔磁贴，越界部分不会落笔，弹出的画笔栏统一切换画笔、橡皮擦、颜色和粗细；当前选中的颜色以白框和右上角勾选标记显示。
6. 从文件菜单创建或切换项目、导入或保存 .pch，也可以进入图片排版页导出 PNG。
7. 使用底栏最后一个按钮完成并保存编辑；倒数第二个按钮会在确认后放弃本轮全部修改。

新建项目时，“重置作业”会保留当前科目、布局和配色并清空全部内容；“重置作业和科目布局”会创建空白项目。项目默认按创建日期命名，同一天继续新建时会自动追加序号。

“保存”首次要求选择 .pch 位置，之后更新同一文件；“导出”直接打开图片排版页。项目切换或导入时，若项目记录的主题、色系与当前软件不同，可以分别选择是否应用。

按 Esc 会先结束当前编辑；未在编辑时按下则退出全屏。

🚀 构建与运行

环境要求

• Windows 10 1809（版本 17763）或更高版本
• x64 设备
• .NET 8 SDK
• Visual Studio 2022（推荐），并安装“使用 .NET 的 Windows 应用 SDK”相关工作负载
• .NET 8 Runtime（直接运行框架依赖产物时需要）；正式便携包自带 .NET 与 Windows App SDK 所需运行资源

命令行

git clone https://github.com/Edge-HH/Pancake.git
cd Pancake
dotnet restore .\src\Pancake\Pancake.csproj
dotnet build .\src\Pancake\Pancake.csproj -c Release -p:Platform=x64
dotnet run --project .\src\Pancake\Pancake.csproj -c Release -p:Platform=x64

也可以使用 Visual Studio 打开 Pancake.slnx，选择 x64 后启动 Pancake 项目。

自动构建与发布

• 推送 v主版本.次版本.修订版本 格式的标签（例如 v1.2.3）时，GitHub Actions 会执行 Release x64 构建、设置和排版逻辑测试、更新覆盖/回滚测试以及静态交互契约检查。
• 工作流名称为“📦 构建与发布”，各步骤均使用前置 emoji 的中文名称。
• 发布包包含 .NET 与必要的 WinUI 运行时，精简未使用的 AI、ML、Widgets、WinForms 依赖，仅保留简体中文、繁体中文和英语语言回退资源。
• 精简之后压缩 ZIP，再解压成品并在临时副本中实际加载主窗口，确认正常退出才创建 GitHub Release；EnableMsixTooling 保证主窗口与控件主题的 PRI/XBF 资源进入发布包。
• 在 Actions 页手动运行该工作流只会生成 ZIP 产物供检查，不会创建 GitHub Release。

正式发布示例：

git tag v1.0.0
git push origin v1.0.0

请等待“📦 构建与发布”工作流成功后再分发 Release 地址。用户完整解压 ZIP 后运行 Pancake.exe 即可，不能只复制单个 EXE；项目数据保存在程序旁的 data 目录。

应用内确认更新后会自动解压并覆盖旧文件，再重新启动。更新不会覆盖 data，文件备份和执行日志保存在 data/updates/<随机标识>/backup 和 update.log，覆盖失败时尝试回滚。请先关闭同一目录中其他 Pancake 实例；如果安装目录不可写，更新会在退出前报告错误。旧版无法启动或尚不支持自动覆盖时，需要首次手动解压新版，保留原 data 目录。

本地验证同样的发布流程：

dotnet publish .\src\Pancake\Pancake.csproj -c Release -r win-x64 --self-contained true -p:Platform=x64 -p:WindowsAppSDKSelfContained=true -o .\artifacts\publish
.\installer\Optimize-Publish.ps1 -PublishDirectory .\artifacts\publish
.\tests\verify-release-startup.ps1 -PublishDirectory .\artifacts\publish

精简脚本仅处理没有用户 data 的独立发布目录，保留运行库、字体和许可证。

启动参数

参数	作用
--windowed	使用普通窗口启动，而不是默认全屏
--view=editor	启动后直接进入看板编辑模式
--view=ink	启动后直接进入可手写的编辑模式
--view=settings	启动后直接打开设置页

例如：

dotnet run --project .\src\Pancake\Pancake.csproj -- --windowed --view=editor

🌤️ 天气配置

在设置页点击“选择地区”，输入地区名称搜索并从结果中选择。实现依据社区维护的 XiaomiWeather.md 及其配套地区数据库；该接口不是小米公开承诺稳定性的正式开放 API，若服务端变更可能需要同步适配。

🔒 隐私说明

• 麦克风数据只用于实时计算音量，不录音，也不保存音频。
• 添加图片时会复制到 data/projects/<项目标识>/assets，不会上传或改写原图片。
• 项目清单、内容和软件设置写入 data/projects.json；旧版 data/pancake.json 首次启动时会迁移，并保留 .before-projects.bak 备份。
• .pch 是带版本清单的 ZIP 容器，只接受受控的附件路径；保存缺少附件的项目会明确报错，不会生成残缺文件。
• 如果把程序放在无写入权限的目录（例如受保护的系统安装目录），自动保存会在设置页报告失败。

📁 项目结构

Pancake/
├─ src/Pancake/
│  ├─ Controls/       # 科目磁贴、拖动、缩放与手写交互
│  ├─ Models/         # 看板、作业、图片与笔迹模型
│  ├─ Services/       # 项目、作业包、导出排版、字体、噪音、天气与更新
│  ├─ Themes/         # WinUI 主题资源
│  ├─ ViewModels/     # 主看板状态与编辑快照
│  └─ MainWindow.*    # 主界面与窗口交互
├─ tests/             # 项目逻辑、隔离 UI 渲染与交互契约验证
├─ design-qa.md       # 设计验收记录
└─ Pancake.slnx

🧪 验证

运行静态交互契约检查：

powershell -NoProfile -ExecutionPolicy Bypass -File .\tests\verify-interaction-contract.ps1

该脚本检查触控交互、网格吸附、全局手写工具栏和全屏退出提示等关键实现是否存在。项目与 .pch 往返测试可运行 dotnet run --project tests/ProjectLogic/ProjectLogic.csproj -c Release，也覆盖紧密网格排版、区域中轴和相邻磁贴吸附。更新测试运行 dotnet run --project tests/UpdateLogic/UpdateLogic.csproj -c Release，在临时目录检查解压、覆盖、数据保留、锁定文件回滚和危险路径拒绝。仓库还包含按条件编译的隔离 WinUI 渲染测试，用于验证内置字体、长富文本、图片、笔迹、多比例 PNG、图标、底栏顺序和实际点击后的色卡选中状态；它不会随正式构建进入应用。

🚧 当前限制

• Release 中优先选择 x64 便携版 ZIP 自动更新，也支持 7z 和上述分卷格式；.exe、.msix 和 .msixbundle 仍按安装包启动。更新包需与便携版一致，将 Pancake.exe 等文件放在压缩包根目录。文件被占用或目录不可写时可能无法更新，可查看保留的备份和日志。
• 小米天气来自第三方整理的非正式接口文档，服务端兼容性不由本项目控制。
• 噪音数值是基于 PCM 电平和校准偏移的估算值，不等同于经过认证的声级计读数。
• 原生触屏手势、触控笔压感和目标教室大屏的视觉比例仍需在实际设备上完成最终验收。

🤝 参与开发

欢迎通过 Issue 报告问题或提出建议。提交代码前，请至少完成 Release 构建和交互契约检查，并说明是否在真实触控设备上验证过相关操作。

📄 许可证

本项目采用 GNU General Public License v3.0 开源许可证。你可以在遵守 GPL-3.0 条款的前提下使用、修改和分发本项目；分发衍生作品时需以 GPL-3.0 提供对应源代码。

设置侧边栏

• 设置采用 WinUI 侧边栏导航，一级分类为布局、外观、组件和关于；外观、组件与关于的具体页面直接显示为可展开的左侧层级子项，不再在内容区使用横向分页按钮。右侧内容可滚动；左右面板使用直角连接，背景透出 Windows Mica 系统材质。不支持 Mica 时由系统回退到 Desktop Acrylic。
• 布局 / 布局模式：选择分屏、仅作业、仅时钟、自由布局。分屏的分隔条可横向或纵向拖动，拖至起点显示仅作业，拖至终点显示仅时钟；在设置中重新选择分屏可恢复两区。分屏和仅时钟模式进入编辑后，时钟只能沿时钟区域中轴线上下移动并等比缩放；天气与噪音保持同一排，作为整体沿中轴线上下移动和缩放。自由布局中每个作业磁贴、时钟、天气和噪音组件仍可独立放置，编辑模式下拖动组件上边缘移动、右下角缩放，位置随软件设置保存，并支持放弃本轮组件位置修改。后续组件使用稳定标识注册并复用同一套布局规则。
• 无限作业板：开启后使用滚动条、鼠标中键拖动或触摸平移，Ctrl + 滚轮与双指手势缩放；画板向右、向下持续扩展，网格仅绘制视口附近的部分。关闭后恢复正常比例和原点，保留磁贴原始坐标。网格大小可在 16–160 px 之间调整。
• 外观 / 磁贴：设置标题大小、背景颜色或图片、图片模式、毛玻璃开关和模糊程度。缩放为保持比例铺满并裁剪，拉伸为填满区域，适应为保持比例完整显示。选择的背景图片复制到 data/backgrounds，清除图片可回到纯色背景。
• 外观 / 背景板：跨区背景仅在分屏模式生效，开启后两区共用一张连续底图，区域底图设置暂时禁用，但时钟区和作业区仍能独立开启毛玻璃与调整模糊。时钟区域背景只在分屏、仅时钟中可设置，作业板区域背景只在分屏、仅作业中可设置。模式切换保留已有背景配置。
• 外观 / 控制窗：默认无字模式；关闭后在靠近边框的一侧显示按钮名称并增加按钮间距。支持左下、下居中、右下、上居中、左上、右上及左右居中竖置，画笔菜单跟随主控制窗位置；大小、圆角、边距可连续调节，角落位置显示两个边距设置。支持毛玻璃与模糊程度，窗口放不下工具栏时可滚动访问按钮。
• 外观：深色、浅色、跟随系统；鲜明和马卡龙色系。内置磁贴主题色（包括旧项目中曾被误标为手动色的内置颜色）以及画笔、高光、磁贴色卡和文字色卡中的彩色色块会跟随色系；文字色卡始终保留纯黑和纯白。已有文字、高光和笔迹颜色保持原值，自定义磁贴颜色也保持原值。色卡使用 Windows 强调色边框和右上角勾选标记当前颜色；混合选区或不在当前色卡内的颜色不会误标为其他颜色。项目与文件操作在查看和编辑模式下均位于顶栏，项目名前显示文件夹图标，最近项目之间留有间隔。
• 组件 / 天气：选择地区、刷新天气和显示极端天气预警。读取接口的完整预警列表，包括强对流、海区大风等类型；看板显示预警标题，悬停和设置页可查看详情。是否有预警取决于该地区接口返回的信息。
• 组件 / 噪音检测：检测间隔为 0.1–2 秒，步长 0.1 秒（这是音量统计间隔，音频采样格式由设备决定）；可选择系统默认或指定输入设备，并刷新设备列表。设备失联会报错，不会自动切换到其他麦克风。
• 吵闹阈值可在 20–120 dB 调整，提示音音量可在 0–100% 调整并直接试听。提示音为三声短促的“嘀嘀嘀”；报警使用独立的约 50 ms 采集通道，不等待音量显示的统计间隔。新一轮噪音立即提醒，持续超阈值时每 2 秒重复一次；播放后的 750 ms 内抑制回授，音量低于阈值 3 dB 后重新待命。实际响应还受输入输出设备延迟影响。
• 校准时先填写当前环境实际音量（20–120 dB），等待有效读数后点击“校准到此音量”；偏移由该目标值减去原始测量值计算，重复校准不会累加偏差。更换输入设备会重置偏移，需要重新校准。
• 关于 / 仓库、版本、更新：提供 GitHub 与 Gitee 仓库图标链接、实际构建版本、检查更新和启动时自动检查开关。更新源默认 GitHub；选择 Gitee 时比较两个源的最新版本，若 Gitee 落后，会在设置与看板提醒切换 GitHub。无法连接 GitHub 时不会把网络错误误报为版本一致，仍可使用 Gitee 更新。
• 分卷更新：支持 .zip.001/.002/...、.7z.001/.002/...，以及 .z01/.z02/.../.zip 标准分卷 ZIP。同一发布中需要包含完整且同名的全部分卷，自动按序下载并校验，再复用便携版更新流程；缺卷、损坏、危险路径或试图覆盖 data 的包会被拒绝，当前应用保持运行。独立 7z 解压工具及许可随包分发，来源与源码地址见 Tools/7zip/README.md。
• 画笔菜单：画笔和橡皮擦改为图标切换，不再显示“当前：科目”；红色垃圾桶可选择清空当前磁贴或全部笔迹。菜单具有边框，笔模式隐藏无法操作的添加、排列与网格按钮，退出后恢复。
• 浅色模式使用白色界面背景及黑色默认前景，已有默认白色文字和笔迹也会适配；切回深色时默认内容恢复白色，彩色内容保持原色。笔迹原始数据不因切换主题改写。
• 上述设置会保存到 data/projects.json；项目内容和软件设置分开建模，旧配置缺少的新字段使用默认值。

运行设置逻辑回归测试：dotnet run --project tests/SettingsLogic/SettingsLogic.csproj -c Release；追加 -- --live 可验证实际天气接口。该测试覆盖预设色系往返、富文本保留和特殊天气预警解析，不替代界面及真实音频设备验收。

新版设置与布局的真实窗口回归测试：

dotnet publish src/Pancake/Pancake.csproj -c Release -p:Platform=x64 -p:EnableUiVerification=true -o artifacts/ui-check
./tests/verify-ui.ps1 -PublishDirectory artifacts/ui-check -EvidenceDirectory artifacts/ui-evidence

测试每次在不含旧数据的临时目录启动，覆盖四种布局、组件持久化、无限画板缩放与复位、跨区背景、独立模糊、画笔图标、八种控制窗位置、超宽工具栏滚动及全部设置层级子页面。正式发布会关闭 EnableUiVerification，不会携带测试入口；目标设备的触屏与压感体验仍需设备验收。