openxiangda 2.20.4 → 2.21.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/bin/distribution/launcher.js +1 -2
- package/documentation/AGENTS.md +2 -2
- package/documentation/appspec.md +8 -1
- package/documentation/backend.md +38 -0
- package/documentation/data-authz.md +35 -0
- package/documentation/declarations-cheatsheet.md +7 -1
- package/documentation/design-workflow.md +90 -74
- package/documentation/development.md +3 -3
- package/documentation/frontend.md +11 -4
- package/documentation/getting-started.md +41 -9
- package/documentation/manifest.json +17 -29
- package/documentation/product-design.md +1 -1
- package/documentation/public-access.md +16 -6
- package/documentation/reference/cli.md +3 -1
- package/documentation/reference/mcp.md +12 -6
- package/documentation/testing.md +2 -0
- package/documentation/upgrading.md +1 -1
- package/documentation/workflow-events.md +42 -0
- package/package.json +23 -17
- package/releases/2.0.0.json +50 -0
- package/releases/2.0.1.json +39 -0
- package/releases/2.1.0.json +44 -0
- package/releases/2.1.1.json +48 -0
- package/releases/2.10.0.json +42 -0
- package/releases/2.11.0.json +41 -0
- package/releases/2.12.0.json +38 -0
- package/releases/2.13.0.json +41 -0
- package/releases/2.13.1.json +33 -0
- package/releases/2.13.2.json +31 -0
- package/releases/2.14.0.json +41 -0
- package/releases/2.15.0.json +40 -0
- package/releases/2.16.0.json +41 -0
- package/releases/2.17.0.json +39 -0
- package/releases/2.17.1.json +34 -0
- package/releases/2.18.0.json +37 -0
- package/releases/2.18.1.json +31 -0
- package/releases/2.18.10.json +29 -0
- package/releases/2.18.2.json +30 -0
- package/releases/2.18.3.json +30 -0
- package/releases/2.18.9.json +37 -0
- package/releases/2.19.0.json +38 -0
- package/releases/2.2.0.json +48 -0
- package/releases/2.2.1.json +35 -0
- package/releases/2.2.2.json +34 -0
- package/releases/2.20.0.json +36 -0
- package/releases/2.21.0.json +35 -0
- package/releases/2.21.1.json +36 -0
- package/releases/2.3.0.json +37 -0
- package/releases/2.4.0.json +37 -0
- package/releases/2.4.1.json +35 -0
- package/releases/2.5.0.json +37 -0
- package/releases/2.6.0.json +37 -0
- package/releases/2.7.0.json +37 -0
- package/releases/2.7.1.json +31 -0
- package/releases/2.8.0.json +32 -0
- package/releases/2.8.1.json +30 -0
- package/releases/2.9.0.json +33 -0
- package/releases/2.9.1.json +31 -0
- package/releases/2.9.2.json +33 -0
- package/releases/2.9.3.json +31 -0
- package/releases/2.9.4.json +37 -0
- package/skills/manifest.json +2 -2
- package/skills/openxiangda-v2/SKILL.md +15 -15
- package/skills/openxiangda-v2/references/appspec.md +8 -1
- package/skills/openxiangda-v2/references/backend.md +38 -0
- package/skills/openxiangda-v2/references/cli.md +3 -1
- package/skills/openxiangda-v2/references/data-authz.md +35 -0
- package/skills/openxiangda-v2/references/declarations-cheatsheet.md +7 -1
- package/skills/openxiangda-v2/references/design-workflow.md +90 -74
- package/skills/openxiangda-v2/references/development.md +3 -3
- package/skills/openxiangda-v2/references/frontend.md +11 -4
- package/skills/openxiangda-v2/references/getting-started.md +41 -9
- package/skills/openxiangda-v2/references/mcp.md +12 -6
- package/skills/openxiangda-v2/references/product-design.md +1 -1
- package/skills/openxiangda-v2/references/public-access.md +16 -6
- package/skills/openxiangda-v2/references/testing.md +2 -0
- package/skills/openxiangda-v2/references/upgrading.md +1 -1
- package/skills/openxiangda-v2/references/workflow-events.md +42 -0
- package/documentation/design-craft.md +0 -1526
- package/documentation/opendesign-methods.md +0 -756
- package/releases/2.20.2.json +0 -30
- package/releases/2.20.3.json +0 -29
- package/skills/openxiangda-v2/references/design-craft.md +0 -1526
- package/skills/openxiangda-v2/references/opendesign-methods.md +0 -756
|
@@ -1,119 +1,135 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Agent 原生视觉设计与实现
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
有界面影响的新应用、页面或改版,由当前 AI Agent 在同一个 OpenXiangda 工作区内完成
|
|
4
|
+
视觉方向、真实页面实现、浏览器走查和修正。按需使用用户指定或当前可用的图片生成能力
|
|
5
|
+
(例如 Image 2.5)输出少量设计参考;不安装或调用独立设计运行时,也不在图片与实现之间
|
|
6
|
+
建立第二个项目状态。纯后端或无视觉影响的文字修正沿用已有设计。
|
|
4
7
|
|
|
5
|
-
|
|
8
|
+
图片只回答构图、层次、色彩、材质和氛围等视觉问题。AppSpec 继续定义用户、任务、页面、
|
|
9
|
+
字段、权限、状态和验收;真实 React 页面才是最终界面事实。静态图不能证明加载、失败、
|
|
10
|
+
拒绝、校验、提交、未保存输入、键盘、响应式或业务权限已经实现。
|
|
6
11
|
|
|
7
|
-
|
|
12
|
+
## 先固定设计输入 {#inputs}
|
|
8
13
|
|
|
9
|
-
|
|
10
|
-
pnpm openxiangda design open
|
|
11
|
-
pnpm openxiangda design status --json
|
|
12
|
-
pnpm openxiangda design cli --help
|
|
13
|
-
pnpm openxiangda design cli project list
|
|
14
|
-
pnpm openxiangda design cli templates list
|
|
15
|
-
pnpm openxiangda design cli design-systems list
|
|
16
|
-
pnpm openxiangda design cli tools directions --json
|
|
17
|
-
pnpm openxiangda design cli plugin --help
|
|
18
|
-
pnpm openxiangda design cli mcp
|
|
19
|
-
```
|
|
20
|
-
|
|
21
|
-
`cli` 后面的参数、标准输入、输出、JSON、错误码和取消交给原版;享搭不维护上游命令白名单。查看每条原生命令的 `--help` 再执行当前需要的操作。原版 MCP 可直接接到支持 stdio 的 Agent,启动命令为 `openxiangda design cli mcp`;它与享搭平台 MCP 分别拥有设计项目和平台契约,不合并权限。
|
|
22
|
-
|
|
23
|
-
AI 通过 CLI/MCP 工作时使用原生 `OD_DAEMON_URL` 或原版自动发现的本地运行时;不需要先执行 `design open`。桌面版 sidecar 只在用户主动预览时使用。原版桌面文件导入等操作可能要求桌面授权上下文;AI 应保留原版错误并停止该步骤,不伪造 token 或改数据库。享搭不会在 npm 安装时下载桌面应用、自动修改 Agent 凭据或开启云付费功能。
|
|
14
|
+
开始界面工作前,从当前 AppSpec、平台契约和用户材料形成一个短设计输入,至少明确:
|
|
24
15
|
|
|
25
|
-
|
|
16
|
+
- 目标用户、主任务、页面归属以及 PC/移动设备范围;
|
|
17
|
+
- 必须保留的平台 Shell、导航、字段协议、权限和数据来源;
|
|
18
|
+
- 页面信息层次、关键操作,以及空、加载、失败、拒绝、校验、提交中和成功状态;
|
|
19
|
+
- 用户提供的品牌、参考图和素材授权;没有品牌事实时标记为 Agent 推断;
|
|
20
|
+
- 目标视口、可访问性、内容长度、数据量和性能边界;
|
|
21
|
+
- 本轮可以改变、必须保留和明确不做的内容。
|
|
26
22
|
|
|
27
|
-
|
|
23
|
+
已有有效设计继续沿用。只有视觉方向存在真实取舍时才比较候选;已经确认的意图不重复
|
|
24
|
+
提问。不得凭空补充 KPI、品牌故事、业务统计、角色能力或示例数据来源。
|
|
28
25
|
|
|
29
|
-
|
|
26
|
+
## 图片参考 {#image-reference}
|
|
30
27
|
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
| 浏览器走查、修正已有原型及实现 | impeccable-design-polish | typography、color、anti-ai-slop、animation-discipline、accessibility-baseline |
|
|
36
|
-
| 信息层次、密集工作台、表单 | 按当前阶段选择上述方法 | typography-hierarchy、laws-of-ux、form-validation,按实际问题选读 |
|
|
28
|
+
图片生成是可选步骤。需要建立新视觉方向、比较布局或统一多页面风格时,可用 Image 2.5
|
|
29
|
+
等当前 Agent 图片能力生成一至三个关键视图;普通 CRUD、小范围样式修正或已有明确设计时
|
|
30
|
+
直接实现。生成提示应包含真实页面类型、主要内容、设备、密度、组件约束和不应出现的元素,
|
|
31
|
+
不得包含生产秘密、真实个人数据或未经授权的品牌和人物素材。
|
|
37
32
|
|
|
38
|
-
|
|
33
|
+
只保留实际采用的参考图,并记录实际模型、日期、提示摘要、目标视口和采用/拒绝理由。
|
|
34
|
+
不要逐像素照抄图片中的伪文字、虚构控件或不可能交互。Agent 应从参考图提取可实现的布局、
|
|
35
|
+
排版、颜色、间距和组件关系,再对照真实内容与平台组件修正。图片生成失败、不可用或结果
|
|
36
|
+
不合格时,记录事实并使用现有设计约束、成熟组件和浏览器迭代继续开发,不伪造产物。
|
|
39
37
|
|
|
40
|
-
##
|
|
38
|
+
## 页面归属与平台边界 {#adapter}
|
|
41
39
|
|
|
42
|
-
|
|
40
|
+
应用结构先于视觉:标准管理后台是默认骨架,必须保留平台 Shell、后台路由、显式菜单、
|
|
41
|
+
资源表单、数据列表、详情/编辑、权限和流程入口。Agent 可以在这些边界内优化布局、视觉和
|
|
42
|
+
交互,但不能用设计图、独立原型、单页 HTML 或 iframe 替代后台。
|
|
43
43
|
|
|
44
|
-
|
|
44
|
+
用户端 PC 与移动端按真实旅程分别实现,通过平台 runtime/Data API 使用后台数据,并与
|
|
45
|
+
后台保持独立的导航状态。Shell 的路由、当前用户、授权菜单和拒绝事实仍来自平台,不在
|
|
46
|
+
用户端复制。先复用 PC/移动 Field Kit 的输入、校验、上传、只读和权限行为;替换外观或
|
|
47
|
+
专业控件时,证明字段值、未保存输入、拒绝和恢复行为仍正确。
|
|
45
48
|
|
|
46
|
-
|
|
49
|
+
普通管理与录入保持工作型界面的扫描效率和信息密度。专业交互先评估项目已有依赖与成熟
|
|
50
|
+
组件,图表优先评估 ECharts。营销式大标题、装饰性卡片堆叠、无任务依据的插画、纯氛围
|
|
51
|
+
背景和重复导航不能因为参考图中出现就进入业务应用。
|
|
47
52
|
|
|
48
|
-
|
|
53
|
+
## 从参考到真实实现 {#loop}
|
|
49
54
|
|
|
50
|
-
|
|
55
|
+
1. 读取设计输入和相关契约,确定本轮页面、状态、视口与验收动作。
|
|
56
|
+
2. 需要时生成并筛选图片参考,提取可实现的视觉规则;不需要时直接沿用现有设计系统。
|
|
57
|
+
3. 在 `tokens.css` 或应用现有 token 源中定义实际采用的数值,派生 AntD theme 与移动 CSS
|
|
58
|
+
变量;不要在图片说明、组件和全局偏好中维护多份数值事实。
|
|
59
|
+
4. 直接使用真实 React、平台 Shell、Field Kit 和受支持组件实现页面。原型只有在能降低
|
|
60
|
+
高风险交互的不确定性时创建,且不得成为另一套长期业务代码。
|
|
61
|
+
5. 在目标尺寸打开真实页面,操作完整关键任务;检查布局、滚动、弹层、键盘、长文本、
|
|
62
|
+
空、加载、失败、拒绝、校验、提交、恢复和离开保护。浏览器控制台错误必须处理。
|
|
63
|
+
6. 获取实际截图与交互发现,修正代码并重复检查。截图用于比较视觉,不替代操作断言。
|
|
64
|
+
7. 连接平台后,从真实入口按实际角色验证后台与用户端、允许与拒绝路径;只有业务证据
|
|
65
|
+
通过后才进入部署。组件样例、本地数组和图片参考不能冒充远端业务验收。
|
|
51
66
|
|
|
52
|
-
|
|
67
|
+
现有交互模式作为任务检查依据,见[交互模式](interaction-patterns.md);它们允许按当前设计
|
|
68
|
+
改进,不是固定页面皮肤。
|
|
53
69
|
|
|
54
|
-
|
|
55
|
-
2. AI 通过原版 CLI/MCP 创建或复用项目、选择模板/设计系统,提供任务与必要参考;工作目录由当前 OpenXiangda 工作区确定。使用原版工作流形成设计方向,保留上游的项目和资源结构;用户可选打开客户端查看。
|
|
56
|
-
3. 通过原版 Agent、项目和预览做可运行原型,关键任务能从入口走到完成。标明示例数据;覆盖适用的空、加载、失败、拒绝、校验、提交中和成功状态。真实业务请求尚未接入时明确说明。
|
|
57
|
-
4. 使用原版预览、lint、导出和修正能力;在目标尺寸实际打开、点击和键盘操作。证据记录实际 URL/文件、尺寸、操作与发现,没有浏览器证据就写未验证。不能用 AI 评分或勾选表代替画面和操作结果。
|
|
58
|
-
5. 依据已有授权和实际答复记录确认范围,固定设计文档和 assets 摘要。工具检查只证明资料与资源一致,不代表审美通过。
|
|
59
|
-
6. 消费同一设计包接入真实组件、平台数据和权限。对照原型检查布局、字段、弹层、未保存输入、拒绝/返回、键盘与移动任务。验收证据关联本次真实实现;原型成功不能冒充业务验收。
|
|
70
|
+
## AppSpec 设计资源 {#artifacts}
|
|
60
71
|
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
## 原版产物交接到 AppSpec {#artifacts}
|
|
64
|
-
|
|
65
|
-
OpenDesign 项目保留自己的设计文件、清单和数值 token。交接时用原版文件/导出功能复制本轮实际采用的文件及依赖到以下目录,记录原版版本、项目 ID 和导出来源;不要求为了享搭改写上游 manifest 或重复制作原型。大型媒体和完整上游工作目录留在原项目,AppSpec 引用本轮可审阅、自包含的产物。
|
|
72
|
+
只固定本轮实际采用、可审阅且自包含的资源。目录可以按任务裁剪:
|
|
66
73
|
|
|
67
74
|
```text
|
|
68
|
-
appspec/design/visual.md
|
|
69
|
-
appspec/design/
|
|
70
|
-
appspec/design/system/DESIGN.md
|
|
71
|
-
appspec/design/system/tokens.css
|
|
72
|
-
appspec/design/prototypes/<task>/
|
|
75
|
+
appspec/design/visual.md # 范围、来源、取舍与受影响页面
|
|
76
|
+
appspec/design/references/<task>/ # 实际采用的图片参考及来源说明
|
|
77
|
+
appspec/design/system/DESIGN.md # 视觉语义与实现交接
|
|
78
|
+
appspec/design/system/tokens.css # 数值 token 的唯一可编辑来源
|
|
79
|
+
appspec/design/prototypes/<task>/ # 仅在必要时保留的可运行交互原型
|
|
73
80
|
```
|
|
74
81
|
|
|
75
|
-
|
|
82
|
+
图片来源可以用工具无关的清单记录;字段只描述实际事实,不要求特定模型或提供商:
|
|
76
83
|
|
|
77
84
|
```json
|
|
78
85
|
{
|
|
79
86
|
"schema": "openxiangda.design-system/v1",
|
|
80
|
-
"
|
|
81
|
-
|
|
82
|
-
|
|
87
|
+
"sources": [
|
|
88
|
+
{
|
|
89
|
+
"kind": "generated-image",
|
|
90
|
+
"model": "Image 2.5",
|
|
91
|
+
"path": "../references/request/desktop.png",
|
|
92
|
+
"viewport": "1440x1024",
|
|
93
|
+
"promptSummary": "内部事项办理台,紧凑主从布局"
|
|
94
|
+
}
|
|
95
|
+
],
|
|
83
96
|
"tokens": "tokens.css",
|
|
84
|
-
"design": "DESIGN.md"
|
|
97
|
+
"design": "DESIGN.md",
|
|
98
|
+
"status": "reviewed-reference"
|
|
85
99
|
}
|
|
86
100
|
```
|
|
87
101
|
|
|
88
|
-
|
|
102
|
+
没有图片参考时省略 `sources` 和 `references`,不要创建占位文件。历史设计包已有其他来源
|
|
103
|
+
字段时仍可读取,不要求为了新流程重写。业务规则引用 AppSpec ID,图片清单不复制权限、
|
|
104
|
+
字段或页面协议。
|
|
105
|
+
|
|
106
|
+
运行时代码从 `tokens.css` 派生 AntD theme 与移动 CSS 变量。标准应用使用
|
|
107
|
+
`OpenXiangdaApplication` 的 `ui`,独立组件预览使用 `OpenXiangdaUiProvider` 的同名参数:
|
|
89
108
|
|
|
90
109
|
```tsx
|
|
91
110
|
const ui = { theme: derivedAntdTheme, className: 'project-design' };
|
|
92
111
|
<OpenXiangdaApplication {...applicationProps} ui={ui} />
|
|
93
112
|
```
|
|
94
113
|
|
|
95
|
-
`.project-design` 下的样式只覆盖本应用。移动端使用可继承的 `--oxa-mobile-*`
|
|
114
|
+
`.project-design` 下的样式只覆盖本应用。移动端使用可继承的 `--oxa-mobile-*` 输入;平台
|
|
115
|
+
Provider 让 PC 下拉、对话框、消息与通知留在当前应用作用域。使用上下文反馈 API,避免
|
|
116
|
+
AntD 静态 API 脱离作用域;不要通过 theme 变化给整个应用换 key,以免清空正在编辑的值。
|
|
96
117
|
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
维护仓库包含[可运行事项工作台样例](https://github.com/1377385356/openxiangda/tree/master/scripts/fixtures/design-workbench),演示同一设计包、PC/移动字段、错误恢复与主题作用域。它是示例,具体设计未获得用户确认,也不代表生产数据或业务验收。复制时固定所用工具版本并更换为实际平台契约。浏览器检查还覆盖 reduced-motion:保留组件所需的动画完成事件,不能简单用全局 animation:none 让弹层停在初始隐藏态。
|
|
100
|
-
|
|
101
|
-
在 `visual.md` 的 front matter 加入实际资源引用(路径从工作区根开始):
|
|
118
|
+
在 `visual.md` 的 front matter 中引用实际资源:
|
|
102
119
|
|
|
103
120
|
```yaml
|
|
104
121
|
assets:
|
|
122
|
+
- appspec/design/references/request
|
|
105
123
|
- appspec/design/system
|
|
106
|
-
- appspec/design/prototypes/request
|
|
107
124
|
```
|
|
108
125
|
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
## 上游更新与项目升级 {#updates}
|
|
114
|
-
|
|
115
|
-
原版运行时使用官方更新器或官方发行版升级;CLI 每次从当前安装读取入口和版本。进行中的设计在 AppSpec 记录实际版本与导出摘要。不要把 npm 包里的离线资料版本当成原版安装版本。下面的每日检查只维护随包离线资料,不替代原版更新器。
|
|
126
|
+
目录引用包含所有后代文件;新增、修改或删除依赖都会改变评审摘要。引用拒绝越界、符号
|
|
127
|
+
链接、空目录和超预算;每次检查最多 128 文件、单文件 2 MiB、总计 8 MiB、16 层目录。
|
|
128
|
+
参考图应压缩为足以评审的尺寸,大型媒体放在受控来源并记录摘要,不靠删除 assets 声明
|
|
129
|
+
绕过检查。`spec context` 只读取资源字节,不执行原型或图片内容。
|
|
116
130
|
|
|
117
|
-
|
|
131
|
+
## 完成标准 {#acceptance}
|
|
118
132
|
|
|
119
|
-
|
|
133
|
+
视觉完成至少同时具备:当前 AppSpec 设计范围、真实实现、目标视口截图、关键交互断言、
|
|
134
|
+
无不可解释的浏览器错误,以及适用的真实角色允许/拒绝证据。图片模型的输出、Agent 自评、
|
|
135
|
+
结构检查或组件样例只能是过程证据,不能单独宣称设计或业务验收通过。
|
|
@@ -20,7 +20,7 @@
|
|
|
20
20
|
## 选择平台能力 {#capabilities}
|
|
21
21
|
|
|
22
22
|
- 普通数据管理:通过 `defineDataModel`、`defineApplicationModule` 和显式 CRUD 视图声明;模型不自动生成菜单或写权限。
|
|
23
|
-
- 界面工作先按[
|
|
23
|
+
- 界面工作先按[Agent 原生设计工作流](design-workflow.md)形成具体视觉并直接实现真实页面;设备范围按真实任务选择。复用平台导航和字段行为,自定义报表/工具使用 admin 页面与显式导航。详见[页面归属](frontend.md#surface-selection)。
|
|
24
24
|
- 用户页面按实际旅程选择独立 PC/移动布局,手机端只覆盖已确认的用户任务。
|
|
25
25
|
- 图表等专业交互先检查已有依赖,再评估成熟组件或开源库;报表优先评估 ECharts,记录选型理由和加载/销毁边界。详见[组件选型](frontend.md#component-selection)。
|
|
26
26
|
- 无平台账号的外部表单:使用[匿名公开访问](public-access.md),不用普通 RBAC 角色冒充匿名主体。
|
|
@@ -38,8 +38,8 @@
|
|
|
38
38
|
| 列表、筛选、排序、分页接口 | `createNativeResourceClient` 的 `list`,服务端条件树与分页 | [前端数据访问](frontend.md#data-access) |
|
|
39
39
|
| 新增 / 编辑 / 删除接口 | 标准 CRUD 页面,或同一客户端的 `create` / `update` / `remove`(`expectedRevision` 乐观锁) | [前端数据访问](frontend.md#data-access) |
|
|
40
40
|
| 提交防重、幂等重试 | `transactNativeData` / 事务请求自带 `idempotencyKey` 幂等回执 | [前端数据访问](frontend.md#data-access)、[按需后端](backend.md#business-action) |
|
|
41
|
-
| 时间窗、状态前置、指定人角色校验 | 平台事务守卫:`operation-time`、`record-assert`、`record-exists`、`role-member` | [按需后端](backend.md#business-action) |
|
|
42
|
-
| 统计报表数据 | Data API 服务端聚合 `batchAggregateNativeResources`(单个指标也用它),前端不拉全量求和 | [前端](frontend.md#
|
|
41
|
+
| 时间窗、状态前置、指定人角色校验 | 平台事务守卫:`operation-time`、`record-assert`、`record-exists`、`record-match`、`role-member`、`databaseNowAssertion` | [按需后端](backend.md#business-action) |
|
|
42
|
+
| 统计报表数据 | Data API 服务端聚合 `batchAggregateNativeResources`(单个指标也用它),前端不拉全量求和 | [前端](frontend.md#data-access) |
|
|
43
43
|
| 导入 / 导出 | 标准 CRUD 的 `import` / `export` 动作声明 | [业务模块](application-foundation.md) |
|
|
44
44
|
| 跨模型原子写、外部 API、硬件或第三方推送 | Nest 具名 operation + 平台事务,必要时事务内 `emitEvent` | [按需后端](backend.md) |
|
|
45
45
|
|
|
@@ -14,13 +14,13 @@
|
|
|
14
14
|
|
|
15
15
|
## 先选页面归属,再写布局 {#surface-selection}
|
|
16
16
|
|
|
17
|
-
管理后台的设备范围按实际办理任务确定。数据管理、录入和报表复用平台 Shell 的路由与菜单事实,视觉依据[
|
|
17
|
+
管理后台的设备范围按实际办理任务确定。数据管理、录入和报表复用平台 Shell 的路由与菜单事实,视觉依据[Agent 原生设计工作流](design-workflow.md)实现并在浏览器修正;存在手机办理任务时同步设计与验证。
|
|
18
18
|
|
|
19
|
-
###
|
|
19
|
+
### 应用骨架优先与视觉页面边界
|
|
20
20
|
|
|
21
21
|
标准管理后台是每个业务应用的默认开发骨架,必须保留后台 Shell、显式菜单、资源表单、数据列表、详情/编辑、权限和流程入口。开发顺序先完成后台资源与契约,再实现用户端 PC/移动端;不能以用户端首页或设计原型替代后台。
|
|
22
22
|
|
|
23
|
-
|
|
23
|
+
Agent 可以在标准后台内部优化布局、视觉和交互,但后台仍复用平台 Shell、导航、字段行为和权限。用户端 PC 与移动端按真实旅程分别设计,通过平台 runtime/Data API 使用后台数据。图片参考和原型不拥有业务事实;禁止用图片、单页 HTML、iframe 或自定义假后台替换标准后台,也不能把后台权限、导航状态复制到用户端。
|
|
24
24
|
|
|
25
25
|
发布前分别验证后台入口、表单、数据列表、流程入口和用户端 PC/移动端入口;没有完成后台骨架的应用不得发布。
|
|
26
26
|
|
|
@@ -365,7 +365,14 @@ renderer,但共享同一授权与命令生命周期。主决策操作固定在
|
|
|
365
365
|
|
|
366
366
|
资源用 `mutationOwner: 'native' | 'action' | 'readonly' | 'workflow'` 声明 mutation owner,
|
|
367
367
|
并可用 `generated.list/detail/create/update/delete` 精确选择标准 surface。非 Native owner
|
|
368
|
-
不能生成或向应用角色授予 Native mutation;零可写业务字段不能开放 create/update
|
|
368
|
+
不能生成或向应用角色授予 Native mutation;零可写业务字段不能开放 create/update。运行时直接对
|
|
369
|
+
非 Native owner 资源调用 Data API create/update/delete 会被平台以 409
|
|
370
|
+
`OPENXIANGDA_NATIVE_DATA_CAPABILITY_MISSING` 拒绝——这不是权限配置错误,而是 mutation owner
|
|
371
|
+
契约:`readonly` 资源只能读,`action` 资源的写入走 named operation,`workflow` 资源由流程命令推进。
|
|
372
|
+
`workflow` 资源的数据修正不绕过流程:平台为应用超级管理员提供专门的 correction 入口(记录的
|
|
373
|
+
correction-surface/corrections),保留审批快照;非 workflow 资源走该入口返回 409
|
|
374
|
+
`WORKFLOW_OWNER_REQUIRED`,修正失败错误码为 `OPENXIANGDA_WORKFLOW_CORRECTION_<reason>` 族。
|
|
375
|
+
排查这两类错误先核对资源的 `mutationOwner` 声明和期望的写入通道,不要试图用扩角色绕过。
|
|
369
376
|
Workflow definition 用 `launch.mode` 声明 `standalone`、`custom-page`、`hidden-handoff` 或
|
|
370
377
|
`work-center-only`;只有 `standalone` 可进入菜单,`hidden-handoff` 保留同一标准 PC/移动路由
|
|
371
378
|
但不进菜单。缺省 submission 使用 compiler 生成的标准 process operation。action-owned 资源
|
|
@@ -68,10 +68,10 @@ MCP 服务随项目根包一起安装,AI 客户端的 stdio 连接仍需配置
|
|
|
68
68
|
以下命令的版本占位符由随包资料替换为该根包的精确版本。网站源码阅读者应先确认要使用的发行版本。
|
|
69
69
|
|
|
70
70
|
```bash
|
|
71
|
-
pnpm dlx openxiangda@2.
|
|
72
|
-
pnpm dlx openxiangda@2.
|
|
73
|
-
pnpm dlx openxiangda@2.
|
|
74
|
-
pnpm dlx openxiangda@2.
|
|
71
|
+
pnpm dlx openxiangda@2.21.1 skill install --force
|
|
72
|
+
pnpm dlx openxiangda@2.21.1 auth status --base-url <平台地址> --json
|
|
73
|
+
pnpm dlx openxiangda@2.21.1 login --cwd my-app --base-url https://platform.example.com
|
|
74
|
+
pnpm dlx openxiangda@2.21.1 create my-app --base-url https://platform.example.com
|
|
75
75
|
cd my-app
|
|
76
76
|
pnpm openxiangda context --json
|
|
77
77
|
pnpm openxiangda dev
|
|
@@ -79,7 +79,7 @@ pnpm openxiangda dev
|
|
|
79
79
|
|
|
80
80
|
将两处示例平台地址替换为同一个目标地址。`create` 先核对目标与当前登录平台,再创建本地目录、安装依赖并初始化远端应用;新应用不会自动沿用文件中最后登录的站点。CI 使用原有成对的 `OPENXIANGDA_BASE_URL` 和 `OPENXIANGDA_TOKEN` 时,可以由该显式地址指定目标。
|
|
81
81
|
|
|
82
|
-
初始化中断后重试同一命令;已有目录会核对原平台绑定,不能通过 `create`
|
|
82
|
+
初始化中断后重试同一命令;已有目录会核对原平台绑定,不能通过 `create` 改绑到其他站点。地址不一致时先检查目标并登录正确的平台;确需把工作区切换到其他站点时,使用 `openxiangda link rebind --base-url <新平台>` 显式换绑(见[跨站点与换绑](#cross-site)),不手改 link 文件绕过检查,也不要使用内部 provision 接口另建应用。创建操作应在用户要求创建应用的范围内执行。
|
|
83
83
|
|
|
84
84
|
进入项目后使用 `pnpm openxiangda`,由项目依赖和锁文件决定版本。查看使用资料运行 `pnpm openxiangda docs`;查看单一主题运行 `pnpm openxiangda docs frontend`。安装到其他 AI 工具时使用 `skill install --destination <Skill根目录>`。
|
|
85
85
|
|
|
@@ -145,6 +145,7 @@ pnpm openxiangda source push -m "完成本轮应用开发"
|
|
|
145
145
|
| --- | --- |
|
|
146
146
|
| 新应用 | 正常执行 `create`,平台启用后自动建仓、配置凭据和首次推送 |
|
|
147
147
|
| 已有项目首次交接给另一个 AI | 先读 `context --json` 和 `source status`,沿用项目绑定与版本 |
|
|
148
|
+
| 交接给另一位开发者 | 平台管理员先把对方加为该应用的应用管理员;对方执行 `source clone <仓库URL> <新目录> --base-url <平台>`,克隆后在同目录 `login --base-url <平台>` 继续开发 |
|
|
148
149
|
| 换电脑或初始化中断 | 在应用目录执行 `pnpm openxiangda source setup`;已有提交及未提交修改会保留 |
|
|
149
150
|
| 从个人远端迁入 | 明确迁入后运行 `source setup --import`,原远端保留为 `external-source` |
|
|
150
151
|
| 本轮修改完成 | 检查差异后运行 `source push -m "AppSpec: <本轮变更ID> 变更说明"`;多个任务共享目录时先精确提交本轮文件,再不带 `-m` 推送 |
|
|
@@ -173,9 +174,9 @@ MCP 的 `docs_read` 可以读取本说明,当前没有独立的源码操作 MC
|
|
|
173
174
|
无需本地工作区,使用本 Skill 随包精确版本或已安装的对应 CLI:
|
|
174
175
|
|
|
175
176
|
```bash
|
|
176
|
-
pnpm dlx openxiangda@2.
|
|
177
|
-
pnpm dlx openxiangda@2.
|
|
178
|
-
pnpm dlx openxiangda@2.
|
|
177
|
+
pnpm dlx openxiangda@2.21.1 auth status --base-url <平台> --json
|
|
178
|
+
pnpm dlx openxiangda@2.21.1 source resolve <仓库URL> --base-url <平台> --json
|
|
179
|
+
pnpm dlx openxiangda@2.21.1 source clone <仓库URL> <新目录> --base-url <平台> --json
|
|
179
180
|
```
|
|
180
181
|
|
|
181
182
|
登录缺失或站点不匹配时,先按该平台执行 login。resolve 根据平台已经登记的绑定返回
|
|
@@ -200,6 +201,32 @@ pnpm dlx openxiangda@2.20.4 source clone <仓库URL> <新目录> --base-url <平
|
|
|
200
201
|
使用 CLI 时无需自行调用凭据 API;支持工具不得记录其响应或另建身份体系。
|
|
201
202
|
未登记的外部仓库先在原工作区执行 `source setup --import`,再使用平台返回的仓库 URL。
|
|
202
203
|
|
|
204
|
+
## 跨站点与平台换绑 {#cross-site}
|
|
205
|
+
|
|
206
|
+
源码仓库、应用与数据都归属各自站点:A 站点的平台只认 A 站点登记的仓库绑定,
|
|
207
|
+
发布校验要求当前工作区 `origin` 与该站点绑定仓库一致。站点之间流动的是代码(git),
|
|
208
|
+
应用的数据库数据、发布历史与环境配置不会自动迁移。
|
|
209
|
+
|
|
210
|
+
```bash
|
|
211
|
+
openxiangda link # 查看当前绑定、登录态匹配与 origin 归属
|
|
212
|
+
openxiangda link rebind --base-url https://platform-b.example.com # 显式换绑
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
一个工作区同一时间只绑定一个平台;换绑只改写 `.openxiangda/link.json`
|
|
216
|
+
(清空旧站点环境列表),不修改 git remote、不迁移登录凭据,也不在远端产生变更。
|
|
217
|
+
换绑后必须重新登录,`create` 会在新平台幂等初始化同 code 应用。
|
|
218
|
+
|
|
219
|
+
| 场景 | 执行方式 |
|
|
220
|
+
| --- | --- |
|
|
221
|
+
| 在 A 开发、也要发布到 B | 在 B 站点创建同 code 应用并由其管理员启用源码;`source clone <B仓库URL> <B目录> --base-url <B平台>` 得到第二个检出;同步代码用 `git remote add external-source <A仓库URL>` 后 fetch/merge,再 `source push`;在 B 目录执行 `deploy` |
|
|
222
|
+
| 后续发布永久切换到 B | 在原目录依次执行 `link rebind --base-url <B平台>` → `login --base-url <B平台>` → `create <目录> --base-url <B平台>`(幂等初始化)→ `source status` 核对 origin;如报告 `APPLICATION_SOURCE_ORIGIN_CONFLICT`,用 `source setup --import` 把 origin 切到 B 仓库(原 origin 保留为 `external-source`) |
|
|
223
|
+
| 换绑后想回退 | `link rebind --base-url <原平台>` 即恢复;link.json 随仓库提交时也可用 git 还原该文件 |
|
|
224
|
+
| 换绑对象不是同一应用 | 拒绝执行(`OPENXIANGDA_LINK_APP_CODE_CONFLICT`);请在对应应用的目录操作 |
|
|
225
|
+
|
|
226
|
+
换绑命令对地址做与 `login` 相同的归一化校验;地址拼错时失败会在下一步登录或
|
|
227
|
+
幂等初始化处暴露,随时可以再次 rebind 修正。详细决策记录见仓库
|
|
228
|
+
`docs/architecture-decisions/workspace-platform-rebind.md`。
|
|
229
|
+
|
|
203
230
|
## 检查与交付 {#delivery}
|
|
204
231
|
|
|
205
232
|
只检查时运行 `pnpm openxiangda check`。需要部署测试环境时直接运行 `pnpm openxiangda deploy`,它已包含检查、测试和构建;无需再连续重复运行全部脚本。
|
|
@@ -220,8 +247,13 @@ pnpm exec openxiangda --mcp-stdio --cwd <应用绝对路径>
|
|
|
220
247
|
|
|
221
248
|
## 工作区登录态
|
|
222
249
|
|
|
223
|
-
平台授权保存到所选工作区的 `.openxiangda/session.json`,CLI、MCP、刷新与退出共用该文件。不再读取或迁移旧全局会话;升级后需在每个项目重新登录。已有项目可在根目录或子目录运行 `openxiangda login --base-url <platform>`;`login --cwd <directory>` 和 `auth --cwd <directory>`
|
|
250
|
+
平台授权保存到所选工作区的 `.openxiangda/session.json`,CLI、MCP、刷新与退出共用该文件。不再读取或迁移旧全局会话;升级后需在每个项目重新登录。已有项目可在根目录或子目录运行 `openxiangda login --base-url <platform>`;`login --cwd <directory>` 和 `auth status --cwd <directory>` 明确选定工作区。首次 `create` 目标目录尚无会话时,按工作区发现规则向上继承父目录会话,并在 `.git` 仓库边界停止,不跨仓借用账号。
|
|
224
251
|
|
|
225
252
|
创建应用前先执行 `openxiangda login --cwd my-app --base-url <platform>`,再执行 `openxiangda create my-app --base-url <platform>`。仅含受管登录文件的目录允许初始化,凭据会保留并自动加入 Git 忽略规则。
|
|
226
253
|
|
|
227
254
|
本地文件优先;仅在文件缺失时使用成对的 `OPENXIANGDA_BASE_URL` 与 `OPENXIANGDA_TOKEN` CI 环境凭据。损坏、过期或平台不符的文件不会触发其他身份回退。请勿提交或打包登录文件。钉钉支持由 DWS 管理自己的授权,不与平台会话混用。
|
|
255
|
+
|
|
256
|
+
查看当前绑定与登录态匹配情况运行 `openxiangda link`;登录地址与绑定平台不一致时
|
|
257
|
+
`login` 会拒绝执行(`OPENXIANGDA_PLATFORM_SESSION_MISMATCH`),防止凭据跨平台发送。
|
|
258
|
+
需要切换站点时先运行 `openxiangda link rebind --base-url <新平台>`,再登录,见
|
|
259
|
+
[跨站点与平台换绑](#cross-site)。
|
|
@@ -139,7 +139,8 @@ MCP 使用项目锁定的根包;在客户端配置下列 stdio 启动参数,
|
|
|
139
139
|
"minimum": 0,
|
|
140
140
|
"maximum": 9007199254740991
|
|
141
141
|
}
|
|
142
|
-
}
|
|
142
|
+
},
|
|
143
|
+
"additionalProperties": false
|
|
143
144
|
}
|
|
144
145
|
```
|
|
145
146
|
|
|
@@ -169,7 +170,8 @@ MCP 使用项目锁定的根包;在客户端配置下列 stdio 启动参数,
|
|
|
169
170
|
},
|
|
170
171
|
"required": [
|
|
171
172
|
"deploymentId"
|
|
172
|
-
]
|
|
173
|
+
],
|
|
174
|
+
"additionalProperties": false
|
|
173
175
|
}
|
|
174
176
|
```
|
|
175
177
|
|
|
@@ -229,7 +231,8 @@ MCP 使用项目锁定的根包;在客户端配置下列 stdio 启动参数,
|
|
|
229
231
|
"production"
|
|
230
232
|
]
|
|
231
233
|
}
|
|
232
|
-
}
|
|
234
|
+
},
|
|
235
|
+
"additionalProperties": false
|
|
233
236
|
}
|
|
234
237
|
```
|
|
235
238
|
|
|
@@ -265,7 +268,8 @@ MCP 使用项目锁定的根包;在客户端配置下列 stdio 启动参数,
|
|
|
265
268
|
},
|
|
266
269
|
"required": [
|
|
267
270
|
"workflowCode"
|
|
268
|
-
]
|
|
271
|
+
],
|
|
272
|
+
"additionalProperties": false
|
|
269
273
|
}
|
|
270
274
|
```
|
|
271
275
|
|
|
@@ -298,7 +302,8 @@ MCP 使用项目锁定的根包;在客户端配置下列 stdio 启动参数,
|
|
|
298
302
|
"description": "仅本地完整检查;结果 validationScope=local,不核对现场条件",
|
|
299
303
|
"type": "boolean"
|
|
300
304
|
}
|
|
301
|
-
}
|
|
305
|
+
},
|
|
306
|
+
"additionalProperties": false
|
|
302
307
|
}
|
|
303
308
|
```
|
|
304
309
|
|
|
@@ -523,7 +528,8 @@ MCP 使用项目锁定的根包;在客户端配置下列 stdio 启动参数,
|
|
|
523
528
|
"description": "持续跟踪原运行至结束,最多 15 分钟",
|
|
524
529
|
"type": "boolean"
|
|
525
530
|
}
|
|
526
|
-
}
|
|
531
|
+
},
|
|
532
|
+
"additionalProperties": false
|
|
527
533
|
}
|
|
528
534
|
```
|
|
529
535
|
|
|
@@ -141,4 +141,4 @@ context 的 `readyForImplementation` 为真时才制定具体实现任务,把
|
|
|
141
141
|
- [Design OS,固定提交](https://github.com/buildermethods/design-os/tree/529dedb43bfec24b2cbb128f26dd8cbc6143f754)(MIT)。
|
|
142
142
|
- [Spec Kit,固定提交](https://github.com/github/spec-kit/tree/4a7341a93d944d6efe153b71da4a1adb9c2b578c)(MIT)。
|
|
143
143
|
|
|
144
|
-
|
|
144
|
+
有界面影响的工作默认由当前 AI Agent 完成视觉方向、真实页面实现和浏览器修正,见[设计工作流](design-workflow.md)。需要建立新方向时可按需使用 Image 2.5 等当前图片能力生成少量参考;图片不定义交互、权限或验收,采用的资源以 AppSpec assets 固定。
|
|
@@ -92,8 +92,11 @@ export default defineOpenXiangdaApp({
|
|
|
92
92
|
|
|
93
93
|
附件、图片、多选等多值字段使用数组,存储不允许 null;这不意味着用户必须填写。上例照片可选,
|
|
94
94
|
可以省略或提交空数组,不放入 `requiredFields`。如果业务确实要求上传,资源字段声明 `required: true`,
|
|
95
|
-
公开策略也必须将它列入 `requiredFields`;提交时省略、null
|
|
96
|
-
|
|
95
|
+
公开策略也必须将它列入 `requiredFields`;提交时省略、null 或空数组都会被拒绝。`requiredFields` 必须覆盖
|
|
96
|
+
资源已有的必填业务字段;比模型必填**更严**(列入模型未声明 `required: true` 的字段)时编译器给出警告
|
|
97
|
+
`APP_CONFIG_ANONYMOUS_POLICY_REQUIRED_FIELDS_STRICTER_THAN_MODEL`:标准表单控件不为这些字段生成必填
|
|
98
|
+
校验,空值提交会被服务端 `REQUIRED_FIELD_MISSING` 拒绝。需要前端必填校验时在模型字段上声明
|
|
99
|
+
`required: true`,使模型必填与策略对齐。缺失覆盖的诊断会指出字段和 `fields`/`requiredFields` 路径。
|
|
97
100
|
|
|
98
101
|
操作按页面实际需要最小声明:
|
|
99
102
|
|
|
@@ -158,15 +161,22 @@ publicFilters: [{ field: 'enabled', operator: 'eq', value: true }]
|
|
|
158
161
|
|
|
159
162
|
匿名创建需要平台生成的不可预测字段时,使用 `serverGeneratedFields`。这些字段不属于
|
|
160
163
|
`fields`,调用方不能在草稿中写入;提交事务会由平台生成随机值并在提交回执的 `generated`
|
|
161
|
-
|
|
164
|
+
对象中返回。目前仅支持 `random-token` 一种 kind,只适用于不承载身份信息的核验令牌等用途:
|
|
162
165
|
|
|
163
166
|
```ts
|
|
164
167
|
serverGeneratedFields: [{ field: 'qrToken', kind: 'random-token' }]
|
|
165
168
|
```
|
|
166
169
|
|
|
167
|
-
需要跨资源复核预约窗口等业务不变量时,可声明 `schedule
|
|
168
|
-
|
|
169
|
-
|
|
170
|
+
需要跨资源复核预约窗口等业务不变量时,可声明 `schedule`。它把本策略资源上的
|
|
171
|
+
`campusField`(校区)、`dateField`(日期)和 `timeField`(时间)绑定到另外两个**只读公开
|
|
172
|
+
策略**(`campusPolicyCode`/`rulePolicyCode`,必须是同 `publicAccess` 中已声明的策略 code),
|
|
173
|
+
并在规则策略暴露的资源上指定读取哪些字段:`ruleCampusField`(规则所属校区)、
|
|
174
|
+
`ruleWeekdaysField`(开放星期)、`ruleOpenAtField`/`ruleCloseAtField`(每日开放窗口)、
|
|
175
|
+
`ruleSlotMinutesField`(离散时段分钟数)、`ruleAdvanceHoursField`/`ruleAdvanceDaysField`
|
|
176
|
+
(可提前预约的小时/天数上限),以及两个策略各自的启用开关
|
|
177
|
+
`campusEnabledField`/`ruleEnabledField`。十四个键全部必填,字段 code 必须真实存在于
|
|
178
|
+
对应资源。平台会在最终创建事务中重新读取启用的校区与规则,校验星期、日期范围、提前量
|
|
179
|
+
和离散时段;页面端校验只能改善体验,不能替代这次服务端复核。
|
|
170
180
|
|
|
171
181
|
子表中的文件引用会自动带上受控的 `resourceCode` 与父字段绑定;应用如需为附件生成下载地址,使用
|
|
172
182
|
`fileContentUrl(fileId, disposition, variant, resourceCode, parentFieldCode)`,不要自行拼接文件路径。
|
|
@@ -32,6 +32,8 @@ Web 默认保留开发服务回环访问检查。按需 Nest 使用 `tsx --test`
|
|
|
32
32
|
|
|
33
33
|
应用入口或导航变更必须从平台应用列表实际点击进入,再验证应用根路径、登录返回和刷新后的深链接。使用后台的应用检查 `/admin` 进入首个有权菜单、自定义页只出现一个 Shell、菜单切换与未保存保护、无权限拒绝;纯用户应用验证其声明首页,不强制增加后台。直达开发者给出的 `/home` 或报表链接通过,不能替代平台实际入口验收。
|
|
34
34
|
|
|
35
|
+
平台浏览器入口有两个:`/view/<应用标识>/...` 是正式环境入口,`/dev/<应用标识>/...` 是预发(测试环境)入口,路径中的应用标识即 `app.code`。测试部署通过后从 `/dev/<应用标识>` 做浏览器验收;生产晋级后用 `/view/<应用标识>` 复核。`/dev` 入口要求已登录平台账号(应用内数据和功能仍按应用角色权限控制),未部署的环境返回明确的 503 页面,响应头 `X-OpenXiangda-Environment` 标识当前环境。本地 `pnpm openxiangda dev` 的回环地址只用于开发迭代,不能替代这两个平台入口的验收。
|
|
36
|
+
|
|
35
37
|
只改文案时验证受影响页面。复杂事务、并发和值转换使用聚焦测试。浏览器验收实际操作并检查错误,不能用模拟响应或空页面加载代替真实角色验收。
|
|
36
38
|
|
|
37
39
|
匿名访问另验证续填、上传、校验、幂等提交、own.list/own.read;另一浏览器应无法获取前一浏览器的记录。工作流按已启用功能检查发起、处理、历史详情和消息跳转,不为未启用通道增加测试负担。
|
|
@@ -16,7 +16,7 @@
|
|
|
16
16
|
|
|
17
17
|
共享校验使用 `configuration-compatibility/v2` 描述,包含校验实现摘要。切换到这一契约时,平台和项目工具链需按同一发布说明配套升级。随后每次发布在构建前核对实现摘要;不要反复修改业务代码来处理工具版本不配套。
|
|
18
18
|
|
|
19
|
-
引导式开发使用 workspace-context/v3 与 AppSpec context/
|
|
19
|
+
引导式开发使用 workspace-context/v3 与 AppSpec context/v4。升级后按实际业务补齐总纲与关联变更;空模板不能正式测试发布,生产晋级需要原测试版本的验收计划和实际报告。旧候选缺少计划时建立新的测试候选并验收,不自动补写过去的确认或通过记录。普通 dev/check 仍可用于整理和验证尚未完成的项目。
|
|
20
20
|
|
|
21
21
|
## 更新项目 {#upgrade}
|
|
22
22
|
|
|
@@ -58,6 +58,46 @@ events: {
|
|
|
58
58
|
外部 Webhook 和自定义代码仍使用已有签名、回执、重试及接收端幂等协议,按至少
|
|
59
59
|
一次投递处理。轻量操作历史仍通过已有审计 API 查询,不依赖是否订阅了事件。
|
|
60
60
|
|
|
61
|
+
## 定时与日期触发
|
|
62
|
+
|
|
63
|
+
除订阅平台数据事件外,`events` 还能声明两类自有时程触发器;两者都只负责在到期时
|
|
64
|
+
发出应用事件,业务效果仍由订阅(含 `execution: native-data`)或应用后端处理。
|
|
65
|
+
|
|
66
|
+
`events.timers` 按 cron 周期发事件。`code` 为 kebab-case 且唯一;`eventType` 必须是
|
|
67
|
+
`events.schemas` 已声明的应用事件;`cronExpression` 为六段 cron(秒 分 时 日 月 周),
|
|
68
|
+
`timezone` 使用 IANA 名称(如 `Asia/Shanghai`),最短触发间隔为 60 秒;`misfirePolicy`
|
|
69
|
+
目前仅支持 `coalesce_one`(错过合并为一次);`payload` 是普通对象,必须完整满足所引用
|
|
70
|
+
事件的 JSON Schema 且不超过 64 KiB。定时声明属于环境中立的 AppVersion,不写
|
|
71
|
+
`environmentKey`;启用/暂停和下次触发时间由平台按环境管理。
|
|
72
|
+
|
|
73
|
+
```ts
|
|
74
|
+
events: {
|
|
75
|
+
schemas: [{
|
|
76
|
+
eventType: 'app.report.digest.v1',
|
|
77
|
+
dataSchemaVersion: '1',
|
|
78
|
+
jsonSchema: {
|
|
79
|
+
type: 'object', additionalProperties: false,
|
|
80
|
+
required: ['kind'], properties: { kind: { type: 'string' } },
|
|
81
|
+
},
|
|
82
|
+
}],
|
|
83
|
+
timers: [{
|
|
84
|
+
code: 'daily-digest',
|
|
85
|
+
eventType: 'app.report.digest.v1',
|
|
86
|
+
cronExpression: '0 0 9 * * *',
|
|
87
|
+
timezone: 'Asia/Shanghai',
|
|
88
|
+
payload: { kind: 'daily' },
|
|
89
|
+
}],
|
|
90
|
+
},
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
`events.dateTriggers` 相对记录的 date/datetime 字段发事件:字段值加 `offset`(ISO-8601
|
|
94
|
+
时长,十年内,如 `-PT1H` 表示提前一小时)到达时触发。适合到期提醒、超期升级等场景;
|
|
95
|
+
同一条记录的字段更新后按新值重算。`code` 唯一,`eventType` 同样引用已声明应用事件。
|
|
96
|
+
|
|
97
|
+
两类触发器各最多 100 条。事件 Schema 用 `events.schemas` 声明
|
|
98
|
+
(`{ eventType, dataSchemaVersion, jsonSchema, sensitiveFields? }`),`eventType` 遵循
|
|
99
|
+
`xxx.yyy.v1` 版本后缀模式;触发器只发事件,不直接写数据或调用流程。
|
|
100
|
+
|
|
61
101
|
## 标准详情与当前用户入口
|
|
62
102
|
|
|
63
103
|
普通记录、流程记录、任务和实例复用同一详情框架。流程详情提供申请内容、审批历史和变更记录三个标签页;管理员在当前抽屉或页面中切换到普通表单编辑,直接保存并自动留下变更记录,审批结果保持不变。PC 子表在表格内编辑,父表提交时统一校验。
|
|
@@ -113,6 +153,8 @@ Workflow 发起只接受 `{ resourceCode, id }` 形式的 `dataRef`,并要求
|
|
|
113
153
|
|
|
114
154
|
首期只支持 `approval`、`condition`、`end`,以及 `single`、`any`、`all`、`sequence` 审批模式。标准操作为提交、同意、拒绝、退回、重新提交、转交、委托、前/后加签、撤回、管理员改派、管理员终止和不改变流程状态的催办。
|
|
115
155
|
|
|
156
|
+
除命令集之外,平台为实例管理员提供两个维护动作:`admin_jump`(把处于运行或退回状态的实例跳转到指定节点)与 `admin_delete`(删除实例,可选同时删除表单数据、是否触发自动化)。两者走平台管理端点的预览/执行两步流程并要求同源浏览器请求,不属于应用声明的工作流命令,也不占用 `commandToken` 命令合同。
|
|
157
|
+
|
|
116
158
|
复杂业务状态机继续放在应用领域服务。不要把任意 JavaScript、Service Task、BPMN、通用长事务或业务记录复制进 Workflow。
|
|
117
159
|
|
|
118
160
|
所有页面和消息动作必须来自后端 Workflow Surface 的 `operations[]`。前端、模板和渠道 Adapter 不自行推断操作权限。
|