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

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

@@ -184,7 +184,7 @@ Admin 工作台还原本轮决策：
 | Shell | 任一路径恰好一个菜单选中；标签边界对齐；无全局搜索和内容区重复标题；直接 URL、关闭、恢复、身份/环境切换正确 |
 | 视觉 | PC 冻结稿尺寸 1536x1024（并补充 1280x800 结构检查）；移动 390x844、375x812 截图回归 |
 | 数据 | 默认一行与更多筛选、服务端搜索/排序/分页、四类列表设置、空/错/加载、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` |
+| 字段 | 官方验收表单覆盖 `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/workflowStatus`；关联表单组件弃用 |
 | 目录 | 打开即能看到真实根组织；树展开、搜索、路径、单选/多选和失败重试 |
 | 身份 | 页面显示真实姓名/部门；正则扫描页面不存在裸 UUID |
 | 流程 | 提交前没有预览；保存和 prepare 后弹窗；预览仅含具体审批人路径；Surface DataRef 可读业务数据；同意、拒绝、转交、回退、加签和代理按 Surface 展示 |

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

@@ -0,0 +1,76 @@
+# 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. 迁移原则
+
+- “复用 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` | 不迁移 | - | 平台组件弃用；复杂关联查询由应用页面和 App API 实现 | 已确认弃用 |
+| `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. 验收清单
+
+- 除已明确弃用的关联表单外，1.0 标准字段都有明确的 2.0 映射；别名不重复实现。
+- 每种 `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,133 @@
+# 经过验证的平台字段组件与三端标准页面决策
+
+状态：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 合同；三端可以有独立页面组合，
+   不能维护第二份数据、权限或流程状态。
+
+公开受影响面包括：Field Kit 的 Desktop/Mobile/Readonly 导出与样式、User 包的标准页面、
+模板 DataResource/Surface/fixture、组件使用指南和参考应用路由与测试。Native Data API 的文件
+安全语义和现有 URL 不变化。
+
+本轮采用简单目录和单一 Registry。1.x 只提供已验证的功能、样式、交互与移动端基线，不建立
+逐文件追溯、兼容运行时或第二套协议。组件通过一个 `fileService` 调用既有 2.0 文件接口，页面和
+字段组件不感知 initiate/PUT/complete/delete-unbound 的步骤。
+
+## 4. 失败、并发与清理行为
+
+- 同一控件的并发上传有独立 abort/progress 状态；单个失败不覆盖其他文件，重复选择按稳定标识去重。
+- 超出数量、大小或 accept 规则在上传前显示字段内错误；服务端仍重复校验并返回权威错误。
+- 组件卸载或取消未完成上传时中止请求；已经取得票据但未完成的文件继续由平台未绑定文件清理兜底。
+- 删除未绑定文件调用现有删除接口；已绑定文件只从候选表单值移除，由记录更新事务执行绑定/孤儿转换。
+- 预览 Object URL 在关闭、替换和卸载时释放；预览失败保留下载动作和可重试错误。
+- 定位优先使用钉钉能力，失败后降级浏览器 Geolocation；超时、拒绝和不支持分别显示可恢复错误。
+- 签名保存只接受非空轨迹，生成图片和哈希任一步失败都不覆盖原值；重复保存以最后一次成功值为准。
+- 富文本迁移 1.x 的完整格式、表格、链接、图片、粘贴/拖拽与安全只读能力。需要上传图片时，
+  Surface 显式提供一个声明为 `file` 的伴随字段，编辑器仍通过同一个 `fileService` 上传；未配置时
+  保留图片 URL，不建立旁路上传协议。编辑器销毁后不得提交迟到回调。
+- 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 不引用本次未发布源码，影响面为零。
+
+`relation`/关联表单不再属于 Field Kit 标准组件，不迁移到新模板。普通供应商选择使用单选、
+下拉或应用自己的业务页面；复杂关联查询由应用 App API 和页面自行实现。
+
+## 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/docs/field-components.md

@@ -0,0 +1,93 @@
+# 平台字段组件使用指南
+
+OpenXiangda 2.0 应用的持久化表单字段统一使用 `openxiangda-field-kit`。桌面端从
+`openxiangda-field-kit/desktop` 导入，移动端从 `openxiangda-field-kit/mobile` 导入；列表、
+详情和只读状态使用对应的 `FieldValue`。应用可以自由组合页面，但不要在业务页面重新实现字段值、
+文件上传、人员部门目录、地址、定位或签名协议。
+
+## 基本用法
+
+```tsx
+import { DesktopFieldControl, DesktopFieldValue } from 'openxiangda-field-kit/desktop';
+
+<DesktopFieldControl
+  definition={{ code: 'amount', label: '预算金额', kind: 'money', precision: 2 }}
+  value={values.amount}
+  onChange={amount => setValues(current => ({ ...current, amount }))}
+/>
+
+<DesktopFieldValue
+  definition={{ code: 'amount', label: '预算金额', kind: 'money', precision: 2 }}
+  value={values.amount}
+/>
+```
+
+移动端替换为 `MobileFieldControl` 与 `MobileFieldValue`。平台目录、地址、定位和文件字段还需要传入
+当前应用的 `FieldPlatformContext`；标准 Admin/User 页面已经自动提供。
+
+常用体验配置继续沿用 1.0 的语义：文本支持 `maxLength`、`showCount`、前后缀和清空；数值支持
+`min`、`max`、`step`、`precision`、单位位置和千分位；日期支持今天之前、今天之后或自定义区间；
+多选支持 `maxCount`，子表支持 `minRows` / `maxRows`。这些都是页面行为，不改变 2.0 稳定值协议。
+标准模板锁定 Ant Design 的尺寸、圆角和密度，不开放会造成三端样式分裂的任意 `variant` / `size` 覆盖。
+
+## 什么时候使用哪个组件
+
+| 需求 | 使用 | 不应使用 |
+| --- | --- | --- |
+| 标题、名称、编号 | `text` | 不用富文本 |
+| 多行纯文本说明 | `textarea` | 不需要格式时不用 `richtext` |
+| 表格、链接、图片和带格式正文 | `richtext` | 简单备注不用它 |
+| 数量、金额、比例 | `number` / `money` / `percent` | 不用文本保存可计算数值 |
+| 少量互斥选项 | `radio` | 选项很多时用 `option` |
+| 少量并列多选 | `checkbox` | 选项很多时用 `options` |
+| 平台成员与组织 | `user(s)` / `department(s)` | 不用自由文本或复制组织树 |
+| 邮寄或行政区地址 | `address` | 需要经纬度时用 `location` |
+| 现场打点、签到 | `location` | 普通地址填写不用定位 |
+| 任意类型文件 | `attachments` | 只收图片时使用 `images` |
+| 照片、截图、凭证 | `images` | 不要直接使用 Ant Upload |
+| 同一表单的多行明细 | `subtable` | 独立生命周期的大量记录应建资源页面 |
+| 现场手写确认 | `signature` | 法律电子签章接专业签署服务 |
+| 流程状态展示 | `workflowStatus` | 不允许页面直接编辑流程状态 |
+
+完整机器可读清单由 `fieldCatalog` 导出，包含每个 `FieldKind` 的值协议、适用和不适用场景。
+
+关联表单组件已经弃用。普通关联选择使用 `option`、`radio` 或文本；需要分页检索、复杂权限和业务
+联动时，由应用通过 NestJS App API 实现独立页面，不把业务查询重新塞进通用字段组件。
+
+## 附件和图片
+
+DataResource 中对应字段必须声明为 `type: 'file'`。组件保留 1.0 已验证的上传、进度、取消、失败
+重试、预览、下载和删除交互；底层由一个 `fileService` 调用 2.0 Native Files API。应用不接触
+`initiate → PUT → complete → delete-unbound` 细节，也不要拼接对象存储地址。
+
+```ts
+{ code: 'attachments', type: 'file', nullable: true,
+  file: { multiple: true, maxCount: 10, maxSizeMb: 50 } }
+```
+
+同名文件不会合并；只按平台 `fileId` 或稳定 URL 去重。图片字段可以配置 `imageCompression`，但页面
+不能放宽 DataResource 已声明的数量、类型和大小限制。
+
+## 富文本图片
+
+富文本本身仍保存清洗后的 HTML 字符串。需要上传内嵌图片时，把 `richTextImageFieldCode` 指向同一
+资源中真实的 `file` 字段；标准表单会把上传结果追加到该文件字段，确保记录保存时完成文件绑定。
+
+```ts
+{
+  code: 'description',
+  label: '详细说明',
+  kind: 'richtext',
+  richTextToolbar: 'full',
+  richTextImageFieldCode: 'images',
+}
+```
+
+没有配置伴随文件字段时，桌面编辑器仍支持图片 URL，但不会开放本地图片上传。
+
+## 验收要求
+
+- 编辑、禁用、只读和空值均可用。
+- 必填标识紧邻标签；提交失败定位到第一个错误字段。
+- Desktop 与 Mobile 使用独立 renderer，移动入口不加载桌面 Ant Design 录入控件。
+- 附件、图片、富文本、人员、部门、地址、定位和签名必须在标准模板真实保存后回显。

package/docs/frontend.md

@@ -53,11 +53,11 @@ OpenXiangda 2.0 桌面管理端采用 React 19、Ant Design 6、Umi Max 4、ProC
 
 ## Field Kit 与移动用户端
 
-所有平台字段使用 `openxiangda-field-kit` 的稳定值协议。人员、部门、单选、多选、单选框、复选框、日期、日期区间、地址、关联、图片、附件、数值等都由统一定义驱动存储与显示。
+所有平台字段使用 `openxiangda-field-kit` 的稳定值协议。人员、部门、单选、多选、单选框、复选框、日期、日期区间、地址、图片、附件、富文本和数值等都由统一定义驱动存储与显示。组件选型见[平台字段组件使用指南](./field-components.md)。
 
 - 桌面 Admin 从 `openxiangda-field-kit/desktop` 使用 Ant Design 控件。
 - 移动用户端由 `openxiangda-user/mobile` 提供工作台、数据列表/表单/详情和流程提交/任务/实例页面，并从 `openxiangda-field-kit/mobile` 使用 Ant Design Mobile 的独立字段交互；不把桌面 Select、DatePicker 或 Cascader 缩小后复用。
-- 人员、部门、行政区、关联数据、上传、下载和预览都通过平台 API；应用不自行复制平台目录或文件协议。
+- 人员、部门、行政区、上传、下载和预览都通过平台 API；应用不自行复制平台目录或文件协议。关联表单平台组件已弃用，复杂关联查询由应用页面和 App API 实现。
 - UI 必填、默认值、显隐、布局和帮助文本属于页面层；后端业务不应假设自定义页面一定执行了前端校验。
 
 生成模板将桌面 Admin 与移动用户端放在同一个 AppPackage 的两个独立懒加载路由树中；`/admin` 只加载 Pro 页面，`/m` 只加载 `openxiangda-user/mobile`，根入口按设备能力一次性选择。移动 Chromium 已验证两棵树不混用 DOM，并覆盖稳定角色切换、列表/详情、流程发起与平台特殊字段。

package/docs/index.md

@@ -23,3 +23,5 @@ features:
 OpenXiangda 2.0 保留平台统一数据与治理能力，同时把应用开发恢复成成熟的前后端工程。本工具链只面向 2.0 应用；旧应用由独立的 1.x 产品线维护。
 
 当前能力的完成证据、真实缺口和实施顺序见[实施路线图与证据矩阵](/architecture/implementation-roadmap)。Admin 已确认[全量切换到 Ant Design Pro v6](/architecture/ant-design-pro-v6-admin-foundation)，不再维护自研 Shell/Vite 双轨。实现前先阅读[环境配置内核](/architecture/environment-configuration-kernel-v2)、[Alpha 退役与 Native 切换前置审计](/architecture/native-kernel-inventory-v2)、[原生配置投影蓝图](/architecture/native-configuration-projection-v2)与[授权一致性内核](/architecture/authorization-consistency-v2)，Admin 页面协议建立在这些可验证的运行时事实之上。
+
+开发表单、列表或详情前阅读[平台字段组件使用指南](/field-components)，按场景选择桌面、移动和只读组件。

package/docs/llms.txt

@@ -3,6 +3,7 @@
 - /getting-started.md: standard workspace and development loop
 - /concepts.md: application, platform, data, runtime, and version boundaries
 - /frontend.md: React admin shell, role session, CRUD, workflow UI
+- /field-components.md: platform field catalog, usage, selection rules, file and rich-text examples
 - /backend.md: NestJS modules, identity, Data API, health, secrets
 - /data-authz.md: RBAC plus contextual data and field authorization
 - /workflow-events.md: Workflow Kernel v2, providers, actions, durable events

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda-skill-kit",
-  "version": "2.0.0-alpha.36",
+  "version": "2.0.0-alpha.38",
   "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",

package/skills/openxiangda-v2-frontend/SKILL.md

@@ -23,13 +23,15 @@ Build in `apps/web` with React 19, Ant Design 6, Umi Max 4 and ProComponents 3.
 ## Platform fields and mobile user UI
 
 1. Use `openxiangda-field-kit/desktop` in the desktop Admin. Build the independent mobile tree with `OpenXiangdaUserProvider` from `openxiangda-user` and the standard pages from `openxiangda-user/mobile`; those pages consume `openxiangda-field-kit/mobile`. Mobile is not a CSS-responsive copy of the Admin.
-2. Platform fields include all supported kinds, not only personnel and files: text/textarea, number/money/percent, boolean, single/multiple select, radio/checkbox/cascade, date/datetime/date range, user/users, department/departments, relation, address/location, image/attachments, signature, subtable/JSON, serial and workflow status.
-3. Persist established stable values. Directory/option/relation values use `{ label, value }`; address, location and attachment values use the `openxiangda-field-kit` types. Never replace them with display-only strings or Ant Design component instances.
-4. Personnel, departments, administrative divisions, relations, uploads, downloads and previews must use platform APIs. Do not copy platform directory data or write a second upload protocol.
-5. Keep database declarations minimal: field code, storage type, nullability, index and storage constraints. Required/default/hidden/layout/help/conditional display are page behavior. A custom page may implement different UI validation, so critical business rules must also be enforced by NestJS/Data API policy.
-6. Render list/detail values by field kind. Show readable labels, tags, formatted dates/numbers/amounts, address text, user/department identity, image preview and attachment download instead of raw JSON or internal IDs.
-7. Prefer `MobileAppShell`, `MobileWorkbenchPage`, `MobileResourceListPage`, `MobileResourceFormPage`, `MobileResourceDetailPage`, `MobileWorkflowSubmissionPage`, `MobileWorkflowWorkCenterPage`, `MobileWorkflowTaskPage` and `MobileWorkflowInstancePage`. The Workflow submission page must show only the business form and one Submit action until save and prepare succeed; only then open the approval preview.
-8. Keep the mobile package out of NestJS dependencies. The browser may call only platform-relative Native clients under the current RoleSession; it must not persist platform tokens, service addresses, permission decisions or business responses.
+2. Before choosing a field, read [Platform field components](../../docs/field-components.md) or the exported `fieldCatalog`. It records every kind's value contract, when to use it and when not to use it.
+3. Platform fields include text/textarea/richtext, number/money/percent, boolean, single/multiple select, radio/checkbox/cascade, date/datetime/date range, user/users, department/departments, address/location, image/attachments, signature, subtable/JSON, serial and workflow status. The association-form/relation platform component is discontinued; use option/radio for ordinary choices or an application page plus App API for complex relation queries.
+4. Persist established stable values. Directory and option values use `{ label, value }`; address, location and attachment values use the `openxiangda-field-kit` types. Never replace them with display-only strings or Ant Design component instances.
+5. Personnel, departments, administrative divisions, uploads, downloads and previews must use platform APIs. Do not copy platform directory data or write a second upload protocol. Do not use Ant Upload or a raw file input in an application page for a persistent file field.
+6. Use `attachments` for general files and `images` when thumbnail/preview/photo selection is required. The DataResource field must be `file`. Rich-text local images require `richTextImageFieldCode` pointing to a companion `file` field so uploaded files bind with the saved record.
+7. Keep database declarations minimal: field code, storage type, nullability, index and storage constraints. Required/default/hidden/layout/help/conditional display are page behavior. A custom page may implement different UI validation, so critical business rules must also be enforced by NestJS/Data API policy.
+8. Render list/detail values by field kind. Show readable labels, tags, formatted dates/numbers/amounts, address text, user/department identity, image preview and attachment download instead of raw JSON or internal IDs.
+9. Prefer `MobileAppShell`, `MobileWorkbenchPage`, `MobileResourceListPage`, `MobileResourceFormPage`, `MobileResourceDetailPage`, `MobileWorkflowSubmissionPage`, `MobileWorkflowWorkCenterPage`, `MobileWorkflowTaskPage` and `MobileWorkflowInstancePage`. The Workflow submission page must show only the business form and one Submit action until save and prepare succeed; only then open the approval preview.
+10. Keep the mobile package out of NestJS dependencies. The browser may call only platform-relative Native clients under the current RoleSession; it must not persist platform tokens, service addresses, permission decisions or business responses.
 
 ## Verification