plugin development

插件开发与发布约定

本页适用于通过 SandAdmin 目录发现、从独立仓库发布的插件。无需独立市场平台的清单、打包和下载安装流程见仓库插件分发。具体业务约束由插件自己的 README 补充。

saipackage-pg-v1 普通安装沿用 SaiPackage 上游流程，数据库适配及旧记录切换见 SaiPackage PostgreSQL 适配。 下述 sand_platform.required_plugins 自动安装扩展属于旧安装线；新普通入口会明确拒绝 依赖该扩展的包。消费者须保留原锁定宿主，完成兼容验证后再切换。

必备交付物

每个可发布插件至少应包含：

• README.md：用途、非目标、宿主兼容范围、安装/升级/卸载、配置、权限、验证步骤和已知限制。
• 版本元数据与依赖声明，例如 info.ini、config.json。
• 对应的安装、升级、卸载生命周期实现和 PostgreSQL SQL。
• 后端与前端载荷的实际目录说明；若有宿主镜像副本，说明唯一权威来源与同步方式。
• 适用的许可证、来源与第三方署名文件，确保单独分发后仍可追溯。
• 独立公开源码仓库；Release、标签和 README 与目录声明的 repository 一致。

旧安装线曾通过 sand_platform.required_plugins 声明随包依赖与 SHA-256。该扩展不能作为当前普通入口的开发方式：当前入口会拒绝非空 sand_platform，也不能仅删字段绕过真实依赖。需要其他插件时，先在自己的版本 README 写清前置版本和公开调用契约，核实所选安装器能够处理的依赖方式；未完成兼容验证时保留原锁定宿主。

PostgreSQL 规则

• 新业务表使用 sand_<domain>_* 前缀，并使用 PostgreSQL 语法和类型。
• 不将 MySQL 方言、会话变量或原地迁移承诺混入 PostgreSQL 安装包。
• 安装、升级、卸载必须对应实际版本生命周期；卸载的影响和数据保留策略要在 README 中写明。

发布前检查

1. 版本号、README、发布说明和实际包内容一致。
2. 在干净 PostgreSQL 验证环境完成安装；升级和卸载按插件风险单独验证。
3. 验证菜单、权限、后端加载和至少一条核心业务路径。
4. 对比发布包与权威源码，确认未漏掉前端、SQL、文档或许可证文件。
5. 在插件 README 与宿主兼容矩阵中更新可支持的版本范围，并记录消费工作区验证宿主的 SandAdmin revision。

静态检查或构建通过不能替代真实宿主安装和业务路径验收。

宿主兼容声明

发布元数据的 host_min 是最低宿主版本，host_max 可选。默认保持最低版本及以后开放，不因只测过一个版本就把上下界写成同值。新版提高最低版本时，旧版上界须依据实际存在且兼容的宿主版本维护；不能把不兼容的新边界误包含进旧范围。实际验收环境和业务结果另外记录，不用兼容字段替代。

宿主提供身份、通用权限与运行扩展，业务插件拥有自己的表、菜单、权限、路由及生命周期；基础 Composer 包不作为 ZIP 业务插件发布。需要修改其他插件或基础包前，应先证明通用性或提供最小复现，由提供方审查归属，再实施有界修改。见架构和治理。