openxiangda-skill-kit 2.0.0-alpha.35 → 2.0.0-alpha.36

package/docs/architecture/ant-design-pro-v6-admin-foundation.md

@@ -318,3 +318,26 @@ AppPackage 的边界不变：生产构建仍输出静态前端 `dist`、NestJS O
 3. 从候选 tarball 新建空目录应用以及绿地同步后的独立参考应用均通过 generate/check/test/build；旧 `ApplicationShell`、仪器和预约源码不再存在。
 4. release plan 只在参考应用 manifest 与全部公开包候选版本完全一致时生成；正式发布前重新校验 lockfile 与 registry 工件一致。
 5. 参考验收调用标准 CLI 命令而不要求应用增加仓库私有的 generate 脚本；显式安装候选到参考工作树时先写入一次生成契约，后续隔离副本和普通发布验收只允许 `generate --check`。生成模板必须从 Git 与 OCI 构建上下文排除 `.codegraph`、`.openxiangda`、`.env` 等本地状态。
+
+## 14. 2026-08-17 导航 JSX 双运行时一致性
+
+### 问题证据与能力所有者
+
+- 使用当前 `master` 和本地 SDK 在空目录创建应用后，`generate --check` 与类型检查通过，但 `openxiangda test` 在 Node/tsx 加载 `navigation.tsx` 时以 `React is not defined` 失败。
+- 同一文件既是 Umi Admin 的导航事实源，也是模板单测读取的导航事实源；React/Umi 继续唯一拥有 JSX 生命周期，不增加测试专用导航副本。
+
+### 稳定不变量与受影响合同
+
+- `applicationRoutes` 和 `adminNavigation` 仍分别是路由与菜单的单一事实源，菜单结构、路径、capability 与运行时行为不变。
+- 不改变 React 19、Umi Max、TypeScript JSX 模式或公开包 API；只让 JSX 模块显式具备在 Umi 与 Node/tsx 两种受支持执行器中的运行时依赖。
+- 影响只限 `create-openxiangda` 生成的新 2.0 应用。1.x、平台服务、既有 AppVersion 与其他租户均不加载该模板源文件。
+
+### 失败、并发、安全与资源边界
+
+- 新应用的 `openxiangda test` 继续直接导入生产导航模块；若运行时依赖再次缺失，必须在首次测试中失败，不能用 Mock 或条件分支绕过。
+- 变更不引入网络、持久状态、并发状态或额外浏览器资源，也不改变身份、授权和数据边界。
+
+### 回滚与可证伪验证
+
+- 回滚单位是 `create-openxiangda` 的单个补丁提交，不要求迁移已生成应用。
+- 模板单测必须断言导航模块保留显式 React 运行时导入；从本地 SDK 创建的全新应用必须通过 `generate --check`、`check`、`test`、Umi production build 与 Chromium E2E。

package/docs/architecture/best-practice-template-rebuild-v2.md

@@ -26,25 +26,45 @@
 
 每页实现必须同时通过结构断言、交互断言和指定视口截图回归。字段内容可以换成真实业务数据，页面区块、相对层级、对齐、主动作顺序和语义色不得擅自删减。
 
+### 1.2 线上复核增量基线（2026-08-17）
+
+P1-P5 的技术链路交付不等于产品模板验收。用户在 prod-1 preproduction 复核后发现页面仍存在重复信息、列表交互退化、文件组件能力退化、环境入口和流程业务引用错误，因此 P1-P5 的产品状态重新打开；以下七张实拍图与本节合同覆盖 1.1 中冲突的旧描述。
+
+| 复核基线 | 评审附件 | SHA-256 | 新增或修正合同 |
+| --- | --- | --- | --- |
+| 当前模板问题页 | `codex-clipboard-ea7a610d-0ebf-4c63-977a-ceb5bcc18ee5.png` | `8ce67f32f9c69d51fd985f8a1623a6c41fcf8760775001a62736ab6fd3d6ddc3` | 顶栏和缓存标签已表达当前位置时，内容区不得重复面包屑、页标题和说明；全局顶栏不显示搜索框 |
+| 参考 Shell | `codex-clipboard-315df6dc-9cbc-4f25-87e6-9e6997ccc30f.png` | `46bd393288080486a573aba9a09768a4f2647badc6fdc76c93d9358041ea14ac` | 侧栏分组、图标、选中态、顶栏与标签几何采用成熟企业后台密度 |
+| 参考侧栏 | `codex-clipboard-458d7e0f-ead5-488d-9c8c-6959294f6672.png` | `40d851713e2f4eaf4c029fc8234d636e6c0f654fc63658fdf10ac322683eb2c5` | 分组、子项、折叠和滚动区可辨识，图标统一使用语义色和正式图标 |
+| 参考标准列表 | `codex-clipboard-928424b7-b02e-49ff-bb08-d5abaa98a70f.png` | `cb3945283db167c4aeb747d8fd5613cf7107d356db72e73d824d56d50170916c` | 筛选默认一行并可展开更多；筛选下方左侧为业务操作，右侧为刷新和列表设置；表格支持服务端排序 |
+| 参考列表设置 | `codex-clipboard-e1f64efb-3634-4563-a251-a9e4e48b339e.png` | `0bb7c01364cb5161b2fe0591409cb0e97132bdf8ea32f37fcc71b155001e317d` | 设置抽屉固定包含“搜索项、列设置、排序、显示”四类账号级偏好，不修改资源合同 |
+| 当前流程预览问题 | `codex-clipboard-60472a98-577b-418d-8eca-34aafded02d9.png` | `421d011f1d939763b02f8b1ff0c7a5c15a0134e38d5129770631d8a26a85d81c` | 提交预览只展示审批路径，不重复业务表单摘要；审批节点必须展示内核解析出的具体审批人，不能用“无需指定审批人”掩盖未解析状态 |
+| 当前流程详情错误 | `codex-clipboard-4a7aadd0-c484-4f87-89cc-583d2a2fc47d.png` | `4263041dddd7307ce69f390f8a36b9195f9d1314d846b47f415fcb5e959268d7` | 流程 Surface 必须提供可验证的 DataRef，详情只能据此读取业务数据；缺失引用是合同错误并须在提交链路修复 |
+
+本轮另外冻结三项行为合同：应用列表打开时优先进入已激活 production，否则自动进入已激活 preproduction；preproduction 顶栏在 production 已发布时提供快捷切换；官方模板必须提供覆盖全部稳定字段类型的验收表单。附件和图片继续由 `openxiangda-field-kit` 消费 Files API，迁移 1.x 已验证的上传、下载、预览、缩略图、进度、失败重试和删除交互，但 2.0 不依赖 1.x 运行包、不新增第二份文件协议。
+
 ## 2. 问题证据
 
 1. `ProLayout` 未显式提供唯一菜单选中键，`/admin` 与其子路径可能同时高亮。
 2. 缓存标签直接使用 `Tabs editable-card` 并以局部 CSS 修补，标签、侧栏、顶栏和页面边界没有共同几何基准。
-3. 工作台、数据列表和移动页面只完成通用组件拼接，没有落实已评审稿的信息层级、色彩、图标和状态设计。
+3. 工作台、数据列表和移动页面只完成通用组件拼接，没有落实已评审稿的信息层级、色彩、图标和状态设计；线上复核还发现内容区重复标题、顶栏冗余搜索和标准列表能力退化。
 4. 部门字段只提供关键词扁平搜索。平台后端能返回真实部门和路径，但当前 2.0 Field Kit 没有根组织浏览、树展开、懒加载、面包屑和完整路径展示。
 5. 参考应用把用户 ID 同时写入目录值的 `label` 与 `value`，导致列表出现裸 UUID。
 6. Chromium 测试只验证可见与可点击，没有唯一菜单选中、裸 ID、组织树、视觉截图和布局几何门禁。
+7. 应用入口固定打开 production，未发布 production 时没有回退到 preproduction；用户端快捷入口丢失应用基础路径并错误跳转到 `/m`。
+8. 流程预览重复展示业务摘要且没有稳定呈现具体审批人；流程详情收到的 DataRef 不完整时只能展示“业务数据加载失败”。
+9. 2.0 文件控件只保留最简上传路径，未达到 1.x 已稳定的预览、下载、缩略图、进度、失败恢复和删除体验。
 
 ## 3. 能力所有者与稳定不变量
 
 | 能力 | 唯一所有者 | 不变量 |
 | --- | --- | --- |
 | 路由、菜单、缓存标签描述 | 应用 route manifest，经 `openxiangda-admin` 投影 | 不维护第二套路由或菜单树；任一路径只选中一个最具体菜单项 |
-| Admin 布局和标准页面 | `openxiangda-admin` | 应用不能复制 Shell、ProTable、ProForm、详情和流程标准壳 |
+| Admin 布局和标准页面 | `openxiangda-admin` | 应用不能复制 Shell、ProTable、ProForm、详情和流程标准壳；内容区不重复顶栏已有上下文 |
 | 移动页面组合 | `openxiangda-user/mobile` | 与 Admin 分离，只消费同一身份、Data、Workflow 和 Field Kit 合同 |
 | 字段值和渲染 | `openxiangda-contracts` + `openxiangda-field-kit` | 保持已经运行稳定的值协议，不以显示字符串替换平台值 |
 | 人员和部门目录 | Platform Server Directory API | Field Kit 不复制组织数据；平台 API 是唯一事实来源 |
 | 文件 | Platform Server Files API + Field Kit | 上传、下载、鉴权、预览和稳定文件值不得由应用自建 |
+| 环境 head 与默认应用入口 | Platform Server Environment Head + 平台管理前端 | production 存在时优先，否则回退 preproduction；前端不维护第二份发布状态 |
 | 显示身份 | Native Principal/RoleSession/Directory | 默认页面不得显示 UUID、内部 code 或原始 JSON |
 | 业务数据和流程状态 | Data/App API 与 Workflow Kernel | 页面只解释合同，不复制权限、审批或状态机规则 |
 
@@ -65,7 +85,7 @@
 - 由最具体的可见菜单路径确定唯一 `selectedKey`。
 - 统一 56px 顶栏、44px 标签栏、220px 侧栏和页面内容网格。
 - 用 Ant Design 公开 Tabs API 和语义槽实现有界缓存标签，不使用默认 editable-card 外观。
-- 完成品牌、折叠、全局搜索入口、通知、个人中心、身份切换和环境标识的固定位置。
+- 完成品牌、折叠、通知、个人中心、身份切换和环境标识的固定位置；移除当前没有完整能力闭环的全局搜索框。
 
 完成条件：菜单唯一选中；标签、顶栏和内容区边界对齐；直接 URL、详情路由和身份切换均保持正确。
 
@@ -89,9 +109,9 @@
 ### P3 标准 PC 页面
 
 - 工作台：问候、四个有界指标、待办、快捷入口、趋势与最近活动。
-- 数据管理：服务端搜索、排序、分页、列配置、密度、刷新、导出和有界行操作。
+- 数据管理：默认一行筛选、更多筛选、服务端搜索/排序/分页、搜索项/列/排序/显示设置、密度、刷新、导出和有界行操作。
 - 表单：分组、字段策略、附件和一个主提交动作。
-- 流程：点击提交并保存业务数据后才打开真实审批预览 Modal。
+- 流程：点击提交并保存业务数据后才打开真实审批预览 Modal；Modal 只展示含具体审批人的真实路径，不重复业务表单摘要。
 - 详情：业务字段、审批时间线、审计记录和 Surface 允许的操作。
 
 完成条件：设计稿中的层级与操作顺序逐页面通过截图和交互验收，采购领域代码不进入通用包。
@@ -161,15 +181,16 @@ Admin 工作台还原本轮决策：
 
 | 范围 | 必须通过 |
 | --- | --- |
-| Shell | 任一路径恰好一个菜单选中；标签边界对齐；直接 URL、关闭、恢复、身份切换正确 |
+| Shell | 任一路径恰好一个菜单选中；标签边界对齐；无全局搜索和内容区重复标题；直接 URL、关闭、恢复、身份/环境切换正确 |
 | 视觉 | PC 冻结稿尺寸 1536x1024（并补充 1280x800 结构检查）；移动 390x844、375x812 截图回归 |
-| 数据 | 搜索、排序、分页、列配置、空/错/加载、revision 冲突 |
-| 字段 | 单/多选、级联、日期/区间、金额、地址、人员、部门、附件、图片和子表 |
+| 数据 | 默认一行与更多筛选、服务端搜索/排序/分页、四类列表设置、空/错/加载、revision 冲突 |
+| 字段 | 官方验收表单覆盖 `text/textarea/number/money/percent/boolean/date/datetime/dateRange/option/options/radio/checkbox/cascade/user/users/department/departments/attachments/images/address/location/richtext/signature/subtable/json/serial/relation/workflowStatus` |
 | 目录 | 打开即能看到真实根组织；树展开、搜索、路径、单选/多选和失败重试 |
 | 身份 | 页面显示真实姓名/部门；正则扫描页面不存在裸 UUID |
-| 流程 | 提交前没有预览；保存和 prepare 后弹窗；同意、拒绝、转交、回退、加签和代理按 Surface 展示 |
+| 流程 | 提交前没有预览；保存和 prepare 后弹窗；预览仅含具体审批人路径；Surface DataRef 可读业务数据；同意、拒绝、转交、回退、加签和代理按 Surface 展示 |
 | 边界 | 移动包没有 Admin/桌面录入依赖；应用没有自建人员、部门和文件协议 |
 | 发布 | 新建应用与独立参考应用使用相同候选包；preproduction 在线通过后才允许 production 晋级 |
+| 环境 | 应用列表 production 不存在时自动进入 preproduction；preproduction 可切换到已发布 production；用户端跳转保留应用 base path |
 
 ## 8. 交付记录
 
@@ -180,3 +201,6 @@ Admin 工作台还原本轮决策：
 | 2026-08-16 | P2 | 已完成 | Directory v2 已提供按层部门树和按部门分页人员浏览，直接复用平台已有的可见范围，不建立第二份组织存储；Desktop 以左树右人员列表和全局搜索消费合同，Mobile 以独立组织钻取和本部门人员面板消费合同；Field Kit 对仅含 ID 的历史稳定值调用 Directory resolve，未知值显示语义占位而不暴露内部 ID。平台定向 4 测试、Devkit 50 测试、Local Platform 21 测试、Field Kit 8 测试与 `verify:affected` 35/35 任务通过 |
 | 2026-08-17 | P3 | 已完成 | 标准列表将主动作、搜索卡、表格工具、服务端分页与行操作分层；详情统一字段渲染与审计；流程表单按 section 分组且只有一个主提交动作，保存业务数据并 prepare 后才展示含业务摘要和真实节点的确认 Modal，确认后进入无裸 ID/code 的流程详情。已冻结 `admin-data-list`、`admin-data-detail`、`admin-workflow-form`、`admin-workflow-preview`、`admin-workflow-detail` 五张 1536x1024 Chromium 基线，并以第二次不更新快照的运行证明基线稳定；边界 fixture 仅用于视觉确定性，真实 PostgreSQL/NestJS 和 preproduction 验收仍保留在 P5 |
 | 2026-08-17 | P4 | 已完成 | 独立移动用户端已按冻结稿重建工作台、数据列表、表单提交、底部审批预览和流程任务详情；使用正式 SVG 图标、语义状态、移动卡片、安全区操作栏和独立路由树，人员、部门、日期、选项、地址、附件与图片仍全部经 `openxiangda-field-kit/mobile`。已冻结五张 390x844 核心页基线和一张 375x812 工作台基线；连续不更新快照运行 2/2 通过，页面无裸 ID/code，`verify:affected` 19/19 任务通过，移动入口依赖门禁确认未加载桌面 Admin/Ant Design。视觉 fixture 只用于确定性截图，真实 OAuth2、Directory、Data、Workflow 与 Files 保留到 P5 prod-1 preproduction 验收 |
+| 2026-08-17 | P5 | 已完成 | 平台后端不可变版本 `20260817-043631-6fd2f6136179abca` 已部署 prod-1，102 条 SQL migration 预检为 0 pending/0 conflict，K3s 后端 1/1 Ready；参考应用 AppVersion `e4713605-fd2d-4710-9b44-518ac779465d` 只部署 preproduction。真实 OAuth2 用户和应用管理员 RoleSession 验证 Directory 根部门/部门人员/裸 ID 解析、Data/App API 用户审计字段、Files 完整下载；Workflow 实例 `139a39ba-7f6e-4840-a25a-40933917166b` 完成部门负责人、财务复核员、采购管理员三角色切换和审批，最终 `approved`，时间线与 created/completed 工作中心均通过。独立参考应用 `da67d7d` 固化了仅允许 preproduction、默认只读且不输出凭据的可重复验收脚本和收据；production 保持停止，平台入口、参考应用 Admin 与 1.x HGY Admin 均返回 HTTP 200 |
+| 2026-08-17 | 产品复核 | 重新打开 | prod-1 实拍证明 P1/P3/P5 仍有可见回归：重复页面上下文、列表设置缺失、文件控件退化、流程预览与 DataRef 错误、环境入口错误。此前“已完成”仅保留为技术链路证据，不再代表官方模板验收通过；按 1.2 增量基线重新开发、截图和在线验收 |
+| 2026-08-17 | 产品复核本地修复 | 已完成，待线上 | 已关闭内容区重复 PageHeader 与全局搜索；标准列表具备默认单行/更多筛选、平台目录筛选、左右工具区和四类账号级设置；Files Field Kit 恢复拖拽、图片、进度、取消、鉴权预览、下载和未绑定清理；审批预览只展示具体审批人路径，Surface 统一 `dataRef`；应用入口 production 不存在时回退 preproduction，用户端链接保留应用 base path；组件验收页覆盖全部稳定字段类型。Admin Chromium 主链路 1/1、Mobile 2/2、Admin/Field Kit 单元测试与模板生产构建已通过，新增 `admin-field-gallery-*`、更新 `admin-data-*` 与 `admin-workflow-*` 1536x1024 基线；尚未替代 prod-1 真实 OAuth2/Directory/Data/Workflow/Files 验收。 |

package/package.json

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