openxiangda-skill-kit 2.0.0-alpha.27 → 2.0.0-alpha.28

package/docs/architecture/frontend-runtime-mount-v2.md

@@ -0,0 +1,82 @@
+# OpenXiangda 2.0 前端运行时挂载路径
+
+状态：2026-08-16 已实现待发布，当前发布阻断项。
+
+## 问题证据
+
+同一个 Native 2.0 前端制品会先挂载在
+`/service/openxiangda-apps/{appCode}/preproduction/`，通过验收后再原样挂载到
+`/view/{appCode}/`。平台已经在返回的 `index.html` 中注入 `<base>` 和
+`openxiangda-runtime-base`，但官方 Umi 模板仍以 `basename=/` 创建 browser
+history。应用加载后，根路由重定向会把预发地址改写成域名根目录；静态资源已经加载，
+但后续路由、刷新和身份初始化不再处于该应用的环境挂载路径。
+
+这不是单个参考应用的页面错误，而是官方模板与平台动态挂载契约不闭合。把模板改为
+hash history 可以规避跳转，但会降低正式地址质量，也会把已有 browser route、标签页和
+深链接语义全部改成另一套协议，因此不采用。
+
+## 能力归属
+
+- Platform Server 是环境、活动前端修订和运行时挂载路径的唯一所有者。
+- Platform Server 通过受控的 `index.html` 装饰写入
+  `meta[name="openxiangda-runtime-base"]`；应用、CLI 和 AI 不自行拼接环境 URL。
+- `openxiangda-admin` 是 Umi/React Admin 的平台适配层，唯一负责把平台挂载路径转换为
+  Umi runtime `basename`。
+- 应用只在 `src/app.ts` 注册官方适配函数，不复制解析、校验或环境判断逻辑。
+
+## 决策
+
+1. 继续使用 Umi browser history，不改为 hash history。
+2. `openxiangda-admin` 提供纯函数读取并校验平台注入的 runtime base，再提供 Umi
+   `modifyContextOpts` 适配函数。
+3. 官方模板在 `src/app.ts` 注册该适配函数；开发者页面和业务路由仍只使用以 `/` 开头的
+   应用内路径。
+4. 本地开发没有 runtime meta 时稳定回退到 `/`。
+5. runtime base 必须是同源绝对路径，不接受协议、host、query、fragment、反斜杠、控制字符
+   或超长输入。无效输入关闭到 `/`，不导航到外部 origin。
+6. 前端制品、AppPackage 和 AppVersion 不包含环境专用 base；预发到正式晋级仍复用完全相同
+   的制品摘要。
+
+## 稳定不变量与契约
+
+- 环境挂载路径只由当前 HTTP 响应中的平台 meta 决定，不由 localStorage、构建变量、角色、
+  URL query 或应用业务数据决定。
+- Umi 的路由定义、`useNavigate('/path')`、Admin 菜单路径和标签页路径始终是应用内路径；
+  SDK 只在 history/router 边界加一次 basename。
+- `/service` Data API、App API、OAuth2 和身份端点仍是平台同源绝对服务路径，不拼入前端
+  basename。
+- 深链接和刷新必须回到同一环境的前端修订；预发路由不得落入 production，production
+  路由不得落入预发。
+- 该契约只作用于 Native 2.0 前端，不修改 1.x View、流程或自动化路由。
+
+## 失败、并发与安全边界
+
+- runtime base 在 React/Umi 创建 history 前同步解析，不产生异步竞争或第二份状态。
+- 多标签、多角色切换和环境同时存在时，每个 HTML 文档只消费自己的 meta；标签之间不共享
+  mutable basename。
+- 平台漏注入或输入非法时回退 `/`，页面可以显示确定性诊断；SDK 不猜测 appCode 或环境。
+- 解析最长接受 2048 字符，只允许以单个 `/` 开头的 pathname，并规范为尾部 `/`。
+- 适配函数不读取 Cookie、token、用户资料或业务数据，不扩大身份和授权边界。
+
+## 资源与性能边界
+
+该方案只增加一次同步 meta 查询和 pathname 校验，不增加请求、缓存、数据库状态或运行实例。
+前端仍只产出一份可复用制品，不为预发和正式重复构建。
+
+## 回滚边界
+
+- SDK helper、官方模板注册和文档属于一个独立发布主题，可通过回退对应
+  `openxiangda-admin` 与 `create-openxiangda` 版本撤销。
+- 平台现有 `<base>`/meta 注入保持兼容，不需要数据库迁移或 Platform Server 发布。
+- 已生成的 2.0 测试应用可显式采用 helper；不自动改写 1.x 或其他历史应用。
+
+## 可证伪验收
+
+1. 纯函数对预发和正式 base 返回规范 pathname，对外部 URL、query、fragment、控制字符和
+   超长输入回退 `/`。
+2. 官方模板继续声明 browser history，并注册 SDK 的 Umi runtime context 适配器。
+3. 生产构建在注入预发 meta 后访问应用根路径，浏览器 URL 保持在预发挂载路径；导航、回退、
+   深链接刷新均不离开该前缀。
+4. 同一前端 artifact 晋升 production 后，在 `/view/{appCode}/` 下通过相同场景。
+5. 两个环境的身份请求分别携带正确环境语义，控制台没有未处理异常、资源 404 或无效 JSON。
+6. 全量 2.0 release gate、仓库外参考应用构建与线上 preproduction→production 验收通过。

package/docs/architecture/implementation-roadmap.md

@@ -32,6 +32,7 @@
 | 环境配置内核 E0-E6 | AppVersion/component revision + native Runtime Environment + minimal Environment Head + 环境运行态 | E1-C0/C1/S0/S1/T0 已完成 | breaking config/contracts v3、平台纯编译器、六领域不可变投影、聚合投影、AppVersion binding、compile receipt、精确 artifact shadow prepare 与真实 PostgreSQL 并发/来源防伪/绑定后不可变已经通过；全新 `openxiangda-v2-native-reference-app` 由候选 tarball 创建并完成 check/test/build，连续构建逐字节一致，config/contract v3 闭包和 artifact/manifest 篡改拒绝已进入发布门禁 | 下一步进入 A0 Native 环境授权；随后实现 Data physical/logical、最小 Head CAS、pending credential、调用委托/网关断言、runtime lease、候选 GC 与 generation cutover。旧 alpha 只留审计历史，不做双读、双写或导入 |
 | 授权内核 A0-N/C/P | 不可变 authz revision + 环境 authz state + native role/scope 表 | 已确认实施；N0/N1/N2/C1/C2/P 完成 | N1/C1 建立不可变定义、两环境 state 与原子版本；N2 建立独立 Native 运行表与局部撤权；C2 建立 DB-authoritative evaluator、request cache、环境/版本 cache namespace、边界 TTL 与 RelationshipGrant 直读；P 升级 `native-2` 配置契约并建立 source definition、projection state/job/receipt/value/closure/effective grant、Data API 与 membership 原子失效、冷启动恢复与 strict gate；89 个 SQL migration 校验、35 个 2.0 migration 真实 PostgreSQL 幂等应用、39 个平台套件 / 263 项测试和工具链全 workspace 测试通过 | 当前推进 N3-N5。alpha membership/grant 不复制、不迁移，禁止给 legacy 表补 environmentKey 或建立长期双读/双写 |
 | Ant Design Pro v6 Admin 全量切换 | Ant Design Pro v6 承担通用 Admin；`openxiangda-admin` 承担平台集成 | 已实现待发布 | Vite/旧自研 Shell 与仪器示例已从模板删除；React 19、Ant Design 6、Umi Max 4、ProComponents 3、utoopack、ProLayout、ProTable、ProForm、Field Kit 和企业采购参考应用已落地。桌面 Chromium 单链路通过工作台、菜单、会话标签、稳定角色切换、列表/详情、独立供应商表单、工作中心、单按钮流程提交和个人中心，并断言无运行时错误；production build 通过 420KB gzip/1.5MB raw 异步块与 1.5MB 首屏门禁 | 补 Changesets、`verify:affected` 和正式包发布；随后以已发布 tarball 创建仓库外新应用并完成 preproduction→production 在线验收。移动用户端 Field Kit 已有独立 renderer，完整移动页面模板与设备 Chromium 验收另列下一阶段 |
+| 前端动态挂载路径 | Platform Server 注入 runtime base；`openxiangda-admin` 适配 Umi basename | 已实现待发布 | 线上预发证实 browser history 错误离开环境前缀；SDK 已实现有界同源 pathname 校验与 Umi runtime context，官方模板保持 browser history 并通过窄 `runtime` 入口消费，纯函数测试、生成器测试、affected gate 与生产 bundle 标记/体积门禁通过 | 发布 `openxiangda-admin` 与 `create-openxiangda`，仓库外参考应用升级后以同一 artifact 完成 preproduction→production 在线导航、深链接刷新、身份与控制台验收；不改 hash history，不增加环境专用构建 |
 | Admin A1 RoleSession 上下文 | Native RoleSession bootstrap 是唯一身份资料/role subject/scope 来源 | 已设计待确认 | SubjectProfile 字段白名单、tenant 联合查询、非 active scope=null、capability=`authz.role-session-context`、有界 role subject 分页与切换 CAS 已定义 | A0 native cutover 后实现；A1 自身不再增加身份存储，但不得建立在 alpha 全局 assignment 上；平台先发，工具链后要求 capability |
 | Admin B0-O 租户公共 Origin | Platform Server Origin module + 版本/head/hostname claim registry | 已设计待确认 | 全仓确认多套模糊解析和广泛 URL 调用者；prod-1 证实 HTTPS/HTTP 配置差异、未登记 vhost 别名，且生产 `default_configs` 没有源码宣称的复合唯一约束；稳定租户 UUID、不可变 staged→challenge→verified→active、head revision CAS、hostname claim、事务审计、全局兼容阶段+单租户事实源状态、无长期双写和[逐文件实施蓝图](./tenant-public-origin-implementation-blueprint.md)已定义 | 确认后先做 O0 只读 inventory/digest 与 plan validator；操作者显式决定 migrate/decommission，所有服务实例同版后进入 migrating，再逐租户冻结/验证/切换，单租户失败不阻塞全平台；B0-R 不得绕过该阶段 |
 | Admin B0-C Cookie 安全 | Platform Server `AuthCookieService` + 无状态 policy resolver | 已设计待确认 | 已确认当前 DOMAIN JSON 同时决定 Cookie Domain 且 `secure:false`；共享会话/协议 Cookie 所有权、HTTPS Secure/`__Host-`/host-only、版本化名称、legacy scope manifest、C0/C1/C2 状态机和旧 host retirement 已定义 | B0-O registry 稳定后独立实现；首期不支持跨子域共享；C1 后只能回滚到理解 v2 Cookie 的兼容镜像，不和 Origin 数据迁移、return target 或 OAuth state 混发 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda-skill-kit",
-  "version": "2.0.0-alpha.27",
+  "version": "2.0.0-alpha.28",
   "description": "Validation and deterministic packaging for OpenXiangda 2.0 AI skills.",
   "type": "module",
   "main": "./dist/index.js",