agentic_huge_data_base / wiki
页面 Mayan EDMS · 7 参考文档·DeepWiki 中文全文译文
DeepWiki 中文译文 / Mayan EDMS / 7

7 · 参考文档（Reference Documentation）

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

项目Mayan EDMS 章节7 状态全文译文 模块文档对象与元数据、系统架构、配置治理、测试、发布与运维
项目要点页2.5 参考项目 项目章节目录Mayan EDMS DeepWiki 原始章节Reference Documentation 上一章6.3 下一章7.1
源码线索
  • mayan/apps/documents/apps.py
  • mayan/apps/documents/icons.py
  • mayan/apps/documents/links/document_version_links.py
  • mayan/apps/documents/managers.py
  • mayan/apps/documents/permissions.py
  • mayan/apps/documents/tasks.py
  • mayan/apps/documents/urls.py
  • mayan/apps/documents/views/document_type_views.py
  • mayan/apps/documents/views/document_version_views.py
  • mayan/apps/documents/views/document_views.py
模块标签
  • 文档对象与元数据
  • 系统架构
  • 配置治理
  • 测试、发布与运维
  • 工作流与编排

中文译文

参考文档（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/mayan-edms/Mayan-EDMS/7-reference-documentation
翻译时间：2026-05-27T08:44:27.392Z
翻译模型：deepseek-chat
原文字符数：14074
项目：Mayan EDMS (mayan-edms)

---

参考文档

相关源文件

以下文件被用作生成此 Wiki 页面的上下文：

  • mayan/apps/documents/apps.py
  • mayan/apps/documents/icons.py
  • mayan/apps/documents/links/document_version_links.py
  • mayan/apps/documents/managers.py
  • mayan/apps/documents/permissions.py
  • mayan/apps/documents/tasks.py
  • mayan/apps/documents/urls.py
  • mayan/apps/documents/views/document_type_views.py
  • mayan/apps/documents/views/document_version_views.py
  • mayan/apps/documents/views/document_views.py
  • mayan/apps/metadata/tests/__init__.py
  • mayan/apps/permissions/links.py
  • mayan/apps/smart_settings/apps.py
  • mayan/apps/smart_settings/classes.py
  • mayan/apps/smart_settings/icons.py
  • mayan/apps/smart_settings/links.py
  • mayan/apps/smart_settings/literals.py
  • mayan/apps/smart_settings/management/commands/settings_revert.py
  • mayan/apps/smart_settings/permissions.py
  • mayan/apps/smart_settings/settings.py
  • mayan/apps/smart_settings/tests/literals.py
  • mayan/apps/smart_settings/tests/mixins.py
  • mayan/apps/smart_settings/tests/mocks.py
  • mayan/apps/smart_settings/tests/test_classes.py
  • mayan/apps/smart_settings/tests/test_utils.py
  • mayan/apps/smart_settings/tests/test_views.py
  • mayan/apps/smart_settings/urls.py
  • mayan/apps/smart_settings/utils.py
  • mayan/apps/smart_settings/views.py
  • mayan/apps/task_manager/literals.py
  • mayan/apps/task_manager/locale/bs/LC_MESSAGES/django.po
  • mayan/apps/task_manager/locale/cs/LC_MESSAGES/django.po
  • mayan/apps/task_manager/locale/el/LC_MESSAGES/django.po
  • mayan/apps/task_manager/settings.py
  • mayan/settings/testing/base.py

本节为使用 Mayan EDMS 的高级用户和开发者提供全面的参考材料。内容涵盖三个关键领域：通过智能设置系统进行配置管理、完整的数据模型架构以及 REST API 端点。

有关一般系统架构和组件关系，请参见核心架构。有关具体的开发工作流和设置说明，请参见开发与运维。

概述

Mayan EDMS 参考文档分为三个主要类别：

  • 配置参考（7.1）——智能设置系统中所有配置设置、环境变量和配置选项的完整目录
  • 数据模型参考（7.2）——所有 Django 模型及其字段、关系、方法和管理器的详细文档
  • API 参考（7.3）——完整的 REST API 文档，包括所有端点、请求/响应格式、认证方法和使用示例

这些参考文档专为需要了解 Mayan EDMS 内部机制详细技术信息的开发者、构建自定义解决方案的系统集成商以及需要精确配置细节的管理员而设计。

配置系统架构

Mayan EDMS 的配置系统基于智能设置框架构建，该框架提供了一个分层、可校验且可迁移的配置管理系统。

智能设置组件结构
graph TB
    subgraph "配置来源"
        ENV["环境变量<br/>MAYAN_*"]
        CONFIG["YAML 配置文件<br/>config.yml"]
        DEFAULTS["默认值<br/>代码中定义"]
    end

    subgraph "智能设置框架"
        NS["SettingNamespace<br/>逻辑分组"]
        SETTING["Setting<br/>单个值"]
        MIGRATION["SettingNamespaceMigration<br/>版本升级"]
    end

    subgraph "应用集成"
        APPS["MayanAppConfig.ready()<br/>应用初始化"]
        DJANGO["Django 设置<br/>settings.py 集成"]
        RUNTIME["运行时访问<br/>setting.value"]
    end

    ENV --> SETTING
    CONFIG --> SETTING
    DEFAULTS --> SETTING

    NS --> SETTING
    SETTING --> MIGRATION

    SETTING --> APPS
    APPS --> DJANGO
    SETTING --> RUNTIME

来源：mayan/apps/smart_settings/classes.py:1-417, mayan/apps/smart_settings/utils.py:1-443

配置解析流程
flowchart TD
    START["设置访问<br/>setting.value"] --> CACHED{"是否已缓存？"}
    CACHED -->|是| RETURN["返回缓存值"]
    CACHED -->|否| ENV_CHECK["检查环境变量<br/>MAYAN_{name}"]

    ENV_CHECK --> ENV_FOUND{"环境变量<br/>是否找到？"}
    ENV_FOUND -->|是| ENV_PARSE["解析 YAML 值"]
    ENV_FOUND -->|否| CONFIG_CHECK["检查配置文件<br/>config.yml"]

    CONFIG_CHECK --> CONFIG_FOUND{"配置文件<br/>条目是否找到？"}
    CONFIG_FOUND -->|是| MIGRATE["应用迁移<br/>SettingNamespaceMigration"]
    CONFIG_FOUND -->|否| DJANGO_CHECK["检查 Django 设置<br/>getattr(settings, name)"]

    DJANGO_CHECK --> DJANGO_FOUND{"Django 设置<br/>是否找到？"}
    DJANGO_FOUND -->|是| VALIDATE["校验值"]
    DJANGO_FOUND -->|否| DEFAULT["使用默认值"]

    ENV_PARSE --> VALIDATE
    MIGRATE --> VALIDATE
    DEFAULT --> VALIDATE

    VALIDATE --> CACHE["缓存结果"]
    CACHE --> RETURN

来源：mayan/apps/smart_settings/classes.py:325-417, mayan/apps/smart_settings/utils.py:137-175

数据模型架构

数据模型架构以文档管理系统为核心，并包含用于元数据、权限和工作流管理的支持模型。

核心文档模型关系
erDiagram
    DocumentType ||--o{ Document : "document_type"
    Document ||--o{ DocumentFile : "document"
    Document ||--o{ DocumentVersion : "document"
    DocumentFile ||--o{ DocumentFilePage : "document_file"
    DocumentVersion ||--o{ DocumentVersionPage : "document_version"
    Document ||--o{ RecentlyAccessedDocument : "document"
    Document ||--o{ FavoriteDocument : "document"
    Document ||--o{ TrashedDocument : "inherits_from"
    DocumentType ||--o{ DocumentTypeFilename : "document_type"

    DocumentType {
        int id 主键
        string label
        int trash_time_period
        string trash_time_unit
        int delete_time_period
        string delete_time_unit
    }

    Document {
        int id 主键
        uuid uuid 唯一键
        string label
        text description
        datetime datetime_created
        string language
        bool in_trash
        bool is_stub
        datetime trashed_date_time
        int document_type_id 外键
    }

    DocumentFile {
        int id 主键
        string filename
        string comment
        string encoding
        string mimetype
        string checksum
        datetime timestamp
        int document_id 外键
    }

    DocumentVersion {
        int id 主键
        string comment
        datetime timestamp
        bool active
        int document_id 外键
    }

来源：mayan/apps/documents/models/document_models.py, mayan/apps/documents/models/document_type_models.py, mayan/apps/documents/models/document_version_models.py

管理器类与查询优化
classDiagram
    class DocumentManager {
        +delete_stubs()
        +get_by_natural_key(uuid)
    }

    class ValidDocumentManager {
        +get_queryset() QuerySet
        +filter(in_trash=False)
    }

    class TrashCanManager {
        +get_queryset() QuerySet
        +filter(in_trash=True)
    }

    class ValidFavoriteDocumentManager {
        +add_for_user(user, document)
        +remove_for_user(user, document)
        +get_for_user(user) QuerySet
    }

    class ValidRecentlyAccessedDocumentManager {
        +add_document_for_user(user, document)
        +get_for_user(user) QuerySet
    }

    Document --> DocumentManager : objects
    Document --> ValidDocumentManager : valid
    Document --> TrashCanManager : trash
    FavoriteDocument --> ValidFavoriteDocumentManager : objects
    RecentlyAccessedDocument --> ValidRecentlyAccessedDocumentManager : objects

来源：mayan/apps/documents/managers.py:20-322

REST 接口结构

REST API 遵循 Django REST Framework 约定，采用按资源类型组织的分层 URL 结构。

API 端点组织
graph TB
    subgraph "文档 API"
        DOC_LIST["GET /api/documents/<br/>APIDocumentListView"]
        DOC_DETAIL["GET /api/documents/{id}/<br/>APIDocumentDetailView"]
        DOC_UPLOAD["POST /api/documents/upload/<br/>APIDocumentUploadView"]
        DOC_TYPE_CHANGE["POST /api/documents/{id}/type/change/<br/>APIDocumentChangeTypeView"]
    end

    subgraph "文档文件 API"
        FILE_LIST["GET /api/documents/{id}/files/<br/>APIDocumentFileListView"]
        FILE_DETAIL["GET /api/documents/{id}/files/{file_id}/<br/>APIDocumentFileDetailView"]
        FILE_DOWNLOAD["GET /api/documents/{id}/files/{file_id}/download/<br/>APIDocumentFileDownloadView"]
        FILE_PAGE_LIST["GET /api/documents/{id}/files/{file_id}/pages/<br/>APIDocumentFilePageListView"]
    end

    subgraph "文档版本 API"
        VER_LIST["GET /api/documents/{id}/versions/<br/>APIDocumentVersionListView"]
        VER_DETAIL["GET /api/documents/{id}/versions/{ver_id}/<br/>APIDocumentVersionDetailView"]
        VER_EXPORT["POST /api/documents/{id}/versions/{ver_id}/export/<br/>APIDocumentVersionExportView"]
        VER_PAGE_LIST["GET /api/documents/{id}/versions/{ver_id}/pages/<br/>APIDocumentVersionPageListView"]
    end

    subgraph "文档类型 API"
        TYPE_LIST["GET /api/document_types/<br/>APIDocumentTypeListView"]
        TYPE_DETAIL["GET /api/document_types/{id}/<br/>APIDocumentTypeDetailView"]
        TYPE_LABELS["GET /api/document_types/{id}/quick_labels/<br/>APIDocumentTypeQuickLabelListView"]
    end

    DOC_LIST --> FILE_LIST
    DOC_LIST --> VER_LIST
    FILE_LIST --> FILE_PAGE_LIST
    VER_LIST --> VER_PAGE_LIST
    TYPE_LIST --> TYPE_LABELS

来源：mayan/apps/documents/urls.py:522-689, mayan/apps/documents/api_views/

API 视图类层次结构
classDiagram
    class APIDocumentListView {
        +get(request) Response
        +post(request) Response
        +filter_backends list
        +ordering_fields list
    }

    class APIDocumentDetailView {
        +get(request, document_id) Response
        +patch(request, document_id) Response
        +delete(request, document_id) Response
    }

    class APIDocumentUploadView {
        +post(request) Response
        +mayan_external_object_permissions dict
        +mayan_view_permissions list
    }

    class APIDocumentFileListView {
        +get(request, document_id) Response
        +post(request, document_id) Response
        +mayan_external_object_class Model
    }

    class APIDocumentVersionListView {
        +get(request, document_id) Response
        +post(request, document_id) Response
        +get_instance_extra_data() dict
    }

    APIDocumentListView --> Document : 管理
    APIDocumentDetailView --> Document : 管理
    APIDocumentFileListView --> DocumentFile : 管理
    APIDocumentVersionListView --> DocumentVersion : 管理

来源：mayan/apps/documents/api_views/document_api_views.py, mayan/apps/documents/api_views/document_file_api_views.py, mayan/apps/documents/api_views/document_version_api_views.py

集成点

参考文档涵盖了这些系统相互连接的几个关键集成点：

系统集成机制代码位置
配置MayanAppConfig.ready() 方法在应用初始化期间加载设置mayan/apps/documents/apps.py:218-1004
权限ModelPermission.register() 将模型连接到权限系统mayan/apps/documents/apps.py:437-518
事件ModelEventType.register() 启用审计追踪和通知mayan/apps/documents/apps.py:336-383
搜索DynamicSerializerField.add_serializer() 启用搜索索引mayan/apps/documents/apps.py:285-288
缓存ModelQueryFields 通过 prefetch/select_related 优化数据库查询mayan/apps/documents/apps.py:519-553

这三个参考部分通过具体示例、配置选项和实现细节，全面覆盖了这些集成点。

来源：mayan/apps/documents/apps.py:1-1004, mayan/apps/smart_settings/classes.py:1-417, mayan/apps/documents/urls.py:1-689