repository governance

仓库与插件治理

目标

SandAdmin 是独立的后台框架宿主。任何用户都应能在不安装 SandWorkflow、SandAI、SandIAM 或其他业务插件的情况下，完成全新安装、数据库迁移、登录和基础后台使用。

Sand 平台插件按需提供，不能成为使用 SandAdmin 的成本或隐含依赖。

仓库模型

采用“统一目录、独立插件仓库”模型：sandadmin 的 server/ 与 sandadmin-artd/ 只包含宿主源码，根目录 catalog.json 保存插件目录。每个插件拥有独立源码仓库、版本和 Release，目录明确声明下载来源。具体契约见仓库插件分发。

普通使用者从仓库获取 server/、sandadmin-artd/ 和必要的根文件。公共文档在此 Wiki 维护；目录校验工具在独立维护仓库中维护。根目录 catalog.json 仍供插件管理器读取。

迁移期间以 sand_plugins 的已提交 revision 为拆分来源，本地未提交工作不得自动公开。每个插件完成历史拆分、独立 Release 校验和目录切换后，独立仓库成为唯一权威来源；sand_plugins 只保留迁移记录，不能继续并行发布。

每个插件是独立发布单元，拥有自己的版本、README、依赖、生命周期、权限、配置、验证记录和发布包。SandAdmin 的完整源码下载和发行版均不得包含业务插件源码或运行副本。

宿主边界

sandadmin 只拥有通用后台能力和插件契约，包括基础后台帐号认证与通用权限、系统配置、安装入口、运行时扩展机制及对外兼容矩阵。

宿主不得新增对某一具体插件的领域表、业务菜单、业务路由、业务权限、环境配置或服务实现的运行依赖。插件之间的依赖必须由插件元数据显式声明，并在安装阶段或运行时以可诊断、失败关闭的方式处理；不得让宿主因为缺少可选插件而无法工作。

需要另一插件作为前置条件的发布包，使用版本化的 sand_platform.required_plugins 清单。发布工件可携带校验和固定的依赖包；宿主先验证已有依赖的安装状态、最低兼容版本和运行入口，只有缺失时才安装随包工件。宿主不得下载未校验的网络包，也不得将某个具体业务插件硬编码为核心依赖。跨插件目录注册由依赖插件自己的公开端口完成；宿主不得直接写入对方领域表。

一个能力如果所有 SandAdmin 使用者都需要，并且不依赖插件的领域模型，才属于宿主核心；否则应作为插件实现。

上述自动依赖安装约定属于旧安装线。当前源码候选的 saipackage-pg-v1 正常入口仅沿用 上游包生命周期与 PostgreSQL 适配，会明确拒绝依赖旧扩展的包；消费者保留原锁定宿主， 待兼容验证后切换。范围见 SaiPackage PostgreSQL 适配。

源码、部署与验收

插件源码只存在于各自权威仓库；SandAdmin 的 catalog.json 只保存发布元数据，不保存源包。本源码工作树仍不得持久保存已安装的 server/plugin/sand-*、server/plugin/sandworkflow 或对应管理端业务插件运行副本。发布载荷、同步副本和真实安装验收材料只存在于插件仓库或消费工作区的演示、隔离宿主，每一份副本必须能追溯到插件权威来源、插件版本和锁定的 SandAdmin revision，禁止双向编辑。

已有目录的迁移、删除或权威来源切换必须作为独立任务：先确认实际运行副本、发布包和回滚路径，再进行变更。

真实插件验收在消费工作区拥有的独立 SandAdmin 验证宿主中完成，至少覆盖：

1. 零插件宿主安装与基础运行；
2. 插件安装后的加载、菜单、权限和一条核心业务路径；
3. 插件版本升级；
4. 插件卸载后的清理，以及宿主仍可正常运行。

SandAdmin 只发布版本和变更通知，不主动修改其他工作区。各消费工作区负责拉取明确的 tag、release candidate 或 commit，维护自己的宿主锁文件、覆盖层和验证记录；详细协议见宿主发布与消费同步。

发布记录

宿主维护 SandAdmin 与已发布插件的兼容矩阵。每个插件发布时至少记录：宿主版本范围、插件版本、依赖插件及版本范围、安装/升级/卸载验收环境和已知限制。

详细的插件目录结构、PostgreSQL 规则与发布前检查见插件开发与发布约定。