openxiangda 2.0.0-alpha.98 → 2.0.0

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

@@ -1,295 +1,269 @@
-# OpenXiangda 2.0 Frontend
-
-Read [Data and authorization](data-authz.md) for every resource or permission
-change and keep the generated [workspace contract](workspace.md) authoritative.
-
-Use the official Vite + React Router + Refine Core + Ant Design template. Import the platform-owned runtime from `openxiangda/react`, field controls from `openxiangda/field-kit` and clients/types from `openxiangda/core`. Do not copy these implementations into application source and do not add per-resource function wrappers.
-
-Generated desktop lists already own row selection, atomic batch update/delete,
-CSV/XLS/XLSX preview import, export, filters, column settings and density. Keep
-imports at 100 rows per transaction, use exact declared labels or field codes,
-and leave attachment values to the platform managed-file component.
-
-Declare searchable and filterable fields on the resource and let the standard
-CRUD renderer compose one toolbar. Keyword search spans the declared searchable
-fields; all declared filters open on demand in the platform modal. Business
-columns are the default; audit columns and density are optional list settings.
-Desktop create/edit opens a drawer over the retained list; existing full-page
-routes use the same form lifecycle. The renderer retains values after failed
-saves, prevents repeated submission and asks before discarding an edited form.
-Declare shared form/detail groups in `crud[].sections` with `title` and `fields`.
-Form/detail field selections remain exhaustive and ordered. Use lightweight
-section headings, two ordinary columns on PC and one on mobile; small forms
-need no artificial group. Do not copy a list/form renderer or add application
-search toolbars, field ordering maps or authorization/debug explanations.
-
-Read the current user, complete application-role union and capabilities from the platform runtime authorization endpoint. There is no application-selected active role or identity switch. The standard Shell owns the optional Perspective selector. Use `hasReadCapability` for navigation, list/detail visibility and readable fields; continue to use `hasCapability` for create/update/delete, workflows and custom actions. The standard client sends the selected Perspective automatically, and the server repeats the projection for rows, fields and RLS. Never implement resource-specific frontend filters for it. Strip unauthorized fields from create and update payloads and never treat a disabled input as server authorization. Verify with `pnpm openxiangda check`.
-
-Use the standard `Shell` unchanged. It owns the authenticated user's display
-name, account identifier, safe avatar upload, localized application-role names,
-Perspective selection, collapsible menu groups and navigation scroll restoration. It
-also owns directory field requests under the current logged-in user's role
-union. Never fetch identity for the header, display role codes, add a second
-identity selector, or copy Shell and
-directory-client implementations into application source.
-
-For a custom application role-management page, use only the typed functions in
-`openxiangda/core`: `loadRoleManagementCatalog`, `listRoleMemberships`,
-`searchRoleManagementUsers`, the membership mutations, and the
-role-management-grant mutations. The catalog's `roleManagement` projection
-drives button visibility, while the platform repeats the check for every
-request. The “Custom role-management pages” section in
-[Data and authorization](data-authz.md) defines the delegation and CAS
-contract. Do not use the developer control-plane client in browser code.
-
-The application owns the editable admin information architecture through the
-typed `defineAdminNavigation`, `adminNavigationGroup`, `adminResourcePage`,
-and `adminOperationPage` helpers in `openxiangda/config`. The compiler emits
-all reachable `adminPages`, but the Shell renders only pages explicitly
-referenced by generated `adminNavigation`, then applies current-user access as
-a final filter. Page existence, route reachability and menu visibility are
-separate: detail/new/edit/dynamic/handoff pages never become menu entries by
-discovery, and permission logic cannot create entries. Read
-`openxiangda://workspace/contracts` or call `contract_describe`, then copy
-`data.adminNavigationAuthoring.suggestion.expression` once into
-`frontend.admin.navigation` with the listed `openxiangda/config` imports. The
-proposal is deterministic and editable; the compiler/runtime never invokes it
-or appends newly added resources later.
-
-Generated desktop resource CRUD routes use the compiler-owned
-`/admin/resources/<resourceCode>...` namespace and always render inside the
-platform's one Shell. Their independent mobile admin surface is projected from
-the same generated route catalog under `/m/admin/resources/<resourceCode>...`.
-Generated pages consume that catalog for every list/create/detail/edit/back
-navigation; do not reconstruct root resource paths in application code. Root
-and ordinary `/m/...` paths remain available to explicit user routes. The
-compiler rejects an explicit route whose canonical path shape conflicts with
-any explicit or platform-generated route, including dynamic routes that differ
-only by parameter name. Do not add aliases, redirects or route-order branches
-for earlier alpha paths.
-
-Declare the application-wide admin boundary at `frontend.admin.access` with
-`allOf` and/or `anyOf` capability arrays. Import generated `adminAccess` and
-pass it to `OpenXiangdaApplication`; the runtime evaluates that same immutable
-expression before `/admin/**`, `/m/admin/**`, the Shell, generated resources or
-admin contribution pages mount. Portal shortcuts may use the exported pure
-`isAdminAccessAllowed` predicate, while Data/App/Workflow APIs remain the
-server-side authority.
-
-Declare custom routes in `openxiangda.config.ts`, import the generated
-`appRoutes`, and bind every route key to exactly one local React page with
-`defineApplicationContributions` from `openxiangda/react`. Pass the result to
-`OpenXiangdaApplication`. The runtime registers `surface: 'admin'` routes inside
-the one platform Shell; do not wrap them in another Shell. It renders
-`surface: 'user'` routes without the admin Shell so mobile/user experiences can
-own their page layout without creating another router, identity provider or
-permission store. Only static admin routes explicitly referenced by
-`frontend.admin.navigation` enter the menu. Hidden routes retain the same
-`capability` or `access.allOf/anyOf`, including ancestor constraints. Keep admin
-operation pages under `/admin/operations`; parameterized routes remain
-reachable but cannot be menu references. `defineAdminContributions` remains an
-admin-only helper and intentionally rejects `user` routes.
-
-When a Workflow Surface must link back to an application-owned business record,
-declare `detailRouteCode: { desktop, mobile }` on that resource. Both codes must
-reference explicit `surface: 'user'` routes that require the resource's read
-capability. The desktop path must stay outside `/m`, the mobile path must start
-with `/m/`, and each path must contain exactly one bounded dynamic record
-parameter; its name may follow the application domain, such as
-`:applicationId`. The compiler emits the pair in the resource Contract and in
-`resourceDefinitions`; the platform substitutes the record id from the
-authorized Workflow Surface. Never derive `/<resourceCode>/<recordId>`, add an
-alias, or build the destination in the browser. Omitting the declaration means
-there is no application business-record target; a broken published mapping
-fails closed.
-
-Wrap bespoke admin content in `OpenXiangdaAdminPage` and use Ant Design default
-components. The platform UI provider supplies Chinese locale and contextual
-feedback only. Do not generate appearance preferences, color settings or palette
-registries. Keep component CSS scoped and verify real PC/mobile interactions,
-including selectors, dialogs, form submission and failure recovery.
-
-Declare application-owned login visuals with optional
-`frontend.authentication`. The only supported account contract is
-`existing-platform-users-only` with `registration.mode: 'reject'`; use exact
-desktop `/login` and mobile `/m/login`, each pointing to a static protected user
-default route. Import generated `authenticationSurfaces` and bind an exact
-desktop/mobile renderer map alongside `appRoutes`:
+# 前端架构
 
-```tsx
-const contributions = defineApplicationContributions(
-  { routes: appRoutes, authenticationSurfaces },
-  {
-    pages,
-    authentication: {
-      applicationLogin: DesktopLogin,
-      applicationLoginMobile: MobileLogin,
+状态：Vite/Refine 已成为 OpenXiangda 2.0 唯一默认前端栈。决策与实测见
+[核心架构](concepts.md)。
+
+## 默认技术栈
+
+- Vite 7：开发服务器与生产构建，只监听 `127.0.0.1`；
+- React 19 + React Router：普通应用路由；
+- Refine Core：资源查询、分页、排序和 mutation 状态；
+- Ant Design 6：B 端页面组件。
+
+不维护 Umi/Pro 双栈，也不在新模板中依赖已退休的前端框架包或旧身份 Provider。
+
+## 数据和权限
+
+`modules/` 中的业务模型由编译器派生 DataResource 契约，`openxiangda.config.ts` 声明页面
+capability、应用角色和数据策略。前端只根据当前登录用户完整应用角色并集的
+`capabilityCodes` 隐藏页面、按钮和只读字段；这些只是展示保护，平台 Data API
+每次请求仍按同一角色并集做权威的行、字段和操作授权。
+
+自定义角色管理页只调用 `openxiangda/core` 的角色管理 SDK。目录搜索使用
+`searchRoleManagementUsers`，页面按钮按 `loadRoleManagementCatalog()` 返回的
+`roleManagement` 投影显示，但前端显示不能替代服务端复核。不要在应用中复制角色表、
+权限表或通过 NestJS 转发开发者凭据。
+
+列表查询必须使用服务端过滤、排序和分页；新增、读取、更新、删除和文件上传都经过
+可替换 Data API adapter。不要调用自定义 Nest CRUD、Function 或 Workflow 来绕过
+Data API。只有真正需要事务或外部系统的动作才使用同源 `/api`。
+
+默认仪器模块有 30 个字段，其中 `id/revision` 是 Data API 系统字段，28 个业务
+字段由资源声明。新增、编辑和详情共用同一份字段元数据。五个边界字段使用五个独立
+capability，不使用角色名或影子字段判断。
+
+字段策略用 `create` / `update` 分别声明能力；显式空数组表示拒绝。学校管理员通过
+`unrestrictedRoleCodes` 跳过行谓词，但仍受资源和字段能力
+约束；学院管理员创建时可填写五个边界字段，更新时禁止修改 `collegeId`；仪器管理员
+更新时禁止修改这五个字段。表单提交必须从 payload 删除无权字段。
+
+DataQuery 使用有界 where 条件树，支持 and/or/not。标准列表的筛选、关键词、分页和导出共用已声明字段与同一查询条件，不在页面重写查询协议。
+
+## 标准后台扩展
+
+默认 CRUD、统一 Shell、current-user 权限和 Data Provider 都由 `openxiangda/react`
+维护；应用拥有后台信息架构声明。页面实现、路由可达、菜单可见是三个不同合同：
+
+- `resource.generated` 与 `frontend.routes` 决定有哪些标准页或 operation route；
+- 编译器把全部可达页生成到 `adminPages`，detail/new/edit/handoff 可以存在但默认不进菜单；
+- `frontend.admin.navigation` 是菜单的唯一权威声明，Shell 只渲染其中引用的页面，最后再按
+  current-user 权限过滤。权限不能发现或创建菜单项。
+
+生成式资源后台固定使用 `/admin/resources/<resourceCode>` 命名空间，detail、create、
+update 分别追加 `/:id`、`/new`、`/:id/edit`；独立移动后台面使用同一编译目录投影出的
+`/m/admin/resources/<resourceCode>...`。所有桌面生成页由平台放进唯一 `Shell`，页面内部
+跳转也只消费生成路径。普通 `/activities`、`/m/activities` 等产品路径留给 `user`
+route。显式 route 与任何平台生成 route 的路径形状冲突时编译失败；即使动态参数名不同，
+例如 `/:id` 与 `/:recordId`，也视为同一路径。不要添加旧根路径别名、重定向或通过注册顺序
+解决冲突。
+
+使用 typed helper 声明业务分组、用户名称、顺序、图标与页面引用，不维护 raw JSON：
+
+```ts
+import {
+  adminNavigationGroup,
+  adminOperationPage,
+  adminResourcePage,
+  defineAdminNavigation,
+  defineOpenXiangdaApp,
+} from 'openxiangda/config';
+
+export default defineOpenXiangdaApp({
+  // ...
+  frontend: {
+    root: 'apps/web',
+    routes: [{
+      code: 'instrument-import',
+      path: '/admin/operations/instrument-import',
+      label: '仪器导入',
+      surface: 'admin',
+    }],
+    user: { applicationTodoCenter: true },
+    admin: {
+      access: { anyOf: ['app:example:admin:view'] },
+      navigation: defineAdminNavigation([
+        adminNavigationGroup('instrument-center', '仪器管理', [
+          adminResourcePage('instruments'),
+          adminOperationPage('instrument-import'),
+        ], { icon: 'database', order: 100 }),
+      ]),
     },
   },
-);
+});
 ```
 
-Renderers receive only `ApplicationLoginSurfaceProps`: safe method descriptors,
-state/error metadata, normalized `returnTo`, and platform callbacks. They never
-receive credentials, provider configuration, OAuth state, tokens, roles, or
-authorization facts. The platform owns the one Router and authentication
-boundary, tokenless v2 facade, Secure HttpOnly session/refresh family and
-logout. Do not put login in `appRoutes`, call v1 auth APIs, persist tokens, or
-translate network/5xx and authenticated 403 states into login. Generated
-`platformAuthManifest` is the independent login QA denominator and does not
-change protected user route counts.
-
-For a deliberately anonymous user page, first read
-[Anonymous public access](public-access.md), declare one static `surface: 'user'`
-route and bind it through `frontend.publicAccess`. The policy must name one
-resource, its writable/returnable fields and only the bounded operations needed
-by the page (`draft.read`, `draft.update`, `validate`, `create`, `own.list`,
-`own.read`). A public route must not also declare `capability` or `access`.
-Pass generated `anonymousPublicAccess` to
-`<OpenXiangdaApplication publicAccess={anonymousPublicAccess}>`, then use
-`createAnonymousPublicClient({ routeCode })` from `openxiangda/react` inside
-the page. This client owns bootstrap, current-draft CAS, named validation,
-managed upload, idempotent submission and owner-scoped list/detail calls. Do
-not call the general Native Data API, store an identity in local storage, or
-derive ownership from IP, user-agent or a browser fingerprint. The HttpOnly
-browser credential identifies only this browser profile; clearing it or using
-another browser loses access by design.
-
-This is also the whole-application composition contract: pass the resulting
-`contributions` to `OpenXiangdaApplication` and let that component remain the
-only owner of `BrowserRouter`, `RuntimeBoundary`, Refine, generated resource and
-Workflow routes, and the admin Shell. A user page may render an independent PC
-or mobile layout, but it must not add a nested router/Shell or copy generated
-routes. Route parameters continue to come from React Router, and generated
-capability plus ancestor access guards run before the component renders.
-
-To expose the standard application-level todo center, declare
-`frontend.user.applicationTodoCenter: true`. The compiler generates `/todos`;
-the same runtime exposes the independent mobile `/m/todos` page. The page reads only the authenticated user's
-Notification Hub recipient projection and deep-links to the platform-resolved
-target. Do not query Notification Hub management endpoints or recreate a local
-message state store.
-
-When an application needs branded user-end composition, keep those generated
-routes and contribute renderers from the application entry through the public
-`openxiangda/react` contract:
+AI 先读取 `openxiangda://workspace/contracts` 的有界索引，再调用
+`contract_describe` 并传入 `{ "selector": "navigation" }`，从 `data.selection.adminNavigationAuthoring.suggestion` 取得确定性的首次建议：
+`proposal` 是有界机器可读声明，`imports` 是 `openxiangda/config` 的 typed helper，
+`expression` 可一次性写入
+`frontend.admin.navigation`，然后由应用正常编辑。该结果明确标记
+`applyMode: "copy-once"` 和 `automaticRuntimeDiscovery: false`；compiler 和 runtime
+从不调用建议器，也不会在以后新增内部资源时偷偷扩展生产菜单。直接使用 compiler API 的
+tooling 也可调用 `renderAdminNavigationSuggestion(config)` 获得同一 proposal。
+
+用 `defineApplicationContributions` 将每个生成的 `appRoutes` route 精确绑定到一个本地
+React page。`admin` page 由 runtime 放入唯一的 `Shell`，component 不再次嵌套；`user`
+page 不套 admin Shell，可独立实现移动/用户端布局，但仍共享当前用户、权限和 Router：
 
 ```tsx
 import {
   defineApplicationContributions,
-  type StandardApplicationTodoCenterProps,
-  type StandardUserPageFrameProps,
-  type StandardUserSurfaceContributions,
+  OpenXiangdaApplication,
 } from 'openxiangda/react';
-
-const standardUserSurfaces = {
-  frame: {
-    desktop: DesktopUserFrame,
-    mobile: MobileUserFrame,
+import {
+  adminNavigation,
+  adminAccess,
+  adminPages,
+  appRoutes,
+  routeManifest,
+} from '@app/contracts/generated';
+import { InstrumentCalibrationPage } from './operations/InstrumentCalibrationPage';
+
+const contributions = defineApplicationContributions(appRoutes, {
+  pages: {
+    instrumentCalibration: InstrumentCalibrationPage,
   },
-  applicationTodoCenter: {
-    desktop: DesktopTodoCenter,
-    mobile: MobileTodoCenter,
+});
+
+<OpenXiangdaApplication
+  adminNavigation={adminNavigation}
+  adminAccess={adminAccess}
+  adminPages={adminPages}
+  routeManifest={routeManifest}
+  contributions={contributions}
+/>;
+```
+
+`pages` 的键必须与生成的 `appRoutes` 完全一致。隐藏 route 仍执行同一 `capability` 或
+`access.allOf/anyOf`，子 route 同时继承全部祖先约束。页面代码随应用不可变前端制品构建，
+不能从平台下载 component/module URL。admin operation page 固定使用
+`/admin/operations` 或其子路径；带参数 route 只可直接访问，不能被导航引用。
+`defineAdminContributions` 是保留的 admin-only helper，会主动拒绝 `user` routes。
+
+应用登录使用可选 `frontend.authentication` 声明：仅允许现有平台用户、拒绝注册，桌面
+固定 `/login`、移动固定 `/m/login`，并分别引用同设备的静态 user 默认 route。登录面由
+编译器生成到独立 `authenticationSurfaces`，不进入受保护 `appRoutes`。应用通过
+`defineApplicationContributions({ routes: appRoutes, authenticationSurfaces },
+{ pages, authentication })` 绑定独立 PC/移动 renderer；renderer 只拥有品牌视觉和本地
+展示状态，并调用 `ApplicationLoginSurfaceProps` 的平台回调。密码、租户 provider、一次性
+OAuth state/callback、Secure HttpOnly 会话与 refresh family、当前身份和 AuthZ 始终由平台
+唯一持有。禁止调用 v1 auth API、在浏览器保存 Token、把登录页塞入受保护路由或创建第二
+Router/identity provider。生成的 `platformAuthManifest` 是独立登录 QA 清单，不改变用户路由
+覆盖数。
+
+## 匿名公开用户页
+
+没有平台账号的外部用户不进入应用登录或角色并集。此类页面使用专门的
+[`frontend.publicAccess` 匿名公开访问合同](public-access.md)，由平台生成 HttpOnly 浏览器凭证，
+并通过 `createAnonymousPublicClient` 提供草稿、附件、具名重复校验、幂等提交和同一浏览器的
+本人列表/详情。不要创建 guest 账号、公开一般 Data API、保存本地身份或使用 IP/指纹判断所有权。
+
+这也是完整应用的一等组合边界：`OpenXiangdaApplication` 始终唯一持有
+`BrowserRouter`、`RuntimeBoundary`、Refine、generated resource/workflow routes
+和后台 `Shell`。应用不要把它包在第二个 Router/Shell 中。桌面/移动用户端可以绑定不同
+组件并拥有各自布局，但仍共享同一个 runtime identity 和 capability ancestor guard。
+
+通用应用级待办中心通过用户 Surface 声明开启：
+
+```ts
+frontend: {
+  user: { applicationTodoCenter: true },
+  // ...
+}
+```
+
+编译器生成 `/todos` 和 `/m/todos`。页面只读取当前登录用户的
+Notification Hub 收件人投影；不调用 management API，不复制消息状态库。桌面端使用
+无常驻详情的全宽列表，移动端使用独立卡片列表；`查看详情` 统一进入平台解析后的
+Workflow/custom application route。
+
+编译器同时生成必填的 `routeManifest`。它是 Workflow/Todo 标准页的唯一桌面/移动成对路由来源，
+每个 entry 都携带稳定 `routeCode`、参数名、访问能力和 `requiresAuthentication: true`，顶层
+`digest` 绑定完整 catalog。模板把该产物直接传给 `OpenXiangdaApplication`；runtime 在注册
+Router 和页面前校验成对 user surface、参数与访问元数据。应用不得重新声明 `/todos`、
+`/m/todos` 或标准 Workflow 路径，也不得添加别名、重定向或第二份
+路由状态。digest 的计算与合同校验由 compiler/platform preflight 负责，浏览器只接受有效格式并
+fail-closed 校验 entry/pair 元数据。
+
+标准 Workflow 详情页直接渲染 Surface 的 `presentation.businessDetail`、`summary`、
+typed timeline 和 operation descriptors。业务字段继续使用平台 `SurfaceFieldValue` 语义；
+父子表、附件、富文本图片和签名不由应用另写 renderer 或拼接 Data API 文件 URL。
+PC canonical 路径为 `/tasks/:taskId` 和 `/workflows/:instanceId`，使用独立全屏页面而不进入
+后台 Shell；旧 admin 详情路径不存在。桌面和移动使用独立
+renderer，但共享同一授权与命令生命周期。主决策操作固定在底部，
+低频操作统一进入“更多操作”；意见输入延迟到动作确认层，页面不常驻空白意见表单。
+页面只显示非系统业务字段与节点内操作，不展示 UUID、revision、事件序列或技术信息区；
+`stale` 不产生常驻提示，真实命令冲突才显示刷新提示。
+应用只有在业务交互确实不能由标准页表达时才声明成对的 custom detail route。
+
+标准流程提交使用浏览器客户端的 `loadBusinessProcessReceipt(commandId)` 和
+`pollBusinessProcessCommand(commandId, afterRevision)`（Nest 使用对应的
+`OpenXiangdaBusinessProcessService.receipt/poll`）。首个回执可能是 `accepted`；按
+`nextPoll` 继续读取直到 `terminal`，再消费 typed command/surface。不要把 accepted 当作提交失败，
+也不要对平台端点发起未类型化的 `fetch`。
+
+资源用 `mutationOwner: 'native' | 'action' | 'readonly' | 'workflow'` 声明 mutation owner，
+并可用 `generated.list/detail/create/update/delete` 精确选择标准 surface。非 Native owner
+不能生成或向应用角色授予 Native mutation；零可写业务字段不能开放 create/update。
+Workflow definition 用 `launch.mode` 声明 `standalone`、`custom-page`、`hidden-handoff` 或
+`work-center-only`；只有 `standalone` 可进入菜单，`hidden-handoff` 保留同一标准 PC/移动路由
+但不进菜单。缺省 submission 使用 compiler 生成的标准 process operation。action-owned 资源
+则在 `standalone`/`hidden-handoff` 上声明 `submission.kind: 'named-operation'`，把 create/existing
+表单字段、平台幂等键、当前用户、subject id/revision 和响应结果显式绑定到原 named operation。
+标准页仍使用 generated field components，但最终由应用服务端完成业务校验、原子写入并决定
+是否返回 durable process command；缺少或返回 null command 表示本次无需审批。浏览器不提供
+save callback，也不直接调用 prepare/start。`custom-page` 仍只能由 verified Named Action 注入
+`OpenXiangdaBusinessProcessService` 发起。
+
+标准资源页提供 `toolbar`、`row`、`detail` 三类 action slot。slot 声明稳定 code、label、
+可选 order 和 capability/access，render 只获得当前 resource、已授权 record/selection 与
+受控 `refresh()`：
+
+```tsx
+const contributions = defineApplicationContributions(appRoutes, {
+  pages: { instrumentCalibration: InstrumentCalibrationPage },
+  resources: {
+    instruments: {
+      row: [{
+        code: 'calibrate',
+        label: '校准',
+        capability: 'instrument.calibration.run',
+        render: ({ record, refresh }) => (
+          <CalibrationButton recordId={String(record.id)} onDone={refresh} />
+        ),
+      }],
+    },
   },
-} satisfies StandardUserSurfaceContributions;
+});
+```
 
-export const applicationContributions = defineApplicationContributions(
-  { routes: appRoutes, authenticationSurfaces },
-  { pages, authentication, standardUserSurfaces },
-);
+slot 只扩展动作区域，不接管查询、字段策略、revision、保存或审计。跨资源事务、外部副作用
+和业务不变量仍调用有 `@OpenXiangdaOperation` 门禁的 Nest App Operation；普通 CRUD 继续
+直接使用 Native Data API。UI 隐藏不是服务端授权。
+
+学院是应用自有 `colleges` Native Resource，仪器 `collegeId` 保存该资源的系统 UUID。
+人员和部门选择器调用平台 Directory 的分页 search，并用 exact resolve 恢复已选 ID；学院
+选择器调用 membership-bound scope-values search/resolve。空结果和错误直接展示，不回退
+静态人员、部门或学院。组织部门与学院属于不同 owner，不能互相推断。
+
+发布态 app/environment 只读取平台为每个 index 注入的
+`openxiangda-runtime-base`、`openxiangda-app-code` 和
+`openxiangda-environment` meta；不得使用 Vite 构建变量或手填环境覆盖它。
+当前用户使用同源 `openxiangda.runtime-authorization/v2` 合同，每个 Data API query/body
+都显式携带 environmentKey。标准客户端读取当前用户角色并集，不保存 Token，也不持久化
+授权结果。该角色并集合同未部署的平台版本
+必须在应用写入前 fail closed。
+
+## 本地与浏览器门禁
+
+```bash
+openxiangda dev
+pnpm --filter @app/web check
+pnpm --filter @app/web test
+pnpm --filter @app/web test:e2e
+pnpm --filter @app/web build
 ```
 
-Both desktop/mobile members and both groups are mandatory once
-`standardUserSurfaces` is present; partial families fail at compile time and
-again at runtime. Omit the property to retain the platform defaults.
-
-`StandardUserPageFrameProps` contains `pageKind`, `device`, `mobile`, rendered
-`children`, safe `route` metadata, `canGoBack` and the platform-owned `back()`
-callback. The frame wraps Todo and standard Workflow work-center, launch, task
-and instance pages. It must not create a Router, resolve identity, redirect a
-standard path or reinterpret route metadata as authorization.
-
-`StandardApplicationTodoCenterProps` contains only the authenticated current
-user's `items`, aggregate `counts`, `total`, `loading`, `loadingMore`, `error`,
-immutable `query`, `hasMore`, and the bounded callbacks `setQuery`, `refresh`,
-`loadMore`, `recordInteraction` and `openItem`. `setQuery` owns view, keyword,
-unread and paged-offset changes; `loadMore` appends and de-duplicates the next
-platform page; `openItem` records a click best-effort and uses the
-platform-resolved desktop/mobile target. Render only these props. Never import
-the private platform client, call Notification Hub endpoints, persist a Todo
-copy, accept a user/token parameter, or navigate from an item object not
-supplied by the current render. A renderer exception is contained by the
-platform error boundary without replacing `RuntimeBoundary` or the Router.
-
-The compiler also emits the required generated `routeManifest`. This is the
-single desktop/mobile paired catalog for standard Workflow and Todo pages. Each
-entry carries stable route codes, path parameters, access metadata and a
-`requiresAuthentication: true` marker; the top-level digest binds the complete
-catalog. Pass it directly to `OpenXiangdaApplication`. The runtime validates
-user Surface pairs, parameter names and shared access metadata before registering
-the Router. Applications must not recreate standard `/todos`, `/m/todos`, or
-Workflow paths, add aliases/redirects, or maintain a second route state. The
-compiler/platform preflight is the digest authority; the browser validates the
-digest shape and fails closed on malformed or inconsistent entries.
-
-For standard process submission, consume the typed browser helpers
-`loadBusinessProcessReceipt(commandId)` and
-`pollBusinessProcessCommand(commandId, afterRevision)` (or the matching Nest
-`receipt`/`poll` methods). A first response may be `accepted`; follow
-`nextPoll` until `terminal` instead of treating it as failure or issuing a
-generic request to the platform endpoint.
-
-For a small business action on a generated resource page, use the typed
-`resources[resourceCode].toolbar`, `.row` or `.detail` slots accepted by
-`defineApplicationContributions`. Declare a stable action code, label and
-capability/access expression. The render context contains only the current
-resource, already-authorized record or selection, and a bounded `refresh()`;
-it does not own CRUD, revisions, fields or authorization. Invoke a guarded Nest
-App Operation for cross-resource transactions, invariants or side effects and
-leave ordinary CRUD on the Native Data API. Do not copy a generated page just
-to insert a button.
-
-Generated contracts intentionally emit each resource Surface once in
-`resourceSurfaces`; `resourceDefinitions[code].surface` references that shared
-object, while an explicit resource `detailRouteCode` is preserved beside it.
-Import the generated runtime definitions normally. Do not serialize, inline or
-duplicate Surface literals in application code.
-
-The standard Workflow detail renderers consume only the authoritative Surface:
-`presentation.businessDetail`, `presentation.summary`, the typed timeline and
-operation descriptors. Continue to use `SurfaceFieldValue` for complete field
-semantics and the Workflow-scoped file client for attachments, rich-text images
-and signatures. Keep desktop and mobile renderers structurally independent;
-place decision actions in the fixed primary group, all low-frequency actions in
-the single more-actions entry, and collect comments in the action confirmation
-layer. The canonical desktop paths are `/tasks/:taskId` and
-`/workflows/:instanceId`; they render as standalone full-screen pages outside
-the admin Shell, while the platform alone replace-redirects historical admin
-detail URLs. Filter `system: true` and internal fields, omit empty sections,
-merge operation actor/action/reason/time into its vertical node, and never show
-UUIDs or revision/event diagnostics. Treat `stale` as metadata and show the
-friendly refresh prompt only after a real command token/CAS conflict. Do not
-copy the standard page into an application merely to show full business fields
-or rearrange platform-owned operations.
-
-## Foundation module and field selection
-
-New applications plan task pages first and compose data models and selected CRUD
-views through `defineApplicationModule`. Internal tables need no page. List, form
-and detail selections are exhaustive; `hidden` controls presentation independently
-of Data API permissions. Keep root configuration short by importing business modules.
-
-Use platform Field Kit before custom input controls. PC input may use `antd`;
-mobile input uses the scoped `openxiangda/mobile` Ant Design Mobile adapter, inside
-`MobileSurface` with `openxiangda/mobile/styles.css` (already included in React styles).
-Do not import the `antd-mobile` root, which resets global page styles.
-Do not write raw business input/select/textarea or
-contentEditable elements. Keep mobile entrypoints in src/mobile/, Mobile*.tsx or
-*.mobile.tsx so the application check can inspect their static local imports.
-Basic text/number/boolean/option/date controls have a mobile adapter; complex field
-migration remains staged, and each field must pass actual interaction acceptance.
-
-
-标准列表使用高级条件分组、显示列浮层、冻结和拖动列序、多排序。仅从页面声明的可读业务字段提供选择；导出与列表共用条件和排序。依赖所选记录的 toolbar contribution 声明 `requiresSelection: true`。显示列修改即时预览，显式保存个人偏好。
-
-标准表单使用“暂存 / 提交”及平台草稿箱，不自行使用 localStorage、业务表或 Nest 保存草稿。PC 抽屉头部提供全屏、新开页面、关闭；新开页面由平台保存并交接草稿。移动端为分组字段行、简单标题和固定底部操作，草稿/恢复确认用移动底部弹层；不显示“返回列表”。草稿字段必须保持权限裁剪，编辑草稿不得用最新 revision 覆盖原编辑版本。
+测试必须真实断言 Vite LAN 不可达、production 警示 DOM 常驻、Data/Directory/App API
+使用同一当前用户角色并集、Perspective 读取投影协议，并约束源码文件数、LOC、构建
+体积和 gzip 体积。

package/skills/openxiangda-v2/references/getting-started.md

@@ -0,0 +1,66 @@
+# 安装与开始开发
+
+OpenXiangda 2.0 默认生成 React 应用和共享契约。普通 CRUD、标准审批和通知使用远端平台能力；只有真实服务端业务动作才按需增加 NestJS。本地无需启动平台、Docker 或 PostgreSQL。
+
+## 准备 {#prerequisites}
+
+准备平台地址、具有应用开发权限的账号、Node.js 24 和 pnpm 10.15.1。向平台维护者取得已验证的 OpenXiangda 2.0 精确版本，并核对平台能力是否支持。`openxiangda@latest` 可能属于 1.x；不能用它选择 2.0。
+
+## 安装与创建 {#create}
+
+以下命令的版本占位符由随包资料替换为该根包的精确版本。网站源码阅读者应先确认要使用的发行版本。
+
+```bash
+pnpm dlx openxiangda@2.0.0 skill install --force
+pnpm dlx openxiangda@2.0.0 auth status --base-url <平台地址> --json
+pnpm dlx openxiangda@2.0.0 login --base-url https://platform.example.com
+pnpm dlx openxiangda@2.0.0 create my-app --base-url https://platform.example.com
+cd my-app
+pnpm openxiangda context --json
+pnpm openxiangda dev
+```
+
+将两处示例平台地址替换为同一个目标地址。`create` 先核对目标与当前登录平台，再创建本地目录、安装依赖并初始化远端应用；新应用不会自动沿用文件中最后登录的站点。CI 使用原有成对的 `OPENXIANGDA_BASE_URL` 和 `OPENXIANGDA_TOKEN` 时，可以由该显式地址指定目标。
+
+初始化中断后重试同一命令；已有目录会核对原平台绑定，不能通过 `create` 改绑到其他站点。地址不一致时先检查目标并登录正确的平台，不修改 link 文件绕过检查，也不要使用内部 provision 接口另建应用。创建操作应在用户要求创建应用的范围内执行。
+
+进入项目后使用 `pnpm openxiangda`，由项目依赖和锁文件决定版本。查看使用资料运行 `pnpm openxiangda docs`；查看单一主题运行 `pnpm openxiangda docs frontend`。安装到其他 AI 工具时使用 `skill install --destination <Skill根目录>`。
+
+## 项目结构 {#workspace}
+
+```text
+apps/web                 页面与应用入口
+packages/contracts       平台编译器生成的契约
+modules                  业务模型、页面选择和模块声明
+openxiangda.config.ts    应用装配、导航、权限和按需能力
+appspec                  需求、架构、变更和验收记录
+AGENTS.md                平台约定与项目自有说明
+```
+
+以实际模板输出为准。资源与页面通过模块声明组合，不创建 `platform/data`。`apps/server` 仅在启用后端时初始化；后续保留用户业务代码。
+
+AppSpec 随开发持续维护：测试发布前补齐总纲、关联变更与验收计划，部署后记录真实业务结果，生产晋级核对该测试版本的验收报告。新应用业务实现前先完成[产品设计与确认基线](product-design.md)；研究、示例原型和技术检查可用于逐步完善设计。具体步骤见[全流程记录](appspec.md)。
+
+## 连接开发 {#connected-development}
+
+`dev` 监听本机回环地址，页面通过同源代理访问平台测试数据。浏览器不持久化平台凭据。终端和页面显示当前环境；只有生产环境时会持续提示生产数据风险。开发数据写入仍是远端真实写入，按任务范围操作。
+
+纯 CRUD 修改优先使用标准模型、字段和页面；跨模型事务或外部副作用再选择后端。角色、行和字段权限在平台执行。详见[开发流程](development.md)、[模型与标准 CRUD](application-foundation.md)和[按需后端](backend.md)。
+
+## 检查与交付 {#delivery}
+
+只检查时运行 `pnpm openxiangda check`。需要部署测试环境时直接运行 `pnpm openxiangda deploy`，它已包含检查、测试和构建；无需再连续重复运行全部脚本。
+
+生产必须复用成功测试运行。部署状态、真实角色验收和回滚步骤见[应用交付](delivery.md)。纯前端发布不要求 Docker；启用后端后才需要官方镜像构建条件。
+
+## 接入 MCP {#mcp}
+
+MCP 使用相同的项目 CLI：
+
+```bash
+pnpm exec openxiangda --mcp-stdio --cwd <应用绝对路径>
+```
+
+先调用 `workspace_context`，再按任务读取 `docs_read` 和当前契约。配置示例与工具参数见[MCP 参考](mcp.md)。登录、创建和长期 dev 进程继续由 CLI/终端管理。
+
+指定站点授权可用 `auth status --base-url <平台地址> --json` 或 MCP `authorization_status` 只读核验，无需工作区。状态为 `authorized` 才证明当前 access 被平台接受；`missing`/`platform_mismatch`/`refresh_required` 需处理会话，`unauthorized` 表示平台拒绝，`unavailable` 表示暂时无法核验，不能当成过期。查询不刷新、不打开浏览器、不修改绑定；应用管理权限需另行核验。