@yss123/cage-admin 0.1.0 → 0.2.0

package/README.md

@@ -12,6 +12,37 @@ pnpm add @yss123/cage-admin
 
 首次使用建议通过脚手架创建完整项目，所需依赖由模板统一配置。需要 Node.js 24 或更新版本。
 
+## 中文管理界面
+
+启动 API 后访问 `/admin/`。页面包含审批待办、用户与部门、角色与授权、操作审计、异步任务和第三方同步。角色页按业务对象分组展示权限，支持中文或代码搜索；操作权限即时保存，数据范围与审批额度需要点击各自的保存按钮。中文显示不改变真实权限标识，也不会自动给角色增加权限。
+
+业务聚合和命令应填写中文 `description`。项目根目录 `cage.config.json` 的 `graph.labels` 同时用于图谱和系统管理，无需再维护一份翻译：
+
+```json
+{
+  "graph": {
+    "labels": {
+      "aggregate:PurchaseOrder": "采购单",
+      "command:PurchaseOrder.submit": "提交审批",
+      "capability:PurchaseOrder.export": "导出采购单",
+      "approval:poApproval": "采购审批流程",
+      "event:OrderSubmitted": "采购单已提交",
+      "job:expireStaleOrders": "清理过期草稿"
+    }
+  }
+}
+```
+
+以上是合并进已有配置的片段，不要覆盖项目中的 domain、contracts 等设置。修改显示名后重启 API。API 进程应在项目根目录启动；Docker 模板也会复制这份配置到运行时镜像。
+
+名称优先级：权限专用 `capability:` → `command:` → 命令 `description` → 常用动作中文；业务对象使用 `aggregate:` → 聚合 `description`。read/export 会自动组合对象中文名，敏感字段明文权限和调用方也会显示中文。框架无法凭代码猜测自定义业务术语，缺少中文时需要在声明或配置中补充。
+
+直接集成 HTTP 服务时，也可以通过 `createServer({ domain, adminLabels: { 'aggregate:Document': '业务单据' } })` 提供显示名；它覆盖本地 `graph.labels`。此选项属于 `@yss123/cage-http`，不是领域授权配置。
+
+## 维护管理前端
+
+`ui/src/app` 负责页面组合，`ui/src/modules` 按管理功能组织，`ui/src/shared` 放请求、标签和 DOM 组件。界面由 TypeScript 编译成原生浏览器模块，不要求业务项目使用特定前端框架。执行 `pnpm build` 同时构建接口与界面；发布时分发 `ui/dist`、HTML 和 CSS，不直接执行 TypeScript 源码。
+
 - [完整使用说明](https://github.com/shunshunyue/cage/blob/main/docs/使用说明.md)
 - [框架源码与范例](https://github.com/shunshunyue/cage)
 - [问题反馈](https://github.com/shunshunyue/cage/issues)

package/dist/catalog.d.ts

@@ -0,0 +1,43 @@
+import { type Registry } from '@yss123/cage-kernel';
+/** 显示名沿用图谱的节点键；只影响文案，不重命名权限、命令、表或业务字段。 */
+export type AdminLabels = Record<string, string>;
+/**
+ * 展示目录独立于内核的授权目录。原始字段继续提供给 API 调用者，额外 label 专供界面使用。
+ * 自定义业务名称来自项目声明或 labels，框架不猜测客户术语；缺少中文时明确提示需要命名。
+ */
+export declare function adminCatalog(registry: Registry, labels?: AdminLabels): {
+    capabilities: {
+        label: string;
+        capability: string;
+        kind: "command" | "read" | "export" | "unmask" | "system";
+        aggregate?: string;
+        description?: string;
+        invokedBy?: readonly string[];
+    }[];
+    aggregates: {
+        name: string;
+        description: string | null;
+        label: string;
+        states: readonly any[];
+        scope: {
+            deptField: string | null;
+            ownerField: string | null;
+        };
+        sensitive: Record<string, string>;
+    }[];
+    combinators: string[];
+    approvals: {
+        name: string;
+        process: string;
+        aggregate: string;
+        routable: readonly string[];
+        label: string;
+    }[];
+    jobs: {
+        name: string;
+        cron: string;
+        description: string | null;
+        label: string;
+    }[];
+    labels: AdminLabels;
+};

package/dist/catalog.js

@@ -0,0 +1,91 @@
+import { sensitiveFields } from '@yss123/cage-kernel';
+const actions = {
+    create: '新建',
+    read: '查看',
+    export: '导出',
+    update: '编辑',
+    rename: '修改名称',
+    delete: '删除',
+    archive: '停用',
+    enable: '启用',
+    disable: '停用',
+    submit: '提交',
+    approve: '审批通过',
+    reject: '驳回',
+    cancel: '取消',
+    revoke: '撤回',
+    confirm: '确认',
+    void: '作废',
+    receive: '确认收货',
+    markReceived: '确认收货',
+    recordErpNo: '回写外部单号',
+    acquire: '占用资源',
+    release: '释放资源',
+    assignRoles: '分配角色',
+    setPassword: '重置密码',
+    grantCapability: '授予操作权限',
+    revokeCapability: '收回操作权限',
+    setScope: '设置数据范围',
+};
+const sensitive = {
+    phone: '手机号',
+    email: '邮箱',
+    idCard: '身份证号',
+    bankCard: '银行卡号',
+    name: '姓名',
+    address: '地址',
+};
+/**
+ * 展示目录独立于内核的授权目录。原始字段继续提供给 API 调用者，额外 label 专供界面使用。
+ * 自定义业务名称来自项目声明或 labels，框架不猜测客户术语；缺少中文时明确提示需要命名。
+ */
+export function adminCatalog(registry, labels = {}) {
+    const aggregates = registry.aggregates.map((a) => {
+        const label = labels[`aggregate:${a.name}`] || a.description || a.name;
+        return {
+            name: a.name,
+            description: a.description ?? null,
+            label,
+            states: a.states.values,
+            scope: { deptField: a.scope.deptField ?? null, ownerField: a.scope.ownerField ?? null },
+            sensitive: sensitiveFields(a),
+        };
+    });
+    const names = new Map(aggregates.map((a) => [a.name, a.label]));
+    const capabilities = registry.capabilityCatalog().map((c) => {
+        const subject = names.get(c.aggregate ?? '') ?? '';
+        const action = c.capability.split('.').at(-1);
+        const override = labels[`capability:${c.capability}`] || labels[`command:${c.capability}`];
+        // 内核的 read/export 文案可能含英文聚合名，重组后才能复用项目提供的中文名称。
+        const label = override ||
+            (c.kind === 'read'
+                ? `查看${subject}`
+                : c.kind === 'export'
+                    ? `导出${subject}`
+                    : c.kind === 'unmask'
+                        ? `查看${sensitive[action] ?? '敏感字段'}明文`
+                        : c.description || actions[action] || '自定义操作');
+        return { ...c, label };
+    });
+    return {
+        capabilities,
+        aggregates,
+        combinators: ['self', 'dept', 'deptSubtree', 'deptSet', 'all'],
+        approvals: registry.approvals.map(({ a, name }) => ({
+            name,
+            process: a.process,
+            aggregate: a.agg.name,
+            routable: a.routable,
+            label: labels[`approval:${name}`] || a.process,
+        })),
+        jobs: registry.jobs.map((j) => ({
+            name: j.name,
+            cron: j.cron,
+            description: j.description ?? null,
+            label: labels[`job:${j.name}`] || j.description || j.name,
+        })),
+        // 事件、状态和连接器也能复用图谱文案，供审计、待办和运维页面解释业务标识。
+        labels,
+    };
+}
+//# sourceMappingURL=catalog.js.map

package/dist/catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.js","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"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"}