feat(P21PWA2-1,P21PWA2-2,P21PWA2-3): 深链路由守卫/离线审批队列/SW缓存策略升级

这个提交包含在:
2026-03-12 12:34:56 +08:00
父节点 102d3dcc2b
当前提交 9112383d23
共修改 10 个文件,包含 975 行新增和 163 行删除
+425 -36
查看文件
@@ -1,5 +1,6 @@
import { useState } from "react";
import { useEffect, useMemo, useRef, useState } from "react";
import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
import { useSearchParams } from "react-router-dom";
import { toast } from "sonner";
import { mapApiErrorMessage } from "../api/errorMessages";
import { isApiError } from "../api/types";
@@ -11,14 +12,29 @@ import {
rejectWorkflowTask,
returnWorkflowTask,
transferWorkflowTask,
type WorkflowTaskDetail,
} from "../api/workflow";
import { useAuth } from "../auth/AuthContext";
import { PageHeader } from "../components/common/PageHeader";
import { Button } from "../components/ui/button";
import { Spinner } from "../components/ui/spinner";
import { Textarea } from "../components/ui/textarea";
import {
cacheWorkflowTaskDetail,
enqueueWorkflowActionDraft,
getCachedWorkflowTaskDetail,
listCachedWorkflowTaskDetails,
listWorkflowActionDrafts,
removeWorkflowActionDraft,
resolveWorkflowTaskReferenceSnapshot,
updateWorkflowActionDraftStatus,
type WorkflowDraftQueueItem,
} from "../mobile/workflowActionQueue";
type MobileAction = "approve" | "reject" | "return" | "transfer";
type ReplayClassification = "failed" | "conflicted";
function entityLabel(entityType: string | undefined) {
if (entityType === "leave") {
return "请假";
@@ -35,53 +51,203 @@ function entityLabel(entityType: string | undefined) {
return entityType || "未知";
}
function resolveErrorMessage(error: unknown) {
if (isApiError(error)) {
return `${error.code}: ${mapApiErrorMessage(error.code, error.details, error.message)}`;
}
if (error instanceof Error) {
return error.message;
}
return "动作执行失败";
}
function classifyReplayError(error: unknown): ReplayClassification {
if (!isApiError(error)) {
return "failed";
}
if (
(error.status === 409 && error.details?.task === "already_processed") ||
error.status === 403 ||
error.status === 404
) {
return "conflicted";
}
return "failed";
}
function queueStatusLabel(status: WorkflowDraftQueueItem["status"]) {
if (status === "queued") {
return "待同步";
}
if (status === "failed") {
return "同步失败";
}
return "存在冲突";
}
function formatDateTime(value: string) {
try {
return new Date(value).toLocaleString("zh-CN");
} catch {
return value;
}
}
export function MobileApprovalsPage() {
const queryClient = useQueryClient();
const [selectedTaskId, setSelectedTaskId] = useState("");
const { me, accessToken, offlineAccessMode } = useAuth();
const [searchParams, setSearchParams] = useSearchParams();
const deepLinkTaskId = searchParams.get("taskId")?.trim() ?? "";
const [selectedTaskId, setSelectedTaskId] = useState(deepLinkTaskId);
const [error, setError] = useState("");
const [message, setMessage] = useState("");
const [comment, setComment] = useState("");
const [transferToApproverId, setTransferToApproverId] = useState("");
const [transferReason, setTransferReason] = useState("");
const [isOnline, setIsOnline] = useState<boolean>(typeof navigator === "undefined" ? true : navigator.onLine);
const autoSyncRequestedRef = useRef(false);
const ownerEmployeeId = me?.id ?? null;
const canUseRemote = isOnline && Boolean(accessToken);
useEffect(() => {
setSelectedTaskId(deepLinkTaskId);
}, [deepLinkTaskId]);
function updateTaskSelection(taskId: string) {
setSelectedTaskId(taskId);
const nextParams = new URLSearchParams(searchParams);
if (taskId) {
nextParams.set("taskId", taskId);
} else {
nextParams.delete("taskId");
}
setSearchParams(nextParams, { replace: true });
}
const tasksQuery = useQuery({
enabled: canUseRemote,
queryKey: ["mobile", "workflow", "tasks"],
queryFn: () => fetchWorkflowTasks({ status: "pending", page: 1, pageSize: 30 }),
});
const detailQuery = useQuery({
enabled: Boolean(selectedTaskId),
enabled: Boolean(selectedTaskId) && canUseRemote,
queryKey: ["mobile", "workflow", "task-detail", selectedTaskId],
queryFn: () => fetchWorkflowTaskDetail(selectedTaskId),
});
const cachedTasksQuery = useQuery({
enabled: Boolean(ownerEmployeeId),
queryKey: ["mobile", "workflow", "task-cache", ownerEmployeeId],
queryFn: () => listCachedWorkflowTaskDetails(ownerEmployeeId),
});
const cachedDetailQuery = useQuery({
enabled: Boolean(selectedTaskId) && Boolean(ownerEmployeeId),
queryKey: ["mobile", "workflow", "task-cache", ownerEmployeeId, selectedTaskId],
queryFn: () => getCachedWorkflowTaskDetail(selectedTaskId, ownerEmployeeId),
});
const queueQuery = useQuery({
enabled: Boolean(ownerEmployeeId),
queryKey: ["mobile", "workflow", "draft-queue", ownerEmployeeId],
queryFn: () => listWorkflowActionDrafts(ownerEmployeeId),
});
useEffect(() => {
if (!detailQuery.data || !ownerEmployeeId) {
return;
}
void cacheWorkflowTaskDetail(detailQuery.data, ownerEmployeeId).then(async () => {
await Promise.all([
queryClient.invalidateQueries({ queryKey: ["mobile", "workflow", "task-cache", ownerEmployeeId] }),
queryClient.invalidateQueries({ queryKey: ["mobile", "workflow", "task-cache", ownerEmployeeId, detailQuery.data?.task.id] }),
]);
});
}, [detailQuery.data, ownerEmployeeId, queryClient]);
const selectedTask = useMemo<WorkflowTaskDetail | null>(() => {
if (detailQuery.data) {
return detailQuery.data;
}
if (!canUseRemote) {
return cachedDetailQuery.data?.detail ?? null;
}
return null;
}, [cachedDetailQuery.data?.detail, canUseRemote, detailQuery.data]);
const canTransfer =
canUseRemote &&
selectedTask?.workflowInstance?.entityType === "reimbursement" &&
selectedTask.allowedActions.includes("transfer");
const approversQuery = useQuery({
enabled: detailQuery.data?.allowedActions?.includes("transfer") ?? false,
enabled: Boolean(canTransfer),
queryKey: ["mobile", "workflow", "approvers"],
queryFn: () => fetchWorkflowApprovers({ page: 1, pageSize: 100 }),
});
const currentQueueItems = queueQuery.data ?? [];
const retryableQueueItems = useMemo(
() => currentQueueItems.filter((item) => item.status !== "conflicted"),
[currentQueueItems],
);
const actionMutation = useMutation({
mutationFn: async (action: MobileAction) => {
if (!selectedTaskId) {
throw new Error("请选择任务");
}
if (!selectedTask) {
throw new Error("当前待办尚未缓存,请联网加载后再操作");
}
if (!selectedTask.allowedActions.includes(action)) {
throw new Error("当前待办不允许该动作");
}
if (!canUseRemote) {
if (action === "return" || action === "transfer") {
throw new Error("离线仅支持通过 / 驳回草稿,退回与转审需联网执行");
}
if (action === "reject" && !comment.trim()) {
throw new Error("驳回必须填写意见");
}
await enqueueWorkflowActionDraft({
taskId: selectedTaskId,
action,
comment: action === "reject" ? comment.trim() : null,
ownerEmployeeId,
detail: selectedTask,
});
return { mode: "queued" as const, action };
}
if (action === "approve") {
return approveWorkflowTask(selectedTaskId);
await approveWorkflowTask(selectedTaskId);
return { mode: "submitted" as const, action };
}
if (action === "reject") {
if (!comment.trim()) {
throw new Error("驳回必须填写意见");
}
return rejectWorkflowTask(selectedTaskId, comment.trim());
await rejectWorkflowTask(selectedTaskId, comment.trim());
return { mode: "submitted" as const, action };
}
if (action === "return") {
if (!comment.trim()) {
throw new Error("退回必须填写意见");
}
return returnWorkflowTask(selectedTaskId, comment.trim());
await returnWorkflowTask(selectedTaskId, comment.trim());
return { mode: "submitted" as const, action };
}
if (!transferToApproverId) {
@@ -91,65 +257,195 @@ export function MobileApprovalsPage() {
throw new Error("转审理由至少 10 个字");
}
return transferWorkflowTask(selectedTaskId, transferToApproverId, transferReason.trim());
await transferWorkflowTask(selectedTaskId, transferToApproverId, transferReason.trim());
return { mode: "submitted" as const, action };
},
onSuccess: async () => {
onSuccess: async (result) => {
if (result.mode === "queued") {
await queryClient.invalidateQueries({ queryKey: ["mobile", "workflow", "draft-queue", ownerEmployeeId] });
setError("");
setMessage(result.action === "approve" ? "当前离线,通过草稿已加入待同步队列。" : "当前离线,驳回草稿已加入待同步队列。");
toast.success(result.action === "approve" ? "已加入通过草稿队列" : "已加入驳回草稿队列");
return;
}
await Promise.all([
queryClient.invalidateQueries({ queryKey: ["mobile", "workflow", "tasks"] }),
queryClient.invalidateQueries({ queryKey: ["mobile", "workflow", "task-detail", selectedTaskId] }),
queryClient.invalidateQueries({ queryKey: ["mobile", "workflow", "task-cache", ownerEmployeeId] }),
]);
setComment("");
setTransferReason("");
setTransferToApproverId("");
setError("");
setMessage("");
toast.success("操作成功");
},
onError: (err) => {
const msg = isApiError(err) ? `${err.code}: ${mapApiErrorMessage(err.code, err.details, err.message)}` : err instanceof Error ? err.message : "动作执行失败";
setError(msg);
toast.error(msg);
onError: (actionError) => {
const nextError = resolveErrorMessage(actionError);
setError(nextError);
setMessage("");
toast.error(nextError);
},
});
const syncMutation = useMutation({
mutationFn: async (items: WorkflowDraftQueueItem[]) => {
let succeeded = 0;
let failed = 0;
let conflicted = 0;
for (const item of items.sort((a, b) => a.updatedAt.localeCompare(b.updatedAt))) {
try {
if (item.action === "approve") {
await approveWorkflowTask(item.taskId);
} else {
await rejectWorkflowTask(item.taskId, item.comment ?? "");
}
await removeWorkflowActionDraft(item.taskId, ownerEmployeeId);
succeeded += 1;
} catch (syncError) {
const classification = classifyReplayError(syncError);
const lastError = resolveErrorMessage(syncError);
await updateWorkflowActionDraftStatus({
taskId: item.taskId,
ownerEmployeeId,
status: classification,
lastError,
});
if (classification === "conflicted") {
conflicted += 1;
} else {
failed += 1;
}
}
}
return { succeeded, failed, conflicted };
},
onSuccess: async (result) => {
await Promise.all([
queryClient.invalidateQueries({ queryKey: ["mobile", "workflow", "draft-queue", ownerEmployeeId] }),
queryClient.invalidateQueries({ queryKey: ["mobile", "workflow", "tasks"] }),
queryClient.invalidateQueries({ queryKey: ["mobile", "workflow", "task-detail", selectedTaskId] }),
]);
setError("");
setMessage(`草稿同步完成:成功 ${result.succeeded},失败 ${result.failed},冲突 ${result.conflicted}`);
if (result.succeeded || result.failed || result.conflicted) {
toast.success(`草稿同步完成:成功 ${result.succeeded},失败 ${result.failed},冲突 ${result.conflicted}`);
}
},
onError: (syncError) => {
const nextError = resolveErrorMessage(syncError);
setError(nextError);
setMessage("");
toast.error(nextError);
},
});
useEffect(() => {
const onOnline = () => {
setIsOnline(true);
autoSyncRequestedRef.current = true;
};
const onOffline = () => {
setIsOnline(false);
};
window.addEventListener("online", onOnline);
window.addEventListener("offline", onOffline);
return () => {
window.removeEventListener("online", onOnline);
window.removeEventListener("offline", onOffline);
};
}, []);
useEffect(() => {
if (!autoSyncRequestedRef.current || !canUseRemote || syncMutation.isPending) {
return;
}
autoSyncRequestedRef.current = false;
if (retryableQueueItems.length) {
syncMutation.mutate(retryableQueueItems);
}
}, [canUseRemote, retryableQueueItems, syncMutation]);
const pendingTasks = tasksQuery.data?.items ?? [];
const selectedTask = detailQuery.data;
const canTransfer =
selectedTask?.workflowInstance?.entityType === "reimbursement" &&
selectedTask.allowedActions.includes("transfer");
const cachedTasks = cachedTasksQuery.data ?? [];
const visibleTaskCards = canUseRemote
? pendingTasks.map((task) => ({
id: task.id,
title: task.stepName,
subtitle: `业务:${entityLabel(task.workflowInstance?.entityType)}`,
status: task.status,
}))
: cachedTasks.map((item) => ({
id: item.detail.task.id,
title: item.taskSnapshot.stepName ?? item.detail.task.stepName,
subtitle: `业务:${entityLabel(item.taskSnapshot.entityType ?? item.detail.workflowInstance?.entityType)} · 缓存于 ${formatDateTime(item.savedAt)}`,
status: item.detail.task.status,
}));
const selectedReference = selectedTask ? resolveWorkflowTaskReferenceSnapshot(selectedTask) : null;
const isOfflineUncachedDeepLink = Boolean(selectedTaskId) && !selectedTask && !canUseRemote;
return (
<div className="space-y-4">
<PageHeader title="移动审批" subtitle="小屏快速处理待办任务。" />
<PageHeader
title="移动审批"
subtitle={deepLinkTaskId ? `深链待办:${deepLinkTaskId}` : "小屏快速处理待办任务,支持离线草稿与联网重放。"}
/>
{!isOnline ? (
<p className="rounded-lg border border-orange-200 bg-orange-50 px-3 py-2 text-sm text-orange-700">
当前离线{offlineAccessMode ? ",已使用本地会话快照进入移动审批壳。" : "。"}仅支持查看已缓存待办,并起草通过 / 驳回草稿。
</p>
) : null}
{error ? (
<p className="rounded-lg border border-red-200 bg-red-50 px-3 py-2 text-sm text-red-600">{error}</p>
) : null}
{message ? (
<p className="rounded-lg border border-emerald-200 bg-emerald-50 px-3 py-2 text-sm text-emerald-700">{message}</p>
) : null}
<div className="card-std space-y-3 p-4" data-testid="mobile-approvals-list">
<h3 className="text-base font-semibold text-zinc-900">待办任务</h3>
<div className="flex items-center justify-between gap-3">
<h3 className="text-base font-semibold text-zinc-900">待办任务</h3>
<span className={`text-sm ${isOnline ? "text-emerald-600" : "text-orange-600"}`}>{isOnline ? "在线" : "离线"}</span>
</div>
{tasksQuery.isLoading ? <div className="flex items-center gap-2 text-sm text-zinc-500"><Spinner size="sm" />加载中...</div> : null}
{canUseRemote && tasksQuery.isLoading ? (
<div className="flex items-center gap-2 text-sm text-zinc-500"><Spinner size="sm" />加载中...</div>
) : null}
{!tasksQuery.isLoading && pendingTasks.length === 0 ? (
<p className="text-sm text-zinc-500">暂无待办任务。</p>
{!canUseRemote ? (
<p className="text-sm text-zinc-500">离线状态下展示已缓存待办;若未缓存任务详情,可通过深链任务号联网后重试。</p>
) : null}
{!visibleTaskCards.length ? (
<p className="text-sm text-zinc-500">{canUseRemote ? "暂无待办任务。" : "暂无已缓存待办。"}</p>
) : null}
<div className="space-y-2">
{pendingTasks.map((task) => (
{visibleTaskCards.map((task) => (
<button
key={task.id}
className={`w-full rounded-lg border px-3 py-2 text-left text-sm ${
selectedTaskId === task.id
? "border-primary bg-primary-50 text-primary"
: "border-zinc-200 bg-white text-zinc-800"
selectedTaskId === task.id ? "border-primary bg-primary-50 text-primary" : "border-zinc-200 bg-white text-zinc-800"
}`}
data-testid={`mobile-approvals-task-${task.id}`}
onClick={() => setSelectedTaskId(task.id)}
onClick={() => updateTaskSelection(task.id)}
type="button"
>
<div className="font-medium">{task.stepName}</div>
<div className="font-medium">{task.title}</div>
<div className="text-xs text-zinc-500">任务ID: {task.id}</div>
<div className="text-xs text-zinc-500">业务: {entityLabel(task.workflowInstance?.entityType)}</div>
<div className="text-xs text-zinc-500">{task.subtitle}</div>
<div className="text-xs text-zinc-500">状态:{task.status}</div>
</button>
))}
</div>
@@ -160,16 +456,27 @@ export function MobileApprovalsPage() {
{!selectedTaskId ? <p className="text-sm text-zinc-500">请先选择任务。</p> : null}
{selectedTaskId && detailQuery.isLoading ? (
{selectedTaskId && canUseRemote && detailQuery.isLoading ? (
<p className="text-sm text-zinc-500">加载任务详情中...</p>
) : null}
{selectedTask && (
{selectedTaskId && canUseRemote && detailQuery.isError ? (
<p className="rounded-lg border border-red-200 bg-red-50 px-3 py-2 text-sm text-red-600">{resolveErrorMessage(detailQuery.error)}</p>
) : null}
{isOfflineUncachedDeepLink ? (
<p className="rounded-lg border border-orange-200 bg-orange-50 px-3 py-2 text-sm text-orange-700">
离线未缓存该待办,请联网后重试。任务号:{selectedTaskId}
</p>
) : null}
{selectedTask ? (
<>
<div className="rounded-lg border border-zinc-200 p-3 text-sm">
<div>任务状态:{selectedTask.task.status}</div>
<div>步骤:{selectedTask.task.stepName}</div>
<div>对象类型:{entityLabel(selectedTask.workflowInstance?.entityType)}</div>
<div>业务参考:{selectedReference?.reference ?? "-"}</div>
{selectedTask.reimbursement ? (
<>
<div>报销单号:{selectedTask.reimbursement.formNumber ?? "-"}</div>
@@ -205,11 +512,15 @@ export function MobileApprovalsPage() {
<Textarea
data-testid="mobile-approvals-comment"
onChange={(event) => setComment(event.target.value)}
placeholder="驳回/退回意见"
placeholder="驳回 / 退回意见;离线仅支持驳回意见入队。"
rows={3}
value={comment}
/>
{!canUseRemote ? (
<p className="text-xs text-zinc-500">离线状态下仅支持通过 / 驳回草稿,退回与转审需联网执行。</p>
) : null}
<div className="flex flex-wrap gap-2">
<Button
data-testid="mobile-approvals-approve"
@@ -217,7 +528,7 @@ export function MobileApprovalsPage() {
onClick={() => actionMutation.mutate("approve")}
type="button"
>
通过
{canUseRemote ? "通过" : "离线加入通过草稿"}
</Button>
<Button
data-testid="mobile-approvals-reject"
@@ -226,11 +537,11 @@ export function MobileApprovalsPage() {
type="button"
variant="secondary"
>
驳回
{canUseRemote ? "驳回" : "离线加入驳回草稿"}
</Button>
<Button
data-testid="mobile-approvals-return"
disabled={actionMutation.isPending || !selectedTask.allowedActions.includes("return")}
disabled={actionMutation.isPending || !canUseRemote || !selectedTask.allowedActions.includes("return")}
onClick={() => actionMutation.mutate("return")}
type="button"
variant="secondary"
@@ -276,7 +587,85 @@ export function MobileApprovalsPage() {
</div>
) : null}
</>
)}
) : null}
</div>
<div className="card-std space-y-3 p-4" data-testid="mobile-approvals-queue">
<div className="flex items-center justify-between gap-3">
<h3 className="text-base font-semibold text-zinc-900">离线审批草稿队列</h3>
<span className="text-sm text-zinc-500">{currentQueueItems.length ? `待处理 ${currentQueueItems.length} 项` : "无待处理项"}</span>
</div>
{currentQueueItems.length ? (
<div className="flex flex-wrap gap-2">
<Button
data-testid="mobile-approvals-sync-queue"
disabled={!canUseRemote || syncMutation.isPending || !retryableQueueItems.length}
onClick={() => syncMutation.mutate(retryableQueueItems)}
type="button"
variant="secondary"
>
{syncMutation.isPending ? "同步中..." : `同步草稿队列 (${retryableQueueItems.length})`}
</Button>
</div>
) : null}
{!currentQueueItems.length ? <p className="text-sm text-zinc-500">暂无待同步审批草稿。</p> : null}
{currentQueueItems.map((item) => (
<div key={item.id} className="rounded-lg border border-zinc-200 px-3 py-3 text-sm">
<div className="font-medium text-zinc-900">
{item.taskSnapshot.reference ?? item.taskId} · {item.action === "approve" ? "通过" : "驳回"}
</div>
<div className="text-zinc-500">业务:{entityLabel(item.taskSnapshot.entityType ?? undefined)} · 步骤:{item.taskSnapshot.stepName ?? "-"}</div>
<div className="text-zinc-500">状态:{queueStatusLabel(item.status)} · 更新时间:{formatDateTime(item.updatedAt)}</div>
<div className="text-zinc-500">意见:{item.comment ?? "-"}</div>
<div className="text-zinc-500">最近错误:{item.lastError ?? "-"}</div>
<div className="mt-2 flex flex-wrap gap-2">
<Button
type="button"
size="sm"
variant="secondary"
onClick={() => updateTaskSelection(item.taskId)}
>
查看任务
</Button>
{item.status === "failed" ? (
<Button
type="button"
size="sm"
variant="secondary"
disabled={syncMutation.isPending}
onClick={async () => {
await updateWorkflowActionDraftStatus({
taskId: item.taskId,
ownerEmployeeId,
status: "queued",
lastError: null,
});
await queryClient.invalidateQueries({ queryKey: ["mobile", "workflow", "draft-queue", ownerEmployeeId] });
if (canUseRemote) {
syncMutation.mutate([{ ...item, status: "queued", lastError: null }]);
}
}}
>
重试
</Button>
) : null}
<Button
type="button"
size="sm"
variant="secondary"
onClick={async () => {
await removeWorkflowActionDraft(item.taskId, ownerEmployeeId);
await queryClient.invalidateQueries({ queryKey: ["mobile", "workflow", "draft-queue", ownerEmployeeId] });
}}
>
丢弃草稿
</Button>
</div>
</div>
))}
</div>
</div>
);