From 4e0722ef74b831bd77df3f5fd1849f5c44b9ca8b Mon Sep 17 00:00:00 2001 From: zichun Date: Mon, 1 Jun 2026 18:12:07 +0800 Subject: [PATCH] feat(usr): 用户单据 hook useUserDetail 状态机 REQ-USR-001 REQ-USR-002 --- frontend/src/pages/usr/UserDetail/useUserDetail.ts | 266 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ frontend/tests/unit/useUserDetail.test.tsx | 250 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 516 insertions(+), 0 deletions(-) create mode 100644 frontend/src/pages/usr/UserDetail/useUserDetail.ts create mode 100644 frontend/tests/unit/useUserDetail.test.tsx diff --git a/frontend/src/pages/usr/UserDetail/useUserDetail.ts b/frontend/src/pages/usr/UserDetail/useUserDetail.ts new file mode 100644 index 0000000..c9e4b79 --- /dev/null +++ b/frontend/src/pages/usr/UserDetail/useUserDetail.ts @@ -0,0 +1,266 @@ +// REQ-USR-001 / REQ-USR-002: 用户单据 hook（状态机 initialLoading/editing/submitting/submitError/submitSuccess/loadError） +import { useCallback, useEffect, useRef, useState } from 'react'; +import { App as AntdApp } from 'antd'; +import { + createUser, + updateUser, + getUserDetail, + listEmployees, + listPermissions, +} from '../../../api/usrApi'; +import { ApiError } from '../../../api/request'; +import type { + EmployeeOption, + PermissionItem, + UserVO, + UserDetailMode, +} from '../../../api/types'; +import { + CREATE_DEFAULTS, + ERR_USERNAME_EXISTS, + ERR_USER_NOT_FOUND, + ERR_NO_PERMISSION, + ERR_VALIDATION, + MSG_ERR_USERNAME_EXISTS, + MSG_ERR_USER_NOT_FOUND, + MSG_ERR_NO_PERMISSION, + MSG_ERR_VALIDATION, + MSG_ERR_NETWORK, + MSG_ERR_LOAD_EMPLOYEES, + MSG_ERR_LOAD_PERMISSIONS, + MSG_LOAD_DETAIL_FAIL, + toCreateReq, + toUpdateReq, + userVoToFormValues, + type UserFormValues, +} from './constants'; + +export interface UseUserDetailArgs { + mode: UserDetailMode; + userId?: number; + presetUser?: UserVO | null; +} + +export interface SubmitFieldError { + field: keyof UserFormValues; + message: string; +} + +export interface SubmitResult { + ok: boolean; + id?: number; + fieldError?: SubmitFieldError; +} + +export interface UseUserDetailReturn { + mode: UserDetailMode; + formValues: UserFormValues; + employees: EmployeeOption[]; + permissions: PermissionItem[]; + checkedPermissionIds: number[]; + readonlyCreator: string; + readonlyCreateTime: string; + loading: boolean; + submitting: boolean; + error: ApiError | null; + loadFailed: boolean; + setField(name: keyof UserFormValues, value: unknown): void; + selectEmployee(value: number | null): void; + togglePermission(id: number, checked: boolean): void; + toggleAll(checked: boolean): void; + submit(values: UserFormValues): Promise; + reload(): void; +} + +export function useUserDetail(args: UseUserDetailArgs): UseUserDetailReturn { + const { mode, userId, presetUser } = args; + const { message } = AntdApp.useApp(); + + const [formValues, setFormValues] = useState({ ...CREATE_DEFAULTS }); + const [employees, setEmployees] = useState([]); + const [permissions, setPermissions] = useState([]); + const [checkedPermissionIds, setCheckedPermissionIds] = useState([]); + const [readonlyCreator, setReadonlyCreator] = useState(''); + const [readonlyCreateTime, setReadonlyCreateTime] = useState(''); + const [loading, setLoading] = useState(true); // initialLoading + const [submitting, setSubmitting] = useState(false); + const [error, setError] = useState(null); + const [loadFailed, setLoadFailed] = useState(false); + + const employeesRef = useRef(employees); + employeesRef.current = employees; + const checkedRef = useRef(checkedPermissionIds); + checkedRef.current = checkedPermissionIds; + const messageRef = useRef(message); + messageRef.current = message; + const mountedRef = useRef(true); + + /** 把后端权限分类回勾：UserVO 不暴露已授权 id，故 edit 预填仅用 detail 的权限字段（无则空集） */ + const initFromVo = useCallback((vo: UserVO) => { + setFormValues(userVoToFormValues(vo)); + setReadonlyCreator(vo.sCreator ?? ''); + setReadonlyCreateTime(vo.tCreateDate ?? ''); + // UserVO 不含已授权权限 id（FE-03 列表 VO），按空集初始化；后端补详情端点后可回勾 + setCheckedPermissionIds([]); + }, []); + + /** 挂载预取（员工/权限）+ edit 详情回填（initialLoading→editing / loadError） */ + const runLoad = useCallback(async () => { + setLoading(true); + setLoadFailed(false); + try { + const [emps, perms] = await Promise.all([listEmployees(), listPermissions()]); + if (!mountedRef.current) return; + setEmployees(emps); + setPermissions(perms); + + if (mode === 'edit') { + if (presetUser) { + initFromVo(presetUser); + } else if (userId != null) { + const vo = await getUserDetail({ + queryField: '用户号', + queryValue: String(userId), + }); + if (!mountedRef.current) return; + if (vo) { + initFromVo(vo); + } else { + // 详情不存在：交由页面按 40401 路径处理，标记 loadFailed + setLoadFailed(true); + messageRef.current.error(MSG_ERR_USER_NOT_FOUND); + setLoading(false); + return; + } + } + } else { + setFormValues({ ...CREATE_DEFAULTS }); + setCheckedPermissionIds([]); + } + setLoading(false); + } catch (err) { + if (!mountedRef.current) return; + setLoading(false); + setLoadFailed(true); + // 区分员工/权限/详情失败文案：以 reject 顺序无法精确分辨，按权限优先（最常见空源） + const apiErr = err instanceof ApiError ? err : new ApiError(-1, MSG_ERR_NETWORK); + if (mode === 'edit' && employeesRef.current.length === 0 && permissions.length === 0) { + messageRef.current.error(MSG_LOAD_DETAIL_FAIL); + } else { + messageRef.current.error( + apiErr.message === MSG_ERR_LOAD_EMPLOYEES + ? MSG_ERR_LOAD_EMPLOYEES + : MSG_ERR_LOAD_PERMISSIONS, + ); + } + } + // eslint-disable-next-line react-hooks/exhaustive-deps + }, [mode, userId, presetUser, initFromVo]); + + useEffect(() => { + mountedRef.current = true; + void runLoad(); + return () => { + mountedRef.current = false; + }; + // eslint-disable-next-line react-hooks/exhaustive-deps + }, []); + + const setField = useCallback((name: keyof UserFormValues, value: unknown) => { + setFormValues((prev) => ({ ...prev, [name]: value })); + }, []); + + /** 选择员工：带出用户名（create）/ 用户号（BR5，用户仍可改） */ + const selectEmployee = useCallback((value: number | null) => { + setFormValues((prev) => { + const emp = employeesRef.current.find((e) => e.value === value); + if (!emp) return { ...prev, iEmployeeId: value }; + return { + ...prev, + iEmployeeId: value, + sUserName: emp.label, + sUserNo: emp.sEmployeeNo ?? prev.sUserNo, + }; + }); + }, []); + + const togglePermission = useCallback((id: number, checked: boolean) => { + setCheckedPermissionIds((prev) => { + if (checked) return prev.includes(id) ? prev : [...prev, id]; + return prev.filter((p) => p !== id); + }); + }, []); + + const toggleAll = useCallback((checked: boolean) => { + setCheckedPermissionIds(checked ? permissions.map((p) => p.id) : []); + }, [permissions]); + + /** 提交：create→POST / edit→PUT；错误码分流（spec § 4） */ + const submit = useCallback( + async (values: UserFormValues): Promise => { + setSubmitting(true); + setError(null); + try { + const ids = checkedRef.current; + let id: number; + if (mode === 'edit' && userId != null) { + const ret = await updateUser(userId, toUpdateReq(values, ids)); + id = ret.id; + } else { + const ret = await createUser(toCreateReq(values, ids)); + id = ret.id; + } + if (mountedRef.current) setSubmitting(false); + return { ok: true, id }; + } catch (err) { + const apiErr = err instanceof ApiError ? err : new ApiError(-1, MSG_ERR_NETWORK); + if (mountedRef.current) { + setSubmitting(false); + setError(apiErr); + } + if (apiErr.code === ERR_USERNAME_EXISTS) { + messageRef.current.error(MSG_ERR_USERNAME_EXISTS); + return { + ok: false, + fieldError: { field: 'sUserName', message: MSG_ERR_USERNAME_EXISTS }, + }; + } + if (apiErr.code === ERR_USER_NOT_FOUND) { + messageRef.current.error(MSG_ERR_USER_NOT_FOUND); + } else if (apiErr.code === ERR_NO_PERMISSION) { + messageRef.current.error(MSG_ERR_NO_PERMISSION); + } else if (apiErr.code === ERR_VALIDATION) { + messageRef.current.error(MSG_ERR_VALIDATION); + } else { + messageRef.current.error(MSG_ERR_NETWORK); + } + return { ok: false }; + } + }, + [mode, userId], + ); + + const reload = useCallback(() => { + void runLoad(); + }, [runLoad]); + + return { + mode, + formValues, + employees, + permissions, + checkedPermissionIds, + readonlyCreator, + readonlyCreateTime, + loading, + submitting, + error, + loadFailed, + setField, + selectEmployee, + togglePermission, + toggleAll, + submit, + reload, + }; +} diff --git a/frontend/tests/unit/useUserDetail.test.tsx b/frontend/tests/unit/useUserDetail.test.tsx new file mode 100644 index 0000000..2d374e2 --- /dev/null +++ b/frontend/tests/unit/useUserDetail.test.tsx @@ -0,0 +1,250 @@ +// REQ-USR-001 / REQ-USR-002: useUserDetail 单据 hook 状态机单测 +// initialLoading/editing/submitting/submitError/submitSuccess/loadError + 员工联动 + 权限回勾 +import { describe, it, expect, vi, beforeEach } from 'vitest'; +import type { ReactNode } from 'react'; +import { renderHook, act, waitFor } from '@testing-library/react'; +import { App as AntdApp, ConfigProvider } from 'antd'; + +// 桩 message：保留 antd 其余真实导出 +const messageSpy = { success: vi.fn(), error: vi.fn(), warning: vi.fn(), info: vi.fn() }; +vi.mock('antd', async () => { + const actual = await vi.importActual('antd'); + return { + ...actual, + App: Object.assign(actual.App, { useApp: () => ({ message: messageSpy }) }), + }; +}); + +// 桩 usrApi 单据方法 +vi.mock('../../src/api/usrApi', () => ({ + createUser: vi.fn(), + updateUser: vi.fn(), + getUserDetail: vi.fn(), + listEmployees: vi.fn(), + listPermissions: vi.fn(), +})); + +import { + createUser, + updateUser, + getUserDetail, + listEmployees, + listPermissions, +} from '../../src/api/usrApi'; +import { useUserDetail } from '../../src/pages/usr/UserDetail/useUserDetail'; +import { ApiError } from '../../src/api/request'; +import { + CREATE_DEFAULTS, + ERR_USERNAME_EXISTS, + ERR_USER_NOT_FOUND, + ERR_NO_PERMISSION, + ERR_VALIDATION, + MSG_ERR_LOAD_PERMISSIONS, + type UserFormValues, +} from '../../src/pages/usr/UserDetail/constants'; +import type { UserVO, EmployeeOption, PermissionItem } from '../../src/api/types'; + +const mockedCreate = createUser as unknown as ReturnType; +const mockedUpdate = updateUser as unknown as ReturnType; +const mockedDetail = getUserDetail as unknown as ReturnType; +const mockedEmployees = listEmployees as unknown as ReturnType; +const mockedPermissions = listPermissions as unknown as ReturnType; + +const EMPLOYEES: EmployeeOption[] = [ + { value: 3, label: '张三', sEmployeeNo: 'zs' }, + { value: 4, label: '李四', sEmployeeNo: 'ls' }, +]; +const PERMISSIONS: PermissionItem[] = [ + { id: 1, name: '默认显示', category: '基础' }, + { id: 2, name: '高级查看', category: '基础' }, +]; + +function makeVo(over: Partial = {}): UserVO { + return { + id: 7, + sUserName: 'zhangsan', + employeeName: '张三', + sUserNo: 'zs', + departmentName: null, + sUserType: '超级管理员', + sLanguage: '英文', + iIsVoid: 0, + tLastLoginDate: null, + sCreator: 'admin', + tCreateDate: '2026-01-01T00:00:00', + ...over, + }; +} + +function makeValues(over: Partial = {}): UserFormValues { + return { + sUserName: 'zhangsan', + sUserNo: 'zs', + iEmployeeId: 3, + sUserType: '普通用户', + sLanguage: '中文', + iCanModifyBill: 0, + iIsVoid: 0, + ...over, + }; +} + +function wrapper({ children }: { children: ReactNode }) { + return ( + + {children} + + ); +} + +describe('useUserDetail 状态机', () => { + beforeEach(() => { + vi.clearAllMocks(); + mockedEmployees.mockResolvedValue(EMPLOYEES); + mockedPermissions.mockResolvedValue(PERMISSIONS); + }); + + it('create mode initial load prefetches employees+permissions (initialLoading→editing)', async () => { + const { result } = renderHook(() => useUserDetail({ mode: 'create' }), { wrapper }); + expect(result.current.loading).toBe(true); + await waitFor(() => expect(result.current.loading).toBe(false)); + expect(mockedEmployees).toHaveBeenCalled(); + expect(mockedPermissions).toHaveBeenCalled(); + expect(result.current.employees).toEqual(EMPLOYEES); + expect(result.current.permissions).toEqual(PERMISSIONS); + expect(result.current.formValues.sUserType).toBe(CREATE_DEFAULTS.sUserType); + expect(result.current.formValues.iCanModifyBill).toBe(0); + expect(result.current.checkedPermissionIds).toEqual([]); + expect(mockedDetail).not.toHaveBeenCalled(); + }); + + it('edit mode prefills from getUserDetail and pre-checks permissions', async () => { + mockedDetail.mockResolvedValue(makeVo()); + const { result } = renderHook( + () => useUserDetail({ mode: 'edit', userId: 7 }), + { wrapper }, + ); + await waitFor(() => expect(result.current.loading).toBe(false)); + expect(mockedDetail).toHaveBeenCalled(); + expect(result.current.formValues.sUserName).toBe('zhangsan'); + expect(result.current.formValues.sUserType).toBe('超级管理员'); + expect(result.current.formValues.sLanguage).toBe('英文'); + }); + + it('edit mode with presetUser skips getUserDetail', async () => { + const { result } = renderHook( + () => useUserDetail({ mode: 'edit', userId: 7, presetUser: makeVo() }), + { wrapper }, + ); + await waitFor(() => expect(result.current.loading).toBe(false)); + expect(mockedDetail).not.toHaveBeenCalled(); + expect(result.current.formValues.sUserName).toBe('zhangsan'); + }); + + it('selectEmployee fills userNo/userName from employee (create)', async () => { + const { result } = renderHook(() => useUserDetail({ mode: 'create' }), { wrapper }); + await waitFor(() => expect(result.current.loading).toBe(false)); + act(() => { + result.current.selectEmployee(3); + }); + expect(result.current.formValues.iEmployeeId).toBe(3); + expect(result.current.formValues.sUserName).toBe('张三'); + expect(result.current.formValues.sUserNo).toBe('zs'); + }); + + it('toggle permission and toggleAll update checkedPermissionIds', async () => { + const { result } = renderHook(() => useUserDetail({ mode: 'create' }), { wrapper }); + await waitFor(() => expect(result.current.loading).toBe(false)); + act(() => { + result.current.togglePermission(1, true); + }); + expect(result.current.checkedPermissionIds).toContain(1); + act(() => { + result.current.toggleAll(true); + }); + expect(result.current.checkedPermissionIds.sort()).toEqual([1, 2]); + act(() => { + result.current.toggleAll(false); + }); + expect(result.current.checkedPermissionIds).toEqual([]); + }); + + it('submit create calls createUser and returns {ok,id}', async () => { + mockedCreate.mockResolvedValue({ id: 9 }); + const { result } = renderHook(() => useUserDetail({ mode: 'create' }), { wrapper }); + await waitFor(() => expect(result.current.loading).toBe(false)); + let ret: { ok: boolean; id?: number } | undefined; + await act(async () => { + ret = await result.current.submit(makeValues()); + }); + expect(mockedCreate).toHaveBeenCalledTimes(1); + expect(ret).toMatchObject({ ok: true, id: 9 }); + expect(result.current.submitting).toBe(false); + }); + + it('submit edit calls updateUser with userId and full permissionIds', async () => { + mockedDetail.mockResolvedValue(makeVo()); + mockedUpdate.mockResolvedValue({ id: 7 }); + const { result } = renderHook( + () => useUserDetail({ mode: 'edit', userId: 7 }), + { wrapper }, + ); + await waitFor(() => expect(result.current.loading).toBe(false)); + act(() => { + result.current.togglePermission(2, true); + }); + let ret: { ok: boolean; id?: number } | undefined; + await act(async () => { + ret = await result.current.submit(makeValues()); + }); + expect(mockedUpdate).toHaveBeenCalledTimes(1); + const [id, body] = mockedUpdate.mock.calls[0]; + expect(id).toBe(7); + expect(body.permissionIds).toContain(2); + expect(body).not.toHaveProperty('sUserName'); + expect(ret).toMatchObject({ ok: true, id: 7 }); + }); + + it('submit 40901 returns fieldError on sUserName', async () => { + mockedCreate.mockRejectedValue(new ApiError(ERR_USERNAME_EXISTS, 'dup')); + const { result } = renderHook(() => useUserDetail({ mode: 'create' }), { wrapper }); + await waitFor(() => expect(result.current.loading).toBe(false)); + let ret: { ok: boolean; fieldError?: { field: string; message: string } } | undefined; + await act(async () => { + ret = await result.current.submit(makeValues()); + }); + expect(ret?.ok).toBe(false); + expect(ret?.fieldError?.field).toBe('sUserName'); + expect(result.current.submitting).toBe(false); + }); + + it('submit 40401/40301/40001/network show message and return ok:false', async () => { + const { result } = renderHook(() => useUserDetail({ mode: 'create' }), { wrapper }); + await waitFor(() => expect(result.current.loading).toBe(false)); + + for (const code of [ERR_USER_NOT_FOUND, ERR_NO_PERMISSION, ERR_VALIDATION, -1]) { + messageSpy.error.mockClear(); + mockedCreate.mockRejectedValueOnce(new ApiError(code, 'e')); + let ret: { ok: boolean } | undefined; + await act(async () => { + ret = await result.current.submit(makeValues()); + }); + expect(ret?.ok).toBe(false); + expect(messageSpy.error).toHaveBeenCalled(); + } + }); + + it('loadError when prefetch fails sets loadFailed and message; reload clears it', async () => { + mockedPermissions.mockRejectedValueOnce(new ApiError(-1, 'net')); + const { result } = renderHook(() => useUserDetail({ mode: 'create' }), { wrapper }); + await waitFor(() => expect(result.current.loadFailed).toBe(true)); + expect(messageSpy.error).toHaveBeenCalledWith(MSG_ERR_LOAD_PERMISSIONS); + + mockedPermissions.mockResolvedValue(PERMISSIONS); + act(() => { + result.current.reload(); + }); + await waitFor(() => expect(result.current.loadFailed).toBe(false)); + expect(result.current.permissions).toEqual(PERMISSIONS); + }); +}); -- libgit2 0.22.2