核心概念

在深入使用 Pinmok 之前，花几分钟了解它的整体架构会让后续的一切都更容易理解。这一章不涉及具体操作，只是帮你在动手之前对系统的结构和各部分的关系有个整体了解。

Pinmok 是什么

Django Admin 是一个强大的工具，但它的设计以 Model 为中心——每个后台页面对应一个数据模型，导航结构自动生成，难以自定义。一旦业务逻辑超出 CRUD 的范围，开发者往往要花大量精力和它的机制对抗。

Pinmok 改变了这个局限，同时对原有的 Django Admin 完全兼容。后台页面不再局限于 Model，任何业务功能都可以拥有自己的后台页面；开发者定义的菜单与 Admin 自动生成的菜单融合在一起，构成完整的导航结构，再也不必迁就框架的默认行为。站点配置统一管理，后台行为可以在运行时调整，而不必修改代码。组件和样式经过重写，全面兼容 Bootstrap 5 的 Tabler——这是一套成熟、现代的 UI 框架，让开发者在编写业务页面时能快速处理界面布局。

这一切的实现方式，是从内部扩展 Django Admin，继承并替换了核心的 AdminSite。这种方式的好处在于，Django Admin 原有的一切能力都完整保留——注册方式、权限模型、URL 结构一概不变。Pinmok 在这个基础上扩展，而不是另起炉灶。对已有项目来说，接入成本很低；熟悉 Django Admin 的开发者几乎可以零学习成本上手，同时获得一套更灵活、更完整的后台开发能力。

整体架构

Pinmok 的层次关系可以用下图来理解：

最底层是 Django 框架本身，它是一切的基础。Pinmok 作为一组 Django 应用安装进来，其中 pinmok/core 负责替换 AdminSite、提供菜单机制、信号定义和各类基类，pinmok/padmin 则负责后台的 UI、视图和模板。

在这套系统之上开发，和开发普通的 Django 应用没有任何区别——你用的还是熟悉的 app 结构、视图、模板和 URL 配置，没有新的概念需要学习。Pinmok 已经把后台界面准备好了，样式全面兼容 Bootstrap 5，你可以直接用现有的前端知识处理界面布局。无论是 Pinmok 官方模块还是你自己开发的业务模块，接入的方式完全一致。 所以，Pinmok 给了你一个开放的 Admin，它替你搭好了框架，剩下的交给你来填。

命名空间包结构

Pinmok 的所有模块共用 pinmok 这个顶级命名空间，但它们是彼此独立的 Python 包，可以单独安装，也可以按需组合。这依赖 Python 的命名空间包机制——pinmok/ 目录下没有 init.py，正是这个设计让多个独立的包能够共享同一个命名空间前缀。

如果你通过 pip 安装，这些细节由包管理器自动处理，无需关心。但如果你选择将源码直接复制进项目目录，有一点需要特别注意：不要在 pinmok/ 目录下添加 _ _init__.py。这个文件的缺席不是遗漏，一旦添加，命名空间包机制就会失效，pinmok/core、pinmok/padmin 等模块将无法正常加载。 保持目录结构不变，按照文档中的方式集成，就不会有问题。

核心模块

pinmok/core

core 是整个系统的基础层，为所有模块提供全局通用的能力。它定义了继承并替换 Django 原生 AdminSite 的站点类、菜单的定义和解构方法、信号、权限相关的基础处理， 以及多语言模型基类、TreeNode 等通用基类和工具。core 本身不实现任何业务逻辑，只为上层模块提供定义和基础服务。

pinmok/padmin

如果说 core 是地基，padmin 就是建在上面的整栋楼。它是 Pinmok 的主体，负责实现所有面向开发者和用户的后台功能。padmin 基于 core 提供的基类和定义，完成了 Django Admin 扩展的全部业务逻辑：菜单的构建、存储、缓存与同步在这里实现；后台的视图、模板、静态资源和 UI 组件在这里提供；站点配置的读写、路由别名解析等辅助功能也在这里。你在浏览器里看到的后台界面，以及背后支撑它运行的一切，都是 padmin 的工作。对开发者来说，无论是注册页面、定义菜单，还是使用后台组件构建界面，日常打交道最多的就是 padmin 提供的能力。

菜单系统

Django Admin 原生的导航由框架根据已注册的 Model 自动生成，结构固定，无法自定义顺序，也无法加入非 Model 页面。这在纯 CRUD 场景下够用， 但是如果希望后台承载更复杂的业务，Django Admin 原有的机制就反而变成了障碍。

Pinmok 单独设计了一套菜单系统，致力于解决菜单封闭的问题。它是模块化的入口，每个应用都可以定义自己的菜单项，由系统统一管理。自定义菜单与 Django Admin 原有的 Model 菜单融合在一起，开发者可以自由指定排列顺序，构成完整的导航结构。任何业务功能，无论是否对应一个 Model，都可以出现在后台菜单中，占据合理的位置。

这套设计让后台的导航结构真正跟着业务走，而不是跟着数据模型走。

站点配置

一个后台系统通常需要管理大量配置项，比如站点名称、Logo、联系方式、功能开关等。常见的做法是把这些配置散落在各个应用的 settings.py 或硬编码在模板里，每次修改都需要改代码、重新部署。

Pinmok 提供了统一的站点配置管理，让这些配置项可以直接在后台界面中修改，实时生效，不需要触碰代码。各模块的配置独立管理，互不干扰，但都集中在同一个地方，方便维护。 这个设计的目标很简单：让后台的行为真正可配置。配置权在开发者手里，使用权在用户手里，而管理的地方就在后台本身，触手可及。