功能手册
Codifier 是平台 Seed-Data 数据的版本控制与部署工具。通过 Git 管理 Flow、Form、Page、连接器、SDK 等配置数据，实现开发环境到测试环境的可控交付。
背景
Ceat 平台的配置代码（Flow、Form、Page、连接器、SDK 等）以单一大 JSON 文件（seed-data.json）的形式存在。这带来几个核心痛点：
| 痛点 | 说明 |
|---|---|
| 无法版本控制 | 单个巨型 JSON 文件无法有效使用 Git 进行 diff、review 和合并，任何变更都是全量覆盖 |
| 无法选择性部署 | 开发环境的改动需要全量导入测试/生产环境，无法只交付某个 Flow 或某个 Form 的变更 |
| 变更不可追溯 | 谁改了什么、什么时候改的，没有历史记录，出问题后无法回溯 |
| 多环境管理困难 | 开发、测试、生产环境之间的配置差异没有管理手段，容易误覆盖 |
| JSON 可读性差 | 配置中大量嵌套 JSON 字符串（字符串值本身又是 JSON），人工难以阅读和审查 |
Ceta Codifier 的解决方式：
- 拆分（Split）：将单一大 JSON 拆解为目录结构，每个 Flow / Form / Page / 连接器各自独立文件，嵌套 JSON 字符串自动展开为结构化对象，脚本代码提取为独立
.groovy/.sql/.js文件 - 版本控制：拆分后的目录结构可通过 Git 进行精确的 diff、blame、merge，方便 git 追踪历史改动
- 选择性打包（Patch）：按需选择要部署的内容（某个 PBC 的某些 Flow），生成最小化 ZIP 包导入目标环境
- 合并（Merge）：将目录结构还原为平台可导入的标准 seed-data.json 格式
系统特性
| 特性 | 说明 |
|---|---|
| 多 Git Provider | 支持 GitLab 和 GitHub |
| 多项目支持 | 同时支持多个项目 |
| 多分支支持 | 每个项目可以同时管理多个分支，可分别管理 开发，测试，生产等不同环境 |
| 国际化 | 中文 / 英文界面切换 |
工作流程
- 开发人员在平台正常开发，开发完成提交相关代码改动
- 开发完成后，通过 Codifier 打包的相关内容（或全量打包）
- 下载 ZIP 导入目标环境
仓库策略建议
根据环境间的差异程度选择合适的 Git 管理策略：
| 场景 | 策略 | 说明 |
|---|---|---|
| 差异比较大的环境 | 独立仓库 | 如开发环境与生产环境差异较大（不同客户、不同功能集），建议为每个环境使用独立的 Git 仓库，避免分支间冲突过多 |
| 差异比较小的环境 | 同仓库不同分支 | 如开发环境与测试环境差异较小（仅版本先后差异），建议使用同一仓库的不同分支，通过 Patch 打包实现增量交付 |
功能模块
一、项目与仓库管理
| 功能 | 说明 |
|---|---|
| 项目配置 | 配置 Git 仓库地址、仓库类型（GitLab / GitHub）和 Access Token |
| 本地仓库缓存 | 每个项目在 data/{project}/repo/ 维护持久化仓库，fetch + checkout 切换分支，避免重复 clone |
| 清除缓存 | 删除项目本地数据目录，下次操作时自动重新拉取 |
| 分支浏览 | 列出远程分支及最后提交时间 |
| 多仓库类型支持 | 同时支持 GitLab 和 GitHub，按项目独立配置 provider |
GitLab 配置
在 GitLab 仓库 Settings → Access Tokens 中创建 Project Access Token：
- Role: Developer
- Scopes:
api,read_api,write_repository
| 字段 | 示例值 |
|---|---|
| 仓库 URL | https://gitlab.dev.bizops.com.cn/project-seed-data/dxsrm-seed-data.git |
| Token | glpat-e-uzHm7mPJ3kEf5eaMKZ |
⚠️ Token 创建后只显示一次，请妥善保存。
GitHub 配置
在 GitHub 中进入 Settings → Developer settings → Personal access tokens → Fine-grained tokens，创建新 Token：
- Repository access: 选择
Only select repositories，指定目标仓库 - Permissions:
- Contents:
Read and write（读写仓库内容） - Metadata:
Read-only（必选）
- Contents:
| 字段 | 示例值 |
|---|---|
| 仓库 URL | https://github.com/your-org/dxsrm-seed-data.git |
| Token | github_pat_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx |
⚠️ Token 创建后只显示一次，请妥善保存。
⚠️ Fine-grained token 有过期时间限制（最长 1 年），请注意续期。
建议创建 Private 仓库，避免 seed-data 泄露。
二、Secret 管理
为项目生成 API Access Secret，用于平台提交 commitTriggerUrl 鉴权。
| 功能 | 说明 |
|---|---|
| 生成 | 为项目生成新的 Secret，支持设置有效期和备注 |
| 有效期选项 | 30 天 / 90 天 / 180 天 / 1 年 / 2 年 / 永久 |
| 吊销 | 立即使 Secret 失效，不可恢复 |
| 删除 | 从列表中移除 |
| 安全 | Secret 生成后仅展示一次，列表中脱敏显示 |
| 使用方式 | 请求头添加 X-Project-Secret 和 X-Project |
三、用户与权限
| 功能 | 说明 |
|---|---|
| 角色 | admin（管理员）/ user（普通用户） |
| 项目级权限 | 每个用户对每个项目可分配：download / upload / secret 权限 |
| 用户管理 | 创建、修改角色、修改权限、修改密码、删除（仅 admin） |
| 修改密码 | 普通用户改密需验证旧密码，admin 可直接重置 |
四、上传拆分
将 seed-data ZIP 上传并拆分为 Git 目录结构，推送到新分支。
| 功能 | 说明 |
|---|---|
| 分支重复检查 | 目标分支已存在时直接报错 |
| 自动拆分 | JSON → 目录结构（pbc/connector/sdkDefinition/frontend/i18n） |
| 推送 | 拆分后自动 commit 并 push 到指定分支 |
操作步骤
- 在 Codifier 首页切换到 上传 标签页
- 选择 Git 仓库
- 输入新分支名称（如
main或dev1） - 选择导出的 seed-data ZIP 文件
- 点击「上传并处理」
系统会自动拆分 ZIP 并推送到指定分支。
五、Patch 打包（核心功能）
从 Git 仓库选择性打包内容，生成可导入的 ZIP。
全量下载
进入 Codifier 首页 → 选择仓库 → 刷新分支 → 点击「全量下载」，下载包含所有内容的完整 seed-data 包。
Patch 模式（推荐）
可选内容
| 类型 | 图标 | 说明 |
|---|---|---|
| 前端配置 | 🎨 | frontEndConfig（菜单、路由、主题等） |
| 多语言 | 🌐 | i18n 语言文件，按语言单独选择 |
| 连接器 | 🔌 | 支持展开到 Action 级别单独选择 |
| SDK 定义 | 🧩 | SDK groovy/json 定义文件 |
| PBC | 📦 | 每个 PBC 下可单独选择 Flow ⚡ / Form 📝 / Page 🖥️ |
三种过滤方式
| 方式 | 说明 |
|---|---|
| 关键词 | 实时文本匹配，所有类型均参与过滤 |
| 类型 | 下拉选择只看某一类（Flows / Forms / Pages / 连接器 / SDK） |
| Git 过滤 | 输入基准分支/标签/commit/日期（YYYY-MM-DD），通过 diff 自动找出变更并勾选 |
输出内容
| 文件 | 说明 |
|---|---|
project-seed-data.json | 合并后的 Seed-Data 数据（仅含选中内容） |
patch.yaml | 选择清单，记录本次打包的范围 |
i18n/*.json | 选中的语言文件 |
打包规则
- 增量包 仅包含选中的 flow/form/change
- 增量包 包含 所选 Form/Flow/Page 的 pbc 的元数据
- 增量包 包含项目的 元数据
- 全量包 包含所有内容
六、Codifier Commit（批量提交）
从 Ceta 平台拉取 seed-data 并提交到 Git 仓库。支持预览差异、选择性批量提交。
工作流
- 配置 Ceta Commit 配置（Ceta 地址、Token、目标分支）
- 触发同步：从 Ceta 下载数据 → 拆分 → 与 Git 分支计算 diff
- 预览差异：查看新增/修改/删除的文件列表
- 选择性提交：勾选要提交的文件，输入 commit message，提交到 Git
功能特性
| 功能 | 说明 |
|---|---|
| 选择性提交 | 支持全选/取消全选/按文件勾选 |
| Diff 查看 | 左右双栏布局，左侧文件树，右侧文件 diff |
| 文件过滤 | 支持关键词过滤 diff 文件列表 |
| 自动作者信息 | 使用当前登录用户作为 commit author |
Ceta Commit 配置
每个 Codifier 项目可配置多个 Ceta Commit 配置，每个配置对应一个目标分支：
| 字段 | 说明 | 示例值 |
|---|---|---|
| 目标分支 | 同步数据提交到的 Git 分支 | main |
| Ceta 地址 | Ceta 平台的访问 URL | https://your-platform.example.com |
| Ceta Project ID | Ceta 平台中项目的数字 ID | 123 |
| Ceta Token | 认证 Token（支持 OAuth 授权自动获取） | eyJhbGciOiJIUzI1NiIs... |
| 默认提交信息 | 定时提交时的默认 commit message | — |
| Cron 表达式 | 定时同步表达式（可选） | 0 0 3 * * ? |
| 启用定时同步 | 开关 | — |
配置步骤：
- 进入 Codifier 项目管理 页面
- 选择目标项目，点击编辑
- 找到 Ceta Commit Configs 配置区域
- 填写 Platform 连接信息（URL、Token、Project ID）
- 保存配置
适用场景：批量同步 Platform 上的变更到 Git 仓库，或在 Platform 未配置 commitTriggerUrl 时手动提交。
OAuth Token 授权
点击"获取 Token"会跳转到 Ceta 平台授权页面，授权完成后自动回调保存 Token。通过 state 参数防止 CSRF 攻击。
七、定时提交
支持 Cron 定时自动执行 Ceta → Git 同步任务。
| 功能 | 说明 |
|---|---|
| Cron 配置 | 每个 Ceta Commit 配置可独立设置 cron 表达式 |
| 自动刷新 | 配置变更后自动重载定时任务 |
| 手动触发 | 界面上可手动触发已配置的定时任务 |
| 示例 | 0 0 3 * * ? 表示每天凌晨 3 点同步 |
八、平台提交（commitTriggerUrl）
平台保存 Flow/Form/Page 后，点击 签入 check-in 按钮提交到 Git。pbc页面的提交按钮仅包含 pbc 的元数据，不包含其下的 Flow/Form/Page.
配置方式
在 Ceta 平台的 项目设置 > 配置管理 > 应用配置 中，配置 commit 触发 URL：
{
"client": {
"commitTriggerUrl": "https://ceta-codifier.int.bizops.com.cn/codifier/api/commit/dev2?X-Access-Token=v7ICDMqy1WWINY2hR_xxxxxxxxxxxxxxx_mYrcSin8E"
}
}
URL 格式
- 如果 Access Token 所属项目与 Codifier 项目名称相同：
{codifier地址}/api/commit/{git-分支}?X-Access-Token={secret} - 如果 Access Token 所属项目与 Codifier 项目名称不同，需显式指定项目名：
{codifier地址}/api/commit/{codifier-项目名}/{git-分支}?X-Access-Token={secret}
使用流程
配置完成后，开发人员在平台中正常开发：
- 修改 Flow、Form、Page
- 保存后，点击 签入/check-in 按钮 commit 到 Git 仓库
- 每次 check-in 对应一次 Git commit
九、分支对比
对比两个分支/标签/commit 的差异，生成结构化报告。
| 功能 | 说明 |
|---|---|
| 对比范围 | 支持分支名、标签、commit SHA 作为对比基准和目标 |
| 分类统计 | 按 PBC 分组展示差异，统计总文件数和行变更 |
| JSON 级对比 | 分析 Flow/Form/Page 的 JSON 字段级变更细节（节点数变化、字段增减等） |
| 自定义标签 | 可为基准和目标添加标签名（如"生产环境""开发环境"） |
| HTML 导出 | 对比报告可导出为 HTML 文件 |