# elated-win

**Repository Path**: solarwinds/elated-win

## Basic Information

- **Project Name**: elated-win
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-04
- **Last Updated**: 2026-10-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 心花桌面版

从 `D:\code\AndroidStudioProjects\Elated` 的 Android/Kotlin 原版迁移到 Tauri 2 + React + TypeScript。源 Android 项目保留。

## 开发

需要 Windows C++ Build Tools、WebView2、Rust MSVC 工具链和 Bun。

```powershell
cd D:\code\elated-win
bun install
bun run tauri dev
```

终端未识别新安装的 Bun/Rust 时，重启终端或 IDE。

## 验证与打包

```powershell
bun run lint
bun run typecheck
bun test
cargo test --manifest-path src-tauri/Cargo.toml
bun run tauri build
```

Windows 安装包位于 `src-tauri/target/release/bundle/nsis/`。

## 已迁移功能

- 火花：新增、编辑、删除，20 个 Unicode 码点感受限制，固定记录时间，默认文字。
- 心赏：对方称呼、内容、默认文字。
- 家庭情景剧：日期、六个时段、地点、人物、互动事件及全部反思字段，感受快捷选择和情绪多选。
- 时间线：倒序按天分组，最近三天默认展开，每次加载十天，搜索记录。
- 设置：昵称、头像、签名、五种分隔符和五种主题。
- 分享：火花/心赏按天预览，情景剧单篇预览，复制文字和保存完整高度 PNG。
- ZIP 备份：两端导入、导出 `xin-hua-backup` 版本 5，保留 UUID 和最近修改时间。按当前要求，不处理历史版本备份。已有数据库仍会自动升级。

## 从 Android 转移数据

1. 在 Android 心花中打开「设置 → 数据备份与恢复 → 备份」。
2. 将得到的 ZIP 文件复制到电脑。
3. 桌面心花打开「设置 → 恢复备份」，选择 ZIP，确认记录数量后恢复。

恢复会替换桌面全部记录、头像和设置，建议先导出桌面备份。不会直接读取手机沙盒里的 SQLite 文件。

## 存储与平台差异

桌面数据通过 Rust 写入 Tauri 应用数据目录下的 `heart_sparks.db`（Windows 通常为 `%APPDATA%\com.qizhibai.elated-win\`）。SQLite 的单行快照包含记录、设置与头像，事务保证恢复和保存整体提交。不是 Android SQLite 表的直接复制；跨平台交换使用 ZIP。浏览器 `bun run dev` 仅预览布局，个人数据操作需要 Tauri 窗口。

Android 系统分享改为桌面保存文件。头像居中裁剪并转为最长 512 像素的 PNG。备份保留 `shareMode` 以兼容原版，桌面预览明确提供文字和图片两个按钮。

原版可拖动/滑动的移动交互改为键鼠按钮；暂未移植 Android 安装、系统分享面板或系统返回键行为。桌面 UI 根据原版主题及 `design/heart-records-prototype.html` 调整，宽窗口使用侧边分类栏，窄窗口使用顶部分类。

## Windows 系统外观

界面跟随系统浅色／深色偏好，并监听运行期间的变化。Windows 高对比度模式采用系统颜色与实体焦点边框。心花的五种主题继续作为强调色；分享图片保留浅色纸张背景。

标题栏与应用背景融合，提供拖动、双击最大化／还原、最小化、最大化和关闭按钮。自绘最大化按钮不提供 Windows 原生按钮的悬停 Snap Layout 菜单，可使用系统窗口快捷键或拖动贴靠。

Windows 11 Build 22621 及以上在非高对比度模式尝试原生 Mica；调用失败、旧版本 Windows 或高对比度模式回退不透明背景。材质使用现有 `window-vibrancy` / `windows-version` 依赖，不增加新的 UI 框架。Windows 的透明效果设置和桌面壁纸会影响 Mica 的可见程度。

情绪选择使用两个标签页，支持左右方向键和 Home／End；跨页切换保留选择，确认后统一写入情绪字段。

开发验证：`bun run lint`、`bun run typecheck`、`bun run test`、`cargo test --manifest-path src-tauri/Cargo.toml --lib`。`.qa/system-ui.cjs` 使用当前电脑已有的 Playwright 运行时模拟原生 IPC，验证明暗切换、高对比度、内容区滚动、情绪跨页选择和最小窗口宽度；此测试不替代 Windows 10／旧版 Windows 11 的实机测试。

## 局域网同步（1.1.0）

电脑点击侧栏「与手机同步 → 开启等待接入」；手机打开「设置 → 与电脑同步」。两端接入同一无线网络，手机发现电脑后点击接入。也可以输入电脑显示的 IPv4 地址与动态端口。电脑确认双方六位配对码相同后允许接入。

默认增量双向同步。单向增量以源端为准，覆盖相同 UUID 并补齐缺失记录，保留目标端独有记录。双向增量取两端记录并集，同 UUID 取 updatedAt 较晚者；时间相同而内容不同会逐条提示选择，选择绑定到所展示的记录版本。删除不传播。

覆盖模式只支持单向，需要勾选清除目标端三类记录的明确警告。同步仅交换火花、心赏、家庭情景剧，昵称、头像和设置各自保留。源端修改时间直接保存，不改成传输时间。两端时钟明显偏差时提示校准，并禁止双向同步直到重新连接。

连接只在用户开启等待时监听；同一时刻仅连接一台手机，手机断开后继续在原端口等待接入并保留 mDNS 广播；每次新连接都重新核对配对码和确认接入。只有电脑关闭同步或退出程序时停止监听。TLS 1.2／1.3 加密，配对码绑定会话证书 SHA-256 指纹和手机随机 nonce。接入确认前禁止交换记录，不修改系统证书信任或全局 TLS 设置。mDNS 使用 _xinhua._tcp.local.，携带协议版本 1 和记录版本 5。协议为 4 字节大端长度加 UTF-8 JSON；单消息最多 64 MiB，初次接入消息最多 8 KiB。每秒内心跳，失联读超时 15 秒；接入审批 120 秒过期。

同步先获取快照并准备目标数据，再校验快照没有变化后事务保存。桌面 SQLite 比较并更新完整快照，手机 SQLite 事务比较原记录后替换。保存前自动保留恢复 JSON：桌面应用数据目录 sync-recovery/，手机应用私有 files/sync-backup-*.json。准备及提交阶段写恢复日志。若一端已保存而另一端确认中断，不宣称同步成功；提示重新连接并再次增量同步。恢复 JSON 属于维护用副本，普通备份与恢复仍使用 ZIP。

三类记录的 id 已改为 UUID 字符串，不增加 syncId。新建使用 UUID v4；现有整数编号数据库按记录类型、createdAt、全部业务字段及相同记录的出现序号确定性迁移为 UUID v3。字段按 UTF-8 字节长度加冒号编码，使用全零 UUID 命名空间；不把旧整数编号纳入 UUID，只用其排序保留完全重复记录的份数。旧记录 updatedAt=createdAt，新建相同，编辑保存时更新时间。升级前两端内容已经不同的旧记录会迁移成不同 UUID。

Android 未增加第三方依赖，使用 NsdManager、SSLSocket、SQLite 和现有协程。target SDK 37，在 Android 17 请求 ACCESS_LOCAL_NETWORK；更早系统使用 INTERNET。桌面增加 UUID JS 库，以及 Rust rustls/rcgen/sha2/uuid/mdns-sd/if-addrs，分别用于加密、证书、配对摘要、标识与局域网发现。

验证：前端 lint、类型检查、9 个模型测试；原生同步规则与快照并发保护测试；Android 单元测试、lint、模拟器数据库迁移与 ZIP 往返测试。只读 Android 11 模拟器与 Windows 实际 TLS 联调覆盖全部五种模式／方向组合，双端校验三类记录、原修改时间和设置保留；Windows 真实 mDNS 广播／解析通过。界面测试覆盖默认增量双向、配对审批、覆盖勾选和双向禁用、成功提示与断开。真机同一 Wi-Fi 自动发现和 Android 17 权限提示尚未实机验证。

复跑网络测试：先编译 Rust 测试与 Android 独立测试包（-PxinhuaIsolatedTest），在端口 5580 的只读模拟器安装独立 APK，再执行 .qa/run-lan-e2e.ps1。测试数据库使用独立临时目录，Android 测试包名 com.example.elated.synctest，不读取或修改实际用户数据。

1.1.1：手机断开、接入被拒绝或超时后，桌面保留监听与 mDNS 广播；再次连接重新审批，并清除旧覆盖确认和冲突选择。电脑主动关闭同步才停止监听。真实 TLS 测试验证同一端口连续接入、拒绝后的再次接入、旧任务清理与主动停止监听。


## 许可与隐私

设置页面的“许可协议”为法律文本主入口，可切换到隐私协议及第三方组件声明。
本软件原创部分采用 `legal/LICENSE.txt` 中的非商业免费使用许可，商业用途需另行书面授权；第三方组件保留其原许可，不受本软件原创部分的非商业限制。
隐私协议生效日期与 Android 心花 App 一致，为 2026 年 10 月 5 日。

`bun run legal:generate` 从 Cargo 实际 Windows 依赖图和已安装的前端运行依赖生成第三方声明，保留许可原文；发布构建会自动执行此步骤。首次构建前需要已下载 Cargo 依赖。缺少许可文本会阻止生成，需从相应上游版本补齐到 `legal/upstream-licenses`。
`legal/sources` 包含本次构建对应的 MPL 2.0 组件原始源码归档和 SHA-256 清单。应用内声明按需加载，法律文本和所需源码同时随安装包放入安装目录的 `legal` 文件夹。

应用 identifier 和前端 package.json 包名为 `com.qizhibai.elated-win`。Rust crate 和可执行文件仍使用 Rust 合法名称 `elated-win`。首次启动新标识版本，若新目录无数据库，则将 `%APPDATA%\com.example.elated-win` 旧目录直接改名为新目录，保留全部文件，不覆盖新目录已有数据库。新目录已存在但没有数据库时，先将其改名为带 `.before-migration-UUID` 后缀的同级目录；旧目录改名失败时恢复原新目录并报告错误。