hs-cfzd-sync

Hola 待打包项目文件同步工具。在 Hola 开发目录下执行，通过读取 git 未提交状态，自动识别修改文件并按规则同步到 nw-h5-base 和 nw-components 两个源码库。

背景与痛点

Hola 项目涉及三个 Git 仓库：

| 仓库 | 说明 | |---|---| | nw-h5-base | 项目底座，fundhola/html5/ 是 Hola 框架核心代码 | | nw-components | 组件库 + 客户个性化文件库 | | 待打包项目 | 开发调试用的完整项目，文件来自上面两个库的合并 |

开发完成后，需要将修改的文件手动拆分回 nw-h5-base 和 nw-components，流程繁琐且容易遗漏。本工具自动完成这一拆分过程。

安装

cd /path/to/hs-cfzd-src-async
npm install
npm link        # 全局注册 hs-cfzd-sync 命令

配置

工具自身目录下的 sync.config.json 存储两个库的本地路径：

{
  "nwH5Base": "/path/to/nw-h5-base",
  "nwComponents": "/path/to/nw-components"
}

路径支持绝对路径或相对路径（相对于 sync.config.json 所在目录）。

首次使用可将 sync.config.example.json 复制为 sync.config.json 后填写。

使用方法

查看 / 更新配置

# 查看当前配置
hs-cfzd-sync config

# 更新 nw-h5-base 路径
hs-cfzd-sync config --h5base /path/to/nw-h5-base

# 更新 nw-components 路径
hs-cfzd-sync config --components /path/to/nw-components

# 同时更新两个路径
hs-cfzd-sync config --h5base /path/to/nw-h5-base --components /path/to/nw-components

执行文件同步

在 Hola 待打包项目根目录下执行：

# 正式同步（会实际写入文件）
hs-cfzd-sync --ext ext-honglijj

# 预览模式（只打印，不写文件）
hs-cfzd-sync --ext ext-honglijj --dry-run

--ext 参数为客户个性化文件夹名称，对应 nw-components/components/ 下的目录，例如 ext-honglijj。

文件映射规则

工具对每个 git 修改文件按以下优先级顺序匹配规则：

git 修改文件
    │
    ├─ 是 src/components/market/*.vue ──→ 规则一：同步到 nw-components 组件目录
    │
    ├─ 否，检查客户个性化目录是否有对应文件
    │       ├─ 有 ──→ 规则二：覆盖到客户个性化目录
    │       └─ 无 ──→ 规则三：同步到 nw-h5-base 底座目录

规则一：组件文件

适用范围：src/components/market/ 下的 .vue 文件

| 源路径 | 目标路径 | |---|---| | src/components/market/m-banner-nw240301.vue | nw-components/components/m-banner-nw240301/m-banner-nw240301.vue | | src/components/market/m-gdlc-fundlist-nw242103.vue | nw-components/components/m-gdlc-fundlist-nw242103/m-gdlc-fundlist-nw242103.vue |

目标文件夹以 .vue 文件名（去掉扩展名）命名，与 nw-components 库保持一致。

规则二：客户个性化文件

适用范围：src/components/market/ 以外的其他文件，且在 nw-components/components/<ext>/h5/html5/ 下已存在对应路径。

| 源路径 | 目标路径（以 ext-honglijj 为例） | |---|---| | src/views/login.vue | nw-components/components/ext-honglijj/h5/html5/src/views/login.vue | | src/utils/request.js | nw-components/components/ext-honglijj/h5/html5/src/utils/request.js |

判断依据：目标文件在客户个性化目录中已存在，工具直接覆盖。

规则三：底座文件

适用范围：不满足规则一和规则二的其他所有修改文件。

| 源路径 | 目标路径 | |---|---| | src/views/home.vue | nw-h5-base/fundhola/html5/src/views/home.vue | | src/assets/logo.png | nw-h5-base/fundhola/html5/src/assets/logo.png |

相对路径结构完整保留，复制到 nw-h5-base/fundhola/html5/ 下。

项目结构

hs-cfzd-src-async/
├── src/
│   ├── index.js          CLI 入口，主流程编排
│   ├── configLoader.js   配置读取与写入（sync.config.json）
│   ├── gitHelper.js      执行 git status，解析修改文件列表
│   └── fileMapper.js     三条路径映射规则实现
├── sync.config.json      实际使用的配置文件（本地路径，不提交）
├── sync.config.example.json  配置模板
└── package.json

模块说明

configLoader.js

• loadConfig() — 读取 sync.config.json，解析路径为绝对路径返回
• updateConfig(updates) — 合并更新指定字段后写回文件

gitHelper.js

• getChangedFiles(projectDir) — 在指定目录执行 git status --porcelain，返回状态为新增（A）、修改（M）、重命名（R）的文件路径列表，忽略删除（D）和未跟踪（??）

fileMapper.js

• mapFile(relPath, options) — 对单个文件路径执行三条规则匹配，返回 { type, destPath }

index.js

• config 子命令 — 调用 configLoader 查看或更新配置
• 默认同步流程 — 串联 configLoader → gitHelper → fileMapper → fs-extra.copy

注意事项

• sync.config.json 包含本地绝对路径，不应提交到 git，建议将其加入 .gitignore
• 工具只处理 git 已跟踪文件中状态为新增或修改的文件，未跟踪的新文件（??）不会被同步
• 规则二的客户个性化匹配以目标文件是否存在为准，文件不存在时自动降级为规则三（底座文件）
• --dry-run 模式可在正式同步前预览所有操作，建议首次使用时先运行预览