feat(usr): 用户单据 API 与类型契约 create/update/detail/employees/permissions REQ-USR-001 REQ-USR-002

zichun
1 parent 3545663a
Showing 3 changed files with 262 additions and 0 deletions
frontend/src/api/types.ts
frontend/src/api/usrApi.ts
frontend/tests/unit/usrApi.userdetail.test.ts
@@ -67,3 +67,56 @@ export interface UserListQuery {
   pageNum: number;
   pageSize: number;
 }
+
+// === REQ-USR-001 / REQ-USR-002 用户单据契约（FE-04） ===
+
+/** 单据模式：新增 / 修改（由路由 :id 判定，spec § 3） */
+export type UserDetailMode = 'create' | 'edit';
+
+/**
+ * 员工名下拉项（D1）。后端 GET /api/usr/employees 原始行
+ * `iIncrement`/`sEmployeeName`/`sEmployeeNo` 在 api 层归一为此结构。
+ */
+export interface EmployeeOption {
+  value: number;
+  label: string;
+  sEmployeeNo: string | null;
+}
+
+/**
+ * 权限项（D2/D3）。后端 GET /api/usr/permissions 原始行
+ * `iIncrement`/`sPermissionName`/`sPermissionCategory` 在 api 层归一为此结构。
+ */
+export interface PermissionItem {
+  id: number;
+  name: string;
+  category: string;
+}
+
+/**
+ * POST /api/usr/users 请求体（create，对齐 docs/05 § REQ-USR-001）。
+ * 密码 `initialPassword` 前端不传，由后端默认 666666（BR9）。
+ */
+export interface UserCreateReq {
+  sUserName: string;
+  sUserNo?: string;
+  iEmployeeId?: number | null;
+  sUserType: string;
+  sLanguage: string;
+  iCanModifyBill?: 0 | 1;
+  permissionIds?: number[];
+}
+
+/**
+ * PUT /api/usr/users/{id} 请求体（edit，对齐 docs/05 § REQ-USR-002）。
+ * `sUserName` 不可改不传、密码不在本接口（BR3/BR9）；`permissionIds` 全量覆盖（BR11）。
+ */
+export interface UserUpdateReq {
+  sUserNo?: string;
+  iEmployeeId?: number | null;
+  sUserType: string;
+  sLanguage: string;
+  iCanModifyBill?: 0 | 1;
+  iIsVoid?: 0 | 1;
+  permissionIds?: number[];
+}
 // REQ-USR-004: USR 模块 API 封装（登录 + 版本下拉取数）。页面只调本文件，不散用 axios。
 // REQ-USR-003: 新增用户列表分页查询 listUsers（GET /api/usr/users，中文键归一 D-PLAN-2）。
+// REQ-USR-001 / REQ-USR-002: 用户单据写/读封装（create/update/detail/employees/permissions，D1/D2/D4）。
 import request from './request';
 import type {
   LoginPayload,
@@ -8,6 +9,10 @@ import type {
   UserVO,
   PageResult,
   UserListQuery,
+  UserCreateReq,
+  UserUpdateReq,
+  EmployeeOption,
+  PermissionItem,
 } from './types';
 // 响应拦截器已拆 Result.data，故此处返回类型即业务数据本体。
@@ -82,3 +87,71 @@ export async function listUsers(query: UserListQuery): Promise&lt;PageResult&lt;UserVO
     pageSize: page.pageSize,
   };
 }
+
+// === REQ-USR-001 / REQ-USR-002 用户单据写/读封装（FE-04） ===
+
+/** POST /api/usr/users —— 新增用户（body 不含密码/审计字段，BR9），返回新建主键 id */
+export function createUser(body: UserCreateReq): Promise<{ id: number }> {
+  return request.post('/usr/users', body) as unknown as Promise<{ id: number }>;
+}
+
+/** PUT /api/usr/users/{id} —— 修改用户（body 不含 sUserName，BR3；permissionIds 全量覆盖，BR11） */
+export function updateUser(id: number, body: UserUpdateReq): Promise<{ id: number }> {
+  return request.put('/usr/users/' + id, body) as unknown as Promise<{ id: number }>;
+}
+
+/**
+ * edit 预填：复用 GET /api/usr/users 列表端点（「等于」匹配 + pageSize=1）定位单条（D4）。
+ * 复用 listUsers 的中文键归一，返回 records[0] ?? null。
+ */
+export async function getUserDetail(params: {
+  queryField: string;
+  queryValue: string;
+}): Promise<UserVO | null> {
+  const page = await listUsers({
+    queryField: params.queryField,
+    matchType: '等于',
+    queryValue: params.queryValue,
+    pageNum: 1,
+    pageSize: 1,
+  });
+  return page.records[0] ?? null;
+}
+
+/** 后端原始员工行（GET /api/usr/employees，D1） */
+interface RawEmployeeRecord {
+  iIncrement: number;
+  sEmployeeName: string;
+  sEmployeeNo: string | null;
+}
+
+/** GET /api/usr/employees —— 员工名下拉数据源，归一为 EmployeeOption（D1） */
+export async function listEmployees(): Promise<EmployeeOption[]> {
+  const rows = (await (request.get('/usr/employees') as unknown as Promise<
+    RawEmployeeRecord[]
+  >)) ?? [];
+  return rows.map((r) => ({
+    value: r.iIncrement,
+    label: r.sEmployeeName,
+    sEmployeeNo: r.sEmployeeNo ?? null,
+  }));
+}
+
+/** 后端原始权限行（GET /api/usr/permissions，D2/D3） */
+interface RawPermissionRecord {
+  iIncrement: number;
+  sPermissionName: string;
+  sPermissionCategory: string;
+}
+
+/** GET /api/usr/permissions —— 权限分类列表数据源，归一为 PermissionItem（D2/D3） */
+export async function listPermissions(): Promise<PermissionItem[]> {
+  const rows = (await (request.get('/usr/permissions') as unknown as Promise<
+    RawPermissionRecord[]
+  >)) ?? [];
+  return rows.map((r) => ({
+    id: r.iIncrement,
+    name: r.sPermissionName,
+    category: r.sPermissionCategory,
+  }));
+}
+// REQ-USR-001 / REQ-USR-002: 用户单据 API 封装单测
+// createUser / updateUser / getUserDetail / listEmployees / listPermissions 透传与归一（D1/D2/D4）
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+// 桩底层 axios 实例（request.ts 的 default 导出），沿用 usrApi.userlist.test.ts 模式
+vi.mock('../../src/api/request', () => {
+  return {
+    default: {
+      post: vi.fn(),
+      put: vi.fn(),
+      get: vi.fn(),
+    },
+  };
+});
+
+import request from '../../src/api/request';
+import {
+  createUser,
+  updateUser,
+  getUserDetail,
+  listEmployees,
+  listPermissions,
+} from '../../src/api/usrApi';
+
+const mockedRequest = request as unknown as {
+  post: ReturnType<typeof vi.fn>;
+  put: ReturnType<typeof vi.fn>;
+  get: ReturnType<typeof vi.fn>;
+};
+
+describe('usrApi 用户单据封装', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('createUser posts /usr/users with body (no password/creator/createDate)', async () => {
+    mockedRequest.post.mockResolvedValue({ id: 9 });
+    const body = {
+      sUserName: 'zhangsan',
+      sUserNo: 'zs',
+      iEmployeeId: 3,
+      sUserType: '普通用户',
+      sLanguage: '中文',
+      iCanModifyBill: 0 as const,
+      permissionIds: [1, 2],
+    };
+    const ret = await createUser(body);
+    expect(mockedRequest.post).toHaveBeenCalledTimes(1);
+    const [url, payload] = mockedRequest.post.mock.calls[0];
+    expect(url).toBe('/usr/users');
+    expect(payload).toEqual(body);
+    expect(payload).not.toHaveProperty('initialPassword');
+    expect(payload).not.toHaveProperty('sCreator');
+    expect(payload).not.toHaveProperty('tCreateDate');
+    expect(ret).toEqual({ id: 9 });
+  });
+
+  it('updateUser puts /usr/users/{id} with body (no sUserName)', async () => {
+    mockedRequest.put.mockResolvedValue({ id: 7 });
+    const body = {
+      sUserType: '超级管理员',
+      sLanguage: '英文',
+      iCanModifyBill: 1 as const,
+      iIsVoid: 0 as const,
+      permissionIds: [2],
+    };
+    const ret = await updateUser(7, body);
+    expect(mockedRequest.put).toHaveBeenCalledTimes(1);
+    const [url, payload] = mockedRequest.put.mock.calls[0];
+    expect(url).toBe('/usr/users/7');
+    expect(payload).toEqual(body);
+    expect(payload).not.toHaveProperty('sUserName');
+    expect(ret).toEqual({ id: 7 });
+  });
+
+  it('getUserDetail queries equals match pageSize 1 and returns records[0]', async () => {
+    mockedRequest.get.mockResolvedValue({
+      records: [
+        {
+          id: 7,
+          sUserName: 'zhangsan',
+          员工名: '张三',
+          sUserNo: 'zs',
+          部门: null,
+          sUserType: '普通用户',
+          sLanguage: '中文',
+          iIsVoid: 0,
+          tLastLoginDate: null,
+          sCreator: 'admin',
+          tCreateDate: '2026-01-01T00:00:00',
+        },
+      ],
+      total: 1,
+      pageNum: 1,
+      pageSize: 1,
+    });
+    const ret = await getUserDetail({ queryField: '用户名', queryValue: 'zhangsan' });
+    expect(mockedRequest.get).toHaveBeenCalledTimes(1);
+    const [url, config] = mockedRequest.get.mock.calls[0];
+    expect(url).toBe('/usr/users');
+    expect(config.params).toMatchObject({
+      queryField: '用户名',
+      matchType: '等于',
+      queryValue: 'zhangsan',
+      pageNum: 1,
+      pageSize: 1,
+    });
+    expect(ret).not.toBeNull();
+    expect(ret!.id).toBe(7);
+    expect(ret!.employeeName).toBe('张三');
+  });
+
+  it('getUserDetail returns null when records empty', async () => {
+    mockedRequest.get.mockResolvedValue({ records: [], total: 0, pageNum: 1, pageSize: 1 });
+    const ret = await getUserDetail({ queryField: '用户名', queryValue: 'none' });
+    expect(ret).toBeNull();
+  });
+
+  it('listEmployees normalizes iIncrement/sEmployeeName/sEmployeeNo to EmployeeOption', async () => {
+    mockedRequest.get.mockResolvedValue([
+      { iIncrement: 3, sEmployeeName: '张三', sEmployeeNo: 'zs' },
+    ]);
+    const ret = await listEmployees();
+    expect(mockedRequest.get).toHaveBeenCalledWith('/usr/employees');
+    expect(ret).toEqual([{ value: 3, label: '张三', sEmployeeNo: 'zs' }]);
+  });
+
+  it('listPermissions normalizes to PermissionItem', async () => {
+    mockedRequest.get.mockResolvedValue([
+      { iIncrement: 1, sPermissionName: '默认显示', sPermissionCategory: '基础' },
+    ]);
+    const ret = await listPermissions();
+    expect(mockedRequest.get).toHaveBeenCalledWith('/usr/permissions');
+    expect(ret).toEqual([{ id: 1, name: '默认显示', category: '基础' }]);
+  });
+});