SandWorkflow Development

开发、PostgreSQL 约束与发布包

面向维护者。权威源码为 sand-plugins 仓库的 sandworkflow/；历史插件目录和 demo 安装副本都不是第二份开发源。

源码与运行宿主

目录	用途
sandworkflow/plugin/sandworkflow/	后端、配置及生命周期副本。
sandworkflow/sandadmin-artd/src/views/plugin/sandworkflow/	管理端源载荷。
sandworkflow/install.sql、update.sql、uninstall.sql	根部生命周期 SQL，须与后端同名副本一致。
/Users/code/project/sand_demo	独立演示与验收宿主；只接收受控导出。

本仓不含可运行宿主。demo 服务端在其 server/ 子目录，通用 /Users/code/project/sandadmin 用于零插件基线。正式验收须冻结 clean 宿主版本与包 revision。

macOS 的 zsh，在 sand-plugins 仓库根目录，可只读查看导出差异：

zsh scripts/sync-plugin-to-demo.sh sandworkflow --dry-run

写入 demo 的 --apply、服务重载、数据库生命周期和发布属于另行授权的操作，本轮不执行。

PostgreSQL 契约

仅支持 PostgreSQL，连接名 pgsql。新表以 sand_workflow_ 开头；定义和分组等配置表使用整型 identity，实例、任务、处理人和日志等运行表使用 21 字符 NanoID。JSON 使用 jsonb；收件人查询使用 JSONB 包含匹配。不要新增 sa_* 业务表或引入 MySQL 方言。

安装会创建七张表并删除同名旧表；不能拿安装 SQL 在有数据环境做重试。升级通过 Install::update() 执行当前 SQL 和标识迁移；卸载删除工作流表及菜单关系。MySQL 原地迁移及任意历史 sa_workflow_* 转换不在当前包的通用契约内。

更新上游安装结构时，转换工具的参考调用为：

php tools/convert-install-sql.php /path/to/upstream/install.sql

输入必须来自已核对版本的上游 SQL，命令会再生成插件安装 SQL，属于源码写入。该转换工具并非当前 NanoID 运行结构的完整重建入口；生成结果必须与当前模型、运行标识和菜单逐项审阅，不能直接当作 1.0.7 安装基线。还须保持两份生命周期文件一致；它不是运行数据库迁移的命令。本轮未执行转换。

包检查与构建入口

在 sandworkflow/ 中运行 bash tools/check-package-integrity.sh，核对根部和后端版本、三份 SQL、运行版本、许可证及 NOTICE。它不证明构建、安装或业务验收通过。

仓库的通用构建器为 sand-package/server/scripts/build-plugin-package.php，参数顺序为源码目录、已存在可写的输出目录、Release tag、host_min 和可选 host_max。运行需要带有相应 SandPackage 类与 Composer 自动加载依赖的 PHP 环境；不能只凭本仓有脚本就承诺当前机器可直接构建。

维护者应从计划发布版本和已核实宿主范围取得 tag 与兼容值，不猜 tag 或上界。先检查实际构建器依赖和发布规范，再执行构建并检查 ZIP 文件、大小、元数据和校验和。本轮未运行该构建器，也未确认可公开安装的 1.0.7 资产。

发布包必须包含 info.ini、config.json、三份生命周期 SQL、README、后端和前端载荷、完整 LICENSE 与 NOTICE。Wiki 不替代包内法定声明，不删除既有构建要求的文件。

来源与许可证

流程设计器基于 zhangjinlibra/workflow-web，当前衍生发行包适用 GNU Affero General Public License version 3。以源码包内 LICENSE 全文和 NOTICE 的来源、修改范围为准，保留继承的归属和第三方声明。本插件不被描述为上游官方发行，也不授予上游商标权。

详细实现和历史证据继续保留在源码现有文档中；面向使用者的当前指南以本 Wiki 为入口。