4.3 · 文档组织（Document Organization）

企业电子文档治理 · 本章是 Mayan EDMS DeepWiki 中文译文的独立章节页，保留原始链接、源码锚点、模块标签和章节层级。

项目Mayan EDMS 章节4.3 状态全文译文模块文档对象与元数据、系统架构、测试、发布与运维、接口与服务契约

项目要点页2.5 参考项目项目章节目录Mayan EDMS DeepWiki 原始章节Document Organization 上一章4.2 下一章4.4

源码线索

mayan/apps/cabinets/tests/test_wizard_steps.py
mayan/apps/cabinets/wizard_steps.py
mayan/apps/document_comments/apps.py
mayan/apps/document_indexing/apps.py
mayan/apps/document_indexing/events.py
mayan/apps/document_indexing/icons.py
mayan/apps/document_indexing/links.py
mayan/apps/document_indexing/serializers.py
mayan/apps/document_indexing/tests/literals.py
mayan/apps/document_indexing/tests/mixins.py

模块标签

文档对象与元数据
系统架构
测试、发布与运维
接口与服务契约
界面与交互

中文译文

文档组织（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/mayan-edms/Mayan-EDMS/4.3-document-organization

翻译时间：2026-05-27T08:44:28.717Z

翻译模型：deepseek-chat

原文字符数：13665

项目：Mayan EDMS (mayan-edms)

---

文档组织

概述

Mayan EDMS 中的文档组织基于三个互补的系统构建，它们满足不同的组织需求：

元数据管理：附加到文档的结构化数据，具有校验和解析能力
标签系统：用于快速分类的简单颜色编码标签
文档索引：使用基于模板的表达式进行动态层级组织

这些系统通过向导步骤与文档上传流程集成，并可通过 REST API 以编程方式访问。

元数据管理系统

元数据系统通过 metadata 应用提供附加到文档的结构化数据。它支持带校验、默认值、查找约束和解析的带类型元数据。

核心模型与关系

erDiagram
    DocumentType ||--o{ DocumentTypeMetadataType : "定义可用元数据"
    MetadataType ||--o{ DocumentTypeMetadataType : "可分配给"
    Document ||--o{ DocumentMetadata : "拥有元数据值"
    MetadataType ||--o{ DocumentMetadata : "定义类型"

    MetadataType {
        string name "唯一标识符"
        string label "显示名称"
        text default "默认值模板"
        text lookup "逗号分隔的选项"
        string validation "校验器类路径"
        text validation_arguments "YAML 配置"
        string parser "解析器类路径"
        text parser_arguments "YAML 配置"
    }

    DocumentMetadata {
        string value "元数据值"
        foreign_key document
        foreign_key metadata_type
    }

    DocumentTypeMetadataType {
        boolean required "是否为必填字段"
        foreign_key document_type
        foreign_key metadata_type
    }

来源： mayan/apps/metadata/models.py:27-329

元数据类型配置

MetadataType 实例定义了元数据字段的结构和行为：

字段	用途	示例
`name`	用于编程访问的唯一标识符	`invoice_number`
`label`	人类可读的显示名称	`Invoice Number`
`default`	默认值模板	`INV-{{ document.pk }}`
`lookup`	逗号分隔的有效选项	`urgent,normal,low`
`validation`	用于校验的 Python 类路径	`mayan.apps.metadata.metadata_validators.DateValidator`
`parser`	用于值解析的 Python 类路径	`mayan.apps.metadata.metadata_parsers.DateParser`

系统支持在 default 和 lookup 字段中进行模板渲染，允许基于文档属性的动态值。

来源： mayan/apps/metadata/models.py:27-186

文档类型集成

DocumentTypeMetadataType 模型控制哪些元数据类型可用于每种文档类型，以及它们是否为必填项：

# 示例：使元数据对文档类型成为必填项
document_type.metadata.create(
    metadata_type=metadata_type,
    required=True
)

来源： mayan/apps/metadata/models.py:279-329

上传向导集成

元数据系统通过 DocumentCreateWizardStepMetadata 与文档上传集成：

flowchart TD
    A["用户上传文档"] --> B["DocumentCreateWizardStepDocumentType"]
    B --> C["DocumentCreateWizardStepMetadata.condition()"]
    C --> D{"文档类型有元数据吗？"}
    D -->|是| E["显示元数据表单"]
    D -->|否| F["跳过元数据步骤"]
    E --> G["DocumentMetadataFormSet"]
    G --> H["save_metadata_list()"]
    H --> I["创建 DocumentMetadata 对象"]

来源： mayan/apps/metadata/wizard_steps.py:11-65, mayan/apps/metadata/api.py:39-99

标签系统

标签系统通过 tags 应用提供简单的颜色编码标签。标签为基本分类提供了一种比元数据更轻量的替代方案。

标签模型架构

erDiagram
    Tag ||--o{ DocumentTagRelation : "附加到"
    Document ||--o{ DocumentTagRelation : "拥有标签"

    Tag {
        string label "唯一标签名称"
        string color "RGB 十六进制颜色"
    }

    DocumentTagRelation {
        foreign_key tag
        foreign_key document
    }

Tag 模型通过 documents 字段与 Document 建立直接的多对多关系。

来源： mayan/apps/tags/models.py:18-114

标签操作

标签支持带事件跟踪的附加和移除操作：

# 将标签附加到文档
tag.attach_to(document=document)  # 触发 event_tag_attached 事件

# 从文档移除标签
tag.remove_from(document=document)  # 触发 event_tag_removed 事件

来源： mayan/apps/tags/models.py:44-92

访问控制集成

标签系统与 Mayan 的 ACL 系统集成：

def get_documents(self, user, permission=None):
    """返回带有此标签的文档的过滤查询集"""
    queryset = Document.valid.filter(pk__in=self.documents.all())

    if permission:
        queryset = AccessControlList.objects.restrict_queryset(
            permission=permission_document_view,
            queryset=queryset,
            user=user
        )
    return queryset

来源： mayan/apps/tags/models.py:67-79

文档索引系统

文档索引系统通过基于模板的表达式提供动态层级组织。它会根据文档属性自动将文档组织成树状结构。

索引模板架构

graph TD
    IT["IndexTemplate"] --> ITN1["IndexTemplateNode (根节点)"]
    ITN1 --> ITN2["IndexTemplateNode (第1级)"]
    ITN1 --> ITN3["IndexTemplateNode (第1级)"]
    ITN2 --> ITN4["IndexTemplateNode (第2级)"]

    IT -.->|"创建实例"| II["IndexInstance"]
    II --> IIN1["IndexInstanceNode (根节点)"]
    IIN1 --> IIN2["IndexInstanceNode"]
    IIN1 --> IIN3["IndexInstanceNode"]
    IIN2 --> IIN4["IndexInstanceNode"]

    IIN2 -.->|"包含"| DOC1["文档 A"]
    IIN3 -.->|"包含"| DOC2["文档 B"]
    IIN4 -.->|"包含"| DOC3["文档 C"]

来源： mayan/apps/document_indexing/models/

模板表达式系统

索引模板使用 Django 模板语法来组织文档：

表达式示例	结果	用例
`{{ document.document_type.label }}`	按文档类型分组	基于类型的组织
`{{ document.datetime_created\	date:"Y" }}`	按年份分组	基于日期的归档
`{{ document.metadata_value_of.department }}`	按元数据分组	部门组织
`{{ document.tags.first.label }}`	按第一个标签分组	基于标签的结构

来源： mayan/apps/document_indexing/tests/test_models.py:111-296

索引重建过程

flowchart TD
    A["IndexTemplate.rebuild()"] --> B["清除现有的 IndexInstanceNodes"]
    B --> C["遍历所有文档"]
    C --> D["对于每个 IndexTemplateNode"]
    D --> E["评估模板表达式"]
    E --> F{"表达式返回值？"}
    F -->|是| G["创建/查找 IndexInstanceNode"]
    F -->|否| H["停止处理此分支"]
    G --> I["将文档添加到节点"]
    I --> J{"还有更多模板节点？"}
    J -->|是| D
    J -->|否| K["下一个文档"]
    K --> C

来源： mayan/apps/document_indexing/tests/test_models.py:259-296

上传向导集成

所有组织系统都通过向导步骤与文档上传流程集成：

sequenceDiagram
    participant U as 用户
    participant W as DocumentCreateWizard
    participant M as MetadataStep
    participant T as TagStep
    participant C as CabinetStep
    participant D as Document

    U->>W: 上传文档
    W->>M: 步骤1：元数据输入
    M->>U: 显示元数据表单
    U->>M: 输入元数据值
    W->>T: 步骤2：标签选择
    T->>U: 显示可用标签
    U->>T: 选择标签
    W->>C: 步骤3：文件柜选择
    C->>U: 显示可用文件柜
    U->>C: 选择文件柜
    W->>D: 创建文档
    W->>M: save_metadata_list()
    W->>T: step_post_upload_process()
    W->>C: step_post_upload_process()

来源： mayan/apps/sources/wizards.py:22-134, mayan/apps/metadata/wizard_steps.py:11-65, mayan/apps/tags/wizard_steps.py:13-55, mayan/apps/cabinets/wizard_steps.py:13-56

REST 接口访问

所有组织系统都提供完整的 REST API 访问：

元数据 API 端点

端点	用途
`GET /api/documents/{id}/metadata/`	列出文档元数据
`POST /api/documents/{id}/metadata/`	向文档添加元数据
`PUT /api/documents/{id}/metadata/{metadata_id}/`	更新元数据值
`DELETE /api/documents/{id}/metadata/{metadata_id}/`	移除元数据

标签 API 端点

端点	用途
`GET /api/documents/{id}/tags/`	列出文档标签
`POST /api/documents/{id}/tags/attach/`	将标签附加到文档
`POST /api/documents/{id}/tags/remove/`	从文档移除标签
`GET /api/tags/{id}/documents/`	列出带有标签的文档

索引 API 端点

端点	用途
`GET /api/documents/{id}/indexes/`	列出文档索引位置
`GET /api/index_instances/`	列出所有索引实例
`GET /api/index_instances/{id}/nodes/`	浏览索引层级

来源： mayan/apps/metadata/urls.py:100-129, mayan/apps/tags/urls.py:68-91, mayan/apps/document_indexing/urls.py:121-212