跳到主要内容

兼容性政策

从版本 1.0.0 起，Canopy 承诺在主要版本线内保持有文档记录的向后兼容性。本页是该承诺的契约：描述哪些内容保持稳定、哪些内容可能更改，以及弃用机制的工作方式，以便运营者无意外地规划升级。

该政策适用于 1.x。未来的 2.x 版本线可能会修订它；若如此，迁移指南将随 2.0.0 发行说明一并发布。

涵盖的内容​

数据库架构（Alembic 迁移）​

在 1.x 内：

  • 迁移是附加的或升级时向后兼容的。
  • 可随时添加新列。
  • 现有列不会在未经弃用周期的情况下被删除。
  • 现有列不会在未经弃用周期的情况下被重命名（重命名实现为添加新列 → 回填 → 弃用旧列 → 在下一主版本中删除）。
  • 类型更改限于扩展（例如 varchar(80) → varchar(255)）；收窄更改经过弃用。
  • 外键约束不会在未经弃用周期的情况下变得更严格（例如 ON DELETE SET NULL 变为 ON DELETE CASCADE）。

运营者可以放心地向前滚动；后端启动时的自动迁移可安全地在生产数据上运行。

内置元模型​

在 1.x 内，backend/app/services/seed.py 中附带的元模型是稳定的：

  • 内置卡片类型键（Application、Initiative、BusinessCapability 等）不会被重命名或删除。
  • 这些类型上的内置字段键不会在未经弃用周期的情况下被删除。
  • 内置关系类型键不会在未经弃用周期的情况下被重命名或删除。
  • 随内置类型附带的默认子类型是稳定的。

运营者自己的定制内容（通过管理界面添加的自定义卡片类型、自定义字段、自定义关系类型）归运营者所有，不在本政策涵盖范围内。

REST API（/api/v1/）​

在 1.x 内：

  • /api/v1/ 下的端点不会在未经弃用周期的情况下被删除。
  • 现有请求和响应字段名称不会在未经弃用周期的情况下被重命名。
  • 字段类型不会发生不兼容的更改（例如字符串 → 数组）。
  • 新的可选请求字段和新的响应字段是非破坏性的，可以在任何次要版本中发布。
  • 新端点是非破坏性的，可以在任何次要版本中发布。
  • 身份验证语义（Bearer JWT、/auth/login 有效载荷形状）是稳定的。
  • HTTP 状态码语义对于已文档化的成功和错误路径是稳定的。

超出文档化范围的行为（未文档化的标头、内部错误消息文本、未指定 sort_by 时的排序）不在涵盖范围内。

权限键​

backend/app/core/permissions.py 中定义的权限键在 1.x 内是稳定的。可以添加新键；现有键不会在未经弃用周期的情况下被重命名或删除。

默认授予预置角色（admin、bpm_admin、member、viewer）的权限集可能在次要版本间更改，并在 CHANGELOG 中注明。在其部署中自定义了角色权限的运营者不受影响。

配置（环境变量）​

CLAUDE.md 和 README.md 中文档化的现有环境变量在 1.x 内是稳定的。可以添加具有合理默认值的新变量。当更改与运营者相关时（例如新的默认端口），默认值可能会随 CHANGELOG 注明而更改。

静态加密密钥​

backend/app/core/encryption.py 中的 enc: 前缀标记和 Fernet 派生密钥在 1.x 内是稳定的。运营者无需在次要版本升级期间重新加密密钥。

弃用周期​

当本政策涵盖的内容需要被删除时：

  1. 在次要版本 N 中标记为已弃用。 CHANGELOG 条目包含一个 Deprecated 节，指出该更改。对于 API 端点，已弃用的路由会发出 Deprecation: true 响应标头（RFC 8594）和一个 Sunset 标头，指示最早的删除目标。
  2. 在次要版本 N+1 中继续支持。 删除不能与弃用在同一次要版本中进行。已弃用的形式继续有效。
  3. 最早在次要版本 N+2 或 2.0 中删除（以先到者为准）。删除时 CHANGELOG 中有 Removed 节和迁移说明。

对于数据形状更改（Alembic 迁移），适用相同的 N → N+1 节奏，表达为添加新项 → 回填 → 删除旧项。

不涵盖的内容​

这些内容明确超出范围，可能随时更改：

  • backend/app/ 下的内部 Python 模块布局。app.models、app.services 等的导入不是公共 API 的一部分。依赖内部导入的插件或脚本应固定特定的 Canopy 版本。
  • 存储在内置表（fields_schema、section_config、attributes、lifecycle）上的 JSONB 数据块的结构，超出已文档化的 REST API 读取范围。磁盘上的 JSON 形状可能会演进以支持新功能。
  • 前端内部：frontend/src/ 中组件的文件路径、组件的 prop 签名、frontend/src/types/index.ts 的内容以及 MUI 组件的样式。使用捆绑前端的运营者是被隔离的；从源代码树嵌入组件的人需自行承担风险。
  • 运营者引入的元模型定制内容。 如果您通过管理界面添加自定义卡片类型或字段，当您更改它时，迁移故事由您负责。
  • 演示和种子数据（SEED_DEMO=true）。演示数据集允许在版本间自由演进。
  • 捆绑的第三方服务：DrawIO 版本、Ollama 捆绑镜像、嵌入的 swagger-ui-dist 版本。这些可以随时升级。
  • 使用非默认配置的行为，这些配置在 CHANGELOG 条目中被明确标记为实验性的。

1.0.0 实际更改了什么​

与 0.x 系列相比，1.0.0 本身不是功能版本——它是上述承诺开始适用的时间点。1.0.0 中发布的代码与 0.71.0 中发布的代码相同，加上 1.0.0 CHANGELOG 条目中记录的供应链强化和贡献者流程变更。

1.0 之前的版本不在本政策涵盖范围内。0.x 版本之间的迁移可能并确实包括架构删除、重命名和破坏性元模型更改。从 1.0.0 起，这些更改需经过弃用周期。