hikvision-cli 1.0.0

package/src/commands/person.ts

@@ -0,0 +1,596 @@
+/**
+ * 人员管理命令
+ */
+
+import { Command } from 'commander';
+import * as fs from 'fs';
+import * as path from 'path';
+import { config } from '../utils/config';
+import { success, error, info, formatOutput } from '../utils/output';
+import { createHikvisionClient } from '../services/hikvisionClient';
+
+export const personCommands = new Command()
+  .command('person')
+  .description('人员管理');
+
+// 新增人员
+personCommands
+  .command('add')
+  .description('新增人员')
+  .option('-n, --name <name>', '姓名')
+  .option('-p, --phone <phone>', '手机号')
+  .option('-i, --id-card <idCard>', '身份证号')
+  .option('-o, --org <orgIndexCode>', '组织 ID')
+  .option('-on, --org-path <orgPath>', '组织路径（如：保洁 或 外部人员/保安保洁/保洁）')
+  .option('-g, --gender <gender>', '性别 (1:男, 2:女)', '1')
+  .option('-e, --email <email>', '邮箱')
+  .option('-c, --card-no <cardNo>', '卡号')
+  .option('-j, --job-no <jobNo>', '工号')
+  .option('-ph, --photo <photoPath>', '照片文件路径（支持 jpg/png），添加人员时同步上传')
+  .action(async (options) => {
+    try {
+      const client = createHikvisionClient(config.get());
+      
+      // 解析组织路径
+      let orgIndexCode = options.org;
+      if (options.orgPath && !orgIndexCode) {
+        orgIndexCode = await findOrgByPath(client, options.orgPath);
+        if (!orgIndexCode) {
+          error(`未找到匹配的组织路径：${options.orgPath}`);
+          return;
+        }
+        info(`已匹配到组织：${options.orgPath} → ${orgIndexCode}`);
+      }
+      
+      if (!orgIndexCode) {
+        error('请指定组织 ID (-o) 或组织路径 (-on)');
+        return;
+      }
+      
+      // 读取照片（如果有）
+      let faces: { faceData: string }[] | undefined;
+      if (options.photo) {
+        const faceData = await loadPhotoBase64(options.photo);
+        faces = [{ faceData }];
+        info(`已读取照片：${options.photo}`);
+      }
+
+      const result = await client.personService.create({
+        personName: options.name,
+        phoneNo: options.phone,
+        idCardNo: options.idCard,
+        orgIndexCode,
+        gender: options.gender as '1' | '2',
+        email: options.email,
+        cardNo: options.cardNo,
+        jobNo: options.jobNo,
+        faces,
+      });
+
+      success(`人员添加成功！`);
+      console.log(formatOutput(result));
+    } catch (err: any) {
+      error(`添加人员失败：${err.message || err}`);
+    }
+  });
+
+// 查询人员列表
+personCommands
+  .command('list')
+  .description('查询人员列表')
+  .option('-p, --page <page>', '页码', '1')
+  .option('-s, --size <size>', '每页数量', '20')
+  .option('-n, --name <name>', '姓名搜索')
+  .option('-ph, --phone <phone>', '手机号搜索')
+  .option('-id, --id-card <idCard>', '身份证号搜索')
+  .option('-o, --org <orgIndexCode>', '组织 ID')
+  .option('-on, --org-name <orgName>', '组织名称（模糊搜索）')
+  .option('-g, --gender <gender>', '性别 (1:男, 2:女)')
+  .action(async (options) => {
+    try {
+      const client = createHikvisionClient(config.get());
+      
+      // 如果指定了组织名称，需要先查找到 orgIndexCode
+      let orgIndexCode = options.org;
+      if (options.orgName && !orgIndexCode) {
+        const orgs = await client.personService.getOrganizations();
+        const found = orgs.find(o => o.orgName === options.orgName);
+        if (found) {
+          orgIndexCode = found.orgIndexCode;
+        } else {
+          error(`未找到名为 "${options.orgName}" 的组织`);
+          return;
+        }
+      }
+      
+      const result = await client.personService.list({
+        pageNo: parseInt(options.page),
+        pageSize: parseInt(options.size),
+        personName: options.name,
+        phoneNo: options.phone,
+        idCardNo: options.idCard,
+        orgIndexCode: orgIndexCode,
+        gender: options.gender as '1' | '2',
+      });
+      
+      console.log(formatOutput(result));
+    } catch (err: any) {
+      error(`查询人员失败：${err.message || err}`);
+    }
+  });
+
+// 查询人员详情
+personCommands
+  .command('get')
+  .description('查询人员详情')
+  .argument('[personId]', '人员 ID')
+  .option('-i, --id <personId>', '人员 ID')
+  .option('-n, --name <name>', '姓名')
+  .option('-o, --org <orgIndexCode>', '组织 ID')
+  .option('-on, --org-name <orgName>', '组织名称')
+  .action(async (personId, options) => {
+    try {
+      const client = createHikvisionClient(config.get());
+      
+      let targetId = personId || options.id;
+      
+      // 如果没有提供 ID，通过名称+组织查找
+      if (!targetId && (options.name || options.orgName)) {
+        targetId = await findPersonId(client, options);
+      }
+      
+      if (!targetId) {
+        error('请提供人员 ID，或使用 --name 和 --org/--org-name 指定人员');
+        return;
+      }
+      
+      const result = await client.personService.getById(targetId);
+      console.log(formatOutput(result));
+    } catch (err: any) {
+      error(`查询人员详情失败：${err.message || err}`);
+    }
+  });
+
+// 修改人员
+personCommands
+  .command('update')
+  .description('修改人员')
+  .argument('[personId]', '人员 ID')
+  .option('-n, --name <name>', '姓名')
+  .option('-p, --phone <phone>', '手机号')
+  .option('-i, --id-card <idCard>', '身份证号')
+  .option('-o, --org <orgIndexCode>', '组织 ID')
+  .option('-on, --org-name <orgName>', '组织名称')
+  .option('-g, --gender <gender>', '性别 (1:男, 2:女)')
+  .option('-s, --status <status>', '状态 (0:正常, 1:禁用, 2:离职)')
+  .option('-j, --job-no <jobNo>', '工号')
+  .action(async (personId, options) => {
+    try {
+      const client = createHikvisionClient(config.get());
+      
+      let targetId = personId;
+      
+      // 如果没有提供 ID，通过名称+组织查找
+      if (!targetId && (options.name || options.orgName)) {
+        targetId = await findPersonId(client, { name: options.name, orgIndexCode: options.org, orgName: options.orgName });
+      }
+      
+      if (!targetId) {
+        error('请提供人员 ID，或使用 --name 和 --org/--org-name 指定人员');
+        return;
+      }
+      
+      await client.personService.update(targetId, {
+        personName: options.name,
+        phoneNo: options.phone,
+        idCardNo: options.idCard,
+        orgIndexCode: options.org,
+        gender: options.gender as '1' | '2',
+        status: options.status as '0' | '1' | '2',
+        jobNo: options.jobNo,
+      });
+      
+      success('人员信息已更新');
+    } catch (err: any) {
+      error(`修改人员失败：${err.message || err}`);
+    }
+  });
+
+// 删除人员
+personCommands
+  .command('delete')
+  .description('删除人员')
+  .argument('[personId]', '人员 ID')
+  .option('-n, --name <name>', '姓名')
+  .option('-o, --org <orgIndexCode>', '组织 ID')
+  .option('-on, --org-name <orgName>', '组织名称')
+  .action(async (personId, options) => {
+    try {
+      const client = createHikvisionClient(config.get());
+      
+      let targetId = personId;
+      
+      // 如果没有提供 ID，通过名称+组织查找
+      if (!targetId && (options.name || options.orgName)) {
+        targetId = await findPersonId(client, { name: options.name, orgIndexCode: options.org, orgName: options.orgName });
+      }
+      
+      if (!targetId) {
+        error('请提供人员 ID，或使用 --name 和 --org/--org-name 指定人员');
+        return;
+      }
+      
+      await client.personService.delete(targetId);
+      
+      success('人员已删除');
+    } catch (err: any) {
+      error(`删除人员失败：${err.message || err}`);
+    }
+  });
+
+// 获取组织列表
+personCommands
+  .command('orgs')
+  .description('获取组织列表')
+  .option('-n, --name <name>', '按名称筛选（模糊匹配）')
+  .action(async (options) => {
+    try {
+      const client = createHikvisionClient(config.get());
+
+      const result = await client.personService.getOrganizations();
+
+      // 如果指定了名称，筛选结果
+      if (options.name) {
+        const filtered = result.filter(o => o.orgName.includes(options.name));
+        console.log(formatOutput(filtered));
+      } else {
+        console.log(formatOutput(result));
+      }
+    } catch (err: any) {
+      error(`获取组织列表失败：${err.message || err}`);
+    }
+  });
+
+// 更新人员照片
+personCommands
+  .command('update-photo')
+  .description('更新人员照片')
+  .argument('[personId]', '人员 ID')
+  .option('-i, --id <personId>', '人员 ID')
+  .option('-n, --name <name>', '姓名')
+  .option('-o, --org <orgIndexCode>', '组织 ID')
+  .option('-on, --org-name <orgName>', '组织名称')
+  .option('-f, --file <filePath>', '照片文件路径（支持 jpg/png/jpeg）')
+  .action(async (personId, options) => {
+    try {
+      const client = createHikvisionClient(config.get());
+
+      // 查找人员
+      let targetId = personId || options.id;
+      if (!targetId && (options.name || options.orgName)) {
+        targetId = await findPersonId(client, {
+          name: options.name,
+          orgIndexCode: options.org,
+          orgName: options.orgName,
+        });
+      }
+
+      if (!targetId) {
+        error('请提供人员 ID，或使用 --name 和 --org/--org-name 指定人员');
+        return;
+      }
+
+      if (!options.file) {
+        error('请提供照片文件路径 (-f/--file)');
+        return;
+      }
+
+      // 读取照片并转为 base64
+      const faceData = await loadPhotoBase64(options.file);
+
+      // 直接尝试添加人脸，海康每人仅限1张，有旧照时 addFace 会报"Already Has Face"
+      try {
+        const result = await client.personService.addFace(targetId, faceData);
+        success(`人员照片已添加（faceId: ${result.faceId}）`);
+      } catch (err: any) {
+        if (err.message?.includes('Already Has Face') || err.message?.includes('already')) {
+          error(`该人员已有照片，每人仅限1张。如需更新，请先删除旧照后再添加。`);
+        } else if (err.message?.includes('Picture Size')) {
+          error(`照片尺寸不合要求，建议：①确保照片中人脸区域清晰可见 ②裁剪图片使脸部占比更大 ③使用标准 JPEG/PNG 格式`);
+        } else {
+          error(`添加照片失败：${err.message || err}`);
+        }
+      }
+    } catch (err: any) {
+      error(`更新照片失败：${err.message || err}`);
+    }
+  });
+
+// 添加人员照片（与 update-photo 相同逻辑）
+personCommands
+  .command('add-photo')
+  .description('为人员添加照片（无照片时添加，有照片时替换）')
+  .argument('[personId]', '人员 ID')
+  .option('-i, --id <personId>', '人员 ID')
+  .option('-n, --name <name>', '姓名')
+  .option('-o, --org <orgIndexCode>', '组织 ID')
+  .option('-on, --org-name <orgName>', '组织名称')
+  .option('-f, --file <filePath>', '照片文件路径（支持 jpg/png/jpeg）')
+  .action(async (personId, options) => {
+    // 复用 update-photo 的逻辑
+    const client = createHikvisionClient(config.get());
+
+    let targetId = personId || options.id;
+    if (!targetId && (options.name || options.orgName)) {
+      targetId = await findPersonId(client, {
+        name: options.name,
+        orgIndexCode: options.org,
+        orgName: options.orgName,
+      });
+    }
+
+    if (!targetId) {
+      error('请提供人员 ID，或使用 --name 和 --org/--org-name 指定人员');
+      return;
+    }
+
+    if (!options.file) {
+      error('请提供照片文件路径 (-f/--file)');
+      return;
+    }
+
+    try {
+      const faceData = await loadPhotoBase64(options.file);
+
+      // 直接添加人脸，有旧照时报"Already Has Face"
+      try {
+        const result = await client.personService.addFace(targetId, faceData);
+        success(`人员照片已添加（faceId: ${result.faceId}）`);
+      } catch (err: any) {
+        if (err.message?.includes('Already Has Face') || err.message?.includes('already')) {
+          error(`该人员已有照片，每人仅限1张。如需更新，请先删除旧照后再添加。`);
+        } else if (err.message?.includes('Picture Size')) {
+          error(`照片尺寸不合要求，建议：①确保照片中人脸区域清晰可见 ②裁剪图片使脸部占比更大 ③使用标准 JPEG/PNG 格式`);
+        } else {
+          error(`添加照片失败：${err.message || err}`);
+        }
+      }
+    } catch (err: any) {
+      error(`添加照片失败：${err.message || err}`);
+    }
+  });
+
+// 删除人员照片
+personCommands
+  .command('delete-photo')
+  .description('删除人员照片')
+  .argument('[personId]', '人员 ID')
+  .option('-i, --id <personId>', '人员 ID')
+  .option('-n, --name <name>', '姓名')
+  .option('-o, --org <orgIndexCode>', '组织 ID')
+  .option('-on, --org-name <orgName>', '组织名称')
+  .action(async (personId, options) => {
+    try {
+      const client = createHikvisionClient(config.get());
+
+      let targetId = personId || options.id;
+      if (!targetId && (options.name || options.orgName)) {
+        targetId = await findPersonId(client, {
+          name: options.name,
+          orgIndexCode: options.org,
+          orgName: options.orgName,
+        });
+      }
+
+      if (!targetId) {
+        error('请提供人员 ID，或使用 --name 和 --org/--org-name 指定人员');
+        return;
+      }
+
+      // 尝试删除人脸。海康无按人员ID删除人脸的API，
+      // 如果知道 faceId 可以直接删除；不知道则无法删除（需手动处理）
+      // 此处直接报错提示用户提供 faceId
+      error(`删除照片需要提供 faceId，请通过其他途径获取后人脸 ID 后再删除。`);
+    } catch (err: any) {
+      error(`删除照片失败：${err.message || err}`);
+    }
+  });
+
+// 查询已删除人员
+personCommands
+  .command('deleted')
+  .description('查询已删除人员（按时间范围，包含 status < 0 的记录）')
+  .option('--start-time <startTime>', '开始时间，格式：yyyy-MM-dd HH:mm:ss 或 yyyy-MM-dd')
+  .option('--end-time <endTime>', '结束时间，格式：yyyy-MM-dd HH:mm:ss 或 yyyy-MM-dd')
+  .option('-p, --page <page>', '页码', '1')
+  .option('-s, --size <size>', '每页数量', '50')
+  .action(async (options) => {
+    try {
+      const client = createHikvisionClient(config.get());
+
+      // 计算时间范围
+      const now = new Date();
+      const oneWeekAgo = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000);
+
+      const startTime = formatTimeForAPI(options.startTime || oneWeekAgo);
+      const endTime = formatTimeForAPI(options.endTime || now);
+
+      info(`查询时间范围：${startTime} ~ ${endTime}`);
+
+      // 调用增量接口
+      const result = await client.personService.listByTimeRange(
+        startTime,
+        endTime,
+        parseInt(options.page),
+        parseInt(options.size)
+      );
+
+      // 筛选出已删除的人员（status < 0）
+      const deletedPersons = result.list.filter(p => (p as any).status < 0);
+
+      if (result.total === 0) {
+        info('在指定时间范围内未查询到任何人员记录');
+        return;
+      }
+
+      console.log(formatOutput(result));
+
+      if (deletedPersons.length > 0) {
+        success(`\n共 ${deletedPersons.length} 条已删除记录（status < 0）：`);
+        for (const p of deletedPersons) {
+          console.log(`  ${p.personId}  ${p.personName}  status=${(p as any).status}  删除时间=${p.updateTime}`);
+        }
+      } else {
+        info('在指定时间范围内未发现已删除的人员记录');
+      }
+    } catch (err: any) {
+      error(`查询已删除人员失败：${err.message || err}`);
+    }
+  });
+
+// ============ 内部辅助函数 ============
+
+interface FindPersonOptions {
+  name?: string;
+  orgIndexCode?: string;
+  orgName?: string;
+}
+
+/**
+ * 根据组织路径（如：保洁 或 外部人员/保安保洁/保洁）查找 orgIndexCode
+ */
+async function findOrgByPath(client: ReturnType<typeof createHikvisionClient>, orgPath: string): Promise<string | null> {
+  const orgs = await client.personService.getOrganizations();
+  const pathParts = orgPath.split('/').map(p => p.trim()).filter(p => p);
+  
+  if (pathParts.length === 0) return null;
+  
+  const lastPart = pathParts[pathParts.length - 1];
+  
+  const matches: { org: any; score: number }[] = [];
+  
+  for (const org of orgs) {
+    if (org.orgName === lastPart) {
+      matches.push({ org, score: 1 });
+    }
+  }
+  
+  if (matches.length === 0) return null;
+  if (matches.length === 1) return matches[0].org.orgIndexCode;
+  
+  // 多个匹配时，返回第一个
+  return matches[0].org.orgIndexCode;
+}
+
+/**
+ * 根据姓名+部门查找人员 ID
+ */
+async function findPersonId(client: ReturnType<typeof createHikvisionClient>, opts: FindPersonOptions): Promise<string | null> {
+  // 如果有 orgName，先查 orgIndexCode
+  let orgIndexCode = opts.orgIndexCode;
+  if (opts.orgName && !orgIndexCode) {
+    const orgs = await client.personService.getOrganizations();
+    const found = orgs.find(o => o.orgName === opts.orgName);
+    if (!found) {
+      return null;
+    }
+    orgIndexCode = found.orgIndexCode;
+  }
+
+  // 搜索人员
+  const list = await client.personService.list({
+    pageNo: 1,
+    pageSize: 50,
+    personName: opts.name,
+    orgIndexCode: orgIndexCode,
+  });
+
+  const persons = (list as any).list ?? list;
+  if (persons.length === 0) {
+    return null;
+  }
+  if (persons.length === 1) {
+    return persons[0].personId || persons[0].personId;
+  }
+
+  // 多个匹配时提示用户
+  console.log(`找到 ${persons.length} 条匹配记录，请使用 ID 删除：`);
+  for (const p of persons) {
+    console.log(`  ${p.personId}  ${p.personName}  ${p.phoneNo || '-'}  ${p.jobNo || '-'}`);
+  }
+  return null;
+}
+
+/**
+ * 读取照片文件并转为 base64（自动去除 data:image/... 前缀）
+ * 添加了文件大小限制和路径安全验证
+ */
+const MAX_PHOTO_SIZE = 10 * 1024 * 1024; // 10MB
+
+async function loadPhotoBase64(filePath: string): Promise<string> {
+  // 安全检查：解析绝对路径并验证在允许范围内
+  const resolvedPath = path.resolve(filePath);
+  const allowedDir = process.cwd();
+  if (!resolvedPath.startsWith(allowedDir) && !fs.existsSync(resolvedPath)) {
+    throw new Error(`文件路径无效：${filePath}`);
+  }
+
+  if (!fs.existsSync(resolvedPath)) {
+    throw new Error(`照片文件不存在：${filePath}`);
+  }
+
+  const ext = path.extname(resolvedPath).toLowerCase();
+  if (!['.jpg', '.jpeg', '.png', '.bmp', '.gif'].includes(ext)) {
+    throw new Error(`不支持的照片格式：${ext}，仅支持 jpg/jpeg/png/bmp/gif`);
+  }
+
+  const buffer = fs.readFileSync(resolvedPath);
+
+  // 文件大小验证，防止内存耗尽或 DoS
+  if (buffer.length > MAX_PHOTO_SIZE) {
+    throw new Error(`照片文件过大：${(buffer.length / 1024).toFixed(2)}KB，最大支持 ${MAX_PHOTO_SIZE / 1024}KB`);
+  }
+
+  if (buffer.length < 100) {
+    throw new Error(`照片文件无效或损坏`);
+  }
+
+  const mimeMap: Record<string, string> = {
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.png': 'image/png',
+    '.bmp': 'image/bmp',
+    '.gif': 'image/gif',
+  };
+  const mime = mimeMap[ext] || 'image/jpeg';
+  const base64 = buffer.toString('base64');
+
+  // 去除 data:image/... 前缀，只保留纯 base64 数据
+  return base64;
+}
+
+/**
+ * 格式化时间为海康 API 所需格式
+ * @param input Date 对象或字符串
+ * @returns 格式：yyyy-MM-dd'T'HH:mm:ss.SSS+0800
+ */
+function formatTimeForAPI(input: Date | string): string {
+  if (typeof input === 'string') {
+    // 如果是纯日期格式如 "2026-05-19"，直接返回加上默认时间
+    if (/^\d{4}-\d{2}-\d{2}$/.test(input)) {
+      return `${input}T00:00:00.000+0800`;
+    }
+    // 尝试解析字符串
+    const d = new Date(input);
+    if (isNaN(d.getTime())) {
+      throw new Error(`无法解析时间字符串：${input}`);
+    }
+    return formatDate(d);
+  }
+  return formatDate(input);
+}
+
+function formatDate(d: Date): string {
+  const pad = (n: number) => n.toString().padStart(2, '0');
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}T${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}.000+0800`;
+}