搜索 K
主题
智档宝开发流程
这篇文档用于说明智档宝研发代码在 GitLab 中的组织方式，以及主线、大版本线、能力线和项目定制线之间的关系。
智档宝不是一个单仓库项目。早期平台开发主要集中在 fit-archive 组下，前端、后端、设备接入、安装脚本和交付工具逐步沉淀。后续随着密集架、回转柜、新大屏、RFID、项目定制等方向扩展，GitLab 中出现了长期子分组、阶段性分组和个人/临时 fork。
总体口径
| 口径 | GitLab 表现 | 用途 |
|---|---|---|
| 主线平台 | fit-archive/fit-archive-ng、fit-archive/smart-doc-vault 等 | 承载智档宝通用前后端能力 |
| 历史版本线 | 基础版本、fit-archive/2024-new-screen、fit-archive/hzg | 承载从基础平台到新大屏、回转柜阶段的历史演进 |
| 稳定版本线 | fit-archive/fdmjj | 承载当前稳定版本和交付能力 |
| 当前开发版 | fit-archive/rfid | 承载目前仍在开发中的最新版本 |
| 项目定制线 | fit-archive/adqrmfy、fit-archive/gdjy、fit-archive/yd、fit-archive/gansu 等 | 承载客户项目差异、阶段性交付和现场版本 |
| 个人 / 临时 fork | icepie/*、lxr/*、Jeff/*、zks/* 等 | 承载个人开发、验证、临时分支或迁移过程 |
这里的“分支”不是只指 Git branch。历史上很多“大版本分支”实际表现为子分组或独立仓库副本。看代码来源时，要同时看 GitLab 分组路径、项目名、默认分支、最近活动和提交历史。
GitLab 组织演化
理解这个图时要注意：版本演进口径按“基础版本 -> 新大屏 -> hzg -> fdmjj 稳定版 -> rfid 开发版”理解。fdmjj 是当前稳定版本，rfid 是目前的开发版本，fdmjj 之前的基础、新大屏、hzg 都按历史版本看。中间创建的子分组通常是从主线或某条版本线 fork / 复制出来，用于项目交付、客户定制或阶段性稳定版本。
版本线说明
| 版本线 | 大致定位 | 什么时候看它 |
|---|---|---|
| 基础版本 | 智档宝最早的平台基础，沉淀通用前后端、安装交付和基础工具 | 查早期平台结构、通用能力来源、历史项目来源 |
2024-new-screen | 基础版本之后的新大屏历史版本，重点是大屏展示和可视化交互 | 查新大屏、定制大屏、库房态势展示相关历史实现 |
hzg | 新大屏之后的回转柜历史版本，重点是回转柜业务、库位和设备联动 | 查回转柜项目、判断回转柜和其他架具体系的差异 |
fdmjj | 当前稳定版本线，围绕飞度密集架交付沉淀，包含平台侧、更新服务等 | 做稳定版本维护、现场交付、密集架相关问题回归 |
rfid | 目前的开发版本，沉淀 RFID、手持机、门口机、打印和相关后端能力 | 做 RFID 新能力开发、手持机/标签/打印联调、验证当前最新方向 |
| 项目定制分组 | 从主线或某条版本线 fork / 复制出来，服务某个客户或阶段性交付 | 查客户差异、现场版本、临时补丁和是否需要回流 |
判断一个项目应该基于哪条线，不要只看项目名。优先看它所处阶段：历史问题按基础版本、新大屏、hzg 追溯；稳定交付优先看 fdmjj；新能力开发看 rfid。如果只是客户字段、页面或部署差异，应放在项目定制线并记录来源。
版本号规则
智档宝前后端版本主要用 Git commit hash 识别，不依赖 package.json 的语义版本号。以 fdmjj/fit-archive-ng 和 fdmjj/smart-doc-vault 为例：
| 项目 | 规则 | 说明 |
|---|---|---|
前端 fit-archive-ng | 构建时取 git rev-parse --short HEAD 注入 __COMMIT_HASH__ | Vite 配置会把当前前端提交短 hash 注入页面；Git 不可用时回退到 CI_COMMIT_SHORT_SHA、COMMIT_HASH 或 unknown |
后端 smart-doc-vault | 编译时通过 -ldflags 注入 Version、BuildTime、BuildHash | Makefile / Windows build 脚本里 BuildHash 来自 git rev-parse --short HEAD |
| 系统信息接口 | 后端返回 v<Version>_<后端hash> | /sys/getSysSWInfo 中 Version 形如 v1.0_<后端hash> |
| 前端展示 | 前端再追加 _<前端hash> | 页面拿到后端 Version 后追加 __COMMIT_HASH__，最终用于区分前后端是否都是预期提交 |
现场核对版本时，优先记录完整显示值，而不是只写“1.0”或“最新版”。推荐格式：
text
后端：smart-doc-vault <后端短 hash>
前端：fit-archive-ng <前端短 hash>
页面显示：v1.0_<后端短 hash>_<前端短 hash>
编译时间：系统信息页显示的编译时间拿到 hash 后，可以打开 飞度一体化平台 的“版本搜索”，输入前端 hash、后端 hash 或完整版本号。平台会按提交、标签和版本信息搜索对应项目，用来定位这个版本来自哪个仓库、哪次提交以及应该找哪条版本线排查。
如果前端页面显示的版本 hash 和 GitLab 当前提交不一致，先判断是否浏览器缓存、部署目录未覆盖、服务未重启或前后端来自不同版本线。
代表性仓库
| 路径 | 定位 | 默认分支 | 最近活动 |
|---|---|---|---|
fit-archive/fit-archive-ng | 智档宝主线前端 | main | 2025-01-01 |
fit-archive/smart-doc-vault | 智档宝主线后端 | main | 2025-01-10 |
fit-archive/fdmjj/fit-archive-ng | 密集架前端 / 平台侧 | main | 2026-06-09 |
fit-archive/fdmjj/smart-doc-vault | 密集架后端 / 平台侧 | main | 2026-06-14 |
fit-archive/hzg/fit-archive-ng | 回转柜前端开发线 | main | 2025-04-10 |
fit-archive/hzg/smart-doc-vault | 回转柜后端开发线 | main | 2026-03-05 |
fit-archive/2024-new-screen/fit-archive-ng | 新大屏前端开发线 | main | 2024-10-22 |
fit-archive/2024-new-screen/smart-doc-vault | 新大屏后端开发线 | main | 2025-12-15 |
fit-archive/rfid/fit-archive-ng | RFID 前端能力线 | main | 2026-06-14 |
fit-archive/rfid/smart-doc-vault-rfid | RFID 后端能力线 | main | 2026-06-15 |
这张表只列代表性入口，不是完整项目清单。完整 GitLab 清单应通过脚本重新采集，避免文档长期复制过期信息。
日常开发流程
开发前先判断归属，不要一上来就新建仓库或复制项目：
| 场景 | 推荐位置 | 原则 |
|---|---|---|
| 多个项目都需要的通用能力 | 主线平台 | 优先进入 fit-archive 主线仓库，再由版本线同步 |
| 稳定版本维护 | fdmjj | 作为当前稳定版本线维护，优先保障交付和回归稳定 |
| 历史版本问题追溯 | 基础版本 / 新大屏 / hzg | 按版本链路追溯来源，不直接在历史线继续扩散新能力 |
| 当前开发 | rfid | 作为目前开发版本承载新能力 |
| 客户项目独有字段、页面、设备差异 | 项目定制线 | 放到客户项目分组，并记录来源主线和差异点 |
| 临时验证、个人实验 | 个人 / 临时 fork | 不直接作为交付源，稳定后迁移到主线或能力线 |
| 现场紧急修复 | 当前交付线 | 修复后补记录，并判断是否需要回流主线 |
分支和子分组约定
- 版本线要按“基础版本 -> 新大屏 ->
hzg->fdmjj稳定版 ->rfid开发版”记录来源。 - 项目定制线要写清楚从哪个主线或能力线 fork / 复制出来。
- 新建子分组时，要在 README 或交付记录中说明客户、用途、来源、前端仓库、后端仓库和部署方式。
- 同名仓库在不同分组下可能含义不同，例如
fit-archive-ng在主线、密集架、回转柜、新大屏、项目定制中都可能存在。 - 如果定制能力已经被多个项目复用，应考虑回流主线或沉淀为能力线，而不是继续在客户仓库里复制。