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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/docs/architecture/field-value-contract-boundary.md +92 -0
  2. package/docs/architecture/implementation-roadmap.md +3 -2
  3. package/package.json +2 -2
package/docs/architecture/field-value-contract-boundary.md ADDED
@@ -0,0 +1,92 @@
1
+ # 稳定字段值合同与 UI 依赖边界
2
+
3
+ 状态：2026-08-16 已实现待发布
4
+
5
+ 本决策是[稳定字段数据协议采用与声明分层决策](./stable-field-protocol-adoption.md)的实现收口，只调整 OpenXiangda 2.0 包所有权和应用依赖图，不改变字段值、数据库、Data API 或 1.x 运行时协议。
6
+
7
+ ## 1. 问题证据
8
+
9
+ 独立参考应用的 NestJS 后端只从 `@app/domain` 导入 `PurchaseRequestRecord` 类型，但当前依赖链为：
10
+
11
+ ```text
12
+ @app/server
13
+ -> @app/domain
14
+ -> openxiangda-field-kit
15
+ -> antd
16
+ -> antd-mobile
17
+ -> React peer/runtime dependency tree
18
+ ```
19
+
20
+ `pnpm --filter @app/server deploy --prod --legacy` 实测生成约 253MB、195 个生产包，并报告 `antd-mobile`/React peer 依赖。`@app/domain` 使用 Field Kit 的唯一原因是三个稳定值 TypeScript 类型；后端不渲染任何组件，也不执行 Field Kit codec。
21
+
22
+ 这不仅增加镜像构建、传输、解压和漏洞扫描成本，也违反已确认的不变量：稳定字段值协议必须是不依赖 React 的跨前后端共享合同。
23
+
24
+ ## 2. 能力所有者
25
+
26
+ | 能力 | 唯一所有者 |
27
+ | --- | --- |
28
+ | 稳定字段值形状 | `openxiangda-contracts` |
29
+ | DataResource、Data API 与工作流跨进程合同 | `openxiangda-contracts` |
30
+ | 值归一化、格式化和平台文件/组织控制器 | `openxiangda-field-kit` |
31
+ | Desktop/Mobile/Readonly/List/Detail renderer | `openxiangda-field-kit` |
32
+ | 应用业务记录与输入类型 | 应用 `packages/domain`，只组合 contracts 类型 |
33
+ | NestJS DTO、业务校验和写入 | 应用 `apps/server` |
34
+
35
+ `openxiangda-contracts` 不依赖 Field Kit、React、Ant Design、浏览器 API 或 Node 专属运行时。Field Kit 可以从 contracts 导入并重新导出稳定值类型，方便 UI 代码使用，但不能成为这些类型的事实源。
36
+
37
+ ## 3. 稳定不变量与受影响合同
38
+
39
+ 以下值形状原样移动，不改字段名、可选性或语义：
40
+
41
+ - `StableOptionValue`
42
+ - `AttachmentVariant`
43
+ - `StableAttachmentValue`
44
+ - `StableAddressValue`
45
+ - `StableLocationValue`
46
+
47
+ 受影响的公开面只有 TypeScript 导出所有权：
48
+
49
+ 1. `openxiangda-contracts` 根入口和 `/browser` 入口新增上述类型。
50
+ 2. `openxiangda-field-kit` 继续重新导出上述类型，现有前端源码无需迁移才能工作。
51
+ 3. 官方模板和参考应用的 `@app/domain` 改从 `openxiangda-contracts/browser` 导入，并删除对 Field Kit 的生产依赖。
52
+ 4. Web 应用仍直接依赖 Field Kit，并继续使用其 Desktop/Mobile 组件、codec、附件与平台数据能力。
53
+ 5. 官方 NestJS Dockerfile 只安装 `@app/server...` 的 workspace 闭包，并在复制源码前禁用 lifecycle script；源码复制后显式执行所选 workspace 的 build，再以已构建产物生成生产目录。前端源码可以仍在 Git 仓库中，但不进入后端依赖安装和构建步骤。
54
+
55
+ 数据库物理类型、JSONB 形状、查询运算符、索引、Data API 请求、业务 API、AppPackage schema 和平台部署合同均不变化。
56
+
57
+ ## 4. 失败、并发与安全边界
58
+
59
+ - 这是编译期所有权迁移，不新增并发状态、缓存、迁移表或运行时分支。
60
+ - contracts 与 Field Kit 的声明不一致必须由 TypeScript 和包测试直接失败，禁止复制两份相似接口。
61
+ - 服务端模板的生产依赖边界必须静态拒绝 React、React DOM、Ant Design、Ant Design Mobile、Umi、Admin 和 Field Kit。
62
+ - 前端仍必须通过 Field Kit 提交稳定值；本次瘦身不授权应用后端或自定义页面发明新的人员、部门、地址或附件格式。
63
+ - 不增加新的网络权限、Secret、数据库权限或容器特权。后端运行镜像只减少无关依赖。
64
+ - Docker 依赖层只复制根/服务端/domain/contracts manifests 与 lockfile，避免普通前端源码修改击穿后端依赖缓存。安装阶段使用 frozen lock，不能在镜像构建中改写解析结果。
65
+ - Field Kit 的实质变更要求候选 tarball、新应用浏览器构建/E2E、模板生成检查和独立参考应用；它本身不触发本地 PostgreSQL 生命周期、Skills 或文档门禁。只有这些领域也发生变化时才运行对应昂贵门禁，避免把“未映射包”当作理由重复执行无关历史校验。
66
+
67
+ ## 5. 资源上限与回滚
68
+
69
+ 服务端部署闭包不得包含 `openxiangda-field-kit`、`antd`、`antd-mobile`、`react`、`react-dom`、`@umijs/*` 或 `openxiangda-admin`。生产目录大小记录为趋势指标，不作为跨 pnpm/Node 版本的唯一正确性判断；依赖闭包门禁才是稳定约束。
70
+
71
+ 回滚单位是 contracts/Field Kit/creator 的一个版本组合，以及参考应用的一个 Git/AppVersion。由于值协议和数据库未变化，回滚不需要数据迁移。1.x 代码、镜像、流程和自动化均不在改动范围内。
72
+
73
+ ## 6. 可证伪验收
74
+
75
+ 1. contracts 根入口与 `/browser` 可以编译导入全部稳定字段值类型，且 package manifest 无运行依赖。
76
+ 2. Field Kit 的 codec、Desktop、Mobile、格式化和现有测试继续通过，证明只移动所有权、不改变值行为。
77
+ 3. 官方模板 `@app/domain` 和独立参考应用 `@app/domain` 不再依赖或导入 Field Kit。
78
+ 4. `pnpm --filter @app/server why openxiangda-field-kit|antd|antd-mobile|react` 不再出现来自服务端的生产依赖路径。
79
+ 5. `pnpm --filter @app/server deploy --prod --legacy` 生成的目录中不存在上述 UI 包。
80
+ 6. 后端 Docker 构建日志的安装/build 选择器只包含 server、domain、应用 contracts；最终镜像启动和 readiness 通过。
81
+ 7. 官方模板 check/test/build、独立参考应用 check/test/build 和工具链 `verify:affected` 全部通过。
82
+ 8. Changesets 确定性覆盖 contracts、Field Kit 和 creator；发布后从 registry 创建的新应用重复第 3-7 项。
83
+ 9. 参考应用使用同一 AppPackage 先部署 preproduction，再显式晋级 production；Data API 与字段往返结果保持一致。
84
+
85
+ ## 7. 当前实现证据
86
+
87
+ - contracts、Field Kit、官方模板 check/test/build 与 49 项 affected task 已通过。
88
+ - Field Kit 的单/多选、地址、附件、UI 校验分层和移动 renderer 测试全部通过。
89
+ - 新的服务端生产目录约 54MB、85 个包，相比基线分别减少约 79% 和 56%。
90
+ - 生产目录未发现 Field Kit、React、React DOM、Ant Design、Ant Design Mobile 或 Admin。
91
+ - 瘦身后的生产目录已直接启动 NestJS，平台健康/就绪、事件、工作流 provider 和采购 App API 路由均完成注册。
92
+ - 正式发包、registry 新应用、Docker 镜像和线上 preproduction→production 仍是本主题的剩余验收。
package/docs/architecture/implementation-roadmap.md CHANGED
@@ -31,8 +31,9 @@
31
31
  | 确定性工具链发布 | Changesets 版本提交、冻结工件清单、release receipt | 已交付 | 待消费 Changeset 在构建前 fail-fast；版本只由 Changesets 物化；正式发布只验证一次同一批 tarball；CLI alpha.20 与 skill-kit alpha.19 已按该状态机发布并打 Git tag | 周期性全量审计保留；不得恢复人工选包、手工版本或重复正式门禁 |
32
32
  | 环境配置内核 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 只留审计历史，不做双读、双写或导入 |
33
33
  | 授权内核 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 或建立长期双读/双写 |
34
- | 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 验收另列下一阶段 |
35
- | 前端动态挂载路径 | 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，不增加环境专用构建 |
34
+ | 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 单链路通过工作台、菜单、会话标签、稳定角色切换、列表/详情、独立供应商表单、工作中心、单按钮流程提交和个人中心；正式包已发布，仓库外参考应用使用 registry lock 构建，并以同一 AppPackage 完成 preproduction→production 晋级 | 移动用户端 Field Kit 已有独立 renderer；完整移动页面模板与设备 Chromium 验收另列后续主题，不回填到 PC Admin |
35
+ | 前端动态挂载路径 | Platform Server 注入 runtime base；`openxiangda-admin` 适配 Umi basename | 已交付 | `openxiangda-admin@2.0.0-alpha.26` 与 `create-openxiangda@2.0.0-alpha.27` 已发布；参考应用的同一前端 digest 先部署 preproduction 再晋级 production。正式根入口和业务深链均返回 200、`application-v2`、production 环境修订和正确 runtime base，全部 JS/CSS 资源 200；Chrome 保持 `/view/openxiangda-v2-reference-app/` 并显示应用标题 | 后续路由能力只按独立需求增加；不改 hash history，不增加环境专用构建或第二套路由状态 |
36
+ | 稳定字段值合同与服务端 UI 依赖边界 | `openxiangda-contracts` 拥有值形状；Field Kit 拥有 codec/平台控制器/renderer | 已实现待发布 | 稳定值类型已移到无依赖 contracts，Field Kit 保留前端重导出，模板 domain 删除 Field Kit；服务端依赖门禁与选择性 Docker 安装已落地。生产目录实测由约 253MB/195 包降至约 54MB/85 包，未含 Field Kit/React/Ant Design，瘦身产物可启动 Nest；49 项 affected task 通过，详见[稳定字段值合同与 UI 依赖边界](./field-value-contract-boundary.md) | 完成 Changesets 正式门禁与发布；registry 参考应用构建新 Docker 镜像，并用同一 AppPackage 完成线上 preproduction→production 验收 |
36
37
  | 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 |
37
38
  | 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 不得绕过该阶段 |
38
39
  | 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 CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "openxiangda-skill-kit",
3
- "version": "2.0.0-alpha.28",
3
+ "version": "2.0.0-alpha.29",
4
4
  "description": "Validation and deterministic packaging for OpenXiangda 2.0 AI skills.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
@@ -21,7 +21,7 @@
21
21
  "README.md"
22
22
  ],
23
23
  "dependencies": {
24
- "openxiangda-devkit-core": "2.0.0-alpha.23"
24
+ "openxiangda-devkit-core": "2.0.0-alpha.24"
25
25
  },
26
26
  "devDependencies": {
27
27
  "tsx": "4.23.12",