文档插件使用说明

本文档面向已经实现后的交付、集成和日常维护。历史过程文档、临时依赖分析和重复的打包说明已合并到当前文档集。

功能范围

• 文档上传、下载、预览、编辑、删除、回收站恢复和彻底删除。
• 文档分类树、标签管理、标签筛选和分类统计。
• 文档级权限：按用户、部门、角色授予查看、下载、编辑、删除、分享权限。
• 文档分享：单文档或批量生成分享链接，支持密码、有效期、访问次数和公开访问校验。
• 版本管理：创建版本、查看版本列表、回退和删除版本。
• 操作日志和统计报表。

后端目录

后端插件位于：

Admin.NET/Plugins/Admin.NET.Plugin.Document/

主要目录：

目录	说明
Entity/	文档、分类、标签、权限、分享、版本、日志实体
Enum/	文档类型、状态、权限类型、操作类型枚举
Service/	动态 API 服务
Service/Dtos/	输入输出 DTO
SeedData/	菜单和默认分类种子数据
Configuration/Document.json	插件配置
Option/DocumentOptions.cs	配置绑定模型
Utils/	文件类型、文件大小、编号命名工具

核心实体中，Document 和 DocumentCategory 继承 EntityBaseData，保留框架数据字段；文档列表查询会根据业务权限显式处理可见范围。其他关系表和日志表继承 EntityBaseId。

前端目录

前端页面位于：

Web/src/views/document/

前端 API 封装位于：

Web/src/api-services/document/

主要页面：

页面	路由/用途
list/index.vue	文档列表、上传、搜索、筛选、预览、下载、分享、权限设置、批量转移
category/index.vue	分类管理
tag/index.vue	标签管理
permission/index.vue	已设置权限的文档管理
recycle/index.vue	回收站
share/index.vue、share/manage.vue	分享管理
share/view.vue	分享码访问页面
statistics/index.vue	统计报表

预览组件使用 @vue-office/docx、@vue-office/excel、@vue-office/pdf、md-editor-v3、Element Plus 图片预览和 HTML5 音视频能力。迁移到目标项目前，请确认目标前端已安装这些依赖。

配置说明

配置文件：

Admin.NET/Plugins/Admin.NET.Plugin.Document/Configuration/Document.json

示例：

{
  "$schema": "https://gitee.com/dotnetchina/Furion/raw/v4/schemas/v4/furion-schema.json",
  "[openapi:Document]": {
    "Group": "Document",
    "Title": "Document",
    "Description": "通用文档管理，支持各种格式的文档在线预览",
    "Version": "1.0.1",
    "Order": 100
  },
  "Document": {
    "preUrl": "",
    "Naming": {
      "NumberPrefix": "DOC",
      "NumberRule": "{yyyy}{MM}{dd}-{No}"
    },
    "Storage": {
      "BasePath": "document",
      "UseCategoryPath": true,
      "UseDatePath": true
    }
  }
}

配置项：

配置项	说明
Document.preUrl	预览服务地址。当前前端优先使用接口返回的文件 URL，保留该配置用于预览服务扩展
Document.Naming.NumberPrefix	文档编号前缀，默认 DOC
Document.Naming.NumberRule	文档编号规则，支持 {yyyy}、{MM}、{dd}、{HH}、{mm}、{ss}、{No}
Document.Storage.BasePath	文档上传基础路径，默认 document
Document.Storage.UseCategoryPath	是否追加分类编码路径
Document.Storage.UseDatePath	是否追加年月日路径

文件存储复用框架 SysFileService，MinIO/OSS 等存储配置走框架上传配置，不在 Document.json 中重复配置。

菜单和按钮权限

菜单种子数据位于 SeedData/SysMenuSeedData.cs。启用种子数据后会生成：

• 文档管理
• 文档列表
• 分类管理
• 回收站
• 标签管理
• 权限管理
• 分享管理
• 统计报表

按钮权限包括 document/page、document/upload、document/delete、document/download、document/category/add、document/permission/set、document/share/create 等。菜单初始化后，需要在角色管理中分配菜单和按钮权限。

常用 API

完整接口以 Swagger 的 Document 分组为准，常用接口如下。

功能	方法	路径
文档分页	POST	/api/document/page
文档详情	GET	/api/document/detail?id={id}
上传文档	POST	/api/document/upload
新增文档	POST	/api/document/add
更新文档	POST	/api/document/update
删除文档	POST	/api/document/delete
下载文档	POST	/api/document/download
搜索文档	POST	/api/document/search
回收站列表	POST	/api/document/recycle/page
恢复文档	POST	/api/document/recycle/restore
彻底删除	POST	/api/document/recycle/delete
分类树	GET	/api/document/category/tree
标签列表	GET	/api/document/tag/list
设置权限	POST	/api/document/permission/set
获取预览 URL	GET	/api/document/preview/url?id={id}
创建分享	POST	/api/document/share/create
批量分享	POST	/api/document/share/batch-create
验证分享	POST	/api/document/share/verify
分享码取文档	GET	/api/document/share/document-by-code?shareCode={code}
统计报表	GET	/api/document/statistics

文档集

• 集成部署指南
• 权限机制说明