============================================
 启动器 (dde-launchpad) 定制包
============================================

内容说明
--------
本项目为"配置驱动 + 现场生成"模式：补丁库由 patch.py / patch_p2.py 按 config.json
从系统库现场生成，GUI 负责调参、生成、部署、重启一体化。

部署（二选一）
-------------
1. GUI 推荐：gui/launcher-customize-gui → 调参 → 「应用并部署」
   （自动：写 config.json → patch.py(P1) → patch_p2.py(P2) → 部署到
    ~/.local/lib + 用户级QML + override + 重启 dde-shell）
2. 命令行：python3 patch.py && python3 patch_p2.py -c config.json --src build/launchpadcommon.so
   然后手动部署（参考 gui/main.cpp doApply 逻辑）

卸载/回退
---------
   ./uninstall.sh            # 完全移除部署
   ./uninstall.sh --all      # 额外清理 build/build_p2 生成物 + 恢复 config.json
   （或 GUI「完全移除」按钮）

关键文件
--------
- config.json         参数全集（GUI 写入）
- config.orig.json    系统原始值（卸载 --all 时恢复用）
- patch.py            P1 补丁生成器（位置/窗口/字体/缩放/间距）
- patch_p2.py         P2 资源源码补丁生成器（图标尺寸/列数/分区宽度）
- launcheritem.qml.template  dock 启动器面板 QML 模板
- metadata.json       dock 启动器面板元数据（patch.py 产物用）
- translations/       启动器面板翻译（GUI 部署时复制，防回退英文）
- gui/                P3 图形工具（含应用闭环）
- uninstall.sh        卸载脚本

更新日志
--------
- 2026-09-10: 移除 install.sh 与 files/ 预打包产物（由 GUI + patch 脚本现场生成替代）；
  translations 与 metadata.json 迁移至项目根。
- 2026-09-08: 新增 translations/（启动器面板官方翻译）。

============================================
 P1 补丁生成器 (patch.py)  —— 2026-09-10 新增
============================================

用途：把"手工二进制补丁"升级为"配置驱动 + 特征定位"的自动生成器。
     【只生成产物到 build/，不写入系统】

用法：
   python3 patch.py                        # 用 config.json，输出 build/
   python3 patch.py -c 配置.json -o 输出目录 --src 系统库路径
   python3 patch.py --verify-only          # 只校验锚点能否定位

配置项 (config.json)：
   position        auto=随dock模式 | center=强制居中 | follow=强制跟随图标
   dockMargin      居中模式下距任务栏间距(px, 0~200)
   window.width    窗口模式宽度(px, 200~4000)
   window.height   窗口模式高度(px, 200~4000)
   font.level      DTK 字号级别 t1~t9 (数字越小字号越大; t9≈11px, t6≈14px)
   icon.scaleFactor 全屏图标缩放(0.2~5.0, 走官方 DConfig, 安装阶段应用)
   sections.frequentlyUsed.cellPaddingColumns  我的常用区列向间距(10~99)
   sections.frequentlyUsed.cellPaddingRows     我的常用区行向间距(1~9, 等长限制)

安全机制：
   1) 每个锚点按"特征串 + 上下文"定位，必须唯一命中，否则中止
   2) 替换保持与原字节等长，绝不增删字节
   3) 生成后校验 ELF 完整性、BuildID 不变
   4) 系统 dde-launchpad 升级后重新运行即可（自动从新库定位）

回归测试（已验证）：
   - 默认配置产物 md5 == files/launchpadcommon.so（精确复现原补丁）
   - 原始值配置产物 md5 == 系统库（幂等）
   - 自定义值差异字节精确落在 6 个锚点偏移
   - QML 模板三种位置模式渲染正确

产物结构 (build/)：
   launchpadcommon.so   补丁后的库
   launcheritem.qml    参数化渲染的 dock 启动器面板
   metadata.json

============================================
 P2 资源源码补丁生成器 (patch_p2.py) —— 2026-09-10 新增
============================================

原理：启动器 QML 界面实际以 rcc 资源（zstd 压缩的 .qml 源码）加载并重新编译，
     qmlData AOT 数据不被运行时使用（侦察证实）。patch_p2.py 修改资源中的源码，
     实现窗口模式图标尺寸/列数/分区宽度调节。

用法：
   python3 patch_p2.py                        # 用 config.json，输出 build_p2/
   python3 patch_p2.py -c 配置.json -o 输出目录 --src 系统库路径
   python3 patch_p2.py --verify-only          # 只校验资源锚点可定位

P2 参数（config.json sections.*）：
   sections.gridView.iconSize     窗口模式图标宽(px, cellWidth, 默认80)
   sections.gridView.iconHeight   窗口模式图标高(px, cellHeight, 默认82)
   sections.gridView.columns      窗口模式网格列数(默认4, 需≤rightPaneWidth能放下)
   sections.windowedFrame.appListWidth   所有应用区宽(默认220)
   sections.windowedFrame.rightPaneWidth 右侧区宽(默认365)

技术要点：
   1) 特征定位（扫描 zstd 帧解压匹配源码特征），系统升级无需人工改偏移
   2) zstd level19 重压缩，流大小变化自动数据搬迁 + 更新节点 data_off（大端）
   3) 幂等：默认配置产物 md5 == 系统原库
   4) 输出到 build_p2/，不写入系统；部署: cp build_p2/launchpadcommon.so ~/.local/lib/

============================================
 P3 GUI 原型 —— 2026-09-10
============================================
gui/main.cpp：C++ Qt6 Widgets 简单原型（网格溢出联动校验 + 模拟预览）
编译/运行/校验逻辑详见 gui/README.md
核心：requiredWidth = columns×(iconSize+cellPadding)，> rightPaneWidth 即溢出，
      自动给出"减小列数/加宽右侧区/缩小图标"联动建议（已单测 8 用例 + 三状态截图验证）
