@yss123/cage-admin 0.2.0 → 0.3.1

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

@@ -1,3 +1,8 @@
+/**
+ * 角色与授权管理界面，区分能力授予、能力参数和对象数据范围。
+ * 页面只按当前登录能力限制可操作项；实际防提权、状态与范围检查由服务端命令执行。
+ * 能力切换即时提交，范围编辑先保留草稿再保存，只有成功响应才更新已保存角色快照。
+ */
 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';
@@ -6,6 +11,10 @@ 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'),
@@ -27,6 +36,9 @@ export async function renderRoles(main) {
     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', {
@@ -43,6 +55,10 @@ export async function renderRoles(main) {
         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', {
@@ -69,6 +85,10 @@ export async function renderRoles(main) {
         const dialog = modal('新建团队角色', form);
         name.focus();
     }
+    /**
+     * 为选中角色重建摘要与选项卡；已停用角色只展示配置。
+     * 局部 updateRole 仅接受服务端成功快照，避免界面把失败请求的临时选择当成已保存授权。
+     */
     function renderDetail() {
         let role = roles.find((item) => item.id === selectedRole);
         if (!role) {
@@ -117,6 +137,10 @@ export async function renderRoles(main) {
                 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();
@@ -151,6 +175,10 @@ export async function renderRoles(main) {
                 if (!visible.length)
                     grid.append(emptyState('没有找到匹配的权限', '换一个关键词，或调整上方授权筛选。', 'search'));
             }
+            /**
+             * 构建能力开关及可选额度编辑器，按钮依据角色状态和当前操作者能力启用。
+             * 切换失败恢复旧勾选值，成功更新角色快照；额度保存保留已有参数并替换 ceiling。
+             */
             function permissionRow(capability, granted) {
                 const checked = granted.has(capability.capability);
                 const authorized = role.status === 'active' &&
@@ -230,6 +258,11 @@ export async function renderRoles(main) {
                 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 === '*');
@@ -265,11 +298,18 @@ export async function renderRoles(main) {
             }, 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 : '由默认数据范围决定；默认未配置时按仅本人处理。';

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

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

package/ui/dist/modules/tasks/operations-pages.js

@@ -0,0 +1,107 @@
+/**
+ * 框架自带的申请催办和站内提醒页面，任何启用审批运营的应用都可从 /admin 直接使用。
+ * 页面仅消费通用审批 HTTP 协议，不依赖业务领域、采购字段或数据库；状态以服务端返回为准。
+ * 过滤保存在 hash 查询参数，写操作完成后刷新当前页；纯文本 DOM 渲染避免把催办原因解释成 HTML。
+ */
+import { api, run, state, toast } 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 function deadlineCell(dueAt) {
+    if (!dueAt)
+        return h('small', {}, '未设时限');
+    const late = Date.parse(dueAt) <= Date.now();
+    return h('div', { class: 'stack-cell' }, badge(late ? '已超时' : '办理中', late ? 'red' : 'neutral'), h('small', {}, formatTime(dueAt)));
+}
+/** 目录显式声明未启用时提供说明并停止加载，不将不存在的接口报错伪装为无提醒。 */
+function enabled(main) {
+    if (state.catalog?.approvalOperations)
+        return true;
+    main.append(panel('流程协作', undefined, emptyState('当前应用未启用流程提醒', '启用后可在此查看站内提醒及本人申请。')));
+    return false;
+}
+/** 使用聚合中文名与完整单据标识，跨业务通用；不猜测应用自定义的详情 URL。 */
+function subject(item) {
+    return h('div', { class: 'stack-cell' }, badge(objectName(item.aggregate)), h('code', { title: item.businessKey }, item.businessKey));
+}
+/** 刷新只重读当前页面；没有后台定时器，离开页面后不会遗留轮询或自动重放催办。 */
+function refresh(page) {
+    return h('button', { class: 'small', onclick: () => navigate(page) }, '刷新');
+}
+/**
+ * 展示本人运行中的可催办申请。提交绑定实例 UUID 和当前步骤，原因必填，防止旧页面催办新轮次。
+ * 冷却期间明确给出下次时间；按钮只是提示，后端仍锁定复核。成功后显示真实接收人数并重新读取。
+ */
+export async function renderApprovalRequests(main) {
+    main.classList.add('approval-workspace');
+    if (!enabled(main))
+        return;
+    const items = await api('GET', '/api/approval/requests');
+    main.append(panel('我的申请', '查看正在审批的申请，向当前办理人发送站内催办。节点时限包含领取、委派和加签所用时间。', h('div', { class: 'table-toolbar' }, h('span', {}, `当前显示 ${items.length} 项`), refresh('requests')), table([
+        ['申请事项', item => subject(item)],
+        ['当前环节', item => h('div', { class: 'stack-cell' }, ...(item.activeSteps?.map(node => h('div', { class: 'stack-cell' }, h('strong', {}, node.title), h('small', {}, node.branchPath.map(part => `${part.parallel} · ${part.branch}`).join(' / ') || '主线审批')))
+                ?? [h('strong', {}, item.title)]))],
+        ['最近截止', item => deadlineCell(item.dueAt)],
+        ['催办', item => {
+                const cooling = !!item.nextUrgeAt && Date.parse(item.nextUrgeAt) > Date.now();
+                const reason = h('input', { 'aria-label': `${item.title}催办原因`, placeholder: '请说明需要加快处理的原因', maxlength: 1000, required: true });
+                const button = h('button', { class: 'small primary', disabled: cooling, onclick: async (event) => {
+                        reason.setCustomValidity(reason.value.trim() ? '' : '请填写催办原因');
+                        if (!reason.reportValidity())
+                            return;
+                        const result = await run(() => api('POST', `/api/approval/instances/${item.id}/urge`, { expectedStep: item.currentStep, ...(item.currentSteps ? { expectedSteps: item.currentSteps } : {}), reason: reason.value.trim() }), undefined, event.currentTarget);
+                        if (result) {
+                            toast(`已发送 ${result.recipientCount} 条站内催办提醒`);
+                            navigate('requests');
+                        }
+                    } }, cooling ? '冷却中' : '发送催办');
+                return h('div', { class: 'task-actions' }, reason, h('div', { class: 'row-actions' }, button), item.nextUrgeAt ? h('small', {}, `可再次催办：${formatTime(item.nextUrgeAt)}${cooling ? '，到时请刷新' : ''}`) : null);
+            }],
+    ], items, '当前没有可催办的运行申请')));
+}
+/**
+ * 分页展示当前仍与本人有关的流程提醒；URL view=unread 固定筛选，可深链接和浏览器前进后退。
+ * 已读写入成功才刷新；翻页沿服务端游标，即使权限过滤形成空页也保留“继续加载”。
+ * 列表读取不自动标已读，离开页面后忽略正在返回的追加页，避免旧页更新当前画面。
+ */
+export async function renderApprovalNotices(main) {
+    main.classList.add('approval-workspace');
+    if (!enabled(main))
+        return;
+    const unread = new URLSearchParams(location.hash.split('?')[1] ?? '').get('view') === 'unread';
+    const page = `notices?view=${unread ? 'unread' : 'all'}`;
+    const query = `/api/approval/notices?limit=50&unreadOnly=${unread}`;
+    const initial = await api('GET', query);
+    const rows = [...initial.items];
+    let next = initial.nextCursor;
+    const content = h('div');
+    const more = h('button', { class: 'small', onclick: async (event) => {
+            if (!next)
+                return;
+            const result = await run(() => api('GET', `${query}&after=${encodeURIComponent(next)}`), undefined, event.currentTarget);
+            if (!result || !content.isConnected)
+                return;
+            rows.push(...result.items);
+            next = result.nextCursor;
+            draw();
+        } }, '继续加载');
+    /** 仅由已完成的读请求重建表格；按钮内容与已读时间始终来自持久状态。 */
+    function draw() {
+        content.replaceChildren(table([
+            ['提醒事项', item => h('div', { class: 'stack-cell' }, badge(item.kind === 'overdue' ? '已超时' : item.kind === 'due_soon' ? '即将到期' : '申请人催办', item.kind === 'overdue' ? 'red' : 'amber'), h('strong', {}, item.title), item.reason ? h('span', {}, item.reason) : h('small', {}, '请及时查看并处理当前审批任务'))],
+            ['关联单据', item => subject(item)],
+            ['节点截止', item => item.dueAt ? formatTime(item.dueAt) : '未设时限'],
+            ['提醒时间', item => formatTime(item.createdAt)],
+            ['阅读状态', item => item.readAt ? h('div', { class: 'stack-cell' }, badge('已读', 'green'), h('small', {}, formatTime(item.readAt))) :
+                    h('button', { class: 'small', onclick: async (event) => {
+                            const result = await run(() => api('POST', `/api/approval/notices/${item.id}/read`), '已标记为已读', event.currentTarget);
+                            if (result)
+                                navigate(page);
+                        } }, '标记已读')],
+        ], rows, unread ? '当前没有可见的未读提醒' : '当前没有可见的流程提醒'));
+        more.hidden = !next;
+    }
+    draw();
+    main.append(panel('流程提醒', '临期、超时与申请人催办集中在这里。提醒只提示办理，不会自动作出审批决定。', h('div', { class: 'table-toolbar' }, h('div', { class: 'row-actions' }, h('a', { class: `approval-filter ${unread ? 'selected' : ''}`, href: '#/notices?view=unread', 'aria-current': unread ? 'page' : undefined }, '未读'), h('a', { class: `approval-filter ${!unread ? 'selected' : ''}`, href: '#/notices?view=all', 'aria-current': !unread ? 'page' : undefined }, '全部'), h('a', { class: 'approval-filter', href: '#/tasks' }, '前往待办')), refresh(page)), content, more));
+}

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

@@ -1,28 +1,45 @@
+/**
+ * 当前用户审批收件箱，合并本人、可领取和等待加签任务；管理动作与决定均通过宿主会话接口提交。
+ * 待办分配只说明选人，最终动作仍受业务结论命令的能力、范围和硬约束；页面不直接改变单据状态。
+ */
 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';
+import { deadlineCell } from './operations-pages.js';
+/**
+ * 加载本人待办与页面需要的对象资料，展示任务、步骤和可用操作。
+ * 提交期间禁止重复动作，成功后刷新待办，失败保留可理解原因；空列表表示当前请求没有可见待办。
+ */
 export async function renderTasks(main) {
+    main.classList.add('approval-workspace');
     const hasApprovals = state.catalog.approvals.length > 0;
     if (!hasApprovals) {
         main.append(panel('我的审批待办', undefined, emptyState('当前没有启用审批流程', '业务启用审批后，分配给你的任务会显示在这里。')));
         return;
     }
-    const tasks = await api('GET', '/api/approval/tasks');
+    const lists = await Promise.all([
+        api('GET', '/api/approval/tasks'), api('GET', '/api/approval/candidate-tasks'),
+        api('GET', '/api/approval/tasks?status=waiting'),
+    ]);
+    const tasks = lists.flat();
     if (!tasks.length) {
         main.append(panel('我的审批待办', undefined, emptyState('待办已处理完毕', '新的审批任务分配给你后，会显示在这里。')));
         return;
     }
-    main.append(panel('等待你处理', `共 ${tasks.length} 项待办。审批结论会继续执行业务权限与规则校验。`, table([
+    main.append(panel('审批收件箱', `待处理 ${lists[0].length} 项 · 可领取 ${lists[1].length} 项 · 等待加签 ${lists[2].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' }, h('strong', {}, task.title), task.branchPath?.length ? h('small', {}, task.branchPath.map(part => `${part.parallel} · ${part.branch}`).join(' / ')) : null, 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 => deadlineCell(task.dueAt)],
+        ['处理阶段', task => badge(task.status === 'waiting' ? '等待加签' : task.assigneeId === null ? '可领取' : task.delegation === 'pending' ? '受托处理中' :
+                task.signPosition === 'before' ? '前签' : task.signPosition === 'after' ? '后签' : task.signPosition === 'parallel' ? '并行加签' : '待处理')],
         [
             '流程信息',
             (task) => h('details', {}, h('summary', {}, '查看详情'), h('pre', {}, JSON.stringify(task.vars, null, 2))),
@@ -30,29 +47,44 @@ export async function renderTasks(main) {
         [
             '处理意见与操作',
             (task) => {
+                if (task.status === 'waiting')
+                    return h('small', {}, '前置签署完成后恢复处理');
                 const comment = h('input', {
-                    placeholder: '填写审批意见（可选）',
+                    placeholder: '审批意见；领取、释放或归还时必填',
                     'aria-label': `${task.title}审批意见`,
+                    maxlength: 1000,
                 });
                 const actions = h('div', { class: 'row-actions' });
                 const submit = async (action, button) => {
+                    const management = ['claim', 'unclaim', 'resolve'].includes(action);
+                    comment.setCustomValidity(management && !comment.value.trim() ? '请填写操作原因' : '');
+                    if (!comment.reportValidity())
+                        return;
                     // 一项待办的两个结论互斥，发送期间同时禁用，避免界面重复提交相反结论。
                     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);
+                    const result = await run(() => api('POST', `/api/approval/tasks/${task.id}/${action}`, { ...(management ? { reason: comment.value } : { comment: comment.value }), expectedRevision: task.revision }), { approve: '已通过审批', reject: '已驳回', claim: '已领取任务', unclaim: '已释放到候选池', resolve: '已归还原审批人' }[action], 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),
-                }, '通过审批'));
+                if (task.assigneeId === null || task.delegation === 'pending') {
+                    const action = task.assigneeId === null ? 'claim' : 'resolve';
+                    actions.append(h('button', { class: 'small primary', onclick: event => submit(action, event.currentTarget) }, action === 'claim' ? '领取任务' : '归还审批人'));
+                }
+                else {
+                    if (task.assignment === 'candidate')
+                        actions.append(h('button', { class: 'small', onclick: event => submit('unclaim', event.currentTarget) }, '释放任务'));
+                    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);
             },
         ],

package/ui/dist/shared/api.js

@@ -1,4 +1,13 @@
+/**
+ * 系统管理浏览器的统一 HTTP、会话状态和操作反馈层。
+ * GET 读取 JSON，POST 自动获取 CSRF 并附幂等键；401 清空会话并通知应用壳，其他失败保留业务原因。
+ * 本模块只消费协议，不导入服务端领域实现；SSE 试聊独立按事件流读取，DOM 输出由调用方负责安全渲染。
+ */
 import { h, icon } from './dom.js';
+/**
+ * 当前页面进程持有的身份、展示目录与 CSRF 令牌缓存，null 表示尚未取得或已清除。
+ * 只用于页面展示与请求头，不作为后端权限判断的事实来源；退出和非登录请求 401 时会清空。
+ */
 export const state = {
     me: null,
     catalog: null,
@@ -16,6 +25,10 @@ const errors = {
     DOMAIN_ERROR: '业务规则未满足',
     RATE_LIMITED: '操作过于频繁，请稍后再试',
 };
+/**
+ * 包含协议 code 的 HTTP 失败异常，message 为页面可显示的中文原因。
+ * 由 checkResponse 创建；网络错误与 JSON 解析错误会以原异常传播，调用方不能假定都是 ApiError。
+ */
 export class ApiError extends Error {
     code;
     constructor(code, message) {
@@ -24,6 +37,11 @@ export class ApiError extends Error {
     }
 }
 /** 系统管理同样使用会话、CSRF 和幂等键，不拥有绕过领域命令的写入通道。 */
+/**
+ * 发送管理接口 JSON 请求，成功返回响应体并按 T 提供静态类型。
+ * POST 在缺少 CSRF 时先取令牌，每次调用生成新的幂等键；这里不自动重试，也不运行响应 schema 校验。
+ * 请求携带同源会话，失败交由 checkResponse 分类；T 只是调用方的类型约定，不能替代服务端验证。
+ */
 export async function api(method, url, body) {
     const headers = { accept: 'application/json' };
     if (method === 'POST') {
@@ -44,6 +62,15 @@ export async function api(method, url, body) {
         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;
@@ -51,19 +78,74 @@ export async function api(method, url, body) {
             state.csrf = null;
             window.dispatchEvent(new Event('cage:session-expired'));
         }
-        const detail = data.domainCode || data.detail?.message || (typeof data.detail === 'string' ? data.detail : '');
+        // 参数校验使用 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);
     }
-    return data;
 }
+/** 管理预览逐段更新，沿用登录、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;

package/ui/dist/shared/dom.js

@@ -1,4 +1,9 @@
 /** 统一用 DOM/textContent 构建界面；业务名称、错误、审计差异不会被当作 HTML 执行。 */
+/**
+ * 创建指定标签并递归追加 children，最后赋属性以保证 select 能匹配已插入的 option。
+ * value/checked 使用 DOM 属性，aria 属性保留字符串语义；事件键去除 on 前缀后注册监听。
+ * 返回对应标签类型的未挂载节点，不做输入业务校验或权限判断。
+ */
 export function h(tag, attrs = {}, ...children) {
     const element = document.createElement(tag);
     const append = (child) => {
@@ -50,6 +55,10 @@ const paths = {
     lock: ['M5 10h14v11H5zM8 10V7a4 4 0 0 1 8 0v3M12 14v3'],
 };
 /** 线条图标是本地 SVG，无字体、CDN 或图片下载依赖。 */
+/**
+ * 从本地 paths 表生成装饰性 SVG，继承 currentColor 并设置 aria-hidden。
+ * name 必须来自已定义图标键；此函数不访问网络或加载外部 SVG。
+ */
 export function icon(name) {
     const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
     for (const [key, value] of Object.entries({
@@ -70,20 +79,43 @@ export function icon(name) {
     }
     return svg;
 }
+/**
+ * 把表单标签、控件和可选提示组合为一个 label，控件状态仍由调用页面维护。
+ */
 export const field = (label, control, hint) => h('label', { class: 'field' }, h('span', {}, label), control, hint && h('small', {}, hint));
+/**
+ * 将存在的时间字符串按浏览器本地时区显示为中文日期时间，null 显示占位符。
+ */
 export const formatTime = (time) => time ? new Date(time).toLocaleString('zh-CN', { hour12: false }) : '—';
+/**
+ * 生成状态徽标，tone 选择既有 CSS 色调；text 作为文本插入，徽标不判断业务终态。
+ */
 export const badge = (text, tone = 'neutral') => h('span', { class: `badge ${tone}` }, text);
+/**
+ * 以列标题与单元格渲染函数构造表格；空行集显示跨列提示。
+ * rows 是调用方已取得的数据，不在这里分页、过滤或请求服务器；单元格仍通过安全 DOM 子项追加。
+ */
 export function table(columns, rows, empty = '暂无记录') {
     return h('div', { class: 'table-wrap' }, h('table', {}, h('thead', {}, h('tr', {}, columns.map(([name]) => h('th', { scope: 'col' }, name)))), h('tbody', {}, rows.length
         ? rows.map((row) => h('tr', {}, columns.map(([, cell]) => h('td', {}, cell(row)))))
         : h('tr', {}, h('td', { colspan: columns.length, class: 'table-empty' }, empty)))));
 }
+/**
+ * 构造含图标、标题和说明的空态块；由调用方区分无记录、无权限和未配置等原因。
+ */
 export function emptyState(title, message, glyph = 'inbox') {
     return h('div', { class: 'empty-state' }, h('span', { class: 'empty-icon' }, icon(glyph)), h('h3', {}, title), h('p', {}, message));
 }
+/**
+ * 组合带标题、可选说明和内容的 section，返回未挂载面板供页面自由布局。
+ */
 export function panel(title, description, ...children) {
     return h('section', { class: 'panel' }, h('div', { class: 'panel-heading' }, h('div', {}, h('h2', {}, title), description && h('p', {}, description))), children);
 }
+/**
+ * 创建搜索输入并将每次 input 的当前值交给 onInput。
+ * 默认不防抖、不请求服务器，调用者决定本地过滤或发起查询。
+ */
 export function searchInput(placeholder, onInput, value = '') {
     const input = h('input', {
         type: 'search',
@@ -94,6 +126,10 @@ export function searchInput(placeholder, onInput, value = '') {
     });
     return h('div', { class: 'search-field' }, icon('search'), input);
 }
+/**
+ * 把原生 dialog 挂到 document.body 并以模态方式打开，返回实例便于提交后关闭。
+ * close 事件只监听一次并移除节点，避免已关闭表单长期留在 DOM；不会替表单提交或保存草稿。
+ */
 export function modal(title, content) {
     const dialog = h('dialog', { class: 'modal' }, h('div', { class: 'modal-heading' }, h('h2', {}, title), h('button', { type: 'button', class: 'icon-button', 'aria-label': '关闭窗口', onclick: () => dialog.close() }, '×')), content);
     dialog.addEventListener('close', () => dialog.remove(), { once: true });

package/ui/dist/shared/labels.js

@@ -1,4 +1,11 @@
+/**
+ * 把目录技术标识映射为系统管理页面的中文展示文字。
+ * 目录由应用启动阶段加载，函数按现有 state.catalog 查找；默认文案只影响显示，不改能力标识、状态或授权规则。
+ */
 import { state } from './api.js';
+/**
+ * 范围组合子的固定名称和说明，供角色范围编辑器复用。实际可见记录仍由聚合字段与服务端授权决定。
+ */
 export const scopes = {
     self: { title: '仅本人', hint: '仅查看归属于自己的记录' },
     dept: { title: '本部门', hint: '查看本人所在部门的记录' },
@@ -6,10 +13,17 @@ export const scopes = {
     deptSet: { title: '指定部门', hint: '仅查看所选部门的记录' },
     all: { title: '全部数据', hint: '查看当前租户内的全部记录' },
 };
+/**
+ * 按聚合标识查找中文 label/description，没有独立中文名时返回通用对象名。
+ */
 export function objectName(name) {
     const object = state.catalog.aggregates.find((item) => item.name === name);
     return object?.label && object.label !== name ? object.label : object?.description || '业务对象';
 }
+/**
+ * 先使用能力目录解释操作名，再处理不属于目录的登录与运维审计动作。
+ * 找不到映射时返回通用名称，原始 capability 仍应保留供诊断。
+ */
 export function capabilityName(capability) {
     const item = state.catalog.capabilities.find((item) => item.capability === capability);
     if (item)
@@ -24,6 +38,9 @@ export function capabilityName(capability) {
     };
     return operations[capability] || '业务操作';
 }
+/**
+ * 为不能由 user 直接调用的命令生成流程来源提示；含 user 或没有调用身份限制时返回空串。
+ */
 export function invocation(capability) {
     if (!capability.invokedBy || capability.invokedBy.includes('user'))
         return '';
@@ -36,6 +53,9 @@ export function invocation(capability) {
     };
     return capability.invokedBy.map((item) => names[item] || '自动流程').join(' / ') + '调用';
 }
+/**
+ * 组织与运行记录的常见状态文案表；展示映射不推断事件已完成或远端调用成功。
+ */
 export const statusNames = {
     active: '已启用',
     disabled: '已停用',
@@ -50,6 +70,15 @@ export const statusNames = {
     dead: '已进入死信',
     retry: '等待重试',
 };
+/**
+ * 返回常见状态的中文说明，未知值显示待确认，避免将新状态误写为成功。
+ */
 export const statusName = (status) => statusNames[status] || '待确认';
+/**
+ * 从项目图谱 labels 查事件中文名，缺配置时只给通用说明。
+ */
 export const eventName = (name) => state.catalog.labels[`event:${name}`] || '业务事件';
+/**
+ * 从当前目录查定时任务展示名；不读取调度执行状态或任务结果。
+ */
 export const jobName = (name) => state.catalog.jobs.find((item) => item.name === name)?.label || '定时任务';

package/ui/dist/shared/navigation.js

@@ -1,4 +1,11 @@
+/**
+ * 管理模块共享的导航意图出口，避免页面反向依赖应用壳。
+ * 改变 hash 触发壳的 hashchange；当前页面再次导航则派发刷新事件重新读取数据。
+ */
 // 事件让模块只发出导航意图，不反向导入应用壳。
+/**
+ * 进入指定管理页面或刷新同一页面。page 是应用壳识别的页面键，不是任意外部 URL。
+ */
 export function navigate(page) {
     if (location.hash !== `#/${page}`)
         location.hash = `#/${page}`;

package/ui/index.html

@@ -1,4 +1,5 @@
 <!doctype html>
+<!-- 系统管理浏览器文档入口。应用脚本挂载到 app，通知层由共享反馈工具管理；页面数据通过认证后的接口加载。 -->
 <html lang="zh-CN">
   <head>
     <meta charset="utf-8" />