@bygghammar / cms-platform

共享CMS平台代码的每个网站在这个工作空间(Voyara， barskola和 未来的网站)。 代码只 -没有内容，没有数据，没有秘密，没有主题。

这里住着什么？

• src/blocks/types.ts -块道具类型和块道具的JSON契约
• src/blocks/icons.ts -图标集块可以参考
• src/blocks/block-props-context.tsx -块道具管道内联编辑
• src/i18n/* 本地化核心（locale, types, resolver, context）
• src/backup/* -存档/媒体安全，浏览器端大型媒体导出和 与提供者无关的验证帮助程序
• src/trips/* -可重用的旅行数据合同、编辑器和遗留课程数据 兼容性。每个主机提供自己的术语(课程，巡航或 旅行)。
• src/navigation/* -公共和后台导航合同加上共享 活动状态的帮手。菜单内容和可视标题保留在每个站点上。
• src/theme.css -设计代币合约+中立启动主题

开始一个新站点

docs/NEW-SITE.md 是支持的启动器路径：install， assert合同， 应用规范模式 bunx cms-platform-migrations、进口 theme.css，注册主机组件/平台数据/翻译，封装 服务器内核和挂载共享的后台视图。

编辑锁

docs/EDIT-LOCKS.md 是什么使一台主机连接两个管理员不能 相互覆盖：运行迁移，通过公开一个服务器端点 editLockActionCore,山 EditLockProvider 与 createEditLockApi, 向前 editSessionId 为救球干杯。在此之前，每个屏幕都是正常的 就像锁出现之前一样。

功能指南

服务器变量

除了现有的提供程序秘密之外，谷歌Sheets的交付也可以读取 GOOGLE_SERVICE_ACCOUNT_JSON，或者 GOOGLE_SERVICE_ACCOUNT_EMAIL 加上 GOOGLE_SERVICE_ACCOUNT_PRIVATE_KEY． 这三个都是服务器专用的；没有谷歌 在浏览器中从未读取过相关的内容，字体选择器不需要API键。看到 docs/GOOGLE-SHEETS.md.

兼容性策略

• CHANGELOG.md 记录每次发布；升级前请阅读。

• pre - 1.0 小 发布可能会破坏共享视图、适配器或核心；补丁 版本总是兼容的。

• PLATFORM_CONTRACT_VERSION （platform/contract)在共享时被撞 屏幕启动需要旧站点所缺乏的模式或适配器功能。 网站将其固定在测试中。它是 v3：页面保存，发布，垃圾和 恢复通过数据库函数（v2），一个版本记录了五个 它过去用一句话断言的事实——迁移应用，模式 能力，发布扫描，决策应用，路由激活，共五项 分开的记录，后者拒绝在没有前者的情况下写入 (v3)。直接从上一个pre-v2发布的软件包升级， 0.90.0-m7.12，意味着应用所有五个新的规范化迁移，在 时间顺序排列:

  1. 20260904090000_c54603f8-a155-40f8-a86c-54434aa5c0ae.sql
  2. 20260904140000_9f2a7c41-06d5-4d6b-8b4e-1c7a5d3e9b20.sql
  3. 20260904160000_0d565000-2839-4738-aacc-537d7090398f.sql
  4. 20260905120000_da2db0b2-6048-4aa8-8e4f-13ee33e9cc24.sql
  5. 20261030120000_46a4febc-227e-42ec-bbe3-a0ae9c97feaa.sql

  文件2和文件3是建立合约v2发布的一对文件 行为，但第一个也是规范模式，所以只应用这对 仍 missingMigrations 和 compareSchema 报告漂移。文件4 添加合同v3：发布分类账、评审模型、路由声明，一个 锁顺序每个页的突变遵循，和复制作为一个单一 事务。它取代了签名处的五个发布功能机构 他们已经有了，没有改变任何一个人的决定，所以没有a 参观者看到了今天的变化。文件5属于无合同版本：它给出 block_templates 它自己的时间戳触发器代替触发它的页面 被创建，它分配了一个 updated_by 表中没有的列 每次更新模板都失败了。 在部署v3包之前应用它们，然后分别进行验证： missingMigrations(applied) 报告没有丢失， 和 assertPlatformContract(3) 传球。第二种方法只比较版本号 在网站本身的代码中，从不读取数据库，所以它是不可替代的 首先。 docs/NEW-SITE.md 给出完整的命令。

• migrations/ 仅为模式。网站内容，SEO副本和种子永远不属于 在那里。

什么东西绝对不能住在这里

• 特定站点使用的颜色、字体或间距值(参见 theme.css）
• 页面内容，SEO文案，媒体，CMS页面JSON
• Supabase生成的类型、认证用户、秘密、API密钥
• 路由文件和每个站点部署配置
• 实际的导航链接、公共页签、品牌特定的标题或菜单样式
• 站点表列表，导入顺序，数据库客户端，身份验证和RLS 政策;每个主机向共享备份核心提供这些适配器

备份的核心

该包拥有cms范围的、与提供商无关的备份和恢复部分：

• 媒体签名/路径验证和秘密清理
• 将大型媒体文件流式传输到经过身份验证的浏览器中的存档中
• 存档进度和清单合同
• 行计数、用户/角色和媒体验证助手

浏览器媒体导出程序接受仅带有的主机存储适配器 list() 和 download() 方法加上主机期望的存档格式/模式 版本。将动态导入保存在文件后面 import.meta.env.SSR SSR守卫 应用程序，因此仅浏览器的邮政编码无法进入优化的服务器 块图。

在停止导出之前，将重试单个媒体下载。公共 介质桶适配器也应该回退到对象的公共URL 经过身份验证的存储下载失败，因此一个临时大文件请求 不能丢弃其他有效的存档。

消费站点仍然负责其数据集组、表导入 订单，Supabase客户端，超级管理员授权，HTTP路由，审计记录 以及数据库迁移。该包从不包含站点数据或凭据。

一个网站连接

翻译数据是每个站点的内容，因此每个站点一次注册自己的地图 在启动时:

import { registerTranslations } from "@bygghammar/cms-platform/i18n";
registerTranslations({ generated: TRANSLATIONS, overrides: TRANSLATION_OVERRIDES });

主机组件必须参与应用程序实际使用的值。 不要只依靠 import "./register-host" 因为优化的构建可能会 删除该模块时，应用程序的 package.json 声明 "sideEffects": false.

import { initializeHostComponents, type HostComponents } from "@bygghammar/cms-platform/host";

const HOST_COMPONENTS = {
  FocalImage,
  LazyVideo,
  FocusPicker,
  RichTextEditor,
  mediaLibraryQueryOptions,
  useMediaUpload,
} satisfies Partial<HostComponents>;

export const BLOCK_REGISTRY = initializeHostComponents(HOST_COMPONENTS, () =>
  createBlockRegistry(),
);

将现有的注册模块保留在消费应用程序的注册模块中 sideEffects Allowlist作为深度防御，直到每个入口点都使用 明确的合同。CSS也必须留在allowlist中。

存储库、开发和发布

真理的权威来源是 https://github.com/byggis79/cms-platform (私人)。这个存储库是独立的——它不再是目录中的目录 站点存储库，并且永远不能将其复制回消费站点。

bun install
bun run check   # typecheck + tests + package verification

该包附带TypeScript源文件；没有构建输出。每一个变化 通过拉取请求，每次释放都是通过推 vX.Y.Z 匹配的标签 package.json． 标签运行 .github/workflows/publish.yml，它使用 信任 出版GitHub生成一个短期的OIDC令牌，作用域为单个 工作流运行后，NPM通过包的属性来交换发布权限 可信发布服务器配置。没有长期的npm证书参与-没有 NPM_TOKEN,没有 NODE_AUTH_TOKEN，没有OTP。 RELEASING.md 是 工作流检查和NPM设置必须匹配的内容。从来没有发布 手动。

看到 CONTRIBUTING.md 获取完整的工作流程和变更日志 约定。用户安装一个明确的发布版本，例如 @bygghammar/[email protected].