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

package/docs/architecture/field-component-migration-matrix-v1-to-v2.md

@@ -0,0 +1,79 @@
+# OpenXiangda 1.x → 2.0 全量字段组件迁移矩阵
+
+状态：2026-08-18 已实现并验证
+
+关联决策：[`proven-field-components-and-standard-surfaces-v2.md`](./proven-field-components-and-standard-surfaces-v2.md)
+
+1.x 基线：`tools/openxiangda/packages/sdk/src/components/core/defaultRegistry.ts`
+
+## 1. 迁移原则
+
+- “复用 1.0”指复用已经验证的功能、信息顺序、交互状态、错误反馈和移动端适配，不在 2.0
+  包中建立对 1.x 源码、运行时、工作区或发布接口的依赖。
+- 2.0 只保留一套稳定值。兼容输入只允许在明确的归一化边界内发生，提交后必须收敛到本表定义的
+  2.0 稳定值。
+- Desktop 和 Mobile 共享稳定值、校验规则、文件控制器和错误语义，使用独立 renderer 实现。
+- 每个组件必须覆盖编辑、只读、禁用、必填、空值、加载、失败、提交回显；文件类组件额外覆盖
+  上传、进度、取消、重试、预览、下载、删除和稳定身份去重。
+- 页面布局容器不冒充字段。分区、栅格、说明、列表/详情容器由 Surface/Page 层实现。
+
+## 2. Registry 全量映射
+
+| 1.x Registry 名称 | 2.0 `FieldKind` | 2.0 稳定值 | Desktop / Mobile 行为基线 | 当前实施状态 |
+| --- | --- | --- | --- | --- |
+| `TextField` | `text` | `string \| null` | 单行输入、placeholder、长度/必填、只读文本 | 已完成，纳入回归 |
+| `NumberField` | `number` / `money` / `percent` | `number \| null` | 数值边界、精度、单位；移动数字输入 | 已完成，纳入回归 |
+| `TextAreaField` / `TextareaField` | `textarea` | `string \| null` | 多行自适应、长度/必填、只读换行 | 已完成，纳入回归 |
+| `SelectField` | `option` | `{label,value} \| null` | 搜索、清空、禁用项、稳定标签回显 | 已完成，纳入回归 |
+| `MultiSelectField` | `options` | `{label,value}[]` | 多选、响应式标签、移动 Popup/CheckList | 已完成，纳入回归 |
+| `RadioField` | `radio` | `{label,value} \| null` | 单选组、禁用项、只读标签 | 已完成，纳入回归 |
+| `CheckboxField` | `checkbox` | `{label,value}[]` | 多选组、禁用项、只读标签集合 | 已完成，纳入回归 |
+| `DateField` | `date` / `datetime` | ISO/格式化日期字符串或 `null` | 日期与日期时间选择、清空、只读格式化 | 已完成，纳入回归 |
+| `CascadeDateField` | `dateRange` | `[start,end]` | 成对日期、范围校验、移动分步选择 | 已完成，纳入回归 |
+| `AttachmentField` | `attachments` | `StableAttachmentValue[]` | 上传进度、取消/重试、预览、下载、删除、同名文件不合并 | 已完成 |
+| `ImageField` | `images` | `StableAttachmentValue[]`，`variant=image` | 图片选择、缩略图、预览、上传状态、删除 | 已完成 |
+| `SubFormField` | `subtable` | `Record<string,unknown>[]` | 行增删、子字段编辑、最少/最多行、只读明细 | 已完成 |
+| `UserSelectField` / `EmployeeSelectField` | `user` / `users` | `{label,value}` 或数组 | 组织树、搜索、单/多选、已选回显 | 已完成，纳入回归 |
+| `DepartmentSelectField` | `department` / `departments` | `{label,value}` 或数组 | 部门树、路径、搜索、单/多选 | 已完成，纳入回归 |
+| `CascadeSelectField` | `cascade` | `{label,value}[]` 路径 | 级联路径、叶子选择、清空、只读路径 | 已完成，纳入回归 |
+| `AddressField` | `address` | `StableAddressValue` | 省市区级联、详细地址、完整地址回显 | 已完成，纳入回归 |
+| `AssociationFormField` | `relation` | `{label,value}` 或数组 | 资源检索、分页、稳定 record id、只读跳转信息 | 已完成，纳入回归 |
+| `EditorField` | `richtext` | 清洗后的 HTML `string` | 常用格式、链接安全、移动简化工具栏、只读二次清洗 | 已完成 |
+| `SerialNumberField` | `serial` | 平台生成的 `string \| null` | 创建前占位、创建后只读，不允许客户端伪造 | 已完成，纳入回归 |
+| `LocationField` | `location` | `StableLocationValue` | 钉钉优先、浏览器降级、地址/坐标/精度、重定位/清空 | 已完成 |
+| `DigitalSignatureField` | `signature` | `StableSignatureValue` | 手写、清空/重签、预览、轨迹/时间/哈希、有界 PNG | 已完成 |
+| `JSONField` | `json` | JSON value | 编辑时语法错误、格式化、只读结构展示 | 已完成，纳入回归 |
+
+## 3. 2.0 原生扩展
+
+以下能力不需要伪装成 1.x Registry 项，但必须服从相同的三端状态和稳定值规则：
+
+| `FieldKind` | 用途 | 稳定值与边界 |
+| --- | --- | --- |
+| `boolean` | 业务开关 | `boolean`；只读显示明确“是/否”语义 |
+| `workflowStatus` | 流程状态投影 | `{label,value}`；只读为主，不维护第二份流程状态 |
+| `departments` / `users` | 组织多选变体 | `{label,value}[]`；复用目录合同和 RoleSession |
+
+## 4. 页面层组件
+
+1.x 中已验证但不属于字段 Registry 的页面能力迁移到标准 Surface/Page：
+
+| 能力 | 2.0 所有者 | 三端要求 |
+| --- | --- | --- |
+| 表单分区、说明、栅格 | Admin/User Surface | Desktop 高密度双列；Mobile 单列分区 |
+| 搜索、筛选、列表、分页 | Admin/User Data Page | 服务端查询；移动端卡片列表，不压缩桌面表格 |
+| 详情与只读容器 | Admin/User Detail Page | 保持字段顺序；文件仍可按权限预览/下载 |
+| 草稿、提交与首错定位 | Form Controller | 草稿允许未完成；提交阻止上传中与字段错误 |
+| 审批预检 | Workflow Page | 保存业务数据并 prepare 成功后，Desktop Modal / Mobile Popup 打开 |
+| 工作台、待办、我的申请 | User/Admin Shell | 同一 RoleSession/Data/Workflow API，不复制状态源 |
+
+## 5. 验收清单
+
+- Registry 中 22 个名称全部有明确的 2.0 映射，`EmployeeSelectField` 和 `TextareaField` 作为别名
+  不重复实现。
+- 每种 `FieldKind` 至少有值归一化测试；关键字段有 Desktop、Mobile、只读和失败态测试。
+- `attachments` 与 `images` 只能绑定到真实声明为 `file` 的 DataResource 字段。
+- 同名不同 `fileId` 的文件保留两份；相同 `fileId` 或同一稳定 URL 只显示一份。
+- Mobile renderer 的依赖图不得包含 Desktop `antd`。
+- 业务 PC、Mobile、Admin 示例使用同一套 FieldDefinition 和后端合同，页面组合可以独立。
+- 1.x 源码、包名、工作区探测与发布 API 不得进入任何 2.0 可发布包。

package/docs/architecture/proven-field-components-and-standard-surfaces-v2.md

@@ -0,0 +1,125 @@
+# 经过验证的平台字段组件与三端标准页面决策
+
+状态：2026-08-18 已实现并通过开发、三端与完整本地运行时验证
+
+适用范围：OpenXiangda 2.0 `openxiangda-contracts`、`openxiangda-field-kit`、
+`openxiangda-user`、官方应用模板及其本地验收夹具。OpenXiangda 1.x 运行时、
+工作区识别、发布协议和已部署应用不在改动范围内。
+
+## 1. 问题证据
+
+当前 2.0 参考应用暴露了四类可复现问题：
+
+1. Desktop 附件组件同时组合受控稳定值与 Ant Upload 内部 `fileList`。上传成功后，
+   业务值加入一份完成项，Ant Upload 的成功回调又保留一份本地项，导致相同附件重复显示。
+2. 组件验收页以 `purchase_requests` 作为文件上下文，却上传字段 `images`；该资源只声明
+   `attachments` 为 `file`，平台按声明失败关闭并返回
+   `OPENXIANGDA_NATIVE_DATA_FILE_FIELD_INVALID:images`。
+3. `location` 和 `signature` 在 Desktop/Mobile 仅渲染只读文本，`richtext` 退化为多行文本；
+   图片和附件的移动交互也缺少 1.x 已验证的进度、预览、失败重试和清理生命周期。
+4. 移动 Form.Item 没有显式投影 `required` 标记；参考应用本地部门审批绑定在选择部门后
+   找不到该范围内的 `department_manager` 成员，提交返回
+   `WORKFLOW_V2_APPROVER_RESOLUTION_EMPTY:department-review`。
+
+现有移动工作台虽然具备基本数据和导航，但卡片比例、信息密度、表单分区、提交前审批预览
+和流程详情没有达到 2026-08-18 验收稿的结构与视觉基线。
+
+## 2. 能力所有者
+
+| 能力 | 唯一所有者 |
+| --- | --- |
+| 附件、图片、位置、签名及富文本稳定值 | `openxiangda-contracts` |
+| 字段输入、只读展示、上传状态机、预览与端侧交互 | `openxiangda-field-kit` |
+| 文件声明、上传票据、内容读取、绑定与孤儿清理 | OpenXiangda Platform Native Data API |
+| 身份、RoleSession、目录和数据范围 | OpenXiangda Platform |
+| 流程准备、审批人解析、动作与审计 | Workflow Kernel v2 |
+| Admin 桌面页面组合 | `openxiangda-admin` 与应用 Admin routes |
+| 业务用户 Desktop/Mobile 页面组合 | `openxiangda-user` 的独立 renderer |
+| 采购领域字段、文案和路由贡献 | 官方参考应用 |
+
+1.x 源码只作为行为、交互和测试基线。2.0 包不得导入 1.x 模块、探测 1.x 工作区、调用
+1.x API，或复制 1.x 的页面壳和发布生命周期。
+
+## 3. 稳定不变量与受影响合同
+
+1. 附件和图片继续保存 `StableAttachmentValue[]`，人员/部门继续保存
+   `{ label, value }`，位置继续保存 `StableLocationValue`；不得新增第二种兼容值格式。
+2. 签名值必须成为 contracts 中明确版本的稳定 JSON 值，沿用 1.x 的预览、轨迹、时间戳和
+   哈希语义。当前 Native Data 只允许文件绑定到 `file` 字段，签名 JSONB 不得借用旁路文件字段；
+   本轮使用有界 PNG data URL，后续若引入嵌套文件绑定必须单独版本化协议。浏览器不保存对象存储凭据。
+3. 富文本持久化为经过清洗的 HTML 字符串，空值为 `null` 或空字符串；只读展示禁止执行
+   script、事件属性和危险 URL。
+4. 每个文件上传必须绑定一个真实 DataResource `file` 字段。组件验收使用独立的验收资源，
+   不增加绕过声明的通用上传 API，也不把测试字段混入采购业务资源。
+5. 文件 UI 只维护一个受控生命周期：`local/uploading -> stable/done` 或 `error`。
+   替换和去重使用本地 uid、`fileId` 和稳定 URL 的确定性标识；成功回调不得追加第二份条目。
+6. Desktop 与 Mobile 共享值归一化、上传控制器、错误模型和能力边界，但分别实现布局、
+   选择器、预览和动作区域。设备分支只在用户端入口选择，不把 Desktop 控件缩放成 Mobile。
+7. `required` 是 Surface 的视觉和客户端校验投影；NestJS/App API、Data API 与 Workflow
+   仍是业务必填和授权的最终裁决者。
+8. 审批人为空必须继续失败关闭。参考夹具应提供与所选部门范围匹配的真实角色成员，
+   不允许前端默认审批人、回退发起人或隐藏错误。
+9. Admin、业务用户 PC 与 Mobile 使用相同 route/data/workflow 合同；三端可以有独立页面组合，
+   不能维护第二份数据、权限或流程状态。
+
+公开受影响面包括：contracts 的签名值类型、Field Kit 的 Desktop/Mobile 导出与样式、
+User 包的 Desktop 入口、模板 DataResource/Surface/fixture、参考应用路由与测试。Native Data
+API 的文件安全语义和现有 URL 不变化。
+
+## 4. 失败、并发与清理行为
+
+- 同一控件的并发上传有独立 abort/progress 状态；单个失败不覆盖其他文件，重复选择按稳定标识去重。
+- 超出数量、大小或 accept 规则在上传前显示字段内错误；服务端仍重复校验并返回权威错误。
+- 组件卸载或取消未完成上传时中止请求；已经取得票据但未完成的文件继续由平台未绑定文件清理兜底。
+- 删除未绑定文件调用现有删除接口；已绑定文件只从候选表单值移除，由记录更新事务执行绑定/孤儿转换。
+- 预览 Object URL 在关闭、替换和卸载时释放；预览失败保留下载动作和可重试错误。
+- 定位优先使用钉钉能力，失败后降级浏览器 Geolocation；超时、拒绝和不支持分别显示可恢复错误。
+- 签名保存只接受非空轨迹，生成图片和哈希任一步失败都不覆盖原值；重复保存以最后一次成功值为准。
+- 富文本迁移 1.x 的格式编辑与安全只读能力；在平台提供可事务绑定的嵌套文件合同前，工具栏不开放
+  会产生未绑定文件的本地图片上传。编辑器销毁后不得提交迟到回调。
+- Workflow prepare/start 使用既有 revision、token 和幂等键；审批人解析为空时保留节点编码并引导修正配置。
+
+## 5. 安全与资源上限
+
+- 默认附件最多 10 个、单个 50MB；字段声明可以收紧，不能由页面放宽平台声明。
+- 默认图片最多 9 个、单个 20MB；只接受图片 MIME/扩展名，缩略图使用稳定受管内容入口。
+- 签名画布 CSS 高度不超过 320px，轨迹点最多 10,000 个；PNG data URL 最大 512KB。
+- 富文本工具栏和表格维持 1.x 的有界集合；HTML 在写入和只读展示前清洗。
+- Object URL、上传任务、Toast/Modal 和定位监听在卸载时清理，不建立全局可变状态。
+- 浏览器不得持久化文件内容、下载票据、Workflow preparation token、RoleSession 或业务响应。
+- 组件验收资源只授予参考应用已有受控角色，不扩大其他租户或生产应用能力。
+
+## 6. 设计基线
+
+三端继续使用 Ant Design 作为唯一设计系统。Admin 保持 Pro 的桌面数据管理密度；业务用户 PC
+使用独立桌面 renderer；Mobile 以 2026-08-18 五屏验收稿为视觉基线：工作台、数据列表、
+表单提交、底部审批预览、流程详情。
+
+移动页面采用冷灰背景、白色业务分区、蓝色主操作、4-8px 圆角、清晰分隔线和底部安全区；
+必填星号紧邻标签。AIDA、营销 Hero、滚动叙事和 GSAP 不适用于高频操作型产品，不进入实现。
+
+## 7. 回滚边界与影响面
+
+实现拆成可独立回滚的发布单元：
+
+1. contracts + Field Kit 的字段生命周期和组件；
+2. User Desktop/Mobile 标准页面；
+3. 官方模板的验收资源、流程夹具和高保真页面。
+
+每个单元通过 Changeset 独立版本化。回滚使用对应 npm 包版本和 AppVersion，不需要数据库数据迁移。
+新增验收资源可随模板 AppVersion 回滚；既有 `purchase_requests` 数据和文件绑定不修改。
+1.x 仓库、已发布 1.x 包、其他租户和当前生产 Head 不引用本次未发布源码，影响面为零。
+
+## 8. 可证伪验收
+
+1. Desktop/Mobile 连续上传两个同名文件时，每个服务端 `fileId` 只显示一次；上传成功不保留本地副本。
+2. 图片在独立验收资源的 `images` 字段完成 initiate/upload/complete/preview/remove，不再返回字段无效。
+3. 附件、图片、定位、签名和富文本具备 Desktop、Mobile、Readonly、disabled、empty、loading、error 状态测试。
+4. contracts/Field Kit 往返测试证明稳定附件、位置、签名和富文本值不依赖 1.x 运行时。
+5. 所有移动必填字段显示红色 `*`，空提交把错误定位到控件；桌面标记和现有 ProForm 行为不退化。
+6. 选择 `dept-product`、`dept-design` 和 `dept-engineering` 分别准备采购流程时，部门节点都能解析至少一名
+   合法 `department_manager`；删除对应夹具后测试必须稳定复现 `WORKFLOW_V2_APPROVER_RESOLUTION_EMPTY`。
+7. 390x844、430x932、1280x800、1440x900 的 Playwright 截图无文字溢出、重叠、布局跳动或桌面控件混入移动端。
+8. 工作台、列表、表单、审批预览、流程详情与验收稿逐屏比对；提交主路径只有一个主按钮。
+9. `openxiangda generate/check/test`、`pnpm verify:affected`、Ant Design lint、模板单测与 Desktop/Mobile E2E 全部通过。
+10. 静态边界检查证明 2.0 包没有 1.x import、1.x workspace detection、原生绕过上传或第二份权限/流程状态。

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

@@ -0,0 +1,293 @@
+# 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、发布门禁和发布后冒烟测试。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda-skill-kit",
-  "version": "2.0.0-alpha.36",
+  "version": "2.0.0-alpha.37",
   "description": "Validation and deterministic packaging for OpenXiangda 2.0 AI skills.",
   "type": "module",
   "main": "./dist/index.js",
@@ -21,7 +21,7 @@
     "README.md"
   ],
   "dependencies": {
-    "openxiangda-devkit-core": "2.0.0-alpha.26"
+    "openxiangda-devkit-core": "2.0.0-alpha.27"
   },
   "devDependencies": {
     "tsx": "4.23.12",