数字化

数字化用于把纸质档案、附件和多媒体材料转成可上传、可预览、可检索、可长期保存的电子档案。它不是单纯“传一个文件”，而是从档案对象出发，把扫描件、Office、PDF、图片、音视频和批量挂接包纳入档案业务。

业务定位

数字化重点回答四个问题：

• 文件怎么进来：扫描件、图片、文档、音视频和批量压缩包如何上传或挂接到档案。
• 文件放在哪里：电子档案文件、预览源文件、索引文本和元数据分别由谁保存。
• 文件怎么用：用户如何预览、下载、重命名、删除和在档案详情里切换电子文件。
• 文件怎么搜：数字化文件名、档案信息和全文内容如何进入检索链路。

目录总览

目录	解决的问题	主要内容
电子档案	文件和档案对象如何绑定	电子档案模型、档案详情入口、文件列表、重命名、删除、下载
文件采集	文件如何进入系统	单文件上传、分片上传、批量挂接、ZIP 模板、扫描件和附件管理
文件存储	文件如何保存和迁移	Minio / 文件目录、bucket、路径规则、MD5、文件大小、备份迁移影响
文件预览	文件如何在线打开	图片、PDF、Office、OFD、音频、视频、不可预览文件和下载兜底
文件解析	文件如何转成可搜索文本	Tika、文档文本提取、索引写入、解析失败处理
全文检索	用户如何查到资料	高级搜索、target=text、target=electronic、Elasticsearch 索引
权限控制	谁能看、下、改、删	数字化权限、文件预览、文件下载、重命名、删除、全文检索、数字化文件检索
研发参考	研发如何定位代码	前端组件、接口封装、后端路由、模型和任务入口
产品边界	哪些属于数字化，哪些不属于	档案业务、环境控制、RFID、打印、部署和存储边界

核心对象

对象	说明
档案	电子档案的业务归属对象；当前主线电子文件通常挂到档案 archiveId 下
电子档案	sys_electronic 中的文件元数据，包含名称、类型、路径、大小、MD5、档案 ID
文件分片	file_models、file_chunk_models 记录分片上传状态、上传 ID、分片总数和 ETag
对象文件	Minio bucket 或本地文件服务中的真实文件内容
搜索文档	Elasticsearch 中的 electronic、档案和装具索引数据
数字化权限	控制用户能否预览、下载、重命名、删除和检索电子档案

前端页面结构

数字化能力当前不是一个独立的完整业务模块页面，而是嵌在档案管理、详情预览、高级搜索和角色权限里。

入口	主要处理对象	前端目录 / 文件
档案详情电子档案	单份档案下的电子文件列表、预览、下载、重命名、删除	fit-archive-ng/src/views/ArchivesManagement/overview/File/components/DetailsFile.vue
电子档案资源管理	档案详情里的文件树、移动、重命名、批量操作	fit-archive-ng/src/views/ArchivesManagement/overview/File/components/fileManagement
批量导入 / 挂接	实体档案导入、电子档案批量挂接、分片上传、ZIP 模板	fit-archive-ng/src/views/ArchivesManagement/overview/File/components/fileImport
文件预览组件	图片、PDF、Office、OFD、音视频预览和下载	fit-archive-ng/src/components/previewFile
高级搜索	数字化档案、全文检索、结果预览	fit-archive-ng/src/components/seniorSearch
数字化权限	角色授权中的预览、下载、重命名、删除、全文搜索、数字化搜索	fit-archive-ng/src/views/SystemManagement/roleMan/components/TreeList.ts
API 封装	上传分片、完成上传、电子档案列表、重命名、删除、下载	fit-archive-ng/src/api/ApiFileManagement/index.ts

写产品说明时要把“档案主数据”和“电子档案文件”分开：档案是业务对象，电子档案是挂在档案下面的文件对象。一个档案可以有多个电子文件，文件名、类型、路径、大小、MD5 和预览能力都属于数字化链路。

核心链路

实体资料 / 扫描件 / 办公文档 / 音视频
  ↓
单文件上传 / 分片上传 / ZIP 批量挂接
  ↓
Minio / 文件目录保存对象文件
  ↓
sys_electronic 保存电子档案元数据
  ↓
预览组件按文件类型选择打开方式
  ↓
Tika 提取文本，Elasticsearch 建索引
  ↓
高级搜索和全文检索返回档案 / 电子档案结果

这条链路里，任何一段失败都会表现成不同问题：上传失败通常看后端和对象存储；文件打不开看预览和路径；能预览但搜不到看 Tika 和 Elasticsearch；搜索结果能出来但无法预览，通常要回头查电子档案路径、权限和 Minio 文件。

电子档案

电子档案是数字化的核心业务对象。后端模型 ElectronicModel 对应表 sys_electronic，它只保存文件元数据和档案关联，不直接保存文件二进制内容。

字段	产品含义
name	电子档案文件名
type	文件类型，当前模型口径包括文档、图片、视频、音频、其他
path	文件在对象存储 / 文件服务中的路径
size / sizeStr	文件大小和展示用大小
archiveId	归属档案 ID
md5	文件内容摘要，用于识别文件和上传链路
approval	电子档案可被借阅审批关联

文件操作

操作	产品说明	典型接口 / 入口
查看列表	在档案详情或搜索结果中加载电子档案列表	/electronic/getElectronicList，前端 getElectronicList
预览	按文件类型打开预览组件	/electronic/preview、/minio/preview、/oo/preview
下载	直接下载单个文件或打包下载多个文件	/minio/download、/minio/downloadMap
重命名 / 移动	修改文件名或文件路径	/electronic/rename
删除	删除电子档案记录和对应索引	/electronic/deleteElectronicArchives

部分接口在后端服务方法和前端封装中保留，具体现场是否注册到路由，要以当前版本 router/system/electronic.go 和发布包为准。

文件采集

文件采集包含日常上传和批量挂接两类场景。日常上传面向档案详情里的少量附件；批量挂接面向已有档案和大量扫描件的对应关系。

上传方式

方式	场景	当前代码口径
普通上传	小文件、少量附件、系统图片类资源	/minio/upload
电子档案创建	直接把文件挂到指定档案	/electronic/createElectronicArchive
分片上传	大文件或批量导入中避免一次性上传失败	/electronic/getUploadChunkID、/electronic/uploadPart、/electronic/completeChunkUpload
ZIP 批量挂接	先下载模板包，再把电子档案压缩包上传解析	/electronic/createArchiveZip、/electronic/parseArchiveZip、ZIP 分片上传接口

前端批量挂接入口在 fileImport 下，代码里会先计算文件信息和 MD5，再走分片上传，最后完成合并。这个链路更适合大量扫描件，不适合人工逐个点开档案上传。

路径规则

电子档案路径通常和档案 ID 绑定，例如后端索引任务里会按 archive/<archiveId>/ 去掉前缀后展示相对路径。写导入模板或迁移脚本时，不要只保存文件名，必须保留归属档案、对象存储路径和电子档案记录之间的关系。

文件存储

数字化文件最终落到 Minio / 文件目录，数据库只保存元数据。备份迁移时必须同时处理数据库和对象文件，否则会出现“档案能查到，附件打不开”的问题。

层	保存内容	维护重点
数据库	sys_electronic、上传分片表、档案关联关系	记录完整性、软删除、MD5、路径一致性
Minio / 文件目录	原始文件、预览源文件、下载文件	bucket、目录、对象路径、磁盘空间、备份恢复
文件映射	大文件打包下载或临时下载映射	下载 UUID、过期清理、路径是否可访问
搜索索引	文件名、相对路径、类型、大小、全文内容	Elasticsearch 索引是否同步

对象文件不要脱离数据库单独移动。文件路径如果变化，预览、下载、全文索引和借阅审批关联都会受到影响。

文件预览

前端 previewFile 组件根据文件扩展名选择预览方式。无法识别或无法在线打开的文件，应回退到下载。

类型	支持格式口径	预览方式
图片	jpg、jpeg、png、bmp、webp、ico、jfif、gif	前端图片预览
PDF	pdf	pdfJS/web/viewer.html
Office / 文档	doc、docx、xls、xlsx、ppt、pptx、txt、rtf、csv、odt、epub 等	/oo/preview 转到 7001 文档预览前端
OFD	ofd	OFD 预览分支
音频	wav、mp3、aac、opus、flac、ogg	浏览器音频播放
视频	3gp、mp4、mov、mkv、webm、ogv	浏览器视频播放
其他	压缩包、未知格式、无法解析格式	显示不支持在线预览，提供下载

Office 预览链路当前保留 /oo/preview 兼容入口，后端会解析预览文件并跳转到 7001 文档预览前端。这个预览前端来自独立 GitLab 仓库 fit-archive/onlyoffice-web-local，构建产物会被集成进后端 smart-doc-vault/frontend/onlyoffice，再通过后端 go:embed frontend/onlyoffice 以静态站点方式发布。它不是旧的 OnlyOffice Document Server 直连模式，当前预览页内部包含 PDF / OFD / Office 渲染能力，并使用 X2T WASM 等浏览器端能力处理文档。

预览组成	当前口径	代码 / 配置线索
预览前端仓库	独立项目 fit-archive/onlyoffice-web-local	https://gitlab.singzer.cn/fit-archive/onlyoffice-web-local
后端集成位置	预览前端构建后放入后端嵌入目录	smart-doc-vault/frontend/onlyoffice、go:embed frontend/onlyoffice
默认端口	7001	document-convert.preview.port，默认值兜底为 7001
转换服务	sdv-document-convert / document-convert	默认服务地址 http://127.0.0.1:7010
WASM 资源	浏览器端文档转换 / 渲染资源	frontend/onlyoffice/wasm/x2t/x2t.wasm、x2t.js

现场如果 Office 文件打不开，要同时检查后端 /oo/preview、document-convert 配置、7001 预览端口、7010 转换服务、Minio 文件访问地址、WASM 静态资源 MIME 类型和浏览器网络请求。7001 端口打不开时，不要只查主后端 8888；要看后端是否启动了 Office preview web server，以及 document-convert.preview.port 是否被改过。

文件解析

文件解析用于把电子档案内容转成可搜索文本。后端 ElectronicMinioToElastic 会从 Minio 读取电子档案对象，调用 Tika 提取 text/plain，再把清洗后的内容写入 Elasticsearch electronic 索引。

环节	说明
读取文件	从 Minio bucket 按 sys_electronic.path 取对象
文本提取	Tika 解析文档内容，返回纯文本流
内容清洗	当前代码会去掉空白字符，再写入 content
索引写入	文档 ID 使用 electronic-<电子档案ID>，索引名为 electronic
统计累计	解析文本长度会累计到 setting.total_num

解析链路只保证“可提取文本的文件”进入全文检索。图片扫描件如果没有 OCR 结果，Tika 不能自动把图片里的文字变成全文内容；这类需求要单独接 OCR 或在扫描流程里生成可搜索 PDF。

全文检索

当前主线检索使用 Elasticsearch。系统启动后会有任务把档案、档案盒、电子档案同步到索引；后端还提供 /all/syncElastic 手动触发全量同步。

搜索目标	产品含义	典型入口
target=text	全文检索，关注文件内容和档案文本	高级搜索“全文检索”
target=electronic	数字化文件检索，关注电子档案文件名、路径、类型等	高级搜索“数字化档案 / 数字化文件检索”
档案 / 装具索引	检索档案主数据和装具信息	高级搜索综合结果

全文搜索搜不到时，先区分是“索引里没有电子档案记录”，还是“电子档案有记录但没有 content”。前者看 ElectronicToElastic 和索引同步，后者看 Tika、Minio 文件读取和 ElectronicMinioToElastic。

当前 Elasticsearch 不是只启动一个 9200 服务就结束，还依赖 IK 插件和 electronic 索引 mapping 初始化。Linux Docker 离线包里由 docker-install 的 es-chown 容器把 elasticsearch-analysis-ik-8.7.0.zip 解压到 Elasticsearch 插件目录，再由 es-init 容器执行 elastic_init.sh 初始化 electronic 索引。Go 后端 InitElasticsearch() 只负责连接 Elasticsearch 客户端和清理分片上传表，不负责安装 IK 插件，也不负责创建 electronic mapping。

初始化项	当前做法	作用
IK 插件	elasticsearch-analysis-ik-8.7.0.zip 解压到 plugins/analysis-ik	支持中文分词
electronic mapping	elastic_init.sh 执行 PUT /electronic	建立电子档案全文索引结构
正文字段	content 使用 ik_smart 作为 analyzer 和 search_analyzer	支持中文全文检索和高亮
文件辅助字段	name、locationName、path 使用 wildcard	偏文件名、位置、路径匹配
高亮设置	index.highlight.max_analyzed_offset = 5000000	允许较长文本做高亮片段
执行容器	sdv-es-init 等 Elasticsearch healthy 后执行脚本	确保初始化发生在 ES 可用之后

如果中文全文检索效果异常，优先确认三件事：analysis-ik 插件目录是否存在，electronic 索引 mapping 里 content 是否是 ik_smart，以及 sdv-es-init 是否成功执行过。只看 Elasticsearch 容器存活，不能证明全文检索已经初始化完成。

权限控制

数字化权限是角色权限的一部分，前端 digitalTalk 里已经按能力拆分。

权限	控制内容	后端权限种子
文件预览	是否能打开电子档案预览	/electronic/preview，名称 预览
文件下载	是否能下载电子档案	/minio/download，名称 下载
重命名	是否能改电子档案名称或路径	/electronic/rename，名称 重命名
删除	是否能删除电子档案；当前权限种子保留，具体路由注册以发布版本为准	/electronic/deleteElectronicArchives，名称 删除
全文检索	是否能按全文内容搜索	/all/elSearch?target=text，名称 全文搜索
数字化文件检索	是否能按电子档案文件维度搜索	/all/elSearch?target=electronic，名称 数字化

权限说明要和用户视角保持一致：能看到档案，不代表一定能预览或下载电子档案；能预览，也不代表能删除、重命名或全文检索。

搜索接口存在历史大小写口径：权限种子和前端当前使用 /all/elSearch，Swagger / router/system/elastic.go 里也能看到小写 /all/elsearch。现场排查时优先看当前发布包实际注册的路由和中间件。

关联基础设施

基础设施	在数字化中的作用	常见问题
Minio / 文件目录	保存电子档案文件、预览源文件和附件	文件不存在、bucket 错误、路径不一致、磁盘满
Tika	提取 Office、PDF 等文档文本	服务未启动、文件格式不支持、解析超时
Elasticsearch	保存档案、装具、电子档案和全文索引	IK 插件缺失、electronic mapping 未初始化、索引缺失、同步失败、中文检索效果不符合预期
文档预览前端	Office、PDF、OFD 等文档在线预览	7001 端口、WASM 资源、Minio URL、转换后文件不可访问
数据库	保存电子档案元数据、权限和分片状态	记录和对象文件不一致
后端服务	上传、鉴权、预览、解析、下载和搜索接口	路由注册、权限、token、反向代理路径

历史发展

数字化的历史重点主要在三条技术线上：Office 预览方案、文档解析方案和搜索引擎方案。现在代码里会同时看到 OnlyOffice、/oo/preview、Tika、Meilisearch、RedisSearch、Elasticsearch、document-convert 等名字，维护时要先判断它们属于当前主线、兼容入口还是历史残留。

Office 预览方案演进

阶段	方案	典型线索	当前口径
早期 / 历史线	直接对接 OnlyOffice Document Server	旧主线 smart-doc-vault 有 onlyoffice 配置、OnlyOfficeService、InitOnlyOfficeRouter，前端通过 /oo/preview 传入文件 URL、文件名和 token	历史方案；维护旧现场时仍可能遇到
兼容过渡	保留 /oo/preview 入口	当前前端 previewFile 仍把 Office / 文档类文件交给 /oo/preview，后端 office_preview.go 负责解析旧 data 参数	兼容入口，不代表后端仍直接使用旧 OnlyOffice 逻辑
当前主线	独立预览前端 + document-convert 转换服务	fit-archive/onlyoffice-web-local 构建为预览前端，后端嵌入 frontend/onlyoffice 并默认用 7001 发布；document-convert 负责转换缓存，默认 7010	新部署优先按当前预览前端、WASM 资源和转换服务维护

当前主线的思路是：旧格式 Office 文件先按需要转换成更适合预览的格式，再把转换后的文件缓存到 Minio，最后跳转到 7001 预览前端。doc、odt、rtf 会转成 docx，xls、ods 会转成 xlsx，ppt、odp 会转成 pptx。预览前端自身来自 onlyoffice-web-local，其中包含 X2T WASM、PDF worker、OFD 渲染和静态字体资源；后端负责把这些静态资源作为嵌入文件系统发布。所以 Office 预览失败时，不只看浏览器页面，还要看转换服务、Minio 缓存目录、7001 预览端口、WASM 资源加载和 /oo/preview 兼容入口。

文档解析方案演进

阶段	方案	典型线索	当前口径
文件名 / 元数据检索	只把电子档案名称、路径、类型、大小等写入索引	ElectronicToElastic 写入 name、path、type、size、genres、targetId	适合数字化文件检索，但不等于全文检索
Tika 文本解析	从 Minio 读取电子档案对象，调用 Tika 提取纯文本	旧主线和当前主线都有 InitTika、TikaClient、ParseReaderWithHeader、ElectronicMinioToElastic	当前全文内容解析主线
OCR / 可搜索扫描件	需要扫描流程或额外 OCR 生成文字层	当前文档解析代码主要处理可提取文本的文档，不会自动识别普通图片里的文字	不是当前通用主线，需要项目单独接入

这里要区分“预览”和“解析”：文件能预览，只说明浏览器或预览服务能打开它；全文能搜到，说明内容已经被 Tika 或其他解析链路提取并写进搜索索引。扫描图片如果没有 OCR，通常只能按文件名、路径或档案元数据检索，不能按图片里的文字检索。

搜索引擎方案演进

阶段	方案	典型线索	当前口径
早期搜索	Meilisearch	旧主线存在 meilisearch 配置、initialize/meilisearch.go、MeiliSearchApi、UpdateMeiliSearch、MinioToMeilisearch	历史方案，不作为新部署优先口径
中间尝试	RedisSearch / RediSearch	旧分支有 initialize/redisearch.go，使用 github.com/RediSearch/redisearch-go，创建 electronic 索引并维护 text、name、locationName、genres、status、securityLevel、path 等字段	历史方案，不作为当前部署依赖
过渡期	Meilisearch / RedisSearch 代码残留 + Elasticsearch 接入	多个版本线里还能看到 BoxToMeiliSearch、ArchiveToMeilisearch 注释，以及 ElasticService.Search 中的 RediSearch 查询实现；同时已经初始化 Elasticsearch 和 Tika	维护时不要被函数名或文件名误导，要看实际启动任务和路由
当前主线	Elasticsearch + IK 插件 + electronic mapping 初始化	当前 fdmjj 启动任务执行 FileToElastic、ArchiveToElastic、BoxToElastic、ElectronicToElastic，接口是 /all/elSearch / /all/elsearch；部署脚本通过 elasticsearch-analysis-ik-8.7.0.zip 和 elastic_init.sh 初始化中文全文索引	当前全文检索和数字化文件检索主线

当前搜索索引不只服务电子档案，还同时承载档案、档案装具和电子档案。target=electronic 更偏文件名、路径和电子档案元数据；target=text 更偏全文内容。现场排查时先确认 Elasticsearch 是否可用，再看同步任务是否跑过，最后区分是电子档案元数据没进索引，还是 Tika 没把正文写入 content。

维护判断原则

判断问题	当前建议
新部署 Office 预览怎么选	按 onlyoffice-web-local 预览前端、7001 端口、WASM 静态资源和 document-convert 维护；/oo/preview 只是兼容入口
看到 OnlyOffice 怎么处理	先判断是否旧现场或历史分支；新文档不要默认推荐旧 OnlyOffice 直连方案
全文解析依赖什么	当前按 Tika 维护；图片扫描件文字识别要另接 OCR 或可搜索 PDF 流程
新部署搜索引擎怎么选	按 Elasticsearch + IK 插件 + electronic mapping 初始化维护
看到 Meilisearch 怎么处理	视为历史方案或代码残留；除非维护旧现场，不作为当前主线判断依据
看到 RedisSearch / RediSearch 怎么处理	视为中间尝试或旧分支残留；当前主线不要再按 Redis 模块排查全文检索
搜索搜不到怎么查	先看 Elasticsearch 和 IK / mapping 初始化，再看同步任务，再看 Tika 解析和 sys_electronic.path 对应的 Minio 文件

研发参考

代码位置	视角	说明
fit-archive-ng/src/components/previewFile	前端预览	文件类型判断、Blob URL、PDF / Office / 音视频预览
fit-archive-ng/src/api/ApiFileManagement/index.ts	前端接口	分片上传、电子档案列表、重命名、删除、下载
fit-archive-ng/src/components/seniorSearch	前端搜索	全文检索、数字化档案结果、预览入口
fit-archive-ng/src/views/ArchivesManagement/overview/File/components/fileImport	批量导入	电子档案批量挂接、ZIP 模板和分片上传
smart-doc-vault/model/system/electronic.go	数据模型	sys_electronic、电子档案类型、档案关联
smart-doc-vault/model/system/file.go	上传模型	分片上传记录、分片 ETag、上传状态
smart-doc-vault/api/system/electronic.go	后端 API	电子档案创建、列表、分片上传、ZIP 导入、重命名、删除
smart-doc-vault/api/system/minio.go	文件服务 API	上传、预览、下载、文件映射
smart-doc-vault/task/electronic_to_elastic.go	索引任务	电子档案索引、Minio 文件解析、Tika 到 Elasticsearch
smart-doc-vault/task/electronic_role.go	权限初始化	数字化权限种子数据
smart-doc-vault/frontend/onlyoffice	文档预览前端产物	来自 fit-archive/onlyoffice-web-local，被后端嵌入并通过 7001 发布
docker-install/elastic_init.sh	Elasticsearch 初始化	创建 electronic 索引、设置 IK 分词和高亮参数

产品边界

• 数字化关注文件从采集、上传、保存、预览、解析到检索的完整链路。
• 档案分类、档案状态、借阅、上架、盘点和回转柜状态归入档案管理。
• Minio、Tika、Elasticsearch、文档预览服务的部署、端口和备份细节放到系统架构、打包分发和备份迁移。
• RFID 标签、读写器、盘点设备不属于数字化；即使 RFID 结果能定位档案，电子文件仍按数字化链路维护。
• 打印标签、借阅单、移交单不属于数字化；它们属于档案管理里的打印能力。