openxiangda 1.0.21 → 1.0.24

package/templates/sy-lowcode-app-workspace/examples/best-practices/decision-guide.md

@@ -0,0 +1,44 @@
+# Decision Guide
+
+## Page And Data Shape
+
+Use a form when you need a data table. Each form schema defines fields,
+validation, storage shape, and generated platform data APIs.
+
+Use a code page when you need a workbench, portal, dashboard, cross-form
+composition, custom list actions, or complex interaction.
+
+Use `DataManagementList` for list/search/export/batch-management pages. Extend
+it with row actions, custom renderers, and drawers instead of rebuilding
+pagination, export, and filters from scratch.
+
+## State Flow Is Not Workflow
+
+Most business "processes" are lifecycle state changes:
+
+- work tickets: new -> accepted -> processing -> resolved -> closed
+- orders: draft -> submitted -> paid -> fulfilled -> completed
+- assets: available -> reserved -> in_use -> maintenance -> retired
+
+Use a normal form with a `status` field, ownership fields, and an operation-log
+form. Define allowed transitions in `domain/<feature>/state-machine.ts`, and
+execute changes through a service method that updates state and writes logs.
+
+Use workflow only when the platform must create approval tasks with approvers,
+approval comments, agree/reject actions, copy nodes, node field permissions, and
+approval history.
+
+## Automation And JS_CODE
+
+Use automation or workflow JS_CODE when logic must run on the backend after a
+trigger: scheduled scans, cross-form synchronization, notification fan-out,
+external HTTP calls, or platform role synchronization.
+
+Frontend code must not be responsible for data isolation or background jobs.
+
+## Permissions
+
+For dynamic multi-role apps, create a business role table and synchronize it to
+platform app roles. Add redundant ownership fields to business forms, such as
+`collegeId`, `classId`, `ownerDeptId`, and `ownerUserId`. Use form permission
+groups with condition-style data permissions to enforce data isolation.

package/templates/sy-lowcode-app-workspace/examples/best-practices/design-style.md

@@ -0,0 +1,30 @@
+# Design Style
+
+OpenXiangda business apps should feel like focused operational tools.
+
+## Interaction Defaults
+
+- Every async page has loading, refreshing, empty, error, and submit-pending
+  states.
+- List refresh should keep existing rows visible and show a small refresh state.
+- Mutating actions need confirmation, pending feedback, success feedback, and a
+  failure refresh or rollback path.
+- Mobile actions should use a bottom action area, drawer, or action sheet; do
+  not copy a dense PC table toolbar to mobile.
+
+## Layout Defaults
+
+- Use dense but readable workbench layouts for admin and ops pages.
+- Put high-value filters near the list, not in hidden configuration pages.
+- Use status tags, responsibility fields, and latest action summaries for
+  lifecycle data.
+- Do not build marketing-style hero pages for business tools.
+
+## Styling Rules
+
+- Use platform CSS variables, Tailwind semantic classes, Ant Design, and
+  antd-mobile.
+- Keep page styles in `styles.css`; avoid large inline style objects.
+- Keep reusable visual states in shared components: status tags, query states,
+  confirmation triggers, and operation timelines.
+- Do not override private Ant Design class names.

package/templates/sy-lowcode-app-workspace/examples/best-practices/module-structure.md

@@ -0,0 +1,48 @@
+# Module Structure
+
+Use this structure for substantial features:
+
+```text
+src/
+  domain/<feature>/
+    types.ts
+    state-machine.ts
+    permissions.ts
+    query.ts
+    index.ts
+  shared/
+    services/<feature>.ts
+    hooks/use<Feature>.ts
+    components/
+      QueryState.tsx
+      StatusTag.tsx
+  pages/<feature>/
+    page.config.ts
+    index.tsx
+    App.tsx
+    styles.css
+    components/
+  forms/<feature>/
+    schema.ts
+    page.tsx
+```
+
+## Dependency Direction
+
+```text
+pages -> shared/hooks -> shared/services -> domain
+forms -> shared -> domain
+```
+
+- `domain/` has no React, Ant Design, SDK, or page imports.
+- `shared/` does not import from `pages/`.
+- `pages/` compose modules and call hooks; they do not build complex query
+  payloads inline.
+- PC and mobile views can have different components and styles, but they reuse
+  the same domain and service logic.
+
+## File Size
+
+Avoid large single-file pages. If a page grows beyond roughly 250 lines, split
+table actions, drawers, timelines, query builders, hooks, and styles into
+separate files.

package/templates/sy-lowcode-app-workspace/examples/best-practices/src/domain/role-governance/index.ts

@@ -0,0 +1,2 @@
+export * from "./permissions";
+export * from "./types";

package/templates/sy-lowcode-app-workspace/examples/best-practices/src/domain/role-governance/permissions.test.ts

@@ -0,0 +1,35 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+
+import { buildConditionDataPermission, buildRoleCode } from "./permissions";
+
+describe("role-governance permission helpers", () => {
+  it("normalizes dynamic role codes", () => {
+    assert.equal(buildRoleCode({ roleCode: " College Admin " }), "college_admin");
+    assert.equal(buildRoleCode({ roleCode: "class  advisor" }), "class_advisor");
+  });
+
+  it("builds condition-based data permissions from redundant fields", () => {
+    const permission = buildConditionDataPermission({
+      collegeId: "college_science",
+      classId: "",
+      ownerDeptId: "dept_lab",
+    });
+
+    assert.equal(permission.type, "condition");
+    assert.deepEqual(permission.condition.rules, [
+      {
+        field: "collegeId",
+        componentType: "Text",
+        op: "=",
+        value: "college_science",
+      },
+      {
+        field: "ownerDeptId",
+        componentType: "Text",
+        op: "=",
+        value: "dept_lab",
+      },
+    ]);
+  });
+});

package/templates/sy-lowcode-app-workspace/examples/best-practices/src/domain/role-governance/permissions.ts

@@ -0,0 +1,24 @@
+import type { AppRoleRecord, DataOwnershipFields } from "./types";
+
+export function buildRoleCode(role: Pick<AppRoleRecord, "roleCode">) {
+  return role.roleCode.trim().replace(/\s+/g, "_").toLowerCase();
+}
+
+export function buildConditionDataPermission(scope: DataOwnershipFields) {
+  const rules = Object.entries(scope)
+    .filter(([, value]) => Boolean(value))
+    .map(([field, value]) => ({
+      field,
+      componentType: "Text",
+      op: "=",
+      value,
+    }));
+
+  return {
+    type: "condition" as const,
+    condition: {
+      logic: "AND" as const,
+      rules,
+    },
+  };
+}

package/templates/sy-lowcode-app-workspace/examples/best-practices/src/domain/role-governance/types.ts

@@ -0,0 +1,17 @@
+export interface AppRoleRecord {
+  formInstanceId: string;
+  roleCode: string;
+  roleName: string;
+  members?: Array<{ label: string; value: string }>;
+  collegeId?: string;
+  classId?: string;
+  enabled?: { label: string; value: "enabled" | "disabled" };
+  lastSyncedAt?: string;
+}
+
+export interface DataOwnershipFields {
+  collegeId?: string;
+  classId?: string;
+  ownerDeptId?: string;
+  ownerUserId?: string;
+}

package/templates/sy-lowcode-app-workspace/examples/best-practices/src/domain/service-ticket/index.ts

@@ -0,0 +1,4 @@
+export * from "./permissions";
+export * from "./state-machine";
+export * from "./ticket-query";
+export * from "./types";

package/templates/sy-lowcode-app-workspace/examples/best-practices/src/domain/service-ticket/permissions.test.ts

@@ -0,0 +1,42 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+
+import { canViewTicket, getTicketUiPermissions } from "./permissions";
+import type { TicketOperator, TicketRecord } from "./types";
+
+const ticket: TicketRecord = {
+  formInstanceId: "ticket_001",
+  title: "实验室报修",
+  status: "accepted",
+  ownerUserId: "owner_001",
+  ownerDeptId: "dept_lab",
+  collegeId: "college_science",
+};
+
+describe("service-ticket permission helpers", () => {
+  it("allows admins and redundant ownership matches", () => {
+    assert.equal(canViewTicket(ticket, user({ roleCodes: ["app_admin"] })), true);
+    assert.equal(canViewTicket(ticket, user({ userId: "owner_001" })), true);
+    assert.equal(canViewTicket(ticket, user({ collegeIds: ["college_science"] })), true);
+    assert.equal(canViewTicket(ticket, user({ departmentIds: ["dept_lab"] })), true);
+  });
+
+  it("keeps action visibility tied to operation permission", () => {
+    const allowed = getTicketUiPermissions(ticket, user({ departmentIds: ["dept_lab"] }));
+    assert.equal(allowed.canView, true);
+    assert.deepEqual(allowed.actions, ["start", "cancel"]);
+
+    const denied = getTicketUiPermissions(ticket, user({ userId: "other" }));
+    assert.equal(denied.canView, false);
+    assert.deepEqual(denied.actions, []);
+  });
+});
+
+function user(input: Partial<TicketOperator>): TicketOperator {
+  return {
+    userId: "u_001",
+    roleCodes: [],
+    departmentIds: [],
+    ...input,
+  };
+}

package/templates/sy-lowcode-app-workspace/examples/best-practices/src/domain/service-ticket/permissions.ts

@@ -0,0 +1,23 @@
+import type { TicketOperator, TicketRecord } from "./types";
+import { getAvailableTicketActions } from "./state-machine";
+
+export function canViewTicket(ticket: TicketRecord, operator: TicketOperator) {
+  if (operator.roleCodes.includes("app_admin")) return true;
+  if (ticket.ownerUserId === operator.userId) return true;
+  if (ticket.collegeId && operator.collegeIds?.includes(ticket.collegeId)) return true;
+  if (ticket.classId && operator.classIds?.includes(ticket.classId)) return true;
+  if (
+    ticket.ownerDeptId &&
+    operator.departmentIds?.includes(ticket.ownerDeptId)
+  ) {
+    return true;
+  }
+  return false;
+}
+
+export function getTicketUiPermissions(ticket: TicketRecord, operator: TicketOperator) {
+  return {
+    canView: canViewTicket(ticket, operator),
+    actions: getAvailableTicketActions(ticket, operator),
+  };
+}

package/templates/sy-lowcode-app-workspace/examples/best-practices/src/domain/service-ticket/state-machine.test.ts

@@ -0,0 +1,63 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+
+import {
+  assertTicketTransition,
+  getAvailableTicketActions,
+  getNextTicketStatus,
+} from "./state-machine";
+import type { TicketOperator, TicketRecord } from "./types";
+
+const operator: TicketOperator = {
+  userId: "u_001",
+  roleCodes: ["ticket_operator"],
+  departmentIds: ["dept_lab"],
+};
+
+const ticket: TicketRecord = {
+  formInstanceId: "ticket_001",
+  title: "设备故障",
+  status: "new",
+  ownerDeptId: "dept_lab",
+};
+
+describe("service-ticket state machine", () => {
+  it("returns deterministic next status", () => {
+    assert.equal(getNextTicketStatus("new", "accept"), "accepted");
+    assert.equal(getNextTicketStatus("resolved", "close"), "closed");
+    assert.equal(getNextTicketStatus("closed", "start"), null);
+  });
+
+  it("filters available actions by status and operator permission", () => {
+    assert.deepEqual(getAvailableTicketActions(ticket, operator), [
+      "accept",
+      "cancel",
+    ]);
+
+    assert.deepEqual(
+      getAvailableTicketActions(ticket, {
+        userId: "u_002",
+        roleCodes: ["student"],
+        departmentIds: ["dept_other"],
+      }),
+      [],
+    );
+  });
+
+  it("throws clear errors for unauthorized or invalid transitions", () => {
+    assert.throws(
+      () =>
+        assertTicketTransition(ticket, "accept", {
+          userId: "u_002",
+          roleCodes: [],
+          departmentIds: [],
+        }),
+      /无权操作/,
+    );
+
+    assert.throws(
+      () => assertTicketTransition({ ...ticket, status: "closed" }, "start", operator),
+      /不允许执行动作/,
+    );
+  });
+});

package/templates/sy-lowcode-app-workspace/examples/best-practices/src/domain/service-ticket/state-machine.ts

@@ -0,0 +1,73 @@
+import type { TicketAction, TicketOperator, TicketRecord, TicketStatus } from "./types";
+
+export const ticketStatusLabels: Record<TicketStatus, string> = {
+  new: "新建",
+  accepted: "已受理",
+  processing: "处理中",
+  paused: "挂起",
+  resolved: "已解决",
+  closed: "已关闭",
+  cancelled: "已取消",
+};
+
+export const ticketActionLabels: Record<TicketAction, string> = {
+  accept: "受理",
+  start: "开始处理",
+  pause: "挂起",
+  resume: "恢复",
+  resolve: "解决",
+  close: "关闭",
+  cancel: "取消",
+};
+
+const transitionTable: Record<TicketStatus, Partial<Record<TicketAction, TicketStatus>>> = {
+  new: { accept: "accepted", cancel: "cancelled" },
+  accepted: { start: "processing", cancel: "cancelled" },
+  processing: { pause: "paused", resolve: "resolved" },
+  paused: { resume: "processing", cancel: "cancelled" },
+  resolved: { close: "closed" },
+  closed: {},
+  cancelled: {},
+};
+
+export function getNextTicketStatus(
+  status: TicketStatus,
+  action: TicketAction,
+): TicketStatus | null {
+  return transitionTable[status]?.[action] || null;
+}
+
+export function canOperateTicket(ticket: TicketRecord, operator: TicketOperator) {
+  if (operator.roleCodes.includes("app_admin")) return true;
+  if (ticket.ownerUserId && ticket.ownerUserId === operator.userId) return true;
+  if (
+    ticket.ownerDeptId &&
+    operator.departmentIds?.includes(ticket.ownerDeptId)
+  ) {
+    return true;
+  }
+  return false;
+}
+
+export function getAvailableTicketActions(
+  ticket: TicketRecord,
+  operator: TicketOperator,
+): TicketAction[] {
+  if (!canOperateTicket(ticket, operator)) return [];
+  return Object.keys(transitionTable[ticket.status] || {}) as TicketAction[];
+}
+
+export function assertTicketTransition(
+  ticket: TicketRecord,
+  action: TicketAction,
+  operator: TicketOperator,
+) {
+  if (!canOperateTicket(ticket, operator)) {
+    throw new Error("当前用户无权操作该工单");
+  }
+  const nextStatus = getNextTicketStatus(ticket.status, action);
+  if (!nextStatus) {
+    throw new Error(`状态 ${ticket.status} 不允许执行动作 ${action}`);
+  }
+  return nextStatus;
+}

package/templates/sy-lowcode-app-workspace/examples/best-practices/src/domain/service-ticket/ticket-query.test.ts

@@ -0,0 +1,34 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+
+import { buildTicketFilterGroup } from "./ticket-query";
+
+describe("service-ticket query builder", () => {
+  it("builds structured filters instead of browser-side filtering", () => {
+    const group = buildTicketFilterGroup({
+      keyword: "离心机",
+      statuses: ["new", "processing"],
+      priorities: ["urgent"],
+      collegeId: "college_science",
+    });
+
+    assert.equal(group.logic, "AND");
+    assert.deepEqual(
+      group.rules.map((item) => item.key),
+      ["status", "priority", "collegeId"],
+    );
+    assert.equal(group.conditions.length, 1);
+    assert.equal(group.conditions[0]?.logic, "OR");
+    assert.deepEqual(
+      group.conditions[0]?.rules.map((item) => item.key),
+      ["title", "description"],
+    );
+  });
+
+  it("omits empty search fields", () => {
+    const group = buildTicketFilterGroup({ keyword: "   " });
+
+    assert.deepEqual(group.rules, []);
+    assert.deepEqual(group.conditions, []);
+  });
+});

package/templates/sy-lowcode-app-workspace/examples/best-practices/src/domain/service-ticket/ticket-query.ts

@@ -0,0 +1,73 @@
+import type { TicketSearchState } from "./types";
+
+export type FilterLogic = "AND" | "OR";
+
+export interface FilterRule {
+  id: string;
+  key: string;
+  componentName: string;
+  operator: string;
+  value: unknown;
+}
+
+export interface FilterGroup {
+  id: string;
+  logic: FilterLogic;
+  rules: FilterRule[];
+  conditions: FilterGroup[];
+}
+
+const rule = (
+  key: string,
+  componentName: string,
+  operator: string,
+  value: unknown,
+): FilterRule => ({
+  id: `${key}_${operator}`,
+  key,
+  componentName,
+  operator,
+  value,
+});
+
+export function buildTicketFilterGroup(search: TicketSearchState): FilterGroup {
+  const group: FilterGroup = {
+    id: "ticket_filters",
+    logic: "AND",
+    rules: [],
+    conditions: [],
+  };
+
+  if (search.statuses?.length) {
+    group.rules.push(rule("status", "SelectField", "IN", search.statuses));
+  }
+  if (search.priorities?.length) {
+    group.rules.push(rule("priority", "SelectField", "IN", search.priorities));
+  }
+  if (search.ownerUserId) {
+    group.rules.push(rule("ownerUserId", "TextField", "EQ", search.ownerUserId));
+  }
+  if (search.ownerDeptId) {
+    group.rules.push(rule("ownerDeptId", "TextField", "EQ", search.ownerDeptId));
+  }
+  if (search.collegeId) {
+    group.rules.push(rule("collegeId", "TextField", "EQ", search.collegeId));
+  }
+  if (search.classId) {
+    group.rules.push(rule("classId", "TextField", "EQ", search.classId));
+  }
+  if (search.keyword?.trim()) {
+    const keyword = search.keyword.trim();
+    group.conditions.push({
+      id: "keyword_or",
+      logic: "OR",
+      rules: [
+        rule("title", "TextField", "CONTAINS", keyword),
+        rule("description", "TextAreaField", "CONTAINS", keyword),
+      ],
+      conditions: [],
+    });
+  }
+
+  return group;
+}

package/templates/sy-lowcode-app-workspace/examples/best-practices/src/domain/service-ticket/types.ts

@@ -0,0 +1,64 @@
+export type TicketStatus =
+  | "new"
+  | "accepted"
+  | "processing"
+  | "paused"
+  | "resolved"
+  | "closed"
+  | "cancelled";
+
+export type TicketAction =
+  | "accept"
+  | "start"
+  | "pause"
+  | "resume"
+  | "resolve"
+  | "close"
+  | "cancel";
+
+export type TicketPriority = "urgent" | "high" | "normal" | "low";
+
+export interface TicketRecord {
+  formInstanceId: string;
+  title: string;
+  status: TicketStatus;
+  priority?: TicketPriority;
+  ownerUserId?: string;
+  ownerDeptId?: string;
+  collegeId?: string;
+  classId?: string;
+  requester?: { label: string; value: string };
+  currentOwner?: { label: string; value: string };
+  description?: string;
+  lastActionAt?: string;
+}
+
+export interface TicketActionLog {
+  ticketId: string;
+  action: TicketAction;
+  fromStatus?: TicketStatus;
+  toStatus: TicketStatus;
+  operatorId: string;
+  operatorName?: string;
+  comment?: string;
+  operatedAt: string;
+}
+
+export interface TicketOperator {
+  userId: string;
+  userName?: string;
+  roleCodes: string[];
+  collegeIds?: string[];
+  classIds?: string[];
+  departmentIds?: string[];
+}
+
+export interface TicketSearchState {
+  keyword?: string;
+  statuses?: TicketStatus[];
+  priorities?: TicketPriority[];
+  ownerUserId?: string;
+  ownerDeptId?: string;
+  collegeId?: string;
+  classId?: string;
+}

package/templates/sy-lowcode-app-workspace/examples/best-practices/src/forms/app-role/page.tsx

@@ -0,0 +1 @@
+export { default } from "./schema";

package/templates/sy-lowcode-app-workspace/examples/best-practices/src/forms/app-role/schema.ts

@@ -0,0 +1,57 @@
+import { createFormSchema } from "@/shared/form-schema";
+
+export default createFormSchema({
+  formMeta: {
+    formUuid: "",
+    appType: process.env.OPENXIANGDA_APP_TYPE || "APP_XXXX",
+    title: "应用角色维护",
+  },
+  fields: [
+    {
+      fieldId: "roleCode",
+      componentName: "TextField",
+      label: "角色编码",
+      required: true,
+      placeholder: "如 college_admin",
+    },
+    {
+      fieldId: "roleName",
+      componentName: "TextField",
+      label: "角色名称",
+      required: true,
+    },
+    {
+      fieldId: "members",
+      componentName: "UserSelectField",
+      label: "成员",
+      multiple: true,
+    },
+    {
+      fieldId: "collegeId",
+      componentName: "TextField",
+      label: "学院 ID",
+      tips: "与业务表冗余字段配合，用于条件式数据权限。",
+    },
+    {
+      fieldId: "classId",
+      componentName: "TextField",
+      label: "班级 ID",
+      tips: "与业务表冗余字段配合，用于条件式数据权限。",
+    },
+    {
+      fieldId: "enabled",
+      componentName: "RadioField",
+      label: "启用状态",
+      defaultValue: { label: "启用", value: "enabled" },
+      options: [
+        { label: "启用", value: "enabled" },
+        { label: "停用", value: "disabled" },
+      ],
+    },
+    {
+      fieldId: "lastSyncedAt",
+      componentName: "DateField",
+      label: "最近同步时间",
+    },
+  ],
+});

package/templates/sy-lowcode-app-workspace/examples/best-practices/src/forms/customer-profile/page.tsx

@@ -0,0 +1 @@
+export { default } from "./schema";