openxiangda 1.0.264 → 2.0.0-alpha.2

package/openxiangda-skills/references/architecture-design.md

@@ -1,409 +0,0 @@
-# OpenXiangda Architecture Design Reference
-
-Use this reference to turn product material into an OpenXiangda-specific architecture document and task plan.
-
-## Table Of Contents
-
-- [Purpose](#purpose)
-- [Critical Review Stance](#critical-review-stance)
-- [Architecture Gate Workflow](#architecture-gate-workflow)
-- [Anti-Patterns To Reject](#anti-patterns-to-reject)
-- [Question Gates](#question-gates)
-- [Resource Design Checklist](#resource-design-checklist)
-- [Final Document Template](#final-document-template)
-- [Black-Box Demo Scenario](#black-box-demo-scenario)
-
-## Purpose
-
-This design flow is for applications built on OpenXiangda. The output is not a generic PRD. It must tell the implementer exactly which platform resources to create and why:
-
-- forms and fields
-- custom pages and menus
-- data views
-- roles, page permission groups, form permission groups, data scopes, and field access
-- status machines or workflows
-- automations, JS_CODE V2 nodes, and App Functions
-- notifications and connectors
-- application login/auth methods, registration policy, identity matching, and provider boundaries
-- public access routes, external roles, ticket strategy, and explicit grants
-- publish and acceptance steps
-
-The design is complete only when another agent can implement it without deciding major architecture tradeoffs.
-
-## Critical Review Stance
-
-Act as the technical architect. Product requirements are inputs, not orders.
-
-Be direct when a requirement is technically wrong:
-
-- "这个设计不能按你说的实现。把 1000 条数据拉到前端再筛选，会在真实数据量下变慢，也会绕开后端权限边界。这里必须做分页查询和服务端过滤。"
-- "这不是审批流，是业务状态流转。硬做成流程表单会让页面、权限、数据修复和后续扩展都变复杂。应该用普通表单 + 状态机。"
-- "前端隐藏按钮不是权限控制。敏感数据必须落到表单权限组、数据范围和字段权限。"
-
-Do not insult the person. Criticize the proposal and explain the technical consequence.
-
-## Architecture Gate Workflow
-
-Before any implementation for architecture-class work, run the CLI gate when available:
-
-```bash
-openxiangda doctor --profile <name> --json
-openxiangda design gates --topic public-access --json
-openxiangda design template --topic auth,public-access
-```
-
-Until the user confirms the design, only read, inspect, snapshot, dry-run, ask questions, and write/output the architecture document. Do not edit app source, mutate platform resources, publish, deploy, send notifications, or invoke live write/delete endpoints.
-
-1. **Read the input**: user prompt, uploaded requirements, current workspace files, app snapshots, and existing resources.
-2. **Classify the app**: admin CRUD, portal, workbench, dashboard, workflow approval, status lifecycle, automation-heavy app, integration-heavy app, or mixed.
-3. **Draft the resource map**:
-   - forms as data tables
-   - pages/routes/menus
-   - permissions
-   - data views
-   - workflow/status/automation/function boundaries
-   - notifications/connectors
-4. **Ask missing high-impact questions**. Ask in small rounds; do not dump every possible question at once.
-5. **Reject bad assumptions** and replace them with OpenXiangda-native patterns.
-6. **Confirm UI design needs**. For portals, dashboards, mobile pages, and workbenches, ask whether to run Product Design / visual ideation before implementation.
-7. **Write the design artifact**. Default path when a workspace exists:
-   `docs/architecture/<app-slug>-openxiangda-design.md`.
-8. **Create a development task table** that can be executed by OpenXiangda subskills.
-
-## Design Gate Matrix
-
-Use this matrix to decide what to ask. Ask in small rounds, and recommend the default option when the user is unsure.
-
-| Topic | Trigger examples | Must confirm | Recommended default | Resources to design | Acceptance |
-|---|---|---|---|---|---|
-| 新应用 / 大版本 | 新应用、从零搭建、门户、管理系统 | actors, core objects, internal/external access, first screen, integrations | React SPA + `src/resources/**` + design doc first | forms, routes, menus, roles, dataViews, auth/public policies | user confirms resource map and permission matrix |
-| 复杂页面 / 工作台 | 看板、工作台、详情页、移动端、大屏 | page task, data source, edits/batch actions, role visibility, empty/error states | dataView for repeated reads, App Function for backend orchestration | route/menu, page component, dataView/function, permissions | role-specific UI works; no PageProvider errors |
-| 登录 / 注册 | 登录、注册、手机号验证码、SSO、账号绑定 | methods, registration policy, identity match keys, provider function, default roles, rate limits | `registration.mode=reject`; provider returns identity assertion only | `src/resources/auth`, login route/page, App Function provider | methods match SDK DTO; internal route requires auth |
-| 公开访问 | 无需登录、外部人员、公开报名、分享链接 | public routes, external roles, guest vs ticket, grants, rate limit, audit/expiry | `/view/:appType/public/*` + route + public-access policy; sensitive lookup uses ticket | `src/resources/routes`, `src/resources/public-access`, external role permission groups, `PublicAccessGate` | no-login public route works; ungranted resources deny |
-| 权限 / 数据范围 | 角色、只看自己、部门数据、字段权限 | roles, page/menu groups, form operations, data scope, field access, rejection tests | backend permission groups, not frontend-only filtering | roles, page-groups, form-groups, field access policy | `permission audit` clean; allowed/denied paths verified |
-| 流程 / 自动化 / Function | 审批、状态流转、定时、JS_CODE、App Function | trigger, node IO, idempotency, resources, approval vs status machine, logs | normal status machine unless real approval; reusable logic as App Function | workflows, automations, functions, JS_CODE source | invoke/executions/logs verified; duplicate trigger safe |
-| 连接器 / 通知 | 第三方接口、Webhook、短信、钉钉、消息 | auth, timeout/retry, secret owner, notification type/template, recipients, failure policy | connector for external HTTP; notification resources before sending | connectors, notifications, App Function wrapper if needed | `connector invoke` and notification preview/send DTOs pass |
-| 资源维护 | 补路由、修权限、删除配置、同步 manifest | live mutation or repo source of truth, profile/appType, force/delete/send risk | `resource plan/publish` for formal changes; direct CLI with `--write-manifest` for small fixes | affected manifest and state mapping | dry-run path/body reviewed; no repo/platform drift |
-
-## Anti-Patterns To Reject
-
-| Anti-pattern | Why it is wrong | Required replacement |
-|---|---|---|
-| Fetch 1000 rows then filter in React state | Breaks at real data volume, wastes network, and may bypass data permission thinking | Paginated query with `currentPage`, `pageSize`, sort, and structured server filters |
-| Dropdown options load all records | Large forms become slow and stale | `linkedForm` `SelectField` with `remoteSearch`, explicit `searchFieldId`, and page size |
-| Broad `searchKeyWord` for every search | Expensive and imprecise | Explicit searchable fields and `filterGroup` OR conditions |
-| Workflow form for normal ticket lifecycle | Adds approval constraints and operational overhead without approval semantics | Normal form + status field + state machine + action log + automations |
-| Frontend-only data isolation | Hides UI but does not enforce data access | Page permission groups, form permission groups, data scopes, and field access |
-| One large page owns all business logic | Hard to test and change | `domain/`, `shared/services/`, hooks, reusable components |
-| Repeated multi-form joins in page code | Duplicated, slow, inconsistent | Data View for read-only reusable row/aggregate queries |
-| Materialized view for hard realtime data | Users see stale data | `storageMode: "live"` only for bounded realtime joins, or direct source queries/App Function |
-| Live view for unbounded heavy joins | Slow runtime queries | Materialized view with scheduled refresh and indexes |
-| JS_CODE for reusable business service | Logic gets duplicated in graph nodes | App Function for shared backend logic; JS_CODE only for node-local trigger logic |
-| Auth provider issues tokens or writes users directly | Breaks platform account, binding, permission, and audit boundaries | Provider returns identity assertion only; platform creates/binds/rejects and issues token |
-| Phone-code login auto-registers by default | Allows uncontrolled account creation from weak identity proof | Default registration is reject; enable auto-create/whitelist only after explicit confirmation |
-| Raw native form controls | Inconsistent with platform runtime and validation | OpenXiangda platform components first, Ant Design wrappers second |
-| Multiple form permission groups without stable local codes | CLI state and platform `resourceCode` cannot reliably distinguish groups on the same form | Give every group a unique `code`, for example `ticket_reporter_view` and `ticket_repairer_view` |
-| Assuming resource publish means workflow is active | Workflow resources may exist as drafts until explicitly published | Verify `workflow list` shows `isPublished: true`; run `workflow publish <workflowCode>` when needed |
-
-## Question Gates
-
-Ask only what materially changes the design.
-
-### Scope And Actors
-
-- Who are the user roles?
-- Which roles create, process, approve, view, export, or administer data?
-- Is this PC-only, mobile-only, or both?
-- Is the app greenfield or modifying an existing app?
-
-### Forms And Data
-
-- What are the core business objects?
-- Which objects need independent lifecycle, permissions, or reporting?
-- Which fields are visible to users, hidden scope keys, computed fields, or system-derived fields?
-- Which fields will be searched, sorted, grouped, or used for permissions?
-- What data volume is expected now and after growth?
-
-### Pagination And Search
-
-- Which list pages need filters?
-- Which fields support exact filtering versus fuzzy search?
-- Which selectors need remote search?
-- What default page size is acceptable?
-- Which sorts are business-critical?
-
-Default if the user does not know: design conservative pagination with explicit filters, do not fetch all rows.
-
-### Permissions
-
-- Is data sensitive?
-- Is frontend-only filtering acceptable, or must backend data isolation be enforced?
-- Does each role see all records, own records, department records, assigned records, or a custom scope?
-- Are any fields sensitive enough for backend field access policy?
-- Are page permission groups enough for visibility, or do forms also need permission groups?
-
-Default: if the app contains personal data, costs, approval records, or cross-department data, backend-enforced permissions are required.
-
-### Status Machine Or Workflow
-
-- Is there an actual approver task with agree/reject opinion and approval history?
-- Does each node require field permissions?
-- Is audit history tied to approval tasks, or is a business action log enough?
-- Can the process be represented as a normal status transition?
-
-Default: ordinary service, ticket, order, asset, and task lifecycles are status machines, not workflow forms.
-
-### Data Views And Reports
-
-- Is the query single-form CRUD or repeated multi-form read-only logic?
-- Is the output row-level or aggregate?
-- Must users see source changes immediately?
-- What staleness is acceptable: realtime, 10-30 minutes, hourly, daily, manual?
-- Which fields are filters, dimensions, measures, drill-down keys, and permission scope aliases?
-- What rows can be excluded early by definition `where`?
-
-Default: management dashboards usually use materialized views with scheduled refresh. Operational bounded drill-downs can use live views.
-
-### Automation, JS_CODE, App Function
-
-- What should happen after form submit/update/delete or field change?
-- Are there scheduled scans or deadline reminders?
-- Does logic need to be reused by pages and multiple backend flows?
-- Does it need external HTTP or platform API calls?
-- Which logs are needed for diagnosis?
-
-Default: reusable calculations and validations become App Functions; one-off backend trigger orchestration becomes JS_CODE V2 in automation/workflow.
-
-### Notifications And Connectors
-
-- Which channels are required: in-app, email, DingTalk, WeChat, third-party todo?
-- Who receives each notification and why?
-- Which payload fields are needed?
-- Are templates reusable resources?
-- Are external credentials needed? If yes, use connectors/resources, never page source secrets.
-
-### Login And Auth
-
-Ask these before generating any login/auth design:
-
-- Which methods are enabled: password, DingTalk browser OAuth/in-app free login, CAS/SSO, phone code, guest?
-- What is the phone registration policy: reject, auto-create, bind existing only, whitelist, or manual approval?
-- What are the identity match keys and priorities: `phone`, `email`, `externalId`, `unionId`, `jobNumber`, `username`?
-- Which App Function provider validates each external credential, and what identity assertion fields must it return?
-- Which default app roles/page groups/data scopes should new users receive, if registration is enabled?
-- What are the security parameters: code TTL, send frequency, failed attempts, IP/device limits, audit fields, and failure message disclosure?
-- Is CAS/DingTalk configured by the platform tenant, or delegated to an app-level provider function?
-
-Default: registration is rejected; provider functions return identity assertions only; platform auth service owns account creation, binding, permission assignment, cookies, and tokens.
-
-### Public Access
-
-Ask these before designing any page or data that external people can access without normal login:
-
-- Which exact routes are public? Use `/view/:appType/public/*` for new React SPA apps.
-- What can anonymous/external users do: view a page only, submit a form, query a dataView, invoke a function, or call a connector-backed action?
-- Which virtual external role codes should represent these visitors, for example `external_visitor`, `external_applicant`, or `external_ticket_holder`?
-- Is ordinary guest mode enough, or does the link need `mode: "ticket"` with expiry/single-use behavior?
-- Which forms/dataViews/functions/connectors are explicitly granted? Everything not listed in `grants` is denied.
-- Which backend permission groups must also include the external role codes?
-- Is the page safe for search/share, or should the URL contain a generated ticket?
-
-Recommended default if the user is unsure:
-
-- Public marketing/info pages: `mode: "guest"`, no data grants.
-- Public form submission: `mode: "guest"` plus one form grant and a submit permission group for `external_visitor`.
-- Sensitive lookup or status query: `mode: "ticket"` plus one dataView/function grant, short TTL, and a read-only permission group.
-- Never use old `?publicAccess=guest` for new React SPA apps; it is legacy `sy-lowcode-view` compatibility only.
-
-### UI Design
-
-Ask whether to use Product Design or another design skill for:
-
-- dashboard
-- portal
-- mobile entry
-- workbench
-- dense operation console
-- executive report page
-- visually important landing/first screen
-
-For simple CRUD/admin lists, design can proceed with the appropriate OpenXiangda template unless the user asks for visual exploration.
-
-## Resource Design Checklist
-
-### Forms
-
-- Use deterministic `formCode`.
-- Define visible fields, hidden scope keys, and derived values.
-- Use platform field components.
-- Use `SelectField` / `RadioField` for enums.
-- Use `linkedForm` select with remote search for large source forms.
-- Avoid extra system metadata fields unless they represent a separate business concept.
-
-### Pages
-
-- Choose React SPA or classic workspace based on the app mode.
-- Use `DataManagementList` for standard management lists.
-- Split PC/mobile when workflows differ, but reuse `domain/` and `shared/services/`.
-- Keep page components thin.
-
-### Permissions
-
-- App roles use stable local codes.
-- Page permission groups control entry/menu visibility.
-- Form permission groups enforce data access.
-- Form permission group resources use unique stable `code` values. Do not use the same form code for multiple groups.
-- Field permissions hide sensitive fields where backend support exists.
-- Frontend-only button hiding is UX, not security.
-
-### Data Views
-
-- Use row view for joined lists and drill-downs.
-- Use aggregate view for fixed metrics.
-- Choose `materialized` for read-heavy reports with staleness tolerance.
-- Choose `live` only for bounded realtime joins.
-- Index materialized output aliases used for filters, sort, and dimensions.
-- Show `lastRefreshedAt` when users care about freshness.
-
-### Status, Workflow, Automation
-
-- Model normal lifecycles as status fields and state machines.
-- Use workflow for real approval tasks only.
-- Use automation for backend triggers and schedules.
-- Use JS_CODE V2 trusted_node for node-local backend logic.
-- Use App Function for reusable backend services.
-- After publishing workflow resources, verify `workflow list` and record whether `isPublished` is true.
-- In React SPA and classic workspaces, JS_CODE/App Function TypeScript lives under `src/js-code-nodes`, `src/automations`, or `src/functions`; build with `pnpm build-js-code`.
-
-### Auth
-
-- Auth resources use stable local codes under `src/resources/auth/`.
-- Use `/view/:appType/login` or `LoginPage` from `openxiangda/runtime/react` for default React login.
-- Use `createAuthClient({ appType, servicePrefix })` for custom React login pages.
-- DingTalk `flow: "auto"` uses JSAPI only in a confirmed DingTalk container and otherwise starts platform-managed browser OAuth. The platform owns callback state and secrets; app code supplies only an app-local `returnUrl` through `getDingTalkOAuthUrl`.
-- Phone-code providers are App Functions. They validate send/verify events and return identity assertions; they do not issue tokens or mutate platform users.
-- New-user registration must be explicit, with default roles and identity conflict behavior documented.
-
-### Public Access
-
-- Route resources live under `src/resources/routes/` and use `publicAccess: "guest"` or `"ticket"` only for `/view/:appType/public/*` paths.
-- Public policies live under `src/resources/public-access/`.
-- Policy `externalRoleCodes` are virtual role codes carried by the scoped public token; use the same codes in page/form/dataView permission groups.
-- Policy `grants` must list every form/dataView/function/connector the public page can access. Do not rely on broad guest permissions.
-- Use `PublicAccessGate` in React routes or `createPublicAccessClient` for custom bootstrapping. If the page uses Page SDK hooks, the route tree must have `OpenXiangdaProvider` plus `OpenXiangdaPageProvider`; `PublicAccessGate` alone is not enough. Public routes must define visible loading and error fallback states so slow networks, missing tickets, or expired tickets do not become blank pages.
-- In validation scripts, success requires the JSON envelope success code (`200`, `"200"`, or compatible `0`). HTTP 200 with `code: "PUBLIC_GRANT_DENIED"` is a denied request, not a success.
-- Validation must include at least one real browser render check for each public and private route, because API-only E2E can miss provider/runtime crashes such as `usePageSdkStore 必须在 PageProvider 内使用`.
-- Old `?publicAccess=guest` and form `publicAccess` settings are legacy compatibility and should not appear in new-app designs.
-
-## Final Document Template
-
-```markdown
-# <App Name> OpenXiangda Architecture Design
-
-## 1. Design Decision Summary
-
-- App type:
-- Runtime/publish mode:
-- Key platform resources:
-- Main tradeoffs:
-- Rejected unsafe assumptions:
-
-## 2. Actors And Permissions
-
-| Role | Users | Page visibility | Data scope | Field restrictions | Notes |
-|---|---|---|---|---|---|
-
-## 3. Forms And Fields
-
-| Form code | Purpose | Key fields | Hidden/scope fields | Search/sort fields | Permission notes |
-|---|---|---|---|---|---|
-
-## 4. Pages, Menus, And UX
-
-| Page/route | Audience | Pattern/template | Main actions | Data source | Design mockup needed |
-|---|---|---|---|---|---|
-
-## 5. Query, Pagination, And Search
-
-- List pages:
-- Remote selectors:
-- Server-side filters:
-- Default page sizes:
-- Index/search-field plan:
-
-## 6. Data Views And Reports
-
-| Data view | Type | Mode | Freshness | Filters/indexes | Permission scope | Runtime call |
-|---|---|---|---|---|---|---|
-
-## 7. Status, Workflow, Automation, And Functions
-
-- Status machines:
-- Workflow forms:
-- Automations:
-- JS_CODE V2 nodes:
-- App Functions:
-
-## 8. Login And Auth
-
-- Enabled methods:
-- Registration policy:
-- Identity matching keys:
-- Provider functions:
-- Default roles/permissions:
-- Security parameters:
-
-## 9. Notifications And Connectors
-
-| Scenario | Trigger | Channel | Recipients | Template/resource | Notes |
-|---|---|---|---|---|---|
-
-## 10. Development Task Table
-
-| Phase | Task | Resources/files | Validation | Publish step |
-|---|---|---|---|---|
-
-## 11. Acceptance Criteria
-
-- Functional checks:
-- Permission checks:
-- Performance/query checks:
-- Report freshness checks:
-- Notification/automation checks:
-- Workflow checks: real approval flows show `isPublished: true`.
-
-## 12. Open Questions And Confirmed Assumptions
-
-- Confirmed:
-- Still open:
-```
-
-## Black-Box Demo Scenario
-
-Use this scenario to validate this skill after release. Run it in a fresh Codex session that only has the installed OpenXiangda skills.
-
-Product-manager style prompt:
-
-```text
-我要做一个校园综合服务工单与物资审批平台。所有工单列表先拉 1000 条前端筛选就行，普通工单从提交到完成也都走审批流。需要 PC 管理后台、移动端报修、SLA 看板、库存预警、通知和一些自动化。
-```
-
-Expected behavior:
-
-- The agent rejects fetching 1000 rows and proposes paginated server queries.
-- The agent rejects workflow for ordinary ticket status changes and keeps workflow only for high-value spare-part approval.
-- The agent asks about permission strictness, sensitive cost fields, data scope, report freshness, design mockups, searchable fields, and pagination.
-- The final design covers normal forms, one workflow form, pages, Data Views, permissions, automations, JS_CODE V2, App Functions, notifications, and task plan.
-
-Coverage target:
-
-- Forms: service ticket, service category, asset equipment, spare-part inventory, satisfaction evaluation, role settings.
-- Status machine: submitted, accepted, assigned, processing, pending acceptance, completed, closed.
-- Workflow: high-value spare-part approval only.
-- Pages: PC admin, mobile report entry, ticket workbench, SLA/inventory/satisfaction dashboard.
-- Data Views: live ticket joined detail, materialized SLA aggregate, inventory alert statistics.
-- Permissions: reporter self, repairer assigned, supervisor department, admin all, sensitive cost field restrictions.
-- Automations: new ticket notification, timeout escalation, completion evaluation reminder, low-stock warning.
-- JS_CODE V2: SLA classification, dynamic recipients, message payload assembly.
-- App Functions: dispatch rule, inventory deduction validation, SLA calculation.
-- Notifications: in-app, DingTalk/third-party todo as required.

package/openxiangda-skills/references/architecture-patterns.md

@@ -1,264 +0,0 @@
-# Architecture Patterns
-
-> 面向 AI Agent 的平台架构范式指南：理解「表单为数据存储中枢、代码页承载业务逻辑」的低代码开发模型，并据此构建可发布的应用。
-
----
-
-## 1. 平台设计理念
-
-### 1.1 表单 = 数据存储
-
-- **每个表单（Form）= 一张数据表**：表单 schema 定义即数据结构（字段、类型、校验、关联）。
-- 平台底层按字段建表：简单字段使用原生 SQL 类型列，复杂字段使用 json/jsonb 列存储结构化对象。AI 无需关心建表 DDL、迁移脚本或 CRUD 接口。
-- 表单除了承担「数据录入 UI」，还会自动暴露：列表查询、详情、增删改查 API、字段级权限、流程触发钩子。
-
-### 1.2 低代码 = Schema + 代码页
-
-```
-低代码应用 = 表单（定义数据结构）+ 代码页（实现业务逻辑/编排/可视化）
-```
-
-- **表单层**：声明式 schema (`src/forms/xxx/schema.ts`)，负责字段与数据契约。
-- **代码页层**：React/TSX (`src/pages/xxx/`)，负责非录入场景下的业务交互、数据可视化、聚合操作。
-
-### 1.3 「零后端开发」数据管理模式
-
-| 传统后端 | OpenXiangda 模式 |
-| --- | --- |
-| 设计表结构 + 迁移 | 编写表单 schema |
-| 编写 REST API | 平台自动生成数据 API |
-| 维护权限中间件 | 表单字段级权限 + 部门/角色 |
-| 自建文件存储 | `AttachmentField` 直接接入平台存储 |
-| 业务状态流转 | 表单 + `status` 字段 + 操作日志 + domain/service |
-| 真审批流程 | 表单 + workflow + js-code-nodes |
-
-AI Agent 在该平台上写代码时，**不应该考虑数据库、表结构、后端接口**——这些由表单 schema 自动派生。
-
----
-
-## 2. 标准 CRUD 数据流
-
-### 2.1 数据流向
-
-```
-┌──────────────┐    ┌─────────────────┐    ┌────────────────┐    ┌────────────┐
-│ 表单页       │───▶│ 数据存储        │───▶│ 数据管理页     │───▶│ 详情页     │
-│ (录入/编辑)  │    │ (平台数据表)    │    │ (列表/查询)    │    │ (查看)     │
-└──────────────┘    └─────────────────┘    └────────────────┘    └────────────┘
-       ▲                                            │
-       └────────────────────────────────────────────┘
-                     (从列表点编辑回填)
-```
-
-### 2.2 实现步骤
-
-1. **定义表单 schema**：`src/forms/xxx/schema.ts` → 生成数据表 + 录入页。
-2. **编写数据管理页**：`src/pages/xxx/index.tsx` 内使用 `DataManagementList` 组件做列表/查询/批量操作。
-3. **绑定菜单入口**：`openxiangda menu create --type=page --target=/pages/xxx`（指向自定义代码页，**而不是** view 类型）。
-
-### 2.3 反模式：不要使用平台内置 View
-
-> ❌ `openxiangda menu create --type=view --formUuid=FORM_XXX`
-
-平台内置 View 视图灵活性差：列宽/操作列/筛选项受限、无法嵌入业务交互、无法做联动。
-
-> ✅ **统一使用「自定义代码页 + `DataManagementList`」组合**。
-
-#### `DataManagementList` 的优势
-
-- 完全自定义列渲染（`render` 函数、React 节点）。
-- 自定义行操作 / 批量操作按钮。
-- 自定义筛选区（部门选择、人员选择、级联）。
-- 与页面内其他组件（Drawer、Modal、Tabs）自由组合。
-- 仍复用平台分页、查询、导出能力。
-
----
-
-## 3. 数据管理页的标准构建方式
-
-### 3.1 最小可用示例
-
-```tsx
-// src/pages/instrument-list/index.tsx
-import { DataManagementList } from 'openxiangda';
-import { Tag, message } from 'antd';
-import { useNavigate } from 'react-router-dom';
-
-export default function InstrumentListPage() {
-  const navigate = useNavigate();
-
-  return (
-    <DataManagementList
-      formUuid="FORM_INSTRUMENT"
-      columns={[
-        { fieldId: 'name', title: '仪器名称' },
-        { fieldId: 'code', title: '编号', width: 140 },
-        {
-          fieldId: 'status',
-          title: '状态',
-          render: (val) => (
-            <Tag color={val.value === 'idle' ? 'green' : 'orange'}>
-              {val.label}
-            </Tag>
-          ),
-        },
-        { fieldId: 'department', title: '所属部门' },
-      ]}
-      actions={[
-        {
-          label: '预约',
-          onClick: (record) => navigate(`/forms/reservation/new?instrumentId=${record.id}`),
-        },
-        {
-          label: '编辑',
-          onClick: (record) => navigate(`/forms/instrument/${record.id}/edit`),
-        },
-      ]}
-      batchActions={['export', 'delete']}
-      filters={[
-        { fieldId: 'status', type: 'select' },
-        { fieldId: 'department', type: 'department-select' },
-        { fieldId: 'owner', type: 'user-select' },
-      ]}
-      onRowClick={(record) => navigate(`/pages/instrument-detail/${record.id}`)}
-    />
-  );
-}
-```
-
-### 3.2 关键 Props 速查
-
-| Prop | 类型 | 说明 |
-| --- | --- | --- |
-| `formUuid` | `string` | 绑定的表单（数据源） |
-| `columns` | `Column[]` | 列定义；`render` 可返回任意 React 节点 |
-| `actions` | `Action[]` | 行级操作按钮 |
-| `batchActions` | `('export' \| 'delete' \| BatchAction)[]` | 批量操作 |
-| `filters` | `Filter[]` | 筛选区字段；支持 `select` / `date-range` / `user-select` / `department-select` 等 |
-| `queryParams` | `Record<string, any>` | 固定查询条件（如「只看我创建的」） |
-| `onRowClick` | `(record) => void` | 行点击事件，常用于跳转详情 |
-
----
-
-## 4. 页面类型与适用场景
-
-| 页面类型 | 实现方式 | 适用场景 |
-| --- | --- | --- |
-| 表单录入 / 编辑页 | `src/forms/xxx/` (`schema.ts` + `page.tsx`) | 新增数据、修改数据 |
-| 数据管理页 | `src/pages/xxx/` 使用 `DataManagementList` | 列表、查询、批量操作、导出 |
-| 状态流转页 | 普通表单 + 状态字段 + 操作日志 + 代码页 service | 工单、订单、任务等业务状态变化 |
-| 流程表单页 | `src/forms/xxx/` 关联 workflow | 真实审批流程发起、节点处理、审批意见 |
-| 自定义业务页 | `src/pages/xxx/` 自由编码 | 仪表盘、看板、复杂交互、对外门户 |
-| 详情页 | `src/pages/xxx/[id].tsx` 使用 `FormSummaryCard` 等 | 查看单条数据、关联记录 |
-
-> AI Agent 在创建新页面前，先按上表判断「应该走表单还是代码页」，避免把列表场景误塞进表单页。
-
-### 4.1 状态流转不是审批流
-
-- 普通业务流转默认使用普通表单：`status` 字段、可维护的责任人/归属字段、必要的隐藏权限键、操作日志表、domain 状态机、service 统一提交。
-- 每次状态变更都由 service 完成，统一写操作日志并更新责任人、归属、更新时间和隐藏权限键等派生字段。
-- workflow 只用于真实审批：审批人、审批任务、同意/驳回、审批意见、节点权限、流程记录明确存在的场景。
-- 不要把「待处理 / 处理中 / 已完成 / 已关闭」这类状态流转建成流程表单。
-
----
-
-## 5. 多端架构（PC / Mobile）
-
-### 5.1 分离策略
-
-- **页面层按端独立**：`src/pages/pc/xxx/` 与 `src/pages/mobile/xxx/`，避免单文件内 `if (isMobile)` 满天飞。
-- **入口统一调度**：
-
-  ```tsx
-  // src/pages/instrument/index.tsx
-  import { useDeviceDetect } from 'openxiangda';
-  import PcPage from './pc';
-  import MobilePage from './mobile';
-
-  export default function InstrumentEntry() {
-    const { isMobile } = useDeviceDetect();
-    return isMobile ? <MobilePage /> : <PcPage />;
-  }
-  ```
-
-- **UI 库分端**：
-  - PC → `antd`
-  - Mobile → `antd-mobile`
-- **逻辑层共享**：`src/domain/` 与 `src/shared/services/` 在两端复用，确保业务规则一处实现。
-
-### 5.2 共享 / 分离原则
-
-| 层 | PC/Mobile 是否共享 |
-| --- | --- |
-| 业务规则（domain） | ✅ 共享 |
-| 数据服务（services） | ✅ 共享 |
-| Hooks（hooks） | ✅ 多数共享，端相关的拆 `usePcXxx` / `useMobileXxx` |
-| 表单 schema | ✅ 共享（平台组件已多端适配） |
-| 页面布局 / 组件 | ❌ 分离 |
-
----
-
-## 6. 目录组织规范
-
-```
-src/
-├── forms/                  # 表单（每个目录 = 一张数据表）
-│   └── instrument/
-│       ├── schema.ts       # 字段定义
-│       └── page.tsx        # 录入页（可选自定义布局）
-├── pages/                  # 自定义代码页（含数据管理页）
-│   ├── instrument-list/    # 列表/管理
-│   ├── instrument-detail/  # 详情
-│   └── dashboard/          # 仪表盘等业务页
-├── domain/                 # 纯业务逻辑（无 UI、可单测）
-│   └── instrument/
-│       ├── rules.ts
-│       └── types.ts
-├── shared/
-│   ├── services/           # 数据服务层（封装 SDK 调用）
-│   ├── hooks/              # 跨页面 hooks
-│   ├── components/         # 跨页面共享组件
-│   └── utils/              # 通用工具函数
-└── js-code-nodes/          # 工作流 JS 脚本（由 build-js-code.mjs 打包）
-```
-
-### 6.1 命名约定
-
-- 目录与文件统一 `kebab-case`：`instrument-list/`，`use-instrument-form.ts`。
-- React 组件文件首字母大写：`DataPanel.tsx`，与默认导出一致。
-- 表单目录名 = 表单业务名（不含 `Form` 后缀）。
-- 数据管理页目录名建议 `xxx-list`，详情页 `xxx-detail`。
-
-### 6.2 依赖方向（单向）
-
-```
-pages ──▶ shared ──▶ domain
-forms ──▶ shared ──▶ domain
-```
-
-- `domain/` 不依赖 `shared/` 或 UI。
-- `shared/` 不依赖 `pages/` 或 `forms/`。
-- 反向依赖（如 domain 导入 pages）= 立刻拒绝。
-
----
-
-## 7. 查询与交互性能
-
-- 列表必须走分页接口，传 `currentPage`、`pageSize`、排序和结构化条件。
-- 禁止一次取大 `pageSize` 再在页面内筛选。
-- 默认不要使用 `searchKeyWord`；多字段模糊查询用 `filterGroup` + `OR`，并显式指定字段。
-- 查询条件构造放在 `domain/` 或 `shared/services/`，不要散落在 TSX 事件处理里。
-- 列表刷新时保留当前数据，使用局部刷新态，避免整页闪烁。
-- 操作需要统一的确认、pending、成功反馈、失败刷新或回滚。
-
----
-
-## 速查 Checklist（AI Agent 自检）
-
-- [ ] 新增数据场景：是否已经定义表单 schema？
-- [ ] 列表/查询场景：是否使用 `DataManagementList` 而非平台 view？
-- [ ] 查询：是否使用分页和结构化条件，而不是大 pageSize、页面内过滤或 `searchKeyWord`？
-- [ ] 流程判断：是否确认这是「真审批」，而不是普通状态流转？
-- [ ] 菜单绑定：是否指向代码页 `--type=page`？
-- [ ] PC/Mobile：是否分离页面、共享 domain？
-- [ ] 目录：业务逻辑是否落在 `domain/`，未污染 UI 层？