openxiangda 2.0.0-alpha.110 → 2.0.0-alpha.113

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.
Files changed (70) hide show
  1. package/dist/browser/AuthoritativeSelector.d.ts +3 -2
  2. package/dist/browser/AuthoritativeSelector.d.ts.map +1 -1
  3. package/dist/browser/AuthoritativeSelector.js +39 -24
  4. package/dist/browser/AuthoritativeSelector.js.map +1 -1
  5. package/dist/browser/components/platform-fields/MobileFieldControls.d.ts.map +1 -1
  6. package/dist/browser/components/platform-fields/MobileFieldControls.js +2 -2
  7. package/dist/browser/components/platform-fields/MobileFieldControls.js.map +1 -1
  8. package/dist/browser/components/platform-fields/ResourceReferenceField.d.ts +4 -2
  9. package/dist/browser/components/platform-fields/ResourceReferenceField.d.ts.map +1 -1
  10. package/dist/browser/components/platform-fields/ResourceReferenceField.js +2 -2
  11. package/dist/browser/components/platform-fields/ResourceReferenceField.js.map +1 -1
  12. package/dist/browser/components/platform-fields/rich-text-value.d.ts.map +1 -1
  13. package/dist/browser/components/platform-fields/rich-text-value.js +11 -1
  14. package/dist/browser/components/platform-fields/rich-text-value.js.map +1 -1
  15. package/dist/browser/components/resource/SurfaceFields.d.ts +3 -2
  16. package/dist/browser/components/resource/SurfaceFields.d.ts.map +1 -1
  17. package/dist/browser/components/resource/SurfaceFields.js +14 -7
  18. package/dist/browser/components/resource/SurfaceFields.js.map +1 -1
  19. package/dist/browser/components/resource/useResourceFormDrafts.d.ts.map +1 -1
  20. package/dist/browser/components/todo/ApplicationTodoCenterPage.d.ts.map +1 -1
  21. package/dist/browser/components/todo/ApplicationTodoCenterPage.js +1 -2
  22. package/dist/browser/components/todo/ApplicationTodoCenterPage.js.map +1 -1
  23. package/dist/browser/components/workflow/StandardWorkflowPages.d.ts.map +1 -1
  24. package/dist/browser/components/workflow/StandardWorkflowPages.js +29 -21
  25. package/dist/browser/components/workflow/StandardWorkflowPages.js.map +1 -1
  26. package/dist/browser/platform-client.d.ts +3 -2
  27. package/dist/browser/platform-client.d.ts.map +1 -1
  28. package/dist/browser/platform-client.js +68 -18
  29. package/dist/browser/platform-client.js.map +1 -1
  30. package/dist/browser/runtime.d.ts.map +1 -1
  31. package/dist/browser/runtime.js +26 -2
  32. package/dist/browser/runtime.js.map +1 -1
  33. package/dist/browser/workflow-launch.d.ts +4 -1
  34. package/dist/browser/workflow-launch.d.ts.map +1 -1
  35. package/dist/browser/workflow-launch.js +32 -0
  36. package/dist/browser/workflow-launch.js.map +1 -1
  37. package/dist/core.d.ts +1 -1
  38. package/dist/core.d.ts.map +1 -1
  39. package/dist/core.js.map +1 -1
  40. package/documentation/AGENTS.md +2 -2
  41. package/documentation/application-foundation.md +1 -1
  42. package/documentation/appspec.md +61 -11
  43. package/documentation/backend.md +47 -0
  44. package/documentation/data-authz.md +4 -0
  45. package/documentation/development.md +5 -1
  46. package/documentation/field-components.md +34 -2
  47. package/documentation/getting-started.md +7 -4
  48. package/documentation/interaction-patterns.md +56 -0
  49. package/documentation/manifest.json +24 -12
  50. package/documentation/product-design.md +142 -0
  51. package/documentation/reference/cli.md +1 -0
  52. package/documentation/reference/mcp.md +30 -2
  53. package/documentation/testing.md +4 -0
  54. package/documentation/upgrading.md +11 -1
  55. package/package.json +7 -7
  56. package/skills/manifest.json +2 -2
  57. package/skills/openxiangda-v2/SKILL.md +17 -6
  58. package/skills/openxiangda-v2/references/application-foundation.md +1 -1
  59. package/skills/openxiangda-v2/references/appspec.md +61 -11
  60. package/skills/openxiangda-v2/references/backend.md +47 -0
  61. package/skills/openxiangda-v2/references/cli.md +1 -0
  62. package/skills/openxiangda-v2/references/data-authz.md +4 -0
  63. package/skills/openxiangda-v2/references/development.md +5 -1
  64. package/skills/openxiangda-v2/references/field-components.md +34 -2
  65. package/skills/openxiangda-v2/references/getting-started.md +7 -4
  66. package/skills/openxiangda-v2/references/interaction-patterns.md +56 -0
  67. package/skills/openxiangda-v2/references/mcp.md +30 -2
  68. package/skills/openxiangda-v2/references/product-design.md +142 -0
  69. package/skills/openxiangda-v2/references/testing.md +4 -0
  70. package/skills/openxiangda-v2/references/upgrading.md +11 -1
@@ -1,4 +1,25 @@
1
1
  import { SCHEMA_VERSIONS, } from 'openxiangda-contracts/browser';
2
+ export function workflowContextScalarValue(field, value) {
3
+ if (field.type === 'option.single') {
4
+ const option = field.options?.find(item => item.value === value);
5
+ if (!option)
6
+ throw new Error('OPENXIANGDA_WORKFLOW_LAUNCH_CONTEXT_VALUE_INVALID');
7
+ const { label, value: key, description, color } = option;
8
+ return { label, value: key, ...(description ? { description } : {}), ...(color ? { color } : {}) };
9
+ }
10
+ if (field.type === 'number.integer' || field.type === 'number.decimal') {
11
+ const parsed = Number(value);
12
+ if (!Number.isFinite(parsed))
13
+ throw new Error('OPENXIANGDA_WORKFLOW_LAUNCH_CONTEXT_VALUE_INVALID');
14
+ return parsed;
15
+ }
16
+ if (field.type === 'boolean') {
17
+ if (!['true', 'false'].includes(value))
18
+ throw new Error('OPENXIANGDA_WORKFLOW_LAUNCH_CONTEXT_VALUE_INVALID');
19
+ return value === 'true';
20
+ }
21
+ return value;
22
+ }
2
23
  function canonicalWorkflowLaunchJson(value) {
3
24
  if (Array.isArray(value)) {
4
25
  return `[${value
@@ -128,4 +149,15 @@ export function parseWorkflowNamedOperationResult(intent, result, expected) {
128
149
  command,
129
150
  };
130
151
  }
152
+ /** 仅供已接受命令的状态读取;不用于提交、补充或显式重试命令。 */
153
+ export function processStatusReadRetryDelay(error, failures, elapsedMs) {
154
+ if (failures > 5 || elapsedMs >= 60_000)
155
+ return null;
156
+ const status = error && typeof error === 'object' && 'status' in error ? Number(error.status) : 0;
157
+ const networkFailure = error instanceof TypeError || (error instanceof Error && error.name === 'TimeoutError');
158
+ if (!networkFailure && ![408, 429, 500, 502, 503, 504].includes(status))
159
+ return null;
160
+ const delay = Math.min(500 * 2 ** (failures - 1), 5000);
161
+ return elapsedMs + delay < 60_000 ? delay : null;
162
+ }
131
163
  //# sourceMappingURL=workflow-launch.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"workflow-launch.js","sourceRoot":"","sources":["../../src/browser/workflow-launch.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"workflow-launch.js","sourceRoot":"","sources":["../../src/browser/workflow-launch.ts"],"names":[],"mappings":"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"}
package/dist/core.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- export type { DataAuditEntry, DataAuditPage, DataAggregateMeasureType, DataAggregatePage, DataAggregateQuery, DataBatchQueryItemResult, DataBatchQueryOperation, DataBatchQueryRequest, DataBatchQueryResult, DataExportRequest, DataFieldOption, DataFieldSourcePage, DataFieldSourceQuery, DataFieldSurface, DataFilePreview, DataFileRef, DataFileUploadPlan, DataPage, DataQuery, DataRecord, DataResourceSurface, DataTransactionOperation, DataTransactionRequest, DataTransactionResult, DataWhere, DirectoryEntry, DirectoryEntryPage, DirectoryResolveRequest, LabeledValue, NativeAuthorizationManagementCatalog, NativeAuthorizationMutationReceipt, NativeRoleManagementAction, NativeRoleManagementAuthority, NativeRoleManagementGrant, NativeRoleManagementGrantMutationResult, NativeRoleManagementGrantPage, NativeRoleMembership, NativeRoleMembershipMutationResult, NativeRoleMembershipPage, NativeScopeGrant, ResourceReferenceValue, RuntimeAuthorizationContext, RuntimeAuthorizationIdentity, StableAddressValue, StableLocationValue, SubjectProfile, WorkflowDetailNavigation, WorkflowBusinessData, WorkflowBusinessDataStatus, WorkflowCommandResult, WorkflowDetailSurfaceV2, WorkflowInstance, WorkflowSurface, WorkflowTask, WorkflowTimeline, WorkflowWorkCenterItem, } from 'openxiangda-contracts/browser';
1
+ export type { DataAuditEntry, DataAuditPage, DataAggregateMeasureType, DataAggregatePage, DataAggregateQuery, DataBatchQueryItemResult, DataBatchQueryOperation, DataBatchQueryRequest, DataBatchQueryResult, DataExportRequest, DataFieldOption, DataFieldSourcePage, DataFieldSourceQuery, DataFieldSourceLaunchBinding, DataFieldSurface, DataFilePreview, DataFileRef, DataFileUploadPlan, DataPage, DataQuery, DataRecord, DataResourceSurface, DataTransactionOperation, DataTransactionRequest, DataTransactionResult, DataWhere, DirectoryEntry, DirectoryEntryPage, DirectoryResolveRequest, LabeledValue, NativeAuthorizationManagementCatalog, NativeAuthorizationMutationReceipt, NativeRoleManagementAction, NativeRoleManagementAuthority, NativeRoleManagementGrant, NativeRoleManagementGrantMutationResult, NativeRoleManagementGrantPage, NativeRoleMembership, NativeRoleMembershipMutationResult, NativeRoleMembershipPage, NativeScopeGrant, ResourceReferenceValue, RuntimeAuthorizationContext, RuntimeAuthorizationIdentity, StableAddressValue, StableLocationValue, SubjectProfile, WorkflowDetailNavigation, WorkflowBusinessData, WorkflowBusinessDataStatus, WorkflowCommandResult, WorkflowDetailSurfaceV2, WorkflowInstance, WorkflowSurface, WorkflowTask, WorkflowTimeline, WorkflowWorkCenterItem, } from 'openxiangda-contracts/browser';
2
2
  export * from './browser/platform-client';
3
3
  export * from './browser/runtime-meta';
4
4
  export * from './browser/components/platform-fields/resource-query';
@@ -1 +1 @@
1
- {"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,cAAc,EACd,aAAa,EACb,wBAAwB,EACxB,iBAAiB,EACjB,kBAAkB,EAClB,wBAAwB,EACxB,uBAAuB,EACvB,qBAAqB,EACrB,oBAAoB,EACpB,iBAAiB,EACjB,eAAe,EACf,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,EAChB,eAAe,EACf,WAAW,EACX,kBAAkB,EAClB,QAAQ,EACR,SAAS,EACT,UAAU,EACV,mBAAmB,EACnB,wBAAwB,EACxB,sBAAsB,EACtB,qBAAqB,EACrB,SAAS,EACT,cAAc,EACd,kBAAkB,EAClB,uBAAuB,EACvB,YAAY,EACZ,oCAAoC,EACpC,kCAAkC,EAClC,0BAA0B,EAC1B,6BAA6B,EAC7B,yBAAyB,EACzB,uCAAuC,EACvC,6BAA6B,EAC7B,oBAAoB,EACpB,kCAAkC,EAClC,wBAAwB,EACxB,gBAAgB,EAChB,sBAAsB,EACtB,2BAA2B,EAC3B,4BAA4B,EAC5B,kBAAkB,EAClB,mBAAmB,EACnB,cAAc,EACd,wBAAwB,EACxB,oBAAoB,EACpB,0BAA0B,EAC1B,qBAAqB,EACrB,uBAAuB,EACvB,gBAAgB,EAChB,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,sBAAsB,GACvB,MAAM,+BAA+B,CAAC;AACvC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,wBAAwB,CAAC;AACvC,cAAc,qDAAqD,CAAC;AACpE,mBAAmB,6DAA6D,CAAC"}
1
+ {"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,cAAc,EACd,aAAa,EACb,wBAAwB,EACxB,iBAAiB,EACjB,kBAAkB,EAClB,wBAAwB,EACxB,uBAAuB,EACvB,qBAAqB,EACrB,oBAAoB,EACpB,iBAAiB,EACjB,eAAe,EACf,mBAAmB,EACnB,oBAAoB,EACpB,4BAA4B,EAC5B,gBAAgB,EAChB,eAAe,EACf,WAAW,EACX,kBAAkB,EAClB,QAAQ,EACR,SAAS,EACT,UAAU,EACV,mBAAmB,EACnB,wBAAwB,EACxB,sBAAsB,EACtB,qBAAqB,EACrB,SAAS,EACT,cAAc,EACd,kBAAkB,EAClB,uBAAuB,EACvB,YAAY,EACZ,oCAAoC,EACpC,kCAAkC,EAClC,0BAA0B,EAC1B,6BAA6B,EAC7B,yBAAyB,EACzB,uCAAuC,EACvC,6BAA6B,EAC7B,oBAAoB,EACpB,kCAAkC,EAClC,wBAAwB,EACxB,gBAAgB,EAChB,sBAAsB,EACtB,2BAA2B,EAC3B,4BAA4B,EAC5B,kBAAkB,EAClB,mBAAmB,EACnB,cAAc,EACd,wBAAwB,EACxB,oBAAoB,EACpB,0BAA0B,EAC1B,qBAAqB,EACrB,uBAAuB,EACvB,gBAAgB,EAChB,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,sBAAsB,GACvB,MAAM,+BAA+B,CAAC;AACvC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,wBAAwB,CAAC;AACvC,cAAc,qDAAqD,CAAC;AACpE,mBAAmB,6DAA6D,CAAC"}
package/dist/core.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"core.js","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"AA0DA,cAAc,2BAA2B,CAAC;AAC1C,cAAc,wBAAwB,CAAC;AACvC,cAAc,qDAAqD,CAAC"}
1
+ {"version":3,"file":"core.js","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"AA2DA,cAAc,2BAA2B,CAAC;AAC1C,cAAc,wBAAwB,CAAC;AACvC,cAAc,qDAAqD,CAAC"}
@@ -12,13 +12,13 @@
12
12
  - 日常使用 dev 和聚焦测试。只验证时使用 check;授权部署时直接 deploy,它已包含检查、测试和构建。生产必须指定成功测试运行并复用同一版本。
13
13
  - deploy 默认持续反馈并跟踪平台结果;观察中断用 status <运行ID> --watch 继续,保留原运行,不重新构建。平台部署成功后仍需真实角色业务验收。
14
14
  - 开发开始先同步远端默认主分支;同一工作区只有一个写者。发布前将本轮源码、生成契约与记录合入并推送主分支,从干净且同步的主分支冻结候选;任务分支已推送不等于已合入主线。不要覆盖其他会话改动或自动合并所有分支。
15
- - 默认读取 AppSpec 当前规格、活动变更和阶段缺口,按角色、规则、页面、数据澄清模糊需求,再评估架构、权限和性能边界。总纲保存长期规则,本轮变更关联需求、任务、源码与 AC 验收;测试发布前完成设计与计划,生产晋级前保存绑定原测试运行及包摘要的实际验收报告。更新当前规则、验证与发布结果和交接后归档;不得编造确认或通过结果。
15
+ - 默认读取 AppSpec 当前规格、设计索引、活动变更和阶段缺口。新应用先用自然语言对话主动发现模块,完成本期 PRD、旅程、逐页交互、视觉/原型、权限与架构设计及实际确认,形成内容摘要绑定的评审基线后再制定实施计划和实现业务;参见 docs product-design 和 docs interaction-patterns。既有应用仅修订受影响设计,不把 AI 建议写成用户确认。总纲保存长期规则,本轮变更关联需求、任务、源码与 AC 验收;测试发布前完成设计与计划,生产晋级前保存绑定原测试运行及包摘要的实际验收报告。更新当前规则、验证与发布结果和交接后归档;不得编造确认或通过结果。
16
16
  - 根据变化风险记录业务意图。无行为变化引用已有记录;已有授权和已确认意图不重复向用户请求机械确认。真实角色和浏览器验收与本地测试分别记录。
17
17
  - 失败保留错误码、指针和原候选;查询平台状态后使用允许的恢复操作,不自动重放未知结果。
18
18
 
19
19
  MCP 使用同一项目 CLI:`pnpm exec openxiangda --mcp-stdio --cwd <workspace>`。先读取 workspace_context,再按任务读取 docs_read 和当前契约。登录、创建及长期 dev 使用 CLI/终端。
20
20
 
21
- 详细用法:`pnpm openxiangda docs development`、`docs frontend`、`docs data-authz`、`docs administration`、`docs testing`、`docs delivery`。按需加载,无需每次通读全部资料。
21
+ 详细用法:`pnpm openxiangda docs product-design`、`docs interaction-patterns`、`docs development`、`docs frontend`、`docs data-authz`、`docs administration`、`docs testing`、`docs delivery`。按需加载,无需每次通读全部资料。
22
22
  <!-- OPENXIANGDA:END -->
23
23
 
24
24
  ## 项目自有约定
@@ -131,7 +131,7 @@ import 'openxiangda/mobile/styles.css';
131
131
 
132
132
  普通 CRUD 可以省略 `backend`、`platform` 配置,`pnpm dev` 通过现有 connected development 连接平台。默认模板不包含后端源码;显式启用或声明需要应用代码执行的后端能力后,`pnpm openxiangda check` 或 `pnpm dev` 按需初始化源码与依赖,再启动 Nest。标准流程定义和激活由平台执行,不要求应用后端。
133
133
 
134
- 在现有 `appspec/app.md` 保留需求、任务页面、权限矩阵及验收记录。业务角色与权限由用户确认;技术 schema、接口和存储计划由平台产出。简单应用只维护这份短文档,复杂模块再拆分能力记录。
134
+ `appspec/app.md` 维护总纲和设计索引。新应用按[产品设计](./product-design.md)完成本期详细需求、任务旅程、逐页交互、权限与架构及实际确认基线,再制定实施计划;已有小变更只修订受影响材料。业务角色与权限由用户确认,技术 schema、接口和存储计划由平台产出;按业务规模拆分能力记录。
135
135
 
136
136
  先读取 MCP 契约索引,再调用 `contract_describe` 并传入 `{ "selector": "permissions" }`,读取
137
137
  `data.selection.permissionReview`。该产物使用 `openxiangda.permission-review/v2`,
@@ -2,11 +2,15 @@
2
2
 
3
3
  AppSpec 是默认开发流程中的业务记录,保存在应用 Git 仓库。AI 负责整理需求、分析架构和性能、维护记录;产品经理主要说明目标与业务规则。当前总纲、实现声明、实际验收和平台部署各有自己的事实来源,不能互相替代。
4
4
 
5
- ## 最小结构
5
+ ## 资料结构
6
6
 
7
7
  ```text
8
8
  appspec/
9
9
  app.md # 当前有效目标、规则、架构、页面、权限、容量
10
+ product/ # 来源、范围与 PRD
11
+ experience/ # 旅程、逐页交互
12
+ design/ # 视觉、权限、架构与原型引用
13
+ reviews/ # 实际确认与设计基线
10
14
  capabilities/ # 复杂后再按业务能力拆分,不要求小应用创建
11
15
  changes/active/ # 本轮需求、设计、任务、验收与交接
12
16
  changes/history/ # 完成后的变更,按年保存
@@ -14,16 +18,16 @@ appspec/
14
18
  verification/ # 绑定测试版本的业务验收报告
15
19
  ```
16
20
 
17
- 简单应用维护总纲和一份短变更即可。业务规则使用 `### REQ-*`,可观察验收使用 `#### AC-*`;ID 稳定,变更引用当前总纲或能力中的规则。声明和生成契约保存模型、字段与接口,AppSpec 不复制 Schema 全集。截图、请求轨迹等证据保留实际文件或 HTTPS 引用,不提交凭据和敏感业务数据。
21
+ 新应用按[产品设计](./product-design.md)完成本期详细材料和设计基线;既有变更只更新受影响范围,文案和无行为变化沿用有效基线。业务规则使用 `### REQ-*`,可观察验收使用 `#### AC-*`;ID 稳定,变更引用当前总纲或能力中的规则。声明和生成契约保存模型、字段与接口,AppSpec 不复制 Schema 全集。截图、请求轨迹等证据保留实际文件或 HTTPS 引用,不提交凭据和敏感业务数据。
18
22
 
19
23
  ## 从模糊需求到实现
20
24
 
21
- 1. 读取 `context --json`、相关 `spec context <ID> --json`,核对已有规则、活动变更和影响范围。
22
- 2. 把需求整理为角色、场景、输入、规则、输出、异常和非目标。会改变权限、数据归属或难以恢复的业务决定先澄清;可逆技术细节自行选择并记录假设,已有确认持续有效。
23
- 3. 总纲说明领域与模型关系、PC/移动任务页面、平台能力归属、页面/操作/行/字段权限和多角色组合。普通 CRUD、身份、审批和消息复用平台所有者。
24
- 4. 写明数据规模、增长、分页、必要索引、请求次数、延迟目标、并发与批量边界。区分估算、目标和实测;避免全量读后在浏览器聚合、逐行请求和无限重试。
25
- 5. 本次 ChangeSpec 说明为什么、需求依据、方案与影响、任务与实现、性能预算及验收计划。复杂变化补数据与权限、失败/幂等、回滚和 ADR。状态按实际进展维护,不能把草稿自动标成用户已确认。
26
- 6. 实施、检查、测试部署、真实角色验收、生产晋级后,把持续有效规则合回当前总纲或能力规格,记录剩余问题并归档。
25
+ 1. 读取当前总纲、设计索引与相关稳定 ID,分析用户提供资料,区分事实、候选建议、实际确认、延期与冲突。
26
+ 2. 主动帮助用户从真实任务发现模块,逐轮少量提问、建议与复述,已确认且未变的决定持续有效。
27
+ 3. 完成本期产品、旅程、逐页交互、视觉/原型、权限和架构设计;按角色走查主任务与异常,维护容量预算与可证伪 AC。
28
+ 4. ChangeSpec 的 documents 引用一份 review 设计文档;评审关联受评设计的传递引用闭包、实际确认来源和 baselineDigest。具体模板及范围规则见[产品设计](./product-design.md#templates)。
29
+ 5. readyForImplementation 成立后制定实施计划,关联 REQ、设计、源码和 AC;本轮任务及原有交付章节完整后 readyForTest 成立。
30
+ 6. 实施、检查、测试部署、真实角色验收、生产晋级后,更新持续有效规则、实际结果和交接,再归档。
27
31
 
28
32
  `未确认问题` 下的 `- [ ]` 表示正式交付阻断项。非阻断假设另写说明。只有章节、一个 `passed` 标记或 AI 的判断,均不能证明业务验收实际发生。
29
33
 
@@ -36,13 +40,26 @@ pnpm openxiangda spec context booking-window --json
36
40
  pnpm openxiangda spec check
37
41
  ```
38
42
 
43
+ 已有工作区优先用 `spec new` 生成本地记录。访谈尚未创建应用时,可在 `appspec/changes/active/<变更ID>.md` 手工建草稿:front matter 使用 `schema: openxiangda.appspec/change/v1`、与文件名一致的 `id`、`title`、`status: draft`、`currentSpec: pending`、适用的 `risk`,以及 `documents: [实际评审ID]`。不必为整理设计先创建远端应用。
44
+
45
+ | 阶段或风险 | ChangeSpec 必需正文 |
46
+ | --- | --- |
47
+ | 设计阶段 | 为什么、需求依据、方案与影响、验收、性能与容量预算;引用详细权威材料并说明本轮影响 |
48
+ | 设计就绪后 | 补齐任务与实现;草稿不能冒充已可测试 |
49
+ | L2 / L3 | 另写数据与权限、回滚;引用权限和架构材料,说明适用范围或不适用理由 |
50
+ | L3 | 另写失败、并发与幂等、架构决策;需要长期决定时关联实际 ADR |
51
+ | 关闭前 | 验证与发布、交接,填写实际结果和剩余事项 |
52
+
53
+ `未确认问题` 单独保留阻断项,设计评审和实施任务按[开工顺序](./product-design.md#readiness)分步完成。章节名用于定位缺口,空标题、模板提示和未执行的验收计划均不是完成证据。
54
+
39
55
  有且仅有一个活动变更时自动关联。多个活动变更或引用历史记录时,在本次 Git 提交说明中加入 `AppSpec: booking-window`。格式、无行为重构可引用已有记录,在提交说明写清不改变业务行为的依据,无需制造重复文档;新的行为变化仍要更新相应变更。
40
56
 
41
57
  | 操作 | 实际要求 |
42
58
  | --- | --- |
43
59
  | dev、只读分析 | 可以研究和预览,不能把原型当作已完成交付 |
44
60
  | 普通 check / check_app | 技术验证照常进行,需求与设计缺口作为单独诊断返回 |
45
- | spec check | 严格检查当前文档、关联变更和测试发布前的完整性 |
61
+ | spec context | 返回 readyForImplementation、readyForTest、评审摘要与缺口;不自动确认 |
62
+ | spec check | 严格检查当前文档、设计基线、关联变更和测试发布前的完整性 |
46
63
  | 测试 deploy / deploy_app | 总纲、设计、需求依据、性能预算、AC 计划完整;尚不要求线上业务验收报告 |
47
64
  | 生产晋级 | 读取指定成功测试运行的同一制品,并核对绑定该版本的实际验收报告 |
48
65
  | spec close | 当前长期规则已回写,“验证与发布”和“交接”有实际结论;未发布、取消和未覆盖项明确说明 |
@@ -95,8 +112,41 @@ MCP `appspec_verify` 读取同一报告与运行事实。`spec verify` 根据当
95
112
 
96
113
  ## 新任务找回上下文
97
114
 
98
- `context` / `workspace_context` 默认返回总纲、相关变更索引、阶段缺口和下一步。`spec context` / `appspec_context` 的 context v3 默认只返回总纲正文及有界索引,按稳定 ID 加载相关能力、变更和 ADR 正文。当前资料最多 128 文件、2 MiB,正文上下文最多 256 KiB,超出时明确诊断。
115
+ ### 架构决定的编号与创建
116
+
117
+ 需要长期引用的决定写入 `appspec/decisions/` 下的 Markdown。ADR 的 `id` 格式是 `ADR-` 加**恰好四位数字**,可选 `-` 分隔的大写字母或数字后缀,例如 `ADR-0001`、`ADR-0001-DATA-OWNER`;`ADR-001` 不合法。文件名建议与 ID 一致,引用使用元数据中的 ID。当前没有独立的 ADR 创建命令,可以手工创建,随后用 `spec context <ID>` 和 `spec check` 核对。
118
+
119
+ 以下是 `appspec/decisions/ADR-0001.md` 的提议示例;它不表示已经确认或可以发布:
120
+
121
+ ```markdown
122
+ ---
123
+ schema: openxiangda.appspec/decision/v1
124
+ id: ADR-0001
125
+ title: 业务数据的权威来源
126
+ status: proposed
127
+ ---
128
+
129
+ # 业务数据的权威来源
130
+
131
+ ## 问题与方案
132
+
133
+ 业务记录由平台 Data API 持有,应用按当前用户权限读取;前端不另建持久业务数据库。
134
+
135
+ ## 影响与验证
136
+
137
+ 关联查询使用平台字段来源,验收时分别核对允许与禁止角色的真实读取结果。
138
+
139
+ ## 未确认问题
140
+
141
+ - [ ] 确认本期是否存在需要独立后端事务的业务不变量。
142
+ ```
143
+
144
+ ADR 状态支持 `proposed`、`accepted`、`superseded`、`rejected`;按真实决定更新,不为通过检查直接填 `accepted`。可选元数据为 `date`、`deciders`、`supersedes`、`documents`;确认依据和方案取舍写正文。变更用 `decisions: [ADR-0001]` 关联,设计材料也可用 `documents: [ADR-0001]` 引用。修正已有编号时同步相关引用并保留 Git 历史,不删除旧决定来规避检查。
145
+
146
+ ### 按 ID 读取
147
+
148
+ `context` / `workspace_context` 默认返回总纲、相关变更索引、阶段缺口和下一步。`spec context` / `appspec_context` 的 context v4 默认只返回总纲正文及有界索引,按稳定 ID 加载相关能力、变更、ADR 和 DES-* 设计正文及 documents 传递引用。product/experience/design/reviews 的单层 Markdown 也进入当前资料与原测试提交读取;非 Markdown 原型只引用不执行。当前资料最多 128 文件、2 MiB,正文上下文最多 256 KiB,超出时明确诊断。
99
149
 
100
150
  历史与当前资料独立预算,每页 50 条,使用 `--history-offset 50` 或 MCP `historyOffset` 翻页。历史索引仅读取头部,稳定历史 ID 可直接读取页外正文;归档增加不会挤掉当前资料。索引读取上限为 256 个年份目录、10 万个记录名和 5 秒,达到预算给出提示,文件不会删除。`workspaceDigest` 对应当前资料与实时契约,分页不改变它;`selectionDigest` 对应选中的具体正文与契约。
101
151
 
102
- 当前仓库规格不等于生产已上线功能。环境使用哪个版本从平台读取;历史用于解释演进原因,后续实现优先遵循当前有效规则。旧 2.0 应用升级后补齐实际记录,不导入 1.x SDD,也不自动生成虚假确认或验收。
152
+ 当前仓库规格不等于生产已上线功能。环境使用哪个版本从平台读取;历史用于解释演进原因,后续实现优先遵循当前有效规则。旧 alpha 记录没有设计评审时不会自动升级成已确认;补齐真实设计和评审后重新测试发布。旧 2.0 应用升级后补齐实际记录,不导入 1.x SDD,也不自动生成虚假确认或验收。
@@ -24,6 +24,7 @@ operation、事件消费者、人员提供器,然后运行 `pnpm openxiangda c
24
24
  | 当前用户范围的数据 | `OpenXiangdaDataApiService` | 平台行/字段权限和读取 Perspective |
25
25
  | 已授权业务动作的跨模型读写 | `OpenXiangdaBusinessDataApiService` | 声明的 operation;平台保留发起人审计 |
26
26
  | 原子写入与幂等回执 | `.transaction(idempotentTransaction(...))` | 同一平台事务,不读后再写 |
27
+ | 分派对象必须具有指定角色 | 事务 `role-member` 条件 | 具名动作声明允许核对的角色;平台核对有效成员与并发 |
27
28
  | 托管文件 | Data SDK 的 `initiateFileUpload` / `completeFileUpload` / `copyManagedFile` | 平台文件归属和操作授权 |
28
29
  | 标准流程 | `OpenXiangdaWorkflowService`;带业务提交用 `OpenXiangdaBusinessProcessService` | 平台命令 token、版本和回执 |
29
30
  | 当前用户待办 | `OpenXiangdaTodoService` | 平台投影,不另建待办表 |
@@ -55,6 +56,52 @@ operation、事件消费者、人员提供器,然后运行 `pnpm openxiangda c
55
56
 
56
57
  同一业务变更用一次受限事务表达。断言、派生计数、写入和事件保持原子性;遇到可重试响应时复用不可变 payload 和 idempotencyKey,不先读取可变状态再决定写入。
57
58
 
59
+ ## 在分派事务中核对目标角色 {#role-member}
60
+
61
+ 维修派单、指定审核人等规则不能只依赖页面筛选或先查成员再写入。先在对应
62
+ `backend.operations[]` 的 `platformAccess` 声明允许核对的应用角色:
63
+
64
+ ```ts
65
+ platformAccess: { roleAssertions: { roleCodes: ['technician'] } }
66
+ ```
67
+
68
+ `technician` 必须存在于本应用 `authz.roles`,最多声明 20 个角色。应用管理员身份
69
+ 不自动代表维修角色。人员候选可以使用已有且已委托管理范围的成员查询;这项声明
70
+ 本身不授予成员管理或人员目录权限。
71
+
72
+ 在 `OpenXiangdaBusinessDataApiService` 的同一次事务中表达业务状态与目标角色:
73
+
74
+ ```ts
75
+ await businessData.transaction({
76
+ schemaVersion: 'openxiangda.data-transaction-request/v2',
77
+ idempotencyKey: input.idempotencyKey,
78
+ guards: [
79
+ { kind: 'role-member', userId: input.technicianId, roleCode: 'technician',
80
+ errorCode: 'OPENXIANGDA_ASSIGNEE_INVALID' },
81
+ { kind: 'record-assert', resourceCode: 'service-orders', id: input.id,
82
+ lockKey: `service-order:${input.id}`, errorCode: 'OPENXIANGDA_ORDER_STATE_INVALID',
83
+ assertions: [{ kind: 'value', field: 'status', operator: 'eq', value: 'approved' }] },
84
+ ],
85
+ operations: [{ operation: 'update', resourceCode: 'service-orders', id: input.id,
86
+ expectedRevision: input.revision, data: { assignedTo: input.technicianId, status: 'assigned' } }],
87
+ });
88
+ ```
89
+
90
+ 以上是接入片段;模型、字段、角色、动作 capability 和请求输入仍需在应用中声明。
91
+ 角色条件只有 `kind/userId/roleCode/errorCode`,不接受环境、成员快照、调用者锁名或
92
+ 调用者时间。所有 guard 合计最多 20 项。带业务写入的流程提交同样可以使用这一条件。
93
+ 普通用户 Data SDK、应用凭据和事件处理器不能使用;伪造操作请求头不能获得授权。
94
+
95
+ 平台在同一事务内核对当前租户、应用、环境和版本,以数据库取得的统一时间检查
96
+ 显式成员是否生效、过期或已撤销,并核对授权投影就绪。条件不成立返回指定失败码,
97
+ 无业务写入;没有声明返回 `OPENXIANGDA_ROLE_ASSERTION_NOT_DECLARED`。并发角色撤销、
98
+ 投影或环境切换返回 `OPENXIANGDA_ROLE_ASSERTION_CONFLICT`,锁等待最多 1 秒,整笔回滚。
99
+ 保留原请求和幂等键,根据当前业务状态决定是否重试。成功请求重放只返回已有结果;
100
+ 同一幂等请求绑定原发起人和业务动作,换人或换动作不能复用该回执。
101
+
102
+ 分派已接受后撤销角色,不会自动撤销历史分派;后续处理动作必须重新验证当前权限,
103
+ 由管理员重新分派。此规则应写入 AppSpec,并实测撤销先发生和分派先发生两种顺序。
104
+
58
105
  ## 启动与依赖注入 {#bootstrap}
59
106
 
60
107
  ```ts
@@ -56,3 +56,7 @@ impersonation token。mutation 必须携带 UUID `operationId`、`reason`,更
56
56
  `date-range` 与 `datetime-range` 必须显式声明 `rangeBoundary`,取值为 closed 或 half-open。选择半开区间 `[start, end)` 时相邻时间段不冲突;闭区间端点相接可能重叠。
57
57
 
58
58
  业务 uuid 字段与系统 id 不同:可选业务 UUID 省略时为空,必填字段需调用方提供合法值,平台不会替业务 UUID 自动生成默认值。
59
+
60
+ 业务分派需要目标人员具有指定角色时,使用[事务中的角色条件](./backend.md#role-member),
61
+ 由平台在写入事务中核对当前有效成员。候选查询、页面隐藏、应用管理员身份和历史
62
+ 角色列表都不能替代这一规则,也不应在应用中复制一份权限状态。
@@ -2,6 +2,10 @@
2
2
 
3
3
  先确认用户要完成的任务,再选择数据模型、页面和权限。使用项目锁定的 `pnpm openxiangda`,读取 `context --json` 与相关专题。现有项目的代码和实时契约优先于其他项目的样例。
4
4
 
5
+ ## 新应用先完成设计基线
6
+
7
+ 从模糊想法开始时,按[对话发现与产品设计](./product-design.md)分析已有资料、提出可解释的模块建议,用少量自然语言问题持续沟通确认。完整首发范围的 PRD、旅程、页面交互、原型、权限和架构设计齐备后,再制定实施计划和编写业务实现。用户已给出完整材料时先核对矛盾和遗漏,不重复访谈;已有确认持续有效。
8
+
5
9
  ## 根据任务决定工作量 {#risk}
6
10
 
7
11
  | 变化 | 需要明确的内容 | 验证 |
@@ -25,4 +29,4 @@
25
29
 
26
30
  开发使用 `pnpm openxiangda dev`,过程中运行必要的聚焦测试。交接前按[检查与验收](./testing.md)验证;授权发布后按[交付](./delivery.md)部署。失败保留错误码、位置和原始候选,依据平台恢复指令继续。
27
31
 
28
- [AppSpec](./appspec.md)保存业务意图、设计与交付记录,不复制字段 Schema、生成契约和部署状态。简单应用维护总纲与一份短变更;无行为变化可引用已有记录。每轮先读取当前规则、澄清业务、评估架构、权限和性能,随后实施与验证,发布后更新当前规格及交接。测试部署前需要设计和验收计划,生产晋级前需要绑定测试运行及包摘要的实际验收报告。
32
+ [AppSpec](./appspec.md)保存业务意图、设计与交付记录,不复制字段 Schema、生成契约和部署状态。新应用维护具体设计和评审,复杂度随业务展开;既有小变更沿用有效设计,仅修订受影响记录,无行为变化可引用已有记录。每轮先读取当前规则、澄清业务、评估架构、权限和性能,随后实施与验证,发布后更新当前规格及交接。测试部署前需要设计和验收计划,生产晋级前需要绑定测试运行及包摘要的实际验收报告。
@@ -16,7 +16,7 @@ PostgreSQL 物理列、索引、查询运算符、权限路径和桌面/移动
16
16
  | `text.rich` | 富文本 | 清洗后的 HTML `string` | `text` |
17
17
  | `number.integer` | 整数 | `number` | `bigint` |
18
18
  | `number.decimal` | 小数、金额、百分比 | `number` | `numeric(p,s)` |
19
- | `boolean` | 开关 | `boolean` | `boolean` |
19
+ | `boolean` | 是/否选择 | `boolean` | `boolean` |
20
20
  | `date` | 日期 | `YYYY-MM-DD` | `date` |
21
21
  | `time` | 时间,可声明分钟或秒精度 | `HH:mm:ss` | `time(0)` |
22
22
  | `datetime` | 日期时间 | RFC3339 instant | `timestamptz` |
@@ -45,6 +45,33 @@ PostgreSQL 物理列、索引、查询运算符、权限路径和桌面/移动
45
45
  单值空值统一使用 `null`;多值、附件和图片统一使用 `[]`。`subtable` 不在父表保存
46
46
  JSON,而是通过标准 Data API 事务维护普通子资源。
47
47
 
48
+ 布尔字段没有默认值时显示“未选择”,不会把未填写当成“否”。PC 和移动端可以直接选择“否”并提交 `false`;`false` 是有效值,不是必填校验中的空值。只有明确声明默认值时才初始化对应布尔值。
49
+
50
+ ## 图片、缩略图和附件读取
51
+
52
+ 文件本体保存于平台对象存储,业务字段保存 `DataFileRef[]` 或 `DataImageRef[]`,不把 Base64 图片、文件字节、浏览器 `blob:` 地址写入业务字段。`previewUrl` 和 `thumbnailUrl` 是平台按当前应用、环境和文件权限生成的读取地址,不是永久公开 OSS 地址;不要自行替换域名、删除环境参数或拼接对象存储路径。
53
+
54
+ 图片上传完成后,平台保留原文件,并生成最长边 480 像素、保持比例、不放大小图的 WebP 缩略图,编码质量参数为 82。列表、活动卡片、小封面和头像优先用缩略图;大图预览和下载按需读取原文件。当前原生文件端点只支持原文件和 `variant=thumbnail`,不能自行拼接 `width`、`quality` 等未声明参数。附件字段中的图片不保证具有缩略图,需要缩略图能力时声明 `image` 字段。
55
+
56
+ 标准图片/附件展示可以直接使用 Field Kit:
57
+
58
+ ```tsx
59
+ import { AttachmentFileList } from 'openxiangda/field-kit';
60
+
61
+ <AttachmentFileList
62
+ files={record.cover ?? []}
63
+ resourceCode="activities"
64
+ imageTiles
65
+ mobile={isMobile}
66
+ />
67
+ ```
68
+
69
+ 组件按文件引用选择缩略图,预览和下载经过平台接口。自定义活动封面同样先选择 `cover.thumbnailUrl`;只有平台引用没有缩略图时才回退 `cover.previewUrl`。不要写 `previewUrl || thumbnailUrl`,否则小卡片也会下载完整原图。保留真实宽高或稳定的封面比例,非首屏图片使用懒加载;不得在列表渲染时预取所有原图。
70
+
71
+ 受限文件的缓存必须保留权限核验。配套平台支持私有条件缓存时,浏览器可以保存文件响应,再次访问由平台先核对当前权限,内容未变化返回 304,从本地复用字节;`no-cache` 表示复用前校验,和 `no-store` 禁止保存不同。缺少可靠实体标识或请求失败时仍禁止缓存。不应由应用添加长期免校验缓存、公开 CDN 缓存或跨账号 Blob 缓存来绕过该规则。公开长期缓存需要独立、明确的公开发布契约,不能仅因字段名叫封面就视为公开。
72
+
73
+ 验收时同时记录原图/缩略图字节、列表实际请求的变体、重复访问传输量和权限撤销结果。仅看到 `blob:` 地址不能判断用了 Base64,HTTP 200 也不能证明命中了缓存。
74
+
48
75
  ## 声明示例
49
76
 
50
77
  ```ts
@@ -92,7 +119,12 @@ JSON,而是通过标准 Data API 事务维护普通子资源。
92
119
  }
93
120
  ```
94
121
 
95
- 来源端点只接受当前表单绑定值、关键字和游标;页大小由 `source.pageSize` 固定。
122
+ 来源端点接受当前表单绑定值、关键字和游标;页大小由 `source.pageSize` 固定。
123
+ 标准流程的具名动作发起表单由 `WorkflowSubmissionPage` 自动传递 `launch: { workflowCode, operationCode }`。
124
+ 平台核对当前环境已部署的流程、动作、输入字段映射和当前用户动作权限;不要求额外授予宿主表单 CRUD 权限。
125
+ 普通 CRUD 表单不传此绑定,继续检查对应创建/修改权限。自定义选择器可通过 `searchResource` 的同名选项传递
126
+ 已声明的发起绑定,不能用它扩大目标资源的读取范围或执行动作。
127
+ 使用此功能的编译包自动要求平台能力 `workflow.named-input-sources` 的 `1.0.0` 版本;先检查目标平台能力,配套升级后再发布。
96
128
  平台按来源资源的字段权限和 PostgreSQL RLS 查询并返回完整资源快照。来源记录改名或删除后,
97
129
  已经保存的 `{label,value,resourceCode,snapshot}` 仍可直接展示,不需要再次查询。
98
130
 
@@ -11,9 +11,10 @@ OpenXiangda 2.0 默认生成 React 应用和共享契约。普通 CRUD、标准
11
11
  以下命令的版本占位符由随包资料替换为该根包的精确版本。网站源码阅读者应先确认要使用的发行版本。
12
12
 
13
13
  ```bash
14
- pnpm dlx openxiangda@2.0.0-alpha.110 skill install --force
15
- pnpm dlx openxiangda@2.0.0-alpha.110 login --base-url https://platform.example.com
16
- pnpm dlx openxiangda@2.0.0-alpha.110 create my-app --base-url https://platform.example.com
14
+ pnpm dlx openxiangda@2.0.0-alpha.113 skill install --force
15
+ pnpm dlx openxiangda@2.0.0-alpha.113 auth status --base-url <平台地址> --json
16
+ pnpm dlx openxiangda@2.0.0-alpha.113 login --base-url https://platform.example.com
17
+ pnpm dlx openxiangda@2.0.0-alpha.113 create my-app --base-url https://platform.example.com
17
18
  cd my-app
18
19
  pnpm openxiangda context --json
19
20
  pnpm openxiangda dev
@@ -38,7 +39,7 @@ AGENTS.md 平台约定与项目自有说明
38
39
 
39
40
  以实际模板输出为准。资源与页面通过模块声明组合,不创建 `platform/data`。`apps/server` 仅在启用后端时初始化;后续保留用户业务代码。
40
41
 
41
- AppSpec 随开发持续维护:测试发布前补齐总纲、关联变更与验收计划,部署后记录真实业务结果,生产晋级核对该测试版本的验收报告。普通开发和检查可用于逐步补齐资料。具体步骤见[全流程记录](./appspec.md)。
42
+ AppSpec 随开发持续维护:测试发布前补齐总纲、关联变更与验收计划,部署后记录真实业务结果,生产晋级核对该测试版本的验收报告。新应用业务实现前先完成[产品设计与确认基线](./product-design.md);研究、示例原型和技术检查可用于逐步完善设计。具体步骤见[全流程记录](./appspec.md)。
42
43
 
43
44
  ## 连接开发 {#connected-development}
44
45
 
@@ -61,3 +62,5 @@ pnpm exec openxiangda --mcp-stdio --cwd <应用绝对路径>
61
62
  ```
62
63
 
63
64
  先调用 `workspace_context`,再按任务读取 `docs_read` 和当前契约。配置示例与工具参数见[MCP 参考](./reference/mcp.md)。登录、创建和长期 dev 进程继续由 CLI/终端管理。
65
+
66
+ 指定站点授权可用 `auth status --base-url <平台地址> --json` 或 MCP `authorization_status` 只读核验,无需工作区。状态为 `authorized` 才证明当前 access 被平台接受;`missing`/`platform_mismatch`/`refresh_required` 需处理会话,`unauthorized` 表示平台拒绝,`unavailable` 表示暂时无法核验,不能当成过期。查询不刷新、不打开浏览器、不修改绑定;应用管理权限需另行核验。
@@ -0,0 +1,56 @@
1
+ # 页面交互模式与体验评审
2
+
3
+ 按实际角色和任务选择下面的标准起点,并在 AppSpec 页面设计中记录适用范围、差异和验收。模式是设计建议,不是额外运行库;控件、导航、权限和数据继续消费[平台前端](./frontend.md)、[字段组件](./field-components.md)和[数据权限](./data-authz.md)。
4
+
5
+ ## 标准管理页面 {#admin}
6
+
7
+ 适用于管理员维护独立业务对象。显式选择 CRUD 视图,沿用 Field Kit、Ant Design 与组件默认外观。页面优先呈现标题、主要新建入口、常用筛选、列表与行操作;复杂筛选按需展开。列按办理任务选择,记录默认排序、分页上限、空值/长文显示与操作条件。辅助模型无需独立导航。
8
+
9
+ 列表进入详情再返回时明确关键词、筛选、页码、选择范围与位置是否保留;批量操作说明当前页/已选记录范围,确认内容包含实际对象及影响。新建和编辑复用字段规则,失败定位到字段并保留其他输入。删除只在业务明确需要时提供,由服务端权限和业务约束最终裁定。
10
+
11
+ 标准 CRUD 自带的状态可引用共用设计;页面仍需说明角色、数据范围、可见字段、业务校验及差异。AC 至少按实际维护任务验证列表到详情返回、成功写入、禁止写入和适用校验。
12
+
13
+ ## PC 用户任务页面 {#pc-task}
14
+
15
+ 适用于申请、办理和跨模型任务。先给当前任务与下一步,按使用频率和决策顺序安排信息,不把所有底表铺成菜单。列表、详情和办理页按任务分开;同页编辑/提交/成功等状态在同一 PageSpec 中记录。
16
+
17
+ 为每个入口写清直接链接、前置条件、返回位置与成功出口。可编辑区域和只读依据区分,主操作有具体业务动词;确认步骤仅用于需要复核的信息和后果。页面动作对应一个明确的业务契约,提交结果未知时查询原结果,不以新随机幂等键重提。
18
+
19
+ ## 移动用户页面 {#mobile-task}
20
+
21
+ 使用有作用域的 `openxiangda/mobile` 与平台字段组件。根据现场任务独立组织首页、列表、详情和填写顺序;不把宽表格缩小后当作移动设计。确定常用入口、任务卡片上的必要信息、主动作、导航返回与输入退出规则。
22
+
23
+ 逐页检查触摸目标、键盘遮挡、焦点、滚动、安全区和长标题;筛选抽屉的应用/取消含义明确。网络慢时保留输入并阻止误操作,失败后给恢复入口。图片先缩略图、原图按需,附件展示大小限制、进度和失败原因。设计写明目标尺寸和渠道,真实验收在目标端走完主要任务。
24
+
25
+ ## 匿名表单与本人记录 {#public-form}
26
+
27
+ 外部无平台账号的人使用[匿名公开访问](./public-access.md),不建 guest 角色或开放普通 Data API。设计说明公开入口、收集目的、必填/可选信息、附件规则、提交后结果和本人记录的能力范围。
28
+
29
+ 明确同浏览器续填/本人访问的边界与凭证丢失后的实际行为,不承诺跨设备找回能力。所有权由平台填写;前端不接受用户指定其他人的身份。公开页面状态、校验、结果未知与安全提示按所消费契约设计,不虚构额外隐私同意或注册步骤。
30
+
31
+ ## 审批与办理详情 {#workflow}
32
+
33
+ 复用[标准流程、待办和通知](./workflow-events.md)。详情优先显示当前状态、业务摘要、当前任务及历史;只提供当前用户被授权的操作。区分申请人、办理人和旁观者看到的字段、意见与动作,写清退回可编辑范围、撤回条件、转交等已启用能力。
34
+
35
+ 快速重复点击、任务已被他人处理和响应中断要有具体结果与恢复方式。通知详情跳转回标准目标,不复制流程状态或另做审批授权。AC 用真实角色覆盖主流程、退回/拒绝及越权反例。
36
+
37
+ ## 每页交互规格检查 {#page-review}
38
+
39
+ 把下表应用到每个实际页面。共用行为引用一个权威设计,页面写差异;不适用时说明业务理由,不为凑表增加功能。
40
+
41
+ | 维度 | 编码前的具体决定 |
42
+ | --- | --- |
43
+ | 任务与入口 | 稳定页面 ID,REQ/旅程、角色和目标;入口、直链、返回及成功出口 |
44
+ | 信息与字段 | 区域优先级、默认排序/筛选;标签、帮助、默认值、必填、联动、可编辑条件、校验时机和提示位置 |
45
+ | 操作与反馈 | 主次操作、触发条件、文案、隐藏/禁用依据、复核内容、成功反馈和后续动作 |
46
+ | 页面状态 | 初次加载/刷新、正常、首次空数据、筛选无结果、无权限、请求错误和重试 |
47
+ | 写入与恢复 | 未保存、提交中、成功、明确失败、结果未知、他人修改冲突;输入保留与草稿边界 |
48
+ | 数据边界 | 空值、长文本、最大条目、分页、批量选择范围;附件类型/大小/失败及重试 |
49
+ | 权限与多端 | 页面/动作/行/字段、多角色并集;PC 批量与移动任务差异、键盘焦点、触摸和返回 |
50
+ | 原型与验收 | 所选标准模式或原型位置、适用状态;对应 AC、角色、输入条件、操作和可观察结果 |
51
+
52
+ ## 评审与验证尺度 {#evaluation}
53
+
54
+ 先用用户能理解的方式走一遍“从哪里进来、看到什么、怎样完成、出错怎么恢复”,再核对规则、数据与权限的一致性。原型允许样例数据,必须标注;只有效果图不能证明任务可完成。选定标准模式也需完成本应用的逐页差异设计。
55
+
56
+ 实现后用实际界面验证任务成功率和明显阻碍,至少覆盖已纳入范围的角色、入口、重要状态和目标端。记录结果未知、重复操作和并发冲突的服务端读回,不只看 toast;性能记录数据量和请求链路。构建通过、HTTP 200、截图数量或检查表填满均不代替真实业务验收。
@@ -1,30 +1,42 @@
1
1
  {
2
2
  "schemaVersion": "openxiangda.documentation/v1",
3
- "version": "2.0.0-alpha.110",
3
+ "version": "2.0.0-alpha.113",
4
4
  "topics": [
5
5
  {
6
6
  "id": "getting-started",
7
7
  "title": "安装与开始开发",
8
8
  "file": "getting-started.md",
9
- "sha256": "a4087a37eeb1c58a4c239150872fac4882d94747543c52da9ccb0f789787a72d"
9
+ "sha256": "95743ccb011932f26c7e3124ecbbcbfac60bdadd03eae16a2913e09be454f29d"
10
+ },
11
+ {
12
+ "id": "product-design",
13
+ "title": "对话发现与详细产品设计",
14
+ "file": "product-design.md",
15
+ "sha256": "acd5aab8f39c4875a7b26335299b9eede4986058a8cf742b51c2a4ffc0d47ebd"
16
+ },
17
+ {
18
+ "id": "interaction-patterns",
19
+ "title": "页面交互模式与体验评审",
20
+ "file": "interaction-patterns.md",
21
+ "sha256": "14e3be52f1fce85dc913b3c58fa12d416dac7418d9817de2689f26ad38a7a134"
10
22
  },
11
23
  {
12
24
  "id": "development",
13
25
  "title": "需求与开发流程",
14
26
  "file": "development.md",
15
- "sha256": "344626d3fecfa68063bd40a3d5fcd13c7608862e9540f66ec13e6ed7cd03c870"
27
+ "sha256": "88fd8d58d7148c3bc5cab77a96fe5b41e61d42241f7d5d22b9a5d39397989b49"
16
28
  },
17
29
  {
18
30
  "id": "application-foundation",
19
31
  "title": "业务模型与标准 CRUD",
20
32
  "file": "application-foundation.md",
21
- "sha256": "389f3bff7e1f1fbff455e9c74279f17e18b23de32928f497255126872f0bb25d"
33
+ "sha256": "747fed29da3ae0c44337dd8413fb4234d0bb961aef2c9a9f9330b7f6f1efe788"
22
34
  },
23
35
  {
24
36
  "id": "appspec",
25
37
  "title": "需求、设计与交付记录",
26
38
  "file": "appspec.md",
27
- "sha256": "49c94f77d6e59b4c1d84002ea1f6beac48b721d35e4408a55acf1d75447ecaa6"
39
+ "sha256": "69f3238e8e28538a51128fb3f0e2c4df79820020f74eca93b643ed227e8998c7"
28
40
  },
29
41
  {
30
42
  "id": "concepts",
@@ -42,13 +54,13 @@
42
54
  "id": "field-components",
43
55
  "title": "字段、表单与移动控件",
44
56
  "file": "field-components.md",
45
- "sha256": "7973fb0d7960dc913b7c93917516b694494aa2e0f9eab01f52af19605d207eda"
57
+ "sha256": "b26da9fb33518203c59a154dd0117f714f3edab5a4d84936b71107c936516893"
46
58
  },
47
59
  {
48
60
  "id": "data-authz",
49
61
  "title": "数据查询与权限",
50
62
  "file": "data-authz.md",
51
- "sha256": "b679e1becf96ccda0adc834ea9524c30acbbf57b0a0fe0463c5789a8fd2873a2"
63
+ "sha256": "92d0f11e580f7c2ed8e2a8911119b3ece4401b7ee974f4e41ee645598ec721d5"
52
64
  },
53
65
  {
54
66
  "id": "public-access",
@@ -66,7 +78,7 @@
66
78
  "id": "backend",
67
79
  "title": "按需后端与业务动作",
68
80
  "file": "backend.md",
69
- "sha256": "e768d53091a56c770b84fa61686411695fda6947670fc55423ca3750db587055"
81
+ "sha256": "6965b67ecf2bca55f110a963d2a73f036c0215d55b0e68aaeec483ff5be20902"
70
82
  },
71
83
  {
72
84
  "id": "administration",
@@ -78,7 +90,7 @@
78
90
  "id": "testing",
79
91
  "title": "检查与真实业务验收",
80
92
  "file": "testing.md",
81
- "sha256": "3928c5a901abbaf33001c16dbcc6e43535ceabe9d80d7f0a92af0b3def545048"
93
+ "sha256": "c948b31d5a9cb4903bf696ce3e14ad556ab6b1c9e03a28fd1275be2a7f58e9f3"
82
94
  },
83
95
  {
84
96
  "id": "delivery",
@@ -90,19 +102,19 @@
90
102
  "id": "upgrading",
91
103
  "title": "版本升级与资料刷新",
92
104
  "file": "upgrading.md",
93
- "sha256": "3edee1d68564afaacbbc9a3e39e6cc75da8285546baf7101960b0689bca8335b"
105
+ "sha256": "835e34a0c43ccefbc75806a67c742d050baf0fcc420ef501c2dbabf608e3f34a"
94
106
  },
95
107
  {
96
108
  "id": "cli",
97
109
  "title": "CLI 命令参考",
98
110
  "file": "reference/cli.md",
99
- "sha256": "1dbd67ce14524bbc8d889443a31b20fa1d124500c893d9d9c78f851d4cce3431"
111
+ "sha256": "05005a0fb268af776510128132b984bc88ca20c5232190aa1ee26070bce796d4"
100
112
  },
101
113
  {
102
114
  "id": "mcp",
103
115
  "title": "MCP 配置与工具参考",
104
116
  "file": "reference/mcp.md",
105
- "sha256": "4ff9201ed39ced5fef09c55672bc110a6042f4cedb4b97d2fa8c6371f69de020"
117
+ "sha256": "2bbe7a00a054af3914c6eee3f0e46b4ec25b03fd38e875c29d545b05412bd772"
106
118
  }
107
119
  ]
108
120
  }