openxiangda-skill-kit 2.0.0-alpha.39 → 2.0.0-alpha.47

package/docs/delivery.md

@@ -1,77 +0,0 @@
-# 构建与交付
-
-## AppPackage
-
-一个包绑定同一提交的前端、后端镜像、配置、生成契约、依赖锁和平台契约范围。构建输出使用内容摘要密封；修改任一部分都会产生新的 AppVersion。
-
-`deploy` 在发起任何网络请求前会再次计算 AppPackage、每个制品和前端包内每个文件的 SHA-256，并校验大小、入口文件、组件 manifest 指向、后端 OCI digest 以及 config/contracts 资源清单。构建完成后被替换、遗漏或来自另一提交的文件会在本地直接失败，不能进入上传阶段；平台收到后还会独立重复校验，客户端校验不能替代服务端信任边界。
-
-## DeploymentRun
-
-```mermaid
-stateDiagram-v2
-  [*] --> Queued
-  Queued --> Validating
-  Validating --> Preparing
-  Preparing --> Deploying
-  Deploying --> Verifying
-  Verifying --> Activating
-  Activating --> Succeeded
-  Validating --> Failed
-  Preparing --> Failed
-  Deploying --> Failed
-  Verifying --> Failed
-  Activating --> Failed
-```
-
-平台持久保存每个检查点、输入摘要、重试分类和关联日志。客户端只创建或查询运行，因此发布不会依赖某个 AI 会话持续在线。
-
-## 标准门禁
-
-1. 本地 AppPackage/制品/组件清单一致性校验；
-2. 平台端契约兼容、摘要与制品完整性复验；
-3. 配置预检及 Secret 准备；
-4. Kubernetes 资源 apply；
-5. liveness/readiness 与平台回调探测；
-6. 前端和配置版本激活；
-7. 审计、通知和可观测关联。
-
-失败默认不切换当前版本。重试复用同一 AppVersion 和幂等键。promotion 复用同一 AppVersion；rollback 是激活历史版本的新 DeploymentRun，不在服务器上现场改文件。
-
-新应用 provision 只创建预发环境。生产环境在首次 promotion 时由平台惰性创建；CLI 和 AI 不预先生成生产 UUID，也不自行补写环境记录。`environment start/stop` 同样创建平台持久化的 DeploymentRun，停止只把当前 Head 的 K3s 工作负载缩容为零并保留环境、数据、配置、密钥元数据与历史。客户端先用 `environment status` 读取权威 revision，并把 revision 纳入默认幂等键；并发操作由平台唯一约束和 Head/环境 CAS 仲裁。
-
-## 版本管理
-
-Changesets 管理各个 `openxiangda-*` 包、CLI、MCP 与 skill-kit 的独立版本和内部依赖传播。官方模板固定经过同一候选矩阵验证的精确 BOM。文档参考从命令和 MCP 注册表生成，避免文档与实现漂移。
-
-版本物化是发布状态机的独立步骤：`pnpm release:version` 只允许在干净、已同步 `origin/master` 的 `master` 上运行，把尚未消费的评审 Changesets 确定性写入包版本、内部依赖和模板 BOM；它不提交、不发包。生成 diff 经审核、提交并推送后，才允许 `release:plan`、`verify:release` 或 `release:publish` 识别候选。这样 Git 中的版本清单是 npm 工件和 Git tag 的唯一源码事实，不使用临时目录里的虚拟版本，也不允许手工跳过物化。
-
-`verify:release` 在真正写 registry 前执行不可变版本门禁：未发布版本进入候选集；已经发布的版本则分别解包 registry 工件和当前本地包并逐文件比较。相同内容视为未变包，不重复发布；任何内容差异都必须先用 Changesets 产生新版本；没有新版本时拒绝空发布。`release:publish` 只消费该门禁形成的验证凭据。发布范围、版本和是否允许写入由机器判定，不由 AI 临场决定。
-
-`verify:release` 只打包一次，并在 Git 私有目录写入绑定源码 `HEAD`、registry、验证模式、包版本、字节数、SHA-256 与 npm SHA-512 integrity 的工件清单和 `validated` receipt。全新应用、独立 reference app 与正式 npm publish 必须消费同一批 `.tgz`；`release:publish` 没有对应凭据就拒绝写入，任何字节或清单变化也都会在写 registry 前失败。部分发布中断后可以从 receipt 继续：已经发布且 integrity 一致的包被跳过，不一致则停止。npm 在逐包写入时可能先推进预发布 tag；receipt 只接受这一个可恢复中间态，并在所有包确认后统一收敛最终 dist-tag 和 Git tag。
-
-`pnpm verify:local` 是日常可重复执行的全量验收入口。涉及本地 PostgreSQL 生命周期时，候选 tarball 只在 monorepo 外的新应用中运行一次 Chromium：生命周期门禁先通过受所有权校验的 reset 建立确定性数据库，再让同一浏览器套件同时经过 React、本地平台、NestJS 与 PostgreSQL；不会先跑 UI-only 再重复浏览器工作，也不会清理开发者现有应用的数据。正式候选在版本提交推送后由 `pnpm release:plan` 比较 npm 与本地 tarball，并比较候选与上一发布版本；漏升版或待消费 Changeset 会在昂贵测试前直接失败。`pnpm verify:release` 冻结一次候选工件并执行机器生成的增量计划；候选依赖闭包永远完成 check/test/build，每个候选 tarball 都在 monorepo 外安装进全新生成应用并完成 generate/check/test/build。浏览器相关变化提升到真实 Chromium E2E，核心应用 SDK 变化增加持久 reference app，Skill/文档变化增加相应门禁。成功凭据随后由 `release:publish` 复用，发布命令不再重跑这些门禁。未知变化 fail-closed 到完整矩阵；周期审计使用匹配的 `verify:release:full` 与 `release:publish:full`。
-
-Playwright 浏览器使用官方缓存目录；`playwright install chromium` 已安装对应版本时是无操作。发包门禁不会额外运行 1.x 测试，也不会为每个包重复浏览器验收，而是在最终独立新应用上只运行一次完整用户路径。
-
-当计划要求 reference app 时，工具仓只把本次候选包发布到一次性、仅绑定 `127.0.0.1` 的 registry。每个候选包按精确包名注册为本地权威源且禁止回源，防止同版本公网包抢先占位或旧包被静默安装；未变化的包和普通依赖才继续从 npm 代理取得。验收副本不复用 reference worktree 的 lockfile，而是在临时目录从本轮 registry 生成一次 scratch-only lock，避免尚未物化新版本时相同预发布版本的旧 integrity 触发无意义重试；源仓锁文件不会被隐式修改。持久独立 reference app 再执行安装、契约生成、类型检查、单测、真实 NestJS 身份/Data API 进程验收和生产构建。`pnpm reference:install:from-build` 可在未公开发包时通过同一 registry 协议刷新 reference worktree 的本地依赖，避免 `file:`/`link:` 破坏独立性。公开 npm integrity 的采用由发布成功后的 `pnpm release:sync-reference` 显式执行；reference 工作树状态不会参与 registry 事务。
-
-增量门禁先用 Turbo 完成候选包及其依赖闭包的 check/test/build；全量模式完成整个 workspace。后续生成契约、tarball 黑盒、技能校验和文档构建复用已验证的 `dist`。`distribution:smoke`、`skills:check`、`docs:build` 仍保留可独立执行的自包含入口。
-
-官方工作区使用 pnpm 10 的显式依赖构建策略：只允许经过审核的 `esbuild` 生命周期脚本，并启用 `strictDepBuilds`。未来依赖若新增 install/postinstall 脚本，安装会直接失败，必须先审查并更新策略；发行物黑盒验证同时拒绝任何“已忽略构建脚本”警告，避免开发机缓存掩盖不完整安装。
-
-只运行发行物验证：
-
-```bash
-pnpm distribution:smoke
-```
-
-## 平台契约列车验收
-
-当同一候选版本还修改了 OpenXiangda 2.0 平台接口时，平台服务必须先运行自己的独立门禁：
-
-```bash
-npm run verify:openxiangda-v2:release
-```
-
-该门禁固定执行一次平台 SQL migration、全部 2.0 测试、共享出站 HTTP/存储安全测试和平台编译，再执行一次真实 OAuth2、Data API、App API、Events 与 Workflow HTTP 纵向链路。纵向链路内部已经覆盖多次进程重启、持久事件 receipt 接管和 Workflow 并发命令，不重复运行同一套测试。干净提交通过后会获得绑定提交、门禁步骤和本机 Node 运行时的 24 小时本地验收凭据；精确候选不变时发布器复用凭据，任何指纹变化都重新完整运行。根平台发布器只在 Platform Server 进入最终镜像构建计划时自动调用，并保证它发生在第一个 Docker build 之前。它与 `pnpm verify:release` 分工明确：前者证明平台实现，后者证明独立 SDK、CLI、技能、模板和真实 tarball 新应用。两边都通过后才可进入人工发布确认；任何一个命令都不会自动提交、发包或部署。

package/docs/design/admin/README.md

@@ -1,124 +0,0 @@
-# OpenXiangda 2.0 Admin 设计基线
-
-状态：2026-08-16 已退役，仅保留历史记录。新 Admin 将按 [Ant Design Pro v6 全量切换决策](../../architecture/ant-design-pro-v6-admin-foundation.md)重新设计和实现，本目录图片不再是验收基线。
-
-## 设计判断
-
-OpenXiangda 2.0 Admin 面向应用开发者、应用管理员和业务角色用户。界面采用冷静、干净、中低密度的企业级产品语言，组件与交互基于 Ant Design 6，并吸收 ProComponents 的数据管理页面模式。
-
-设计参数：
-
-- `DESIGN_VARIANCE: 4`
-- `MOTION_INTENSITY: 2`
-- `VISUAL_DENSITY: 5`
-- 单一强调色：`#1677ff`
-- 输入框与按钮圆角：8px
-- 主内容容器圆角：12px
-- 页面间距：24px
-- 表格常规行高：约 48px
-
-## 设计稿
-
-### 应用壳与工作台
-
-![应用壳与工作台](./workbench-v1.png)
-
-评审结论：
-
-- 保留侧栏、顶栏、身份切换、缓存标签栏和三列洞察区的层级。
-- 指标区降低图标装饰，数字必须来自真实接口。
-- 快捷入口采用紧凑操作带或非等宽布局，避免三张装饰性等宽卡片。
-- 待办列表不使用无语义状态点。
-- 不实现设计稿中的伪监控数字。应用模板只能展示真实可获取的数据。
-
-### 标准数据管理页
-
-![标准数据管理页](./data-management-v1.png)
-
-评审结论：
-
-- 页面由紧凑标题区、搜索区、表格工具区、数据表格和分页组成。
-- 搜索字段使用上方标签，不使用占位符代替标签。
-- 批量操作只在已选择数据时出现。
-- 导入、导出、密度、列设置和刷新归入统一工具区。
-- 空、加载、错误是互斥运行状态，设计稿底部三态条仅用于评审说明。
-- 侧栏完全由应用路由清单生成，不采用设计稿自行扩展的菜单。
-
-### 流程详情与审批任务页
-
-![流程详情与审批任务页](./workflow-detail-v1.png)
-
-评审结论：
-
-- 业务字段始终放在申请信息区，由 Data API 或 App API 保存。
-- 流程状态、当前节点和审批记录放在审批进度区。
-- 同意、拒绝、转交、回退、加签和应用自定义操作都由后端协议返回。
-- 操作确认抽屉只在执行前展示动作、下一处理人、字段变化和审批意见。
-- 不显示 BPMN 画布、引擎内部节点或低代码配置细节。
-- 侧栏完全由应用路由清单生成。
-
-## 应用壳基线
-
-- 桌面侧栏宽度 232px，折叠宽度 68px。
-- 顶栏高度 56px，标题使用当前路由名称。
-- 稳定角色切换器必须始终可见，并明确显示当前角色与数据范围。
-- 缓存标签栏支持刷新、关闭当前、关闭其他和关闭全部。
-- 页面存在未保存内容时，导航、关闭标签、切换身份和退出都进入统一的脏状态确认流程。
-- 移动端使用抽屉导航，内容区域单列排列。
-
-## 标准页面协议
-
-### 数据管理页
-
-- 必需能力：搜索、排序、分页、列配置、密度切换、刷新。
-- 可选能力：创建、编辑、详情、删除、批量操作、导入、导出。
-- 权限决定能力是否出现，不在前端复制数据权限规则。
-- 列配置和表格密度按应用、身份、资源持久化。
-- 请求失败保留现有查询条件，并提供就地重试。
-
-### 表单提交页
-
-- 标题区包含返回、页面标题和简短说明。
-- 表单正文使用最大宽度约束，字段标签位于控件上方。
-- 主操作为保存或提交，取消为次操作。
-- 字段错误就地展示，服务器错误保留已填写内容。
-- 页面离开、标签关闭、身份切换时接入统一脏状态管理。
-
-### 表单详情页
-
-- 标题区包含业务标题、状态、关键元数据和允许的操作。
-- 字段信息按业务分组显示，不把所有字段堆进一个大表格。
-- 文件、长文本和子表拥有独立展示区。
-- 编辑入口由能力和字段策略共同决定。
-
-### 流程提交页
-
-- 业务字段表单和流程预览分区展示。
-- 提交前解析主部门、角色身份、审批人和条件分支。
-- 预览结果由后端返回，前端不自行模拟审批人解析。
-- 提交失败保留业务字段和准备阶段答案。
-
-### 流程详情页
-
-- 业务数据与流程状态分离。
-- 审批流只展示条件分支、审批节点、处理人、状态、时间和意见。
-- 当前允许操作完全由 Workflow Surface 协议返回。
-- 应用自定义操作与标准操作共享确认、幂等、审计和结果刷新机制。
-
-### 工作台
-
-- 指标、图表和待办必须来自真实 Data API、App API 或 Workflow API。
-- 快捷入口由应用声明，不在框架写死业务菜单。
-- 页面提供加载、空和错误状态。
-- 图表延迟加载，避免进入应用时加载全部 ECharts 代码。
-
-## 实现预检
-
-- 页面只使用一个主题和一个强调色。
-- 不使用渐变、玻璃效果、紫色光晕和装饰性状态点。
-- 卡片只用于表达层级，不给每个内容块套卡片。
-- 所有按钮文本在桌面端保持单行。
-- 表单标签、占位符、帮助文本和错误文本满足可读性要求。
-- 空、加载、错误、无权限和成功状态都可独立验证。
-- 所有 Admin 页面在 1440px、1024px 和移动端宽度下通过布局验证。
-- 所有新增 Ant Design API 在编码前通过本地 `antd` CLI 按 6.4.2 版本核对。

package/docs/design/admin-pro-v6/README.md

@@ -1,26 +0,0 @@
-# OpenXiangda Admin Pro v6 设计基线
-
-状态：2026-08-16 已评审，作为 Ant Design Pro v6 全量切换的实现输入。
-
-这组设计是信息架构、视觉层级、布局几何、密度、操作顺序和状态表现的可执行验收合同。最终实现必须使用锁定的 Ant Design Pro v6、ProComponents 与 Ant Design 6 公共 API，并以真实浏览器、可访问性、协议和截图回归共同验收。业务数据不要求与稿件相同，但不能用组件库默认样式、临时 CSS 或“仅参考信息架构”解释明显的视觉与交互偏差。
-
-## 设计参数
-
-- 模式：2.0 全量重构，不保留旧 Shell 或旧页面兼容层。
-- 视觉变化：3/10；动效：2/10；信息密度：6/10。
-- 主题：统一浅色；冷灰背景、白色内容面、单一 Ant Design 蓝色强调。
-- 形状：控件与内容面统一 8px 圆角，细边框优先，阴影克制。
-- 操作：一个操作面只有一个主动作；错误、空、加载和重试是必需状态。
-- 内容：普通用户只看到业务标签，内部 UUID、环境 key、角色/权限 code、流程节点 key 和原始 JSON 不进入默认页面。
-
-## 已评审界面
-
-| 界面 | 文件 | 评审结论 |
-| --- | --- | --- |
-| 工作台 | [workbench.png](./workbench.png) | 保留 ProLayout、环境入口、标签缓存、待办、快捷入口和受限聚合；实现时把四色大图标收敛为单一主色/必要语义色。 |
-| 标准数据管理 | [data-management.png](./data-management.png) | 使用 ProTable 搜索、服务端排序/分页、列配置、密度和行操作；空状态只在无结果时替换表格，不与有数据列表同时出现。 |
-| 流程提交 | [workflow-submit-modal.png](./workflow-submit-modal.png) | 页面只保留“提交申请”主按钮；点击后 prepare 并在 Modal 展示真实审批路径，确认后用稳定幂等键启动流程。 |
-
-示例业务统一使用企业采购申请，只作为验收载体；采购领域代码不得进入 `openxiangda-admin`。
-
-完整重建阶段、能力所有权和机器验收见[最佳实践模板重建计划](../../architecture/best-practice-template-rebuild-v2.md)。

package/docs/design/admin-v2/README.md

@@ -1,60 +0,0 @@
-# OpenXiangda Admin v2 标准页面设计基线
-
-状态：2026-08-16 已退役，仅保留为历史评审记录。新的实现基线是 [Ant Design Pro v6 Admin 全量切换决策](../../architecture/ant-design-pro-v6-admin-foundation.md)，实施前将按 Pro v6 重新形成设计稿并评审。
-
-> 本目录关于“不引入 ProComponents 运行时”和“流程提交常驻双栏审批预览”的结论已经废止，图片不得再用于实现验收。保留图片只为解释过去的产品判断和迁移输入。
-
-适用范围：OpenXiangda 2.0 新应用。本文和配套设计稿不承担 1.x 兼容，不改变 1.x 页面、流程或自动化运行时。
-
-## 1. 设计结论
-
-OpenXiangda 2.0 的 Admin 使用一套平台官方 React 管理端框架。应用声明路由、菜单、字段、数据资源、流程定义与业务扩展；框架提供壳层、身份、导航、标签、页面生命周期和标准页面。
-
-- 主设计系统：Ant Design 6.4.2。
-- 交互参考：ProLayout、ProTable、ProForm 的成熟模式；不引入与 Ant Design 6 没有声明兼容的 ProComponents 运行时，也不建立第二套查询和页面状态。
-- 视觉方向：企业级 B 端，低到中信息密度，单一蓝色主色，冷灰背景，白色内容面，边框优先、阴影克制。
-- 设计参数：视觉变化度 4/10、动效 2/10、信息密度 5/10。
-- 桌面基线：1440×900；侧栏 232px，顶栏 56px，标签栏 40px。中等宽度变为单列，移动端使用抽屉导航与非粘性操作区。
-- 圆角只使用两级：控件 6px、内容面 8px；不使用胶囊按钮、玻璃拟态、渐变背景或无业务含义的彩色图标。
-- 一个操作面只保留一个主按钮。危险操作、流程拒绝和高级操作使用语义样式与明确确认。
-
-## 2. 已评审页面
-
-| 页面 | 设计稿 | 实现归属 | 评审决定 |
-| --- | --- | --- | --- |
-| 工作台与壳层 | [workbench.png](./workbench.png) | `ApplicationShell`、`DashboardPage` | 固定导航、身份与范围、标签缓存、四项指标、趋势、待办、快捷入口和最近访问形成统一首屏。侧栏必须使用纯色 token。 |
-| 数据管理 | [data-management.png](./data-management.png) | `DataListPage` | 页头、显式搜索、工具栏、跨页选择、列设置、密度、服务端排序与分页属于一个标准工作台；Data API 是查询事实源。 |
-| 表单提交 | [form-submit.png](./form-submit.png) | `DataFormPage` | 支持分区、两列/整行字段、文件、字段帮助、脏状态和稳定操作区；右侧说明是可选 contribution，不强制简单表单双栏。 |
-| 表单详情 | [form-detail.png](./form-detail.png) | `DataRecordPage` | 业务字段、文件和操作记录分层；不显示 revision、数据库字段或内部协议值。快捷业务动作由应用贡献。 |
-| 流程提交 | [workflow-submit.png](./workflow-submit.png) | `WorkflowSubmissionPage` | 左侧保存业务数据，右侧预览审批节点、条件分支、审批人和主部门；隐藏事件、服务任务和内部自动化节点。 |
-| 流程详情/任务 | [workflow-detail.png](./workflow-detail.png) | `WorkflowSurfacePage` | 业务字段、审批记录与当前任务三层清晰；字段策略和允许操作只消费后端 Surface，前端不复制流程规则。 |
-
-设计图是信息架构和视觉协议，不是要求逐像素复制的静态页面。图片中的示例名字、数量和日期都是演示数据，不得进入平台默认业务事实。
-
-## 3. 组件与协议映射
-
-| 设计区域 | Ant Design 基础 | OpenXiangda 所有权 |
-| --- | --- | --- |
-| 应用壳 | `Layout`、`Menu`、`Tabs`、`Drawer`、`Dropdown`、`Avatar` | 路由 manifest、菜单裁剪、标签持久化、keepAlive、身份 epoch、个人中心 |
-| 页面标题 | `Typography`、`Button`、`Space/Flex` | `PageHeader`：返回、标题、描述、状态与单一主操作 |
-| 工作台 | `Statistic`、`Card`、`List`，ECharts 按需加载 | 指标独立请求/错误/重试，流程待办使用服务端 `total` |
-| 数据页 | `Form`、`Table`、`Pagination`、`Popover/Dropdown` | Data API 服务端筛选、排序、分页、字段策略、revision CAS、资源失效 |
-| 表单/详情 | `Form`、`Descriptions`、`Upload`、`Tabs`、`Timeline` | 字段声明、文件适配、脏状态、审计读取和应用动作 contribution |
-| 流程页 | `Steps/Timeline`、`Descriptions`、`Form`、`Alert`、`Button` | Workflow Kernel preview/surface、参与者解析、字段策略、后端允许操作 |
-
-## 4. 状态与可访问性
-
-每个标准页面都必须具备 loading、empty、error、retry、disabled 和 permission-denied 状态。加载失败不能伪装成空数据；权限隐藏不能替代后端授权。
-
-- 所有输入具备可见标签，必填、帮助和校验信息不只依赖颜色。
-- 表格行点击只能是鼠标快捷方式，必须提供可聚焦的“查看/处理”操作。
-- 图表必须有可访问名称，并在无数据或失败时回退为语义状态组件。
-- 隐藏保活页面必须同时 `hidden`、`inert` 与 `aria-hidden`。
-- 身份、角色、租户、环境或授权 epoch 变化时，旧页面实例、查询和选择状态必须失效。
-- 移动端不固定底部操作区，不让流程操作遮挡字段或浏览器安全区域。
-
-## 5. 设计生成与评审记录
-
-本组图片使用内置图片生成能力分别生成，每张图只对应一个标准页面。提示词共同约束为：`production-realistic Ant Design 6 enterprise admin UI, Chinese B2B, 1440x900, medium-low density, solid deep navy navigation, one cobalt primary color, flat-first borders, no gradients/glassmorphism/marketing hero`，再分别补充工作台、数据列表、表单提交、表单详情、流程提交和流程任务的真实字段与操作。
-
-工作台首稿在评审后又做了一次定向编辑：侧栏改为纯色，快捷入口去除绿/紫装饰色，指标只保留必要语义色。其余五张的结构与视觉约束一次通过；实现阶段仍以 Ant Design token、真实协议和响应式验收为最终证据。

package/docs/design/openxiangda-2.0-high-fidelity/README.md

@@ -1,293 +0,0 @@
-# OpenXiangda 2.0 三端标准页面高保真设计
-
-本目录定义 OpenXiangda 2.0 的标准后台、业务用户 PC 端和移动端页面基线。设计以 OpenXiangda 1.0 已验证的字段功能、交互和移动适配为行为基线，只把稳定值、文件事务、工作流解析和页面生命周期迁移到 2.0 协议。
-
-这些稿件不是概念海报。每张图对应一个可实现、可测试、可截图回归的产品页面或关键交互状态。
-
-## 设计判断
-
-- 产品类型：面向应用管理员和业务用户的企业操作型产品。
-- 视觉语言：克制、可信、高信息密度的 Ant Design 和 Ant Design Mobile。
-- `DESIGN_VARIANCE`: 4。
-- `MOTION_INTENSITY`: 2。
-- `VISUAL_DENSITY`: 7。
-- 重设计模式：保留 1.0 的成熟功能和交互，重构 2.0 协议与页面封装。
-- 单一组件系统：桌面端使用 Ant Design，移动端使用 Ant Design Mobile，不混入第二套视觉组件库。
-
-## 页面清单
-
-### 后台管理端
-
-| 页面 | 文件 | 评审重点 |
-| --- | --- | --- |
-| 工作台 | `admin-workbench.png` | 管理导航、指标、待办、趋势、快捷入口、活动时间线 |
-| 数据列表与新建抽屉 | `admin-data-form.png` | 服务端查询、表格、分页、表单校验、上传中和上传成功 |
-| 组件验收 | `admin-component-acceptance.png` | 字段分组、文件状态、图片、定位、签名、富文本、只读和错误计数 |
-
-![后台工作台](admin-workbench.png)
-
-![后台数据列表与表单](admin-data-form.png)
-
-![后台组件验收](admin-component-acceptance.png)
-
-### 业务用户 PC 端
-
-| 页面 | 文件 | 评审重点 |
-| --- | --- | --- |
-| 工作台 | `user-pc-workbench.png` | 独立用户壳层、待办、快捷发起、流程配置提醒、我的申请 |
-| 我的申请 | `user-pc-data-list.png` | 状态切换、服务端筛选、列表选中、详情抽屉、附件和分页 |
-| 发起申请与审批预览 | `user-pc-form-workflow-preview.png` | 详细表单、文件生命周期、定位、签名、审批人实时解析和提交校验 |
-
-![业务用户 PC 工作台](user-pc-workbench.png)
-
-![业务用户 PC 申请列表](user-pc-data-list.png)
-
-![业务用户 PC 发起申请与审批预览](user-pc-form-workflow-preview.png)
-
-### 移动端
-
-| 页面 | 文件 | 评审重点 |
-| --- | --- | --- |
-| 工作台 | `mobile-workbench.png` | 拇指操作区、待办、快捷入口、最近事项、流程提醒、底部导航 |
-| 采购申请列表 | `mobile-data-list.png` | 搜索、状态筛选、卡片列表、浮动新建入口 |
-| 发起采购申请 | `mobile-form.png` | 单列字段、显式必填星号、内联错误、附件去重、图片、定位、签名 |
-| 提交与审批预检 | `mobile-submit-workflow-preflight.png` | 底部弹层、审批人缺失、业务化错误、阻止无效提交 |
-| 流程任务详情 | `mobile-workflow-detail.png` | 表单摘要、附件、流程时间线、审批意见、驳回和同意 |
-
-![移动工作台](mobile-workbench.png)
-
-![移动采购申请列表](mobile-data-list.png)
-
-![移动采购申请表单](mobile-form.png)
-
-![移动提交与审批预检](mobile-submit-workflow-preflight.png)
-
-![移动流程任务详情](mobile-workflow-detail.png)
-
-目录中的 `user-pc-request-list.png`、`user-pc-request-form-approval.png`、`mobile-request-list.png`、`mobile-request-form.png` 和 `mobile-approval-preview.png` 是第一轮方案探索稿。上述页面清单中的文件是本轮实施基线，截图回归和组件落地以实施基线为准。
-
-## 视觉 Token
-
-### 颜色
-
-| Token | 建议值 | 用途 |
-| --- | --- | --- |
-| `colorPrimary` | `#1677FF` | 主按钮、选中态、链接、当前流程节点 |
-| `colorText` | `#101828` | 主标题和主要信息 |
-| `colorTextSecondary` | `#667085` | 元数据、帮助文本和次级说明 |
-| `colorBgLayout` | `#F5F7FA` | 页面背景 |
-| `colorBgContainer` | `#FFFFFF` | 表单、列表和浮层 |
-| `colorBorder` | `#E4EAF1` | 控件和容器边界 |
-| `colorSuccess` | `#12B76A` | 已通过、已匹配和已完成 |
-| `colorWarning` | `#F79009` | 即将超时、上传提醒和非阻断异常 |
-| `colorError` | `#F04438` | 必填错误、流程阻断和驳回 |
-
-语义色只表达真实状态，不用于装饰。页面不使用紫色渐变、玻璃拟态或外发光。
-
-### 字体与字号
-
-- 字体栈：系统中文无衬线字体，保持 Ant Design 默认可读性和跨平台稳定性。
-- 桌面页面标题：24px，600。
-- 桌面分区标题：16px，600。
-- 桌面正文和控件：14px。
-- 移动导航标题：18px，600。
-- 移动分区标题：16px，600。
-- 移动字段标签和正文：14px 至 16px。
-- 表格数字、金额和编号保持等宽数字特性，右对齐金额。
-
-### 间距与形状
-
-- 基础间距单位：4px。
-- 桌面内容间距：16px、20px、24px。
-- 移动页面边距：12px 至 16px。
-- 桌面控件圆角：8px。
-- 移动分区圆角：12px。
-- 标签和状态 Tag 可使用 6px 圆角，不使用装饰性胶囊。
-- 桌面控件高度：32px 至 40px。
-- 移动可点击区域最小高度：44px。
-- 阴影只用于抽屉、弹层、底部操作栏和真正有层级关系的表面。
-
-## 页面壳层
-
-### 后台管理端
-
-- 顶栏高度 64px。
-- 左侧导航宽度 248px。
-- 导航选中态使用浅蓝底和主色文字。
-- 主内容区允许高密度表格、查询区、抽屉和组件验收页面。
-- 数据查询、分页、权限、加载和错误由页面控制器统一管理。
-
-### 业务用户 PC 端
-
-- 顶栏高度 64px，不显示后台管理导航。
-- 工作台和数据列表允许使用 208px 个人视图侧栏，只承载我的待办、我的申请、抄送和草稿等个人范围导航。
-- 聚焦表单不显示个人侧栏，使用返回路径、主表单和审批预览三段结构。
-- 主内容在 1280px 至 1586px 桌面宽度内保持稳定信息密度。
-- 工作台、发起申请、我的申请、待办审批和消息共享一个独立用户 renderer。
-- 表单页使用主表单加审批预览双栏布局。窄屏时审批预览下移或切换为抽屉。
-
-### 移动端
-
-- 使用安全区，底部操作栏不覆盖系统手势区域。
-- 一级页面使用底部导航，表单、预览和任务详情不重复显示底部导航。
-- 表格转换为可扫描的单列记录，不把桌面表格压缩到移动屏幕。
-- 表单标签置于控件上方，错误紧贴当前字段。
-- 固定提交栏只包含当前页面最重要的操作。
-
-## 标准字段分组
-
-组件验收页按以下组组织。实现阶段需通过 1.0 registry 逐项校对具体字段名、默认值、编辑器和移动端行为。
-
-| 分组 | 字段能力 |
-| --- | --- |
-| 基础字段 | 单行文本、多行文本、数字、金额、日期、日期范围、时间、开关 |
-| 选择字段 | 单选、多选、下拉、级联选择 |
-| 组织与关联 | 人员、部门、关联记录、子表 |
-| 文件与媒体 | 附件、图片、上传进度、预览、下载、删除、失败重试 |
-| 高级字段 | 定位、签名、富文本 |
-| 布局容器 | 分区、栅格、说明、只读详情容器 |
-
-每个字段至少验收以下状态：
-
-- 空值和默认值。
-- 可编辑、只读和禁用。
-- 必填、格式、长度和业务校验错误。
-- 加载、空态和请求失败。
-- PC 和移动端输入方式。
-- 稳定值序列化、反序列化和提交回显。
-
-## 文件与图片交互
-
-附件和图片只允许一条状态链：
-
-1. 用户选择文件。
-2. 客户端校验类型、大小和数量。
-3. 创建唯一的本地上传项。
-4. 显示上传进度和取消操作。
-5. 上传成功后用平台文件引用替换本地项。
-6. 稳定身份去重后回写字段值。
-7. 表单提交时绑定业务记录。
-8. 删除时同步更新展示值和稳定值。
-
-禁止同时维护 Ant Upload 内部列表和第二份业务列表。文件身份优先使用平台文件 ID，其次使用稳定上传 ID，不使用文件名作为唯一身份。
-
-错误处理：
-
-- 文件字段未在资源协议声明时，字段附近显示可操作错误，不继续产生孤儿文件。
-- 上传失败保留文件名、失败原因和“重试”操作。
-- 上传中阻止最终提交，但允许保存草稿。
-- 同一文件不得在成功回调后重复展示。
-
-## 定位、签名和富文本
-
-### 定位
-
-- 编辑态显示地址、定位图标、经纬度和重新定位。
-- 移动端优先打开全屏选择器或地图页。
-- 拒绝定位权限时显示原因和手动选择入口。
-- 只读态显示规范化地址，不直接显示原始 JSON。
-
-### 签名
-
-- 编辑态提供手写画布、清除、重签和签名时间。
-- 移动端画布应支持横屏或扩大输入区域。
-- 稳定值包含有界 PNG data URL、轨迹、时间戳和哈希。
-- 只读态提供清晰预览，不显示可编辑工具。
-
-### 富文本
-
-- 工具栏只保留业务表单常用格式。
-- 编辑值提交前做安全清洗，只读渲染再次做安全处理。
-- 平台未提供嵌套文件事务绑定前，不开放会产生孤儿文件的本地图片上传。
-- 移动端使用简化工具栏，不压缩桌面工具栏。
-
-## 表单与错误
-
-- 所有必填字段在桌面和移动端都显示红色 `*`。
-- 字段错误紧贴控件下方，不只使用 Toast。
-- 首次提交失败后滚动并聚焦第一个错误字段。
-- 页面级错误只用于跨字段、权限、网络或工作流阻断。
-- 保存草稿允许未完成字段，但必须保存完整稳定值状态。
-- 正在上传、签名未完成或审批人解析失败时禁用最终提交。
-
-## 工作流解析
-
-`WORKFLOW_V2_APPROVER_RESOLUTION_EMPTY:department-review` 不能被前端吞掉，也不能自动回退到任意审批人。
-
-标准映射：
-
-- 用户消息：`产品部未配置部门负责人，暂时无法提交`。部门名称来自当前表单上下文。
-- 影响：提交按钮禁用。
-- 修复建议：`请先为产品部配置部门负责人`。
-- 辅助操作：`查看处理方式`、`联系管理员`、`返回修改`。
-- 管理员工作台同时显示流程配置提醒。
-
-审批预览必须基于当前表单数据实时计算，并展示条件分支、匹配到的审批人和未解析节点。
-
-## 状态规范
-
-### 加载
-
-- 使用与最终布局一致的骨架屏。
-- 上传进度使用文件行内进度，不用全屏转圈。
-- 审批预览重新计算时保留原布局，局部展示加载状态。
-
-### 空态
-
-- 空列表说明原因并提供唯一的下一步操作。
-- 无最近事项时不占用大面积空白。
-- 空文件字段显示选择文件和限制说明。
-
-### 错误
-
-- 字段错误行内显示。
-- 网络错误保留用户输入并提供重试。
-- 权限错误说明缺少的权限和申请入口。
-- 工作流错误展示业务语言，同时保留可观测的技术错误码供日志使用。
-
-### 只读
-
-- 只读字段保持与编辑态相同的信息顺序。
-- 隐藏编辑按钮和上传入口。
-- 附件保留预览和下载，是否允许下载由权限策略决定。
-
-## 动效
-
-- 动效只服务于反馈和状态变化。
-- 控件按下使用轻微缩放或位移，持续时间 120ms 至 180ms。
-- 抽屉和底部弹层使用 200ms 至 240ms 的进入和退出。
-- 上传进度平滑更新，不使用循环装饰动画。
-- 尊重 `prefers-reduced-motion`。
-
-## 可访问性与验收尺寸
-
-- 正文和控件文字满足 WCAG AA 对比度。
-- 错误不能只靠颜色表达，必须包含文字或图标。
-- 键盘焦点清晰可见。
-- 桌面重点截图尺寸：1586x992。
-- 移动重点截图尺寸约 852x1844，对应约 430px 逻辑宽度的高分屏设备。
-- 额外验证宽度：1440、1280、1024、768、430、390、375、320。
-
-## 生成说明
-
-- 生成方式：Codex 内置 `imagegen`。
-- 用例分类：`ui-mockup`。
-- 用户提供的图片只作为现状问题和信息结构参考。
-- 后台、业务 PC 和移动端分别使用上一张已确认稿作为风格锚点，保证三端同源但壳层独立。
-- 生成提示分别约束了页面结构、可见中文、上传状态、必填错误、审批分支和禁止项。
-- 最终图片已经复制到本目录，项目文档不依赖默认生成目录。
-
-## 实施验收
-
-设计落地后至少覆盖：
-
-1. 全量 1.0 字段矩阵和 PC、移动交互对照。
-2. 文件唯一状态链和重复回显回归测试。
-3. 图片字段资源声明和上传、绑定、删除测试。
-4. 定位权限允许、拒绝和手动选择测试。
-5. 签名输入、清除、重签、只读和稳定值测试。
-6. 富文本编辑、清洗、只读和移动工具栏测试。
-7. 必填错误、保存草稿、提交聚焦和移动底栏测试。
-8. 审批人解析成功、空结果和条件分支测试。
-9. 后台、业务 PC 和移动端 Playwright 截图回归。
-10. 构建、Changeset、发布门禁和发布后冒烟测试。