openxiangda-skill-kit 2.0.0-alpha.32 → 2.0.0-alpha.33

package/docs/architecture/implementation-roadmap.md

@@ -18,7 +18,7 @@
 
 | 能力主题 | 唯一事实来源 | 当前状态 | 已有证据 | 尚缺内容与下一道门 |
 | --- | --- | --- | --- | --- |
-| 按需生产环境与运行启停 | Platform Server Native 环境 registry + Environment Head + DeploymentRun；K3s 只执行平台期望状态 | 已实现待线上验收 | provision 仅创建预发、promotion 惰性创建唯一生产、`runtime_state` CAS、start/stop durable run、停止网关 503、ReplicaFailure 快速诊断、CLI/MCP/Contracts 与能力协商均已实现；平台 targeted 测试、构建、101 条 migration 静态校验和 47 条 Native migration 真实 PostgreSQL 幂等应用通过 | 完成工具链正式发包和 prod-1 migration/image 部署；以全新应用证明初始无 production、预发 stop→0/start→ready、首次 promotion 才出现 production，并停止闲置旧测试环境释放配额 |
+| 按需生产环境与运行启停 | Platform Server Native 环境 registry + Environment Head + DeploymentRun；K3s 只执行平台期望状态 | 已交付 | provision 仅创建预发、promotion 惰性创建唯一生产、`runtime_state` CAS、start/stop durable run、停止网关 503、ReplicaFailure 快速诊断、CLI/MCP/Contracts 与能力协商均已实现；工具链正式包和平台版本已部署 prod-1；全新应用证明初始只有 preproduction、stop→0/start→1 Ready/stop→0，以及首次 promotion 才创建 production，并且两环境使用完全相同的 AppVersion 与包摘要；reference 与 legacy HGY 入口回归 200 | 后续启停策略、闲置环境自动停止和资源诊断分别按独立运维主题演进；不得让客户端或 `kubectl scale` 成为第二状态源 |
 | OAuth2 外部应用身份 | Platform Server OAuth2 服务与数据库；Nest SDK 只消费 token | 已交付 | Client Credentials、租户/应用/环境/scope 绑定、一次性 Secret、轮换宽限、撤销、审计、跨环境拒绝、应用 Principal；平台 unit/持久化/真实 HTTP 和 Nest 测试通过 | 后续只按新 scope 或凭据策略单独设计，不与 Admin 用户会话混合 |
 | 平台托管后端运行凭据 | Platform Server credential 状态 + Environment Head/DeploymentRun | 已交付功能基线，E4 激活语义待收敛 | CAS 暂存、同 AppVersion 滚动部署、旧凭据宽限、重试幂等、CLI 不获得明文；真实 HTTP 两轮通过 | 当前候选凭据仍可能在 Head 前进入可用链路。E4 改为 pending→active→retiring→revoked，业务 token/后台 lease 只授予当前 Head 对应 run；配额、告警另做运维主题 |
 | 应用 Secret | Platform Server Secret 版本与审计表 + runtime activation policy | 已交付功能基线，active-only 注入待收敛 | 环境级 AAD、只写值、不可变版本、CAS 幂等、required/optional 部署语义、删除和审计测试 | P0 只校验所需版本存在，不向 pending runtime 提前注入 active-only Secret；E4 通过短时 runtime identity 按需读取并受 egress policy 约束。KMS 替换保持同一协议，不在应用端增加第二套存储 |

package/docs/architecture/native-managed-files-v2.md

@@ -0,0 +1,18 @@
+# Native 托管文件闭环
+
+## 决策记录
+
+| 维度 | 决策 |
+| --- | --- |
+| 问题证据 | Devkit、Nest SDK 与本地平台已经使用 `/native/data/**`，但 prod-1 的真实 `files/uploads/initiate` 返回 404；平台能力发现仍声明 `data.managed-files`，Field Kit 因而在运行时才失败。 |
+| 能力所有者 | Platform Server Native Data API 唯一拥有文件元数据、绑定、下载授权和对象存储访问；Platform Storage 拥有签名与对象操作；Field Kit 只拥有稳定附件值适配和 UI。 |
+| 稳定不变量 | 业务字段继续保存既有 `name/url/size/type/provider/fileId/...` 稳定附件项；`DataFileRef` 只用于 initiate/complete 传输。2.0 只调用 Native 路径，不回退旧 `/data/**`。 |
+| 受影响合同 | 既有 initiate、complete、delete、content 客户端方法获得真实 Native 服务端实现；Field Kit 保存的受保护 URL 改为 Native 路径；能力名与 DTO 不变。 |
+| 失败与并发 | 上传绑定创建时的 Environment Head；Head 改变后未绑定文件拒绝完成/绑定。业务创建、更新、受限事务和文件绑定同事务提交；重复完成幂等，并发绑定只有一个记录成功。 |
+| 安全与资源 | 用户请求必须携带当前 RoleSession；应用身份上传/删除要求 `data:write`、下载要求 `data:read`。服务端校验字段权限、数据权限、大小、数量和类型；未绑定/孤立对象由有界租约清理。 |
+| 回滚边界 | 工具包只修正 2.0 Native URL 和本地同构实现；无 1.x 代码。平台表独立于旧文件表，回滚包不会改变旧应用数据。 |
+| 可证伪验证 | 包测试逐字节断言所有文件 URL 为 Native；本地真实 PostgreSQL 完成上传、绑定、下载和清理；prod-1 使用同一 AppVersion 验证 OAuth2/RoleSession、Data、文件与 Workflow 全链路。 |
+
+Platform Server 的持久化与运行边界详见根编排仓库
+`docs/architecture/2026-08-16-openxiangda-native-managed-files.md`。本仓库不得用旧
+Data API fallback 掩盖平台未就绪，也不得把对象存储凭据暴露给应用代码。

package/docs/architecture/on-demand-production-environment-v2.md

@@ -1,6 +1,6 @@
 # OpenXiangda 2.0 按需正式环境
 
-状态：2026-08-16 已实现平台与工具链候选，等待正式发包和 prod-1 在线验收。
+状态：2026-08-16 已正式发包并完成 prod-1 全新应用在线验收。
 
 ## 问题证据
 
@@ -85,3 +85,18 @@
 - K3s 执行器只缩放当前 Head 指向的 Deployment。状态只在目标副本就绪或归零且 Head 未变化后提交；停止后的 App API 返回稳定的 503 错误码。
 - CLI 提供 `environment status/start/stop`；MCP 提供只读环境资源以及 `environment_status`、`start_environment`、`stop_environment` 三个工具。
 - AppPackage 自动要求 `environment.on-demand-production` 与 `environment.runtime-lifecycle`，旧平台会在上传制品前被能力协商拒绝。
+
+## prod-1 在线证据
+
+- 全新应用 `openxiangda-v2-lifecycle-acceptance` provision 后只存在
+  `preproduction`；AppVersion 为 `7c931943-1335-479b-93fb-5facb9bf49c3`，
+  包摘要为 `05460ac2e35bd08e36fe289436002d5dc00d6967b2634c70488a95725f34b113`。
+- 同一预发环境完成 stop→0、start→1/1 Ready、再次 stop→0，三次操作都由
+  Durable DeploymentRun 驱动，未重建 AppPackage，也未手工修改 Deployment。
+- 首次显式 promotion 才创建唯一 production 环境
+  `6cacce98-43cb-4055-99d5-2c8782d01835`；promotion run
+  `e54bfd7b-7320-4bbc-9d44-8f96aa1e0a16` 激活上述同一 AppVersion 与包摘要。
+- 验收结束时预发为 stopped/0 副本，正式为 running/1 Ready Pod；应用池仍受
+  原 `2.5 CPU/4Gi` 配额约束，没有为通过验收临时提高资源上限。
+- 正式 `/view/openxiangda-v2-lifecycle-acceptance/admin`、reference app 和
+  legacy HGY Admin 均返回 HTTP 200，证明新生命周期没有进入 1.x 路径。

package/package.json

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