198 lines
13 KiB
Markdown
198 lines
13 KiB
Markdown
# DiffLens 应用开发与版本迭代规范
|
||
|
||
> 适用项目：DiffLens（MetonaTeam / thzxx）
|
||
> 文档维护：随应用版本同步更新
|
||
|
||
---
|
||
|
||
## 1. 版本号总规范
|
||
|
||
版本号遵循 **语义化版本（SemVer）三段式**：`x.y.z`
|
||
|
||
```
|
||
x = 主版本号（Major）
|
||
y = 次版本号（Minor）
|
||
z = 补丁版本号（Patch）
|
||
```
|
||
|
||
**本项目最重要的约束：**
|
||
|
||
> **`x` 永远是 `0`，永远不要提升到 `1.0.0`。**
|
||
> 版本迭代**只允许修改 `y` 和 `z`**，`x` 保持 `0` 不变。
|
||
|
||
当前基线版本：**`0.6.0`**
|
||
|
||
---
|
||
|
||
## 2. x / y / z 各自的含义与规则
|
||
|
||
| 段位 | 值 | 何时提升 | 举例 |
|
||
| --- | --- | --- | --- |
|
||
| `x` 主版本 | **恒为 `0`** | 永不提升 | 不生效 |
|
||
| `y` 次版本 | `0, 1, 2, 3 …` | 新增功能 / 界面较大调整 / 构建方式变更 | `0.1.0 → 0.2.0` |
|
||
| `z` 补丁 | `0, 1, 2, 3 …` | Bug 修复 / 样式微调 / 文档 / 依赖小升级 | `0.1.0 → 0.1.1` |
|
||
|
||
### 何时走 `y`（次版本升级 `0.x.z → 0.(x+1).0`）
|
||
- 新增用户可见的功能特性
|
||
- UI / 交互有较大调整
|
||
- 引入新的差异能力（如导出报告、文件夹对比）
|
||
- 内部引擎算法 / 数据结构的兼容性变更
|
||
|
||
### 何时走 `z`（补丁升级 `0.x.z → 0.x.(z+1)`）
|
||
- 修复 Bug、崩溃、显示异常
|
||
- 细微的样式 / 文案优化
|
||
- 文档补充、依赖补丁级升级
|
||
- 非功能性重构（不改变用户可见行为）
|
||
|
||
### 反例（禁止）
|
||
- ❌ 直接跳到 `1.0.0` 或更高
|
||
- ❌ 只升 `x` 不升 `y/z`
|
||
- ❌ 同时改 `y` 与 `z`（一次发布只应改动一段）
|
||
|
||
---
|
||
|
||
## 3. 版本演进示意
|
||
|
||
```
|
||
0.1.0 ← 初始版本（已发布）
|
||
0.1.1 ← 体验打磨补丁（已发布）：拖拽编码识别 · 行级右键菜单 · 尾部换行显示修正
|
||
0.2.0 ← 导出差异报告（已发布）：HTML / 纯文本 / Markdown 三种格式
|
||
0.2.1 ← 建立测试体系（已发布）：Vitest 单元+组件测试 · 测试策略文档
|
||
0.2.2 ← 体验打磨（已发布）：拖拽处处可用 · 手动粘贴对比 · 导出后一键定位 · 报告/可读性增强 · 仅限文本文件
|
||
0.2.3 ← 安装器优化（已发布）：NSIS 向导式安装，支持手动选择安装目录
|
||
0.2.4 ← 健壮性与体验打磨（已发布）：读取容错与 10MB 大文件防护 · 横向滚动同步 · 下拉点击外部/Esc 关闭 · 二进制误判预警
|
||
0.2.5 ← 一致性与边角修复（已发布）：右键菜单边缘防溢出 · 粘贴入口 10MB 防护 · 拖拽读取失败提示 · 多文件拖拽提示 · 剪贴板统一走主进程 · 主进程异步读取
|
||
0.2.6 ← 主进程异步收尾与边角防护（已发布）：保存报告异步写盘 · 拖拽解码 handler 异步化 · 空白粘贴拦截 · 超多行卡顿预警 · 清理 mac 无效签名配置 · 文档与测试同步
|
||
0.3.0 ← 大文件性能与差异导航增强（已发布）：自研虚拟滚动 · 仅看差异过滤（折叠提示行） · F7/Shift+F7 导航快捷键 · 交换左右侧 · 忽略空行
|
||
0.3.1 ← 稳健性与测试补强（已发布）：超长单行词级 diff 防护 · 打开对话框补“所有文件”筛选 · 虚拟滚动 minWidth 测试覆盖 · 滚动同步去锁化重构
|
||
0.3.2 ← 报告对齐与性能收尾（已发布）：纯文本报告行号右对齐 · 超长行列宽封顶防卡顿 · 对话框与拖拽扩展名清单对齐 · 右键菜单打开时导航快捷键守卫 · 清理导出死属性
|
||
0.4.0 ← 差异计算 worker 化（已发布）：大文件 diff 移入 Worker 后台计算不阻塞界面 · 输入去抖与过期任务丢弃（终止重建实现取消） · 小输入同步快路径 · 无 Worker 环境回退 · 计算中遮罩与导出禁用
|
||
0.4.1 ← worker 创建开销优化与文档对齐（已发布）：worker 延迟至去抖到期才创建（去抖期内取消零创建开销，无 Worker 回退同样走去抖） · 质量门禁文档补 npm test · README 架构树补 hooks · Markdown 报告标题移出引用块 · 安装包排除开发期文件
|
||
0.4.2 ← 导出菜单溢出修复与报告可读性重设计（已发布）：底部工具栏导出菜单改向上弹出（修复超出窗口底边选不到） · HTML 报告全新设计（Hero 概览/人话结论/文件卡片/统计卡/图例/差异分块目录/相同段折叠可展开/打印亮色/窄屏适配，零 JS） · TXT 与 Markdown 报告头部补人话结论
|
||
0.4.3 ← 忽略所有空白比较选项与报告选项说明（已发布）：新增“忽略所有空白”开关（行内空格/制表符/全角空格不参与判等，展示仍为原文，换行结构仍参与对比） · 三种报告头部新增“比较选项”说明行（HTML 为 Hero 区徽标）
|
||
0.5.0 ← 字符级对比模式（已发布）：新增“字符级对比”开关（空白与换行结构全部不参与判等，两侧归一化为字符流 diff，跨行重组也能判等） · 字符差异回映射到行（跨界行配对、单侧行回拉、锚行 zip 配对，输出仍为 DiffRow，视图/报告/导航零改动） · 归一化流超 20 万字符自动降级行级对比并提示（报告头部按实际语义描述） · 字符级开启时三个空白选项置灰（语义已包含）
|
||
0.5.1 ← 字符级同行多块变更重复输出修复（已发布）：字符换位专项测试暴露并修复两处回映射缺陷——同行内多处变更（ne-eq-ne 同行，如换位、同行两处替换）不再重复输出多个 modified · 回拉跨界判定与对齐行判定锚定同一 eq 块，多行换位不再把全 common 行误判为 added · 新增字符换位专项测试组（对齐任意性下的不变量固化）
|
||
0.5.2 ← 稳健性收尾与偏好记忆（已发布）：diff worker 运行崩溃 onerror 兜底（终止实例回退主线程同步计算，effect 取消/jobId 已推进的迟到错误不回填） · 主进程 will-navigate 导航白名单加固（仅放行回到应用首页） · nativeTheme 暗色主题（Windows 标题栏等系统控件跟随应用风格） · 比较选项与仅看差异开关持久化（localStorage 记忆用户偏好，损坏数据防御性回退默认） · 字符级降级报告选项构造与引擎降级分支对齐（补 trimWhitespace 置否）
|
||
0.5.3 ← 稳健性补漏与偏好记忆收尾（已发布）：字符级对比少行大字符量输入改走 worker 后台计算（重输入判定补入字符量维度，行数防不住 diffChars O(ND) 耗时失控） · toast 队列化（最多 3 条堆叠、各自独立计时，二进制预警不再被行数预警顶掉） · 清空按钮二次确认（toast 提示 + 3 秒确认窗口，超时自动复位） · 窗口尺寸/位置记忆（关闭保存 bounds，启动恢复并钳制回工作区，损坏数据回退默认） · 文件对话框记忆上次打开目录 · 状态栏显示两侧行数 · 偏好读取挂载期单次化 · 主进程测试基建建立（windowState 纯逻辑模块 + vitest include 扩展至 src/main）
|
||
0.5.4 ← 比较选项联动可视化与状态透明（已发布）：修复禁用开关零视觉反馈的样式缺陷（原 CSS 仅有 button:disabled，checkbox 禁用后外观不变，用户不知哪些可选） · 字符级开启时三个空白选项灰显勾选（循系统惯例表达“语义已包含且生效”，仅为视觉呈现不改写用户原状态，关闭字符级即复原） · 常显“已包含”徽标（原仅 hover title 可知禁用原因） · 点击被包含选项弹 toast 解释而非无反应 · 字符级因内容超限自动降级时开关旁常显“已降级”标记（状态透明）
|
||
0.5.5 ← 字符级对比无界计算卡死修复（已发布）：diffChars 携 maxEditLength=3000 封顶 Myers 迭代轮数（编辑距离超限立即放弃并降级行级，根治大字符量+大差异输入 O(ND) 无界计算导致遮罩永久卡死——实测 3 万字符全不同无上限需数十分钟） · 字符量降级阈值 20 万收紧至 3 万（双限配合将最坏耗时锁在约 2 秒，worker 内计算界面不冻结） · 重输入 worker 派发阈值随动收紧（原始字符 7500，同步快路径最坏冻结压至 0.5 秒内） · 降级提示文案改“内容或差异过大”覆盖两种降级原因 · DiffOptions 增内部测试参数 charDiffMaxEdit（测试以小阈值毫秒级构造降级场景）
|
||
0.6.0 ← 解码 worker 化 · Playwright E2E · 文件夹对比（当前）：
|
||
- 主进程解码 worker 化：≥256KB 缓冲移入 worker_threads 后台解码（GBK 纯 JS 解码大文件可达数百毫秒，不再阻塞主进程事件循环） · 解码与编码探测抽为纯逻辑模块 decode.ts（Uint8Array 入参，主进程同步路径与 worker 克隆路径共用） · worker 单例管理（崩溃拒绝在途任务并销毁重建，创建/运行失败回退主进程同步解码，行为不降级） · 构建改双入口（index + decodeWorker，iconv-lite 打包进产物） · out/main 整体 asarUnpack（Electron 的 asar 补丁不覆盖 worker 线程，unpacked 路径下无法解析 asar 内 node_modules）
|
||
- Playwright E2E 测试体系建立：对 build 产物启动真实 Electron 验收（复用项目自带 Electron，无需下载浏览器） · 首批 11 用例覆盖 jsdom 无法触达的主进程真实链路（GBK/BOM/大文件 worker 解码、报告写盘、剪贴板、偏好跨实例重启、文件夹真实扫描） · 主进程 dialog stub（showOpenDialog/showSaveDialog 可自动化） · 用例间清空 localStorage 隔离偏好污染 · npm run test:e2e 一键构建+验收，纳入发布 checklist
|
||
- 文件夹对比（MVP）：新增「对比文件夹」入口（依次选择两侧目录） · 递归扫描按相对路径对齐，文件级状态判定（相同/不同/仅左/仅右；大小不同即不同，大小一致做字节级全量比对，超 10MB 采样头部 8KB 近似判定并标注 ≈） · symlink 跳过防环，单侧文件数上限 10000（超限截断提示） · FolderView 虚拟滚动列表（统计徽章/仅看差异默认开/大小列示） · 双击条目进入单文件对比复用全部 diff 能力，一键返回文件夹列表（扫描结果保留） · file:open 与 file:read-by-path 共用同一读取管线（10MB 上限/编码探测/二进制预警一致）
|
||
...
|
||
0.y.z ← 长期停留，永不进入 1.x
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 应用命名约束（三重一致）
|
||
|
||
交付给用户的所有可见名称必须统一为 **DiffLens**：
|
||
|
||
| 环节 | 名称 |
|
||
| --- | --- |
|
||
| 安装包文件名 | `DiffLens-{version}-setup.exe` |
|
||
| 安装后主程序 | `DiffLens.exe` |
|
||
| 开始菜单 / 桌面快捷方式 | `DiffLens` |
|
||
| 窗口标题 | `DiffLens` |
|
||
| 工程内部 name / productName | `DiffLens` |
|
||
|
||
> 注：`appId` 为内部安装标识（如 `com.metonateam.difflens`），不展示给用户，不受此约束。
|
||
|
||
---
|
||
|
||
## 5. 开发流程
|
||
|
||
```
|
||
需求确认 → 方案权衡 → 开发实现 → 本地自测 → 类型检查 → 生产构建 → 代码评审 → 合并 → 发布
|
||
```
|
||
|
||
1. **需求确认**：明确目标，先梳理全貌，避免返工
|
||
2. **方案权衡**：涉及取舍时列出利弊，由负责拍板
|
||
3. **开发实现**：聚焦需求本身，不过度设计
|
||
4. **本地自测**：`npm run dev` 运行验证
|
||
5. **质量门禁**：见第 7 节
|
||
6. **发布**：见第 8 节
|
||
|
||
---
|
||
|
||
## 6. 分支与合并规范
|
||
|
||
- `main`：唯一稳定主干，始终可运行、可发布
|
||
- 功能分支：`feature/<功能名>`
|
||
- 修复分支：`fix/<问题描述>`
|
||
|
||
```
|
||
main
|
||
└─ feature/xxx → （评审后合并回 main）
|
||
```
|
||
|
||
合并且无二次改动时，才允许 rebase 保持历史整洁；否则用普通合并提交。
|
||
|
||
---
|
||
|
||
## 7. 质量门禁（提交/推送前必须通过）
|
||
|
||
每次提交与推送前执行：
|
||
|
||
```bash
|
||
npm run typecheck # 类型检查（node + web 双端）
|
||
npm test # Vitest 单元 + 组件测试（覆盖率 80% 硬门禁）
|
||
npm run build # 生产构建（main/preload/renderer 三端）
|
||
```
|
||
|
||
> 任一命令失败则禁止提交；修复通过后再提交。与《测试策略与方案》第 7 节保持一致。
|
||
|
||
---
|
||
|
||
## 8. 发布流程
|
||
|
||
```bash
|
||
npm run build:win # Windows NSIS 安装包（在 Windows 上）
|
||
```
|
||
|
||
发布前 checklist：
|
||
1. 更新 `package.json` 的 `version` 到新的 `0.y.z`
|
||
2. 更新本文件第 3 节演进记录
|
||
3. 通过质量门禁（typecheck + test + build）
|
||
4. 通过 E2E 验收（`npm run test:e2e`，对 build 产物跑真实 Electron 主链路，0.6.0 起纳入发布必跑）
|
||
5. 打标签并推送到远程 `git.metona.cn/MetonaTeam/DiffLens`
|
||
6. 如需发布安装包，生成对应平台产物与 Release 说明
|
||
|
||
---
|
||
|
||
## 9. 元信息维护表
|
||
|
||
| 文件 | 维护内容 |
|
||
| --- | --- |
|
||
| `package.json` | `version`（唯一版本来源）、`name`、`productName` 保持 DiffLens |
|
||
| `electron-builder.yml` | `productName` / `executableName` / `artifactName` 保持 DiffLens |
|
||
| `README.md` | 特性描述与发布版本号随版本同步 |
|
||
| 本文件 | 第 3 节演进记录同步补写 |
|
||
|
||
> 版本号**只以 `package.json` 的 `version` 为唯一来源**，其余打包产物名由它派生。
|
||
|
||
---
|
||
|
||
## 附：提交信息格式
|
||
|
||
采用约定式提交：
|
||
|
||
```
|
||
<type>: <描述>
|
||
|
||
feat: 新增功能 （配 y 版本）
|
||
fix: 修复问题 （配 z 版本）
|
||
docs: 文档变更
|
||
build: 构建/依赖
|
||
refactor: 重构（不改行为，配 z 版本）
|
||
```
|
||
|
||
例如：
|
||
- `feat: 新增导出差异报告` → `0.2.0`
|
||
- `fix: 修复 GBK 文件乱码` → `0.1.1`
|
||
|
||
---
|
||
|
||
© 2026 MetonaTeam · thzxx · DiffLens |