@yss123/cage-admin 0.1.0 → 0.3.0

package/ui/dist/modules/roles/roles-page.js

@@ -0,0 +1,348 @@
+/**
+ * 角色与授权管理界面，区分能力授予、能力参数和对象数据范围。
+ * 页面只按当前登录能力限制可操作项；实际防提权、状态与范围检查由服务端命令执行。
+ * 能力切换即时提交，范围编辑先保留草稿再保存，只有成功响应才更新已保存角色快照。
+ */
+import { api, can, run, state } from '../../shared/api.js';
+import { badge, emptyState, field, h, icon, modal, searchInput } from '../../shared/dom.js';
+import { invocation, objectName, scopes } from '../../shared/labels.js';
+// 只保存页面交互，角色和权限仍以命令响应为准；搜索不会改动授权数据。
+let selectedRole = null;
+let tab = 'permissions';
+let query = '';
+let filter = 'all';
+/**
+ * 读取角色与可访问部门，构建角色列表和权限/范围详情。
+ * 角色、筛选词及当前选项卡为页面内状态；列表数据来自有界查询，目录来自启动阶段。
+ */
+export async function renderRoles(main) {
+    const [result, departmentResult] = await Promise.all([
+        api('GET', '/api/role?pageSize=200'),
+        can('Dept.read')
+            ? api('GET', '/api/dept?pageSize=200')
+            : Promise.resolve({ items: [] }),
+    ]);
+    let roles = result.items;
+    if (!selectedRole || !roles.some((role) => role.id === selectedRole))
+        selectedRole = roles[0]?.id ?? null;
+    const list = h('div', { class: 'role-list', 'aria-label': '角色列表' });
+    const details = h('div', { class: 'role-details' });
+    let roleQuery = '';
+    const count = badge(String(roles.length), 'neutral');
+    const sidebar = h('aside', { class: 'role-sidebar' }, h('div', { class: 'role-list-heading' }, h('h2', {}, '团队角色'), count), h('p', { class: 'muted sidebar-description' }, '选择角色，配置可以做什么、可以看哪些数据。'), searchInput('搜索角色名称或编码', (value) => {
+        roleQuery = value.toLowerCase();
+        renderList();
+    }), list);
+    if (can('Role.create'))
+        sidebar.append(h('button', { class: 'button primary create-role', onclick: createRole }, icon('plus'), '新建角色'));
+    main.append(h('div', { class: 'role-workspace' }, sidebar, details));
+    /**
+     * 按角色名称或 code 过滤当前加载集合，选择后同步重画详情，不改角色状态或授权。
+     */
+    function renderList() {
+        const visible = roles.filter((role) => `${role.name} ${role.code}`.toLowerCase().includes(roleQuery));
+        list.replaceChildren(...visible.map((role) => h('button', {
+            class: `role-item ${role.id === selectedRole ? 'selected' : ''}`,
+            'aria-pressed': role.id === selectedRole,
+            onclick: () => {
+                selectedRole = role.id;
+                renderList();
+                renderDetail();
+            },
+        }, h('span', { class: 'role-avatar' }, icon('shield')), h('span', { class: 'role-item-copy' }, h('strong', {}, role.name), h('small', {}, role.code)), role.status !== 'active'
+            ? badge('停用')
+            : h('span', { class: 'role-item-count' }, role.capabilities.length))));
+        if (!visible.length)
+            list.append(h('p', { class: 'list-empty' }, '没有匹配的角色'));
+    }
+    /**
+     * 提交新角色名称和 code，成功后把真实返回角色加入列表并选中。
+     * 新角色没有默认业务能力，后续需要显式授权。
+     */
+    function createRole() {
+        const name = h('input', { placeholder: '例如：采购经理', required: true, maxlength: 100 });
+        const code = h('input', {
+            placeholder: '例如：purchase_manager',
+            required: true,
+            pattern: '[a-z][a-z0-9_]*',
+        });
+        const save = h('button', { class: 'primary', type: 'submit' }, '创建角色');
+        const form = h('form', {
+            class: 'stack-form',
+            onsubmit: async (event) => {
+                event.preventDefault();
+                const created = await run(() => api('POST', '/api/role/create', { name: name.value, code: code.value }), '角色已创建，请继续配置权限', save);
+                if (created) {
+                    roles = [...roles, created];
+                    selectedRole = created.id;
+                    count.textContent = String(roles.length);
+                    dialog.close();
+                    renderList();
+                    renderDetail();
+                }
+            },
+        }, field('角色名称', name), field('角色编码', code, '用于业务识别，使用小写字母、数字和下划线。'), h('p', { class: 'inline-info' }, icon('info'), '新角色默认没有操作权限，不会自动获得已有业务能力。'), h('div', { class: 'form-actions' }, save));
+        const dialog = modal('新建团队角色', form);
+        name.focus();
+    }
+    /**
+     * 为选中角色重建摘要与选项卡；已停用角色只展示配置。
+     * 局部 updateRole 仅接受服务端成功快照，避免界面把失败请求的临时选择当成已保存授权。
+     */
+    function renderDetail() {
+        let role = roles.find((item) => item.id === selectedRole);
+        if (!role) {
+            details.replaceChildren(emptyState('从一个角色开始', '选择左侧角色，或创建一个新的团队角色。', 'shield'));
+            return;
+        }
+        const updateRole = (updated) => {
+            role = updated;
+            roles = roles.map((item) => (item.id === updated.id ? updated : item));
+            renderList();
+        };
+        const countText = h('strong', {}, String(role.capabilities.length));
+        const summary = h('div', { class: 'role-summary' }, h('div', { class: 'role-title' }, h('span', { class: 'role-emblem' }, icon('shield')), h('div', {}, h('div', { class: 'title-line' }, h('h2', {}, role.name), badge(role.status === 'active' ? '使用中' : '已停用', role.status === 'active' ? 'green' : 'neutral')), h('p', {}, h('code', {}, role.code), h('span', {}, '· 按角色统一管理访问权限')))), h('div', { class: 'permission-total' }, countText, h('span', {}, '项已授权')));
+        const body = h('div', { class: 'role-tab-body' });
+        const buttons = ['permissions', 'scopes'].map((key) => h('button', {
+            role: 'tab',
+            'aria-selected': tab === key,
+            class: tab === key ? 'active' : '',
+            onclick: () => {
+                tab = key;
+                renderDetail();
+            },
+        }, icon(key === 'permissions' ? 'shield' : 'grid'), key === 'permissions' ? '操作权限' : '数据范围'));
+        details.replaceChildren(summary, h('div', { class: 'role-tabs', role: 'tablist', 'aria-label': '角色配置' }, buttons), body);
+        if (role.status !== 'active')
+            body.append(h('div', { class: 'inline-info' }, icon('lock'), '此角色已停用，当前配置仅供查看。'));
+        if (tab === 'permissions') {
+            const grid = h('div', { class: 'permission-grid' });
+            const filteredCount = h('span', { class: 'muted result-count' });
+            const filters = h('div', { class: 'segmented', 'aria-label': '筛选操作权限' }, ['all', 'granted', 'ungranted'].map((key) => h('button', {
+                class: key === filter ? 'active' : '',
+                'aria-pressed': key === filter,
+                onclick: (event) => {
+                    filter = key;
+                    for (const button of filters.querySelectorAll('button')) {
+                        button.classList.remove('active');
+                        button.setAttribute('aria-pressed', 'false');
+                    }
+                    const button = event.currentTarget;
+                    button.classList.add('active');
+                    button.setAttribute('aria-pressed', 'true');
+                    renderGroups();
+                },
+            }, { all: '全部', granted: '已授权', ungranted: '未授权' }[key])));
+            body.append(h('div', { class: 'permission-toolbar' }, searchInput('搜索业务、操作名称或权限标识', (value) => {
+                query = value;
+                renderGroups();
+            }, query), filters), h('div', { class: 'permission-help' }, h('span', {}, icon('info'), '勾选后即时保存。只能授予你已拥有的权限。'), filteredCount), grid);
+            /**
+             * 根据搜索词和已授权筛选生成能力分组，业务对象排在系统对象之前。
+             * 授权计数来自 role.capabilities，当前显示计数来自筛选集合，两者分别表达不同含义。
+             */
+            function renderGroups() {
+                const granted = new Map(role.capabilities.map((item) => [item.capability, item.params]));
+                const search = query.trim().toLowerCase();
+                const groups = new Map();
+                const visible = state.catalog.capabilities.filter((item) => {
+                    const has = granted.has(item.capability);
+                    return ((filter === 'all' || (filter === 'granted' ? has : !has)) &&
+                        `${item.label} ${item.description ?? ''} ${item.capability} ${item.aggregate ? objectName(item.aggregate) : '系统管理'}`
+                            .toLowerCase()
+                            .includes(search));
+                });
+                for (const capability of visible) {
+                    const key = capability.aggregate ?? 'system';
+                    if (!groups.has(key))
+                        groups.set(key, []);
+                    groups.get(key).push(capability);
+                }
+                grid.replaceChildren();
+                filteredCount.textContent = `显示 ${visible.length} 项权限`;
+                countText.textContent = String(role.capabilities.length);
+                // 客户业务排在前面，框架自带的组织与运维权限放在后面，先回答业务人员最关心的问题。
+                const builtIn = new Set(['Dept', 'User', 'Role', 'system']);
+                const ordered = [...groups].sort(([a], [b]) => Number(builtIn.has(a)) - Number(builtIn.has(b)));
+                for (const [name, capabilities] of ordered) {
+                    const isSystem = name === 'system';
+                    const grantedCount = capabilities.filter((item) => granted.has(item.capability)).length;
+                    const card = h('section', { class: 'permission-card' }, h('div', { class: 'permission-card-heading' }, h('span', { class: `group-icon ${isSystem ? 'system' : ''}` }, icon(isSystem ? 'lock' : 'grid')), h('div', { class: 'group-title' }, h('h3', {}, isSystem ? '系统管理' : objectName(name)), h('code', {}, isSystem ? 'SYSTEM' : name)), h('span', { class: 'group-progress' }, `${grantedCount} / ${capabilities.length}`)));
+                    for (const capability of capabilities)
+                        card.append(permissionRow(capability, granted));
+                    grid.append(card);
+                }
+                if (!visible.length)
+                    grid.append(emptyState('没有找到匹配的权限', '换一个关键词，或调整上方授权筛选。', 'search'));
+            }
+            /**
+             * 构建能力开关及可选额度编辑器，按钮依据角色状态和当前操作者能力启用。
+             * 切换失败恢复旧勾选值，成功更新角色快照；额度保存保留已有参数并替换 ceiling。
+             */
+            function permissionRow(capability, granted) {
+                const checked = granted.has(capability.capability);
+                const authorized = role.status === 'active' &&
+                    can(checked ? 'Role.revokeCapability' : 'Role.grantCapability') &&
+                    (checked || can(capability.capability));
+                const mode = invocation(capability);
+                const toggle = h('input', {
+                    type: 'checkbox',
+                    checked,
+                    disabled: !authorized,
+                    'aria-label': `${checked ? '收回' : '授予'} ${capability.label}`,
+                    onchange: async () => {
+                        toggle.disabled = true;
+                        const updated = await run(() => api('POST', `/api/role/${role.id}/${toggle.checked ? 'grant-capability' : 'revoke-capability'}`, { capability: capability.capability }), toggle.checked ? '操作权限已授予' : '操作权限已收回');
+                        if (updated) {
+                            updateRole(updated);
+                            renderGroups();
+                        }
+                        else {
+                            toggle.checked = checked;
+                            toggle.disabled = !authorized;
+                        }
+                    },
+                });
+                const title = capability.aggregate
+                    ? capability.label.replaceAll(capability.aggregate, objectName(capability.aggregate))
+                    : capability.label;
+                const row = h('div', { class: `permission-row ${checked ? 'granted' : ''}` }, h('label', {
+                    class: 'permission-toggle',
+                    title: !authorized && !checked
+                        ? '你没有该权限，无法授予其他角色'
+                        : capability.kind === 'command'
+                            ? capability.description || title
+                            : title,
+                }, toggle, h('span', { class: 'checkbox-visual' }, icon('check')), h('span', { class: 'permission-copy' }, h('span', { class: 'permission-name' }, title), h('code', {}, capability.capability))), mode &&
+                    h('span', { class: 'invocation-badge', title: '配置此权限后，仍需通过对应流程或外部接口调用' }, mode));
+                if (checked &&
+                    (capability.capability.endsWith('.approve') ||
+                        granted.get(capability.capability)?.ceiling !== undefined)) {
+                    const ceiling = h('input', {
+                        type: 'number',
+                        min: 0,
+                        step: 'any',
+                        placeholder: '请设置额度',
+                        value: String(granted.get(capability.capability)?.ceiling ?? ''),
+                        required: true,
+                        disabled: !can('Role.grantCapability') || !can(capability.capability) || role.status !== 'active',
+                        'aria-label': `${title}额度上限`,
+                    });
+                    const save = h('button', { type: 'submit', class: 'small', disabled: ceiling.disabled }, '保存额度');
+                    row.append(h('form', {
+                        class: 'limit-form',
+                        onsubmit: async (event) => {
+                            event.preventDefault();
+                            const updated = await run(() => api('POST', `/api/role/${role.id}/grant-capability`, {
+                                capability: capability.capability,
+                                params: { ...granted.get(capability.capability), ceiling: Number(ceiling.value) },
+                            }), '额度已保存', save);
+                            if (updated) {
+                                updateRole(updated);
+                                renderGroups();
+                            }
+                        },
+                    }, h('span', {}, '额度上限'), ceiling, save));
+                }
+                return row;
+            }
+            renderGroups();
+        }
+        else {
+            body.append(h('div', { class: 'inline-info' }, icon('info'), '操作权限决定“可以做什么”，数据范围决定“可以看哪些记录”。未单独配置的对象沿用默认范围。'));
+            const scopeGrid = h('div', { class: 'scope-grid' });
+            for (const aggregate of [
+                { name: '*', label: '默认数据范围', scope: { ownerField: null, deptField: null } },
+                ...state.catalog.aggregates,
+            ])
+                scopeGrid.append(scopeCard(aggregate));
+            body.append(scopeGrid);
+        }
+        /**
+         * 构建某聚合的范围编辑卡，区分显式范围、通配继承与未配置时 self。
+         * 可选组合子受聚合 owner/dept 字段约束；deptSet 保留已选 ID，即使当前部门列表无法读取。
+         * 提交 null 删除显式配置，成功后重画详情以反映真实服务端结果。
+         */
+        function scopeCard(aggregate) {
+            const current = role.scopes.find((scope) => scope.aggregate === aggregate.name);
+            const inherited = role.scopes.find((scope) => scope.aggregate === '*');
+            const editable = role.status === 'active' && can('Role.setScope');
+            const usable = state.catalog.combinators.filter((kind) => aggregate.name === '*' ||
+                kind === 'all' ||
+                (kind === 'self' ? aggregate.scope.ownerField : aggregate.scope.deptField));
+            const selected = new Set(current?.deptIds ?? []);
+            const departmentBox = h('div', { class: 'department-options' }, departmentResult.items.map((dept) => h('label', {}, h('input', {
+                type: 'checkbox',
+                checked: selected.has(dept.id),
+                disabled: !editable,
+                onchange: (event) => {
+                    event.currentTarget.checked
+                        ? selected.add(dept.id)
+                        : selected.delete(dept.id);
+                    dirty();
+                },
+            }), dept.name)));
+            if (!departmentResult.items.length)
+                departmentBox.append(h('p', { class: 'muted' }, can('Dept.read') ? '当前没有可选择的部门' : '需要查看部门权限才能调整部门清单，已有选择会保留。'));
+            const status = h('span', { class: 'save-state' }, '已保存');
+            const save = h('button', { class: 'small', type: 'submit', disabled: true }, '保存范围');
+            const description = h('p', { class: 'scope-description' });
+            const select = h('select', {
+                value: current?.combinator ?? '',
+                disabled: !editable,
+                'aria-label': `${aggregate.label}的数据范围`,
+                onchange: () => {
+                    updateDescription();
+                    dirty();
+                },
+            }, h('option', { value: '' }, aggregate.name === '*'
+                ? '未配置（按仅本人处理）'
+                : `沿用默认：${scopes[inherited?.combinator ?? 'self'].title}`), usable.map((kind) => h('option', { value: kind }, scopes[kind].title)));
+            /**
+             * 只标记当前范围表单有未保存变化并启用保存按钮，不立即修改角色快照。
+             */
+            function dirty() {
+                status.textContent = '尚未保存';
+                status.classList.add('pending');
+                save.disabled = !editable;
+            }
+            /**
+             * 解释当前选择或继承后的范围效果；缺所需归属字段时明确无法匹配记录。
+             * 该提示不自动扩大授权，指定部门选择框仅在 deptSet 下显示。
+             */
+            function updateDescription() {
+                const kind = select.value;
+                description.textContent = kind ? scopes[kind].hint : '由默认数据范围决定；默认未配置时按仅本人处理。';
+                const effective = kind || inherited?.combinator || 'self';
+                // 继承允许保留统一默认值，但不能把不适用的范围解释成“可查看本部门”。
+                // 这里只说明真实效果，不修改授权，也不替用户扩大到全部数据。
+                if (aggregate.name !== '*' && effective === 'self' && !aggregate.scope.ownerField)
+                    description.textContent += ' 此对象未设置本人归属，当前范围无法匹配记录。';
+                else if (aggregate.name !== '*' &&
+                    ['dept', 'deptSubtree', 'deptSet'].includes(effective) &&
+                    !aggregate.scope.deptField)
+                    description.textContent += ' 此对象未设置部门归属，当前范围无法匹配记录。';
+                departmentBox.hidden = kind !== 'deptSet';
+            }
+            updateDescription();
+            const form = h('form', {
+                class: `scope-card ${aggregate.name === '*' ? 'default-scope' : ''}`,
+                onsubmit: async (event) => {
+                    event.preventDefault();
+                    const updated = await run(() => api('POST', `/api/role/${role.id}/set-scope`, {
+                        aggregate: aggregate.name,
+                        combinator: select.value || null,
+                        ...(select.value === 'deptSet' ? { deptIds: [...selected] } : {}),
+                    }), '数据范围已保存', save);
+                    if (updated) {
+                        updateRole(updated);
+                        renderDetail();
+                    }
+                },
+            }, h('div', { class: 'scope-heading' }, h('div', {}, h('h3', {}, aggregate.name === '*' ? aggregate.label : objectName(aggregate.name)), h('code', {}, aggregate.name === '*' ? '适用于未单独配置的业务对象' : aggregate.name)), aggregate.name === '*' && badge('默认', 'green')), select, description, departmentBox, h('div', { class: 'scope-footer' }, status, save));
+            return form;
+        }
+    }
+    renderList();
+    renderDetail();
+}

package/ui/dist/modules/tasks/index.js

@@ -0,0 +1,5 @@
+/**
+ * 个人审批待办模块的公开入口。
+ * 应用壳通过这里组合页面，其他模块无需依赖内部表单实现；导出本身不发请求或执行管理操作。
+ */
+export { renderTasks } from './tasks-page.js';

package/ui/dist/modules/tasks/tasks-page.js

@@ -0,0 +1,68 @@
+/**
+ * 当前用户审批待办页面，读取真实任务并通过批准/拒绝接口提交决定。
+ * 待办分配只说明选人，最终动作仍受业务结论命令的能力、范围和硬约束；页面不直接改变单据状态。
+ */
+import { api, run, state } from '../../shared/api.js';
+import { badge, emptyState, formatTime, h, panel, table } from '../../shared/dom.js';
+import { objectName } from '../../shared/labels.js';
+import { navigate } from '../../shared/navigation.js';
+/**
+ * 加载本人待办与页面需要的对象资料，展示任务、步骤和可用操作。
+ * 提交期间禁止重复动作，成功后刷新待办，失败保留可理解原因；空列表表示当前请求没有可见待办。
+ */
+export async function renderTasks(main) {
+    const hasApprovals = state.catalog.approvals.length > 0;
+    if (!hasApprovals) {
+        main.append(panel('我的审批待办', undefined, emptyState('当前没有启用审批流程', '业务启用审批后，分配给你的任务会显示在这里。')));
+        return;
+    }
+    const tasks = await api('GET', '/api/approval/tasks');
+    if (!tasks.length) {
+        main.append(panel('我的审批待办', undefined, emptyState('待办已处理完毕', '新的审批任务分配给你后，会显示在这里。')));
+        return;
+    }
+    main.append(panel('等待你处理', `共 ${tasks.length} 项待办。审批结论会继续执行业务权限与规则校验。`, table([
+        [
+            '审批事项',
+            (task) => h('div', { class: 'stack-cell' }, h('strong', {}, task.title), h('small', {}, state.catalog.approvals.find((item) => item.process === task.process)?.label || '业务审批')),
+        ],
+        [
+            '关联单据',
+            (task) => h('div', { class: 'stack-cell' }, badge(objectName(task.aggregate)), h('code', {}, task.businessKey.slice(0, 8))),
+        ],
+        ['提交时间', (task) => formatTime(task.createdAt)],
+        [
+            '流程信息',
+            (task) => h('details', {}, h('summary', {}, '查看详情'), h('pre', {}, JSON.stringify(task.vars, null, 2))),
+        ],
+        [
+            '处理意见与操作',
+            (task) => {
+                const comment = h('input', {
+                    placeholder: '填写审批意见（可选）',
+                    'aria-label': `${task.title}审批意见`,
+                });
+                const actions = h('div', { class: 'row-actions' });
+                const submit = async (action, button) => {
+                    // 一项待办的两个结论互斥，发送期间同时禁用，避免界面重复提交相反结论。
+                    for (const item of actions.querySelectorAll('button'))
+                        item.disabled = true;
+                    const result = await run(() => api('POST', `/api/approval/tasks/${task.id}/${action}`, { comment: comment.value }), action === 'approve' ? '已通过审批' : '已驳回', button);
+                    if (result)
+                        navigate('tasks');
+                    else
+                        for (const item of actions.querySelectorAll('button'))
+                            item.disabled = false;
+                };
+                actions.append(h('button', {
+                    class: 'small',
+                    onclick: (event) => submit('reject', event.currentTarget),
+                }, '驳回'), h('button', {
+                    class: 'small primary',
+                    onclick: (event) => submit('approve', event.currentTarget),
+                }, '通过审批'));
+                return h('div', { class: 'task-actions' }, comment, actions);
+            },
+        ],
+    ], tasks)));
+}

package/ui/dist/shared/api.js

@@ -0,0 +1,166 @@
+/**
+ * 系统管理浏览器的统一 HTTP、会话状态和操作反馈层。
+ * GET 读取 JSON，POST 自动获取 CSRF 并附幂等键；401 清空会话并通知应用壳，其他失败保留业务原因。
+ * 本模块只消费协议，不导入服务端领域实现；SSE 试聊独立按事件流读取，DOM 输出由调用方负责安全渲染。
+ */
+import { h, icon } from './dom.js';
+/**
+ * 当前页面进程持有的身份、展示目录与 CSRF 令牌缓存，null 表示尚未取得或已清除。
+ * 只用于页面展示与请求头，不作为后端权限判断的事实来源；退出和非登录请求 401 时会清空。
+ */
+export const state = {
+    me: null,
+    catalog: null,
+    csrf: null,
+};
+const errors = {
+    UNAUTHENTICATED: '登录已过期，请重新登录',
+    FORBIDDEN: '你没有执行此操作的权限',
+    NOT_FOUND: '记录不存在或不在你的数据范围内',
+    INVALID_INPUT: '请检查填写内容',
+    INVALID_TRANSITION: '当前状态不允许此操作',
+    CONSTRAINT_VIOLATED: '未满足操作规则',
+    INVARIANT_VIOLATED: '数据未满足业务规则',
+    CONFLICT: '数据已更新，请刷新后重试',
+    DOMAIN_ERROR: '业务规则未满足',
+    RATE_LIMITED: '操作过于频繁，请稍后再试',
+};
+/**
+ * 包含协议 code 的 HTTP 失败异常，message 为页面可显示的中文原因。
+ * 由 checkResponse 创建；网络错误与 JSON 解析错误会以原异常传播，调用方不能假定都是 ApiError。
+ */
+export class ApiError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+/** 系统管理同样使用会话、CSRF 和幂等键，不拥有绕过领域命令的写入通道。 */
+/**
+ * 发送管理接口 JSON 请求，成功返回响应体并按 T 提供静态类型。
+ * POST 在缺少 CSRF 时先取令牌，每次调用生成新的幂等键；这里不自动重试，也不运行响应 schema 校验。
+ * 请求携带同源会话，失败交由 checkResponse 分类；T 只是调用方的类型约定，不能替代服务端验证。
+ */
+export async function api(method, url, body) {
+    const headers = { accept: 'application/json' };
+    if (method === 'POST') {
+        if (!state.csrf) {
+            const response = await fetch('/auth/csrf', { credentials: 'include' });
+            if (!response.ok)
+                throw new Error('无法获取安全令牌，请刷新后重试');
+            state.csrf = (await response.json()).token;
+        }
+        headers['content-type'] = 'application/json';
+        headers['x-csrf-token'] = state.csrf;
+        headers['idempotency-key'] = crypto.randomUUID();
+    }
+    const response = await fetch(url, {
+        method,
+        credentials: 'include',
+        headers,
+        body: method === 'POST' ? JSON.stringify(body ?? {}) : undefined,
+    });
+    const data = await response.json();
+    checkResponse(response, data, url);
+    return data;
+}
+/**
+ * 把非成功 HTTP 响应转换为 ApiError，优先保留业务码、字段级问题或字符串详情。
+ * 非登录接口 401 清空全部会话缓存并广播过期事件；登录失败保留登录页处理流程。
+ * 成功响应不修改状态；服务端未提供已知错误码时使用通用提示。
+ */
+function checkResponse(response, data, url) {
+    if (!response.ok) {
+        if (response.status === 401 && url !== '/auth/login') {
+            state.me = null;
+            state.catalog = null;
+            state.csrf = null;
+            window.dispatchEvent(new Event('cage:session-expired'));
+        }
+        // 参数校验使用 issues 数组。丢弃它会让所有字段错误都退化成“请检查填写内容”。
+        const fields = { baseUrl: 'API 基地址', model: '模型名称', apiKey: 'API Key', apiFormat: '接口协议', contextWindowTokens: '上下文窗口', responsesCompaction: '服务端自动压缩', timeoutMs: '调用超时', label: '显示名称', version: '配置版本', description: '性格描述', avatar: '头像', address: '称呼', examples: '说话示例', defaultKey: '默认性格' };
+        const detail = data.domainCode || data.detail?.message || (Array.isArray(data.detail)
+            ? data.detail.map((issue) => `${fields[issue.path ?? ''] ?? issue.path ?? '参数'}：${issue.message ?? '格式无效'}`).join('；')
+            : typeof data.detail === 'string' ? data.detail : '');
+        const message = `${errors[data.code] ?? '服务暂时无法处理请求'}${detail ? `：${detail}` : ''}`;
+        throw new ApiError(data.code, message);
+    }
+}
+/** 管理预览逐段更新，沿用登录、CSRF 和错误提示；不将模型文本作为 HTML 插入。 */
+/**
+ * 以 POST 发起可取消的 SSE 管理试聊，将完整 data 事件解析为 T 交给 onEvent。
+ * 只在空行分隔处解析 JSON，跨网络分片保留缓冲，未完成缓冲超过上限时拒绝继续积累。
+ * HTTP 错误复用统一处理；缺少事件流响应直接失败。finally 取消 reader 并释放锁，signal 中断不表示已撤销远端处理。
+ */
+export async function postEvents(url, body, onEvent, signal) {
+    if (!state.csrf)
+        state.csrf = (await api('GET', '/auth/csrf')).token;
+    const response = await fetch(url, { method: 'POST', credentials: 'include', signal,
+        headers: { 'content-type': 'application/json', accept: 'text/event-stream', 'x-csrf-token': state.csrf, 'idempotency-key': crypto.randomUUID() }, body: JSON.stringify(body) });
+    if (!response.ok)
+        checkResponse(response, await response.json(), url);
+    if (!response.body || !response.headers.get('content-type')?.includes('text/event-stream'))
+        throw new Error('试聊连接未建立，请重试');
+    const reader = response.body.getReader(), decoder = new TextDecoder();
+    let buffer = '';
+    try {
+        for (;;) {
+            const part = await reader.read();
+            if (part.done)
+                break;
+            buffer += decoder.decode(part.value, { stream: true });
+            if (buffer.length > 1_000_000)
+                throw new Error('试聊返回内容过大');
+            let boundary;
+            while ((boundary = /\r?\n\r?\n/.exec(buffer))) {
+                const block = buffer.slice(0, boundary.index);
+                buffer = buffer.slice(boundary.index + boundary[0].length);
+                const value = block.split(/\r?\n/).filter(line => line.startsWith('data:')).map(line => line.slice(5).trimStart()).join('\n');
+                if (value)
+                    onEvent(JSON.parse(value));
+            }
+        }
+    }
+    finally {
+        await reader.cancel().catch(() => { });
+        reader.releaseLock();
+    }
+}
+/**
+ * 读取当前会话能力列表以控制界面可见性；不考虑对象范围，也不授予后端执行权限。
+ */
+export const can = (capability) => Boolean(state.me?.capabilities.includes(capability));
+/**
+ * 向 notifications 容器追加纯文本操作反馈，5 秒后移除。
+ * failed 决定错误样式与 alert 语义，消息通过 DOM 辅助函数渲染，不解释为 HTML。
+ */
+export function toast(message, failed = false) {
+    const item = h('div', { class: `toast ${failed ? 'error' : 'success'}`, role: failed ? 'alert' : 'status' }, icon(failed ? 'info' : 'check'), message);
+    document.getElementById('notifications').append(item);
+    setTimeout(() => item.remove(), 5000);
+}
+/** 失败会明确显示原因；按钮等待返回，避免界面把未保存的授权显示成成功。 */
+/**
+ * 包装一次页面操作：等待期间禁用按钮，成功可提示文案，失败显示原因并返回 null。
+ * finally 恢复按钮状态；返回值只有实际 action 成功才可用于替换界面数据。
+ * 这里捕获异常供交互反馈，不代表事务补偿或请求重试，调用方应检查返回值后再更新 UI。
+ */
+export async function run(action, success, button) {
+    if (button)
+        button.disabled = true;
+    try {
+        const result = await action();
+        if (success)
+            toast(success);
+        return result;
+    }
+    catch (error) {
+        toast(error instanceof TypeError ? '连接失败，请检查网络与 API 服务' : error.message, true);
+        return null;
+    }
+    finally {
+        if (button)
+            button.disabled = false;
+    }
+}