Breaking Changes

oak-domain 6.0.1 未发布：生产依赖实体必须能从声明和值合并解析

依赖实体解析已经支持 .d.ts + .js 合并，不再要求第三方包发布 src。生产包应发布 es/entities/*.d.ts、es/entities/*.js，以及这些声明依赖到的必要类型声明。

解析顺序是 es/entities -> lib/entities -> src/entities。lib/entities 只是历史兼容回退，未来包可以只保留 es。

oak-domain 6.0.1 未发布：同名实体覆盖必须兼容旧结构

依赖包如果重新定义了默认实体，例如 User、UserEntityGrant、System，编译器会用新实体覆盖已有定义。

覆盖实体必须兼容旧实体的字段、动作、状态、关系、索引、ActionDef、entityDesc.locales 和 style，否则旧逻辑会在权限、checker、trigger、类型生成或 UI 展示中出现不可预测问题。

oak-domain 6.0.1 未发布：Decimal / Price 字段改为字符串精度语义

Decimal<P, S> 和 Price 现在按字符串保存和传递精度，过滤类型也补充了 Q_DecimalValue。业务代码里直接做 +、-、*、/ 或把 decimal 字段传给只接受 number 的格式化函数，可能出现字符串拼接、精度丢失或类型错误。

升级时应把 decimal / price 的计算改成 decimal helper 或显式转换；写入、过滤和 update expression 使用字符串值或 $expr 包装。

oak-domain 6.0.0：编译器输出和依赖初始化规则调整

6.0.0 重构了 schema、dependency、locale、router、tsc 等编译链路，并把依赖包 feature/init metadata 作为发布包元数据处理。

旧项目如果依赖本地 src 或手写初始化拼接，需要按 project:init、make:domain、make:dep 的顺序重新生成，并检查 feature 初始化入口。

oak-db 4.0.2 未发布：migration 不再默认生成物理外键

schema migration 已移除新建表物理外键 SQL，并兼容历史 MySQL 库里从未实际建过外键的情况。

如果项目以前依赖数据库层外键兜底一致性，需要把约束迁移到 Oak 层：checker 做写入前校验，trigger 做级联处理，migration plan 审核结构变化，引用字段和索引负责查询性能。

同一版本里，index.config.unique 也不再生成数据库 UNIQUE INDEX。它现在只表达 Oak 框架层语义，历史唯一索引可能在迁移收敛时被重建为普通索引。需要强唯一约束的业务必须补 Oak checker 或专门的数据库迁移。

oak-cli 5.0.5：依赖实体、render/XML/Less、Desktop 和小程序路由语义收紧

make:domain 的第三方实体解析顺序和 oak-domain 对齐为 es/entities -> lib/entities -> src/entities。发布包缺少 es/entities 产物时，生产项目不应靠发布 src 补洞。

Oak 包的编译 transform 改为优先读取 package.json 中的 oak.compiler.transform，业务模块和 feature 初始化也应迁移到 oak.business.*。旧项目如果长期依赖 extraOakModules 或旧 metadata 字段，需要把共享包元数据补齐，避免不同项目重复维护硬编码转换列表。

Vite Web 不再默认 external React、ReactDOM、FingerprintJS、BN，也不会隐式注入 CDN。需要 CDN 的项目必须在 oak.config.ts 显式配置内置 CDN 插件；没有配置时这些依赖会进入 bundle。

小程序构建引入 route map 静态改写，Oak navigator 继续以 canonical route 为准。历史代码里手写生成产物路径、混用 namespace 路径和业务路由的地方，需要改回框架路由入口。

页面、组件和 namespace 的 index.config.ts 会驱动 web router、namespace config 和小程序虚拟 JSON 输出。升级时不要继续手工改 allRouters.ts、allNamespaceConfigs.ts 或生成后的页面 JSON，这些文件会在下一次构建中被覆盖。

当前应用模板的 build:es 默认启用 --enable-xml-check --emit-injection-types --check-style-less。传统 TSX render 的 props 由编译器从 index.ts 推导；小程序 XML 与 Less Module 也进入正式检查。升级后出现的未声明 property、错误事件、缺失 class、嵌套样式作用域或 portal 可达性错误，应回到组件 properties/formData/methods 与真实样式结构修复，不能继续用手写 WebComponentProps、空规则或宽泛类型绕过。

Desktop 工作区现在覆盖 Tauri 与 Electron，并区分 web platform 和 renderer。应用识别继续使用 web application type，再通过 runtime/renderer metadata 区分桌面壳；不要新增一个自定义 desktop application type 来绕过当前解析合同。

新应用默认只创建 Web workspace。旧脚本或教程如果假定新项目必然存在 wechatMp、native，应改为先执行 oak-cli add mp|rn|desktop。小程序 Node polyfill 也不再默认带入完整 crypto / assert 链；项目显式恢复后必须重新检查主包体积和真机启动。

oak-backend-base 5.0.1 未发布：connector-backed free endpoint 上下文语义变化

普通 free endpoint 仍然使用 makeContext(undefined, headers)，不会自动继承调用方 application、token、user 或 rootMode。

声明 useConnector: true 的 free endpoint 会把 connector 解析出的 oak-cxt 传给 contextBuilder；如果请求没有 oak-cxt，现在会用 {} 初始化上下文，而不是走 undefined 初始化路径。依赖 initialize(undefined) 开 root 或匿名默认状态的旧 SSE / free endpoint，需要复核是否应该继续使用 useConnector。

同一版本里，start / stop routine 可以动态注册和注销 trigger、checker、watcher、timer。动态注册名仍必须唯一，升级时应检查自定义 routine 是否可能重复注册或忘记在 stop routine 中注销。

oak-frontend-base 6.0.4 未发布：web 初始化、route access 和小程序路由进入运行时边界

Web 初始化现在可以接收 options object，并在标准树中统一挂载 RouteAccessProvider、NamespaceConfigProvider、AntD / AntD Mobile provider 和 Oak theme shell。升级时应把 CLI 生成的 namespaceConfigs、oakTheme、renderLoading、AntD provider props 等放进 initialize(...) options，避免应用侧再包一层全局 provider 导致配置或上下文分裂。

route.access.operation 的 checker 范围字段是 target.checkerTypes，不是旧文档里出现过的 paths。依赖 console 上下文的规则使用 $context.entity / $context.entityId 时，如果当前 namespace 的 features.console.contextEntities 不允许该上下文，会返回 contextMismatch，菜单可见性和页面渲染都应按同一范围判断。

小程序 route map、subpackage route mapping、namespace route 语义和 tabBar 判断进入运行时。显式 route map 存在时，缺失路由不再自动猜测 /pages.../index；switchTab 会丢弃 query / state 并输出 warning。直接调用裸 wx.*、手写生成产物路径、或混用 namespace path 与业务 canonical route 的旧代码需要复核。

pageHeader2 已移除，继续导入它会构建失败；改用 @oak-frontend-base/components/pageHeader。ListPro 仍使用 Oak 自有 Pagination，并断言不接受 tablePagination；共享分页布局和文案调整应改 components/pagination。

cache.callSSEEndpoint(...) 只在 connector-backed 运行时可用，默认会带当前前端上下文，ignoreContext: true 才不传；DebugConnector.callSSEEndpoint() 仍会抛出不可用错误。本地 debug 场景不要假设它能模拟 SSE endpoint。

Oak 自有组件主题现在走 oakTheme / features.theme / --oak-* CSS 变量。AntD / AntD Mobile provider props 是三方 UI 库配置入口，不应继续用 AntD Mobile 的 adm cssVar 前缀当 Oak 主题契约。

oak-general-business 6.1.0 与 oak-pay-business 4.1.0 未发布：系统翻译和支付系统扩展会影响覆盖实体

通用业务包新增系统翻译、区域 locale、LocalizedContent 等能力；支付业务包扩展了 Waffo、Stripe、Epay、Creem、PayPal 等支付渠道，并适配 general-system。

如果业务项目覆盖 System、支付配置、支付产品或相关 action/state，必须保留旧结构兼容，尤其是系统翻译 action alias 和支付状态回滚语义。

oak-pay-business 4.1.0 会把支付、退款、账户、提现、结算、系统账户流水等金额列扩成 decimal(32,10)，运行时代码也迁到 decimal 字符串 / helper 语义。旧业务代码如果继续把金额当 JS number 做加减乘除、比较或格式化，可能出现精度丢失、字符串拼接或类型错误。

当前支付包虽然提供多渠道 endpoint 文件，但 src/endpoints/index.ts 默认为空。升级项目必须在自己的 endpoint 索引中显式选择微信、支付宝、Epay、Stripe、Creem、Waffo、PayPal 等实际启用渠道；不能再依赖安装支付包后自动暴露回调路由。

4.1.0 的升级 SQL 分为新渠道表和金额列迁移：upgrade/4.1.0/accounts.sql 创建 Waffo、Stripe、Epay、Creem、PayPal 相关账号 / 产品 / 支付表，并手写物理外键；upgrade/4.1.0/priceDecimal.sql 修改历史金额列。生产库升级前需要确认执行顺序、历史金额单位、精度和项目自己的外键策略。

自定义支付渠道通过 registerPayClazz(...) 注册时会校验 product/account schema。账号实体必须提供 decimal price、decimal 费率字段、systemId、提现转账开关等字段；产品实体必须关联 application 并提供启用、税费、退款和收款配置字段。旧的自定义渠道如果只满足运行时类接口，升级后可能在注册阶段直接 assert。

Redirect 类支付只在 web 平台按当前 application 和 pay.meta URL 判定可用。Epay、Stripe、Creem、Waffo、PayPal 接入项目需要复核支付成功 / 取消 URL、notify URL、webhook secret、沙箱配置和前端 application 选择逻辑。

oak-general-business 6.1.0 的 System 需要 translation、translateState、translationError，以及 translate / translateSuccess / translateFail 动作。共享 components/system/panel 会投影翻译字段并挂载翻译页签；应用侧如果覆盖了 System 却没有同步这些字段，系统面板、翻译 trigger 和翻译定时任务都会出错。

6.1.0 的升级 SQL 会创建 localizedContent、areaLocale、userAuth、invite、inviteTouch、inviteRelation，并从 user 表删除旧的 nationality、idCardType、idNumber、idState 字段。已有实名认证数据不能只靠 schema upgrade 保留，升级前需要写清楚历史数据迁移和回滚策略。

旧的 @oak-general-business/components/user/authenticate 已移除，实名认证入口迁到 @oak-general-business/components/userAuth/upsert/index 和 userAuth 实体。消费项目里本地 /user/auth、/my/auth 或类似 wrapper page 需要同步改路径、节点实体和投影。

HumanVerify 如果配置为 enforce，账号登录、登录名注册、手机验证码、邮箱验证码会拒绝缺少 proof 或校验失败的请求。应用侧必须注册前端 provider bundle / acquire component，确认 oak-humanVerifyHost 被全局组件机制挂载，并保证后端 provider 配置可用；否则升级后登录和验证码链路可能被主动拦截。

registerUserByLoginName 现在注册成功后会直接创建 token 并进入登录态。旧代码如果依赖“注册后仍未登录”的流程，需要调整成功页跳转、token 状态和邀请归因清理逻辑。

通用业务包的主题能力已经迁到 oak-frontend-base。继续从 oak-general-business/features/theme、oak-general-business/types/Theme 或旧主题设置组件引入会失败；应用应改用 oak-frontend-base 的 features.theme、oakTheme、CSS 变量和主题设置组件。

多包同步：React/TypeScript/peer 版本需要整体升级

近期多个包同步了 React 19、TS6 参数、peer 依赖和 toolkit 替换 lodash。项目应按实际依赖整体对齐，否则可能出现类型通过但运行时依赖不一致的问题。

oak-common-aspect 4.0.3 把 oak-domain、oak-external-sdk 从普通依赖迁到 peer 依赖。消费项目或中间包如果以前靠 oak-common-aspect 间接带入这两个 Oak 包，升级后需要显式安装并对齐版本，否则 aspect 入口在构建或运行时可能解析失败。

oak-memory-tree-store 当前未发布变更同样把 oak-domain 迁到 peer 依赖，并把 lodash 工具入口切到 @oak-domain/utils/toolkit。消费项目需要显式安装 oak-domain ^6.0.1，自定义测试如果依赖事务节点上的 $txnId、$next、$path 等调试字段，也要按事务结束后字面量属性被 delete 清理的语义复核。

oak-external-sdk 3.0.2 顶层入口仍导出 SDK 单例，但 instance class 改为 type-only 导出；运行时代码如果从顶层解构 WechatMpInstance、WechatPublicInstance 等构造类会失效。WeChat externalRefreshFn 也从返回 token 字符串改为返回 { access_token, expires_in }，自定义 token 刷新实现必须同步调整。

oak-internal-sdk 1.1.5 新增加密 SSE endpoint 支持，前端 callSSEEndpoint 和服务端 serializeSSEEndpointResult 需要配套升级。只升级一端时，SSE data: 可能被错误地当作普通 JSON 或加密 JSON 解析；自定义网关和 CORS 也要放行 oak-encrypted、oak-nonce 等响应头。