hikvision-cli 1.0.0

package/src/services/hikvisionClient.ts

@@ -0,0 +1,74 @@
+/**
+ * Hikvision 客户端工厂
+ *
+ * 组合 NodeHttpClient 和 API 创建完整客户端
+ * 兼容 CLI 和 Server 使用
+ */
+
+import { NodeHttpClient } from 'hikvision-core-node';
+import { PersonAPI } from 'hikvision-core-node';
+import { CardAPI } from 'hikvision-core-node';
+import { VehicleAPI } from 'hikvision-core-node';
+import { GroupAPI } from 'hikvision-core-node';
+import { PersonService } from 'hikvision-services';
+import { CardService } from 'hikvision-services';
+import { VehicleService } from 'hikvision-services';
+import { HikvisionConfig } from 'hikvision-api-lib';
+import type { CLIConfig } from '../utils/config';
+
+export interface HikvisionClientWrapper {
+  client: NodeHttpClient;
+  personService: PersonService;
+  cardService: CardService;
+  vehicleService: VehicleService;
+  groupService: GroupAPI;
+}
+
+/**
+ * 将 CLIConfig 转换为 HikvisionConfig
+ */
+function toHikvisionConfig(cfg: CLIConfig | null): HikvisionConfig {
+  if (!cfg) {
+    throw new Error('配置无效，请先运行 hikvision-cli config set 进行配置');
+  }
+  return {
+    host: cfg.host,
+    appKey: cfg.appKey,
+    appSecret: cfg.appSecret,
+  };
+}
+
+/**
+ * 创建 Hikvision 客户端实例（Node.js 版）
+ */
+export function createHikvisionClient(config: CLIConfig | null): HikvisionClientWrapper {
+  const hikConfig = toHikvisionConfig(config);
+
+  // 创建 NodeHttpClient
+  const httpClient = new NodeHttpClient({
+    host: hikConfig.host,
+    appKey: hikConfig.appKey,
+    appSecret: hikConfig.appSecret,
+  });
+
+  // 创建 API 实例（注入 IHttpClient）
+  const personAPI = new PersonAPI(httpClient);
+  const cardAPI = new CardAPI(httpClient);
+  const vehicleAPI = new VehicleAPI(httpClient);
+  const groupAPI = new GroupAPI(httpClient);
+
+  // 创建 Service 实例（注入 API）
+  const personService = new PersonService(personAPI);
+  const cardService = new CardService(cardAPI);
+  const vehicleService = new VehicleService(vehicleAPI);
+
+  return {
+    client: httpClient,
+    personService,
+    cardService,
+    vehicleService,
+    groupService: groupAPI,
+  };
+}
+
+export type { HikvisionConfig } from 'hikvision-api-lib';

package/src/types/cli-table3.d.ts

@@ -0,0 +1,20 @@
+declare module 'cli-table3' {
+  interface TableOptions {
+    head?: string[];
+    colWidths?: number[];
+    style?: {
+      head?: string[];
+      border?: string[];
+      'padding-left'?: number[];
+      'padding-right'?: number[];
+    };
+  }
+
+  class Table {
+    constructor(options?: TableOptions);
+    push(row: any[]): void;
+    toString(): string;
+  }
+
+  export = Table;
+}

package/src/utils/config.ts

@@ -0,0 +1,199 @@
+/**
+ * CLI 配置管理
+ * 
+ * 配置优先级（从高到低）：
+ * 1. 环境变量（HIK_HOST, HIK_APP_KEY, HIK_APP_SECRET）
+ * 2. 项目配置文件（packages/server/config.json）
+ * 3. 用户配置文件（~/.hikvision-cli/config.json）
+ * 4. 默认值
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+export interface CLIConfig {
+  host: string;
+  appKey: string;
+  appSecret: string;
+  outputFormat: 'table' | 'json' | 'yaml';
+  pageSize: number;
+  logLevel: 'debug' | 'info' | 'warn' | 'error';
+}
+
+// 非敏感默认值
+const DEFAULT_CONFIG: Omit<CLIConfig, 'appKey' | 'appSecret'> = {
+  host: '127.0.0.1:18443',
+  outputFormat: 'table',
+  pageSize: 20,
+  logLevel: 'info',
+};
+
+const CONFIG_DIR = path.join(os.homedir(), '.hikvision-cli');
+const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
+
+export class ConfigManager {
+  private config: CLIConfig | null = null;
+
+  constructor() {
+    this.config = this.loadConfig();
+  }
+
+  /**
+   * 加载配置：优先用户配置，其次环境变量
+   */
+  private loadConfig(): CLIConfig | null {
+    // 1. 尝试加载用户配置文件
+    try {
+      if (fs.existsSync(CONFIG_FILE)) {
+        const content = fs.readFileSync(CONFIG_FILE, 'utf-8');
+        const userConfig = JSON.parse(content);
+        // 如果用户配置中包含敏感信息，直接使用
+        if (userConfig.appKey && userConfig.appSecret) {
+          return { ...DEFAULT_CONFIG, ...userConfig } as CLIConfig;
+        }
+      }
+    } catch (error) {
+      console.warn('⚠️ 配置文件加载失败');
+    }
+
+    // 2. 尝试从环境变量读取
+    const host = process.env.HIK_HOST;
+    const appKey = process.env.HIK_APP_KEY;
+    const appSecret = process.env.HIK_APP_SECRET;
+
+    if (host && appKey && appSecret) {
+      return {
+        ...DEFAULT_CONFIG,
+        host,
+        appKey,
+        appSecret,
+      };
+    }
+
+    // 3. 尝试从项目配置文件读取
+    const projectConfigPath = path.resolve(__dirname, '../../../../server/config.json');
+    if (fs.existsSync(projectConfigPath)) {
+      try {
+        const projectConfig = JSON.parse(fs.readFileSync(projectConfigPath, 'utf-8'));
+        if (projectConfig.hikvision?.host && projectConfig.hikvision?.appKey && projectConfig.hikvision?.appSecret) {
+          return {
+            ...DEFAULT_CONFIG,
+            host: projectConfig.hikvision.host,
+            appKey: projectConfig.hikvision.appKey,
+            appSecret: projectConfig.hikvision.appSecret,
+          };
+        }
+      } catch (e) {
+        console.warn('⚠️ 项目配置文件加载失败:', e);
+      }
+    }
+
+    // 3. 配置缺失，返回 null 表示需要用户配置
+    return null;
+  }
+
+  /**
+   * 获取配置
+   * @returns 配置对象，如果未配置则返回 null
+   */
+  get(): CLIConfig | null {
+    return this.config ? { ...this.config } : null;
+  }
+
+  /**
+   * 检查是否已配置
+   */
+  isConfigured(): boolean {
+    return this.config !== null && !!this.config.appKey && !!this.config.appSecret;
+  }
+
+  /**
+   * 更新配置
+   */
+  update(updates: Partial<CLIConfig>): void {
+    if (!this.config) {
+      this.config = { ...DEFAULT_CONFIG } as CLIConfig;
+    }
+    this.config = { ...this.config, ...updates };
+    this.saveConfig();
+  }
+
+  /**
+   * 保存配置
+   */
+  private saveConfig(): void {
+    try {
+      if (!fs.existsSync(CONFIG_DIR)) {
+        fs.mkdirSync(CONFIG_DIR, { recursive: true });
+      }
+      fs.writeFileSync(CONFIG_FILE, JSON.stringify(this.config, null, 2));
+    } catch (error) {
+      console.error('❌ 保存配置失败:', error);
+    }
+  }
+
+  /**
+   * 重置配置（删除用户配置文件）
+   */
+  reset(): void {
+    try {
+      if (fs.existsSync(CONFIG_FILE)) {
+        fs.unlinkSync(CONFIG_FILE);
+      }
+      this.config = null;
+    } catch (error) {
+      console.error('❌ 重置配置失败:', error);
+    }
+  }
+
+  /**
+   * 获取配置路径
+   */
+  static getConfigPath(): string {
+    return CONFIG_FILE;
+  }
+
+  /**
+   * 检查配置文件是否存在
+   */
+  static hasConfigFile(): boolean {
+    return fs.existsSync(CONFIG_FILE);
+  }
+
+  /**
+   * 对配置中的敏感信息进行脱敏
+   * @param cfg 配置对象
+   * @returns 脱敏后的配置（不包含原始敏感数据）
+   */
+  maskSensitive(cfg: CLIConfig): CLIConfig {
+    if (!cfg) return cfg;
+    return {
+      ...cfg,
+      appKey: cfg.appKey ? `***${cfg.appKey.slice(-4)}` : '',
+      appSecret: cfg.appSecret ? `***${cfg.appSecret.slice(-4)}` : '',
+    };
+  }
+
+  /**
+   * 提示用户进行配置
+   */
+  static promptConfig(): void {
+    console.log('\n🔧 海康平台配置未设置，请进行配置：\n');
+    console.log('方法一：设置环境变量');
+    console.log('  export HIK_HOST=127.0.0.1:18443');
+    console.log('  export HIK_APP_KEY=你的AppKey');
+    console.log('  export HIK_APP_SECRET=你的AppSecret\n');
+    console.log('方法二：修改配置文件');
+    console.log('  编辑 packages/server/config.json，添加 hikvision 配置：');
+    console.log('  { "hikvision": { "host": "127.0.0.1:18443", "appKey": "***", "appSecret": "***" } }\n');
+    console.log('方法三：使用 CLI 命令配置');
+    console.log('  hikvision-cli config set host 127.0.0.1:18443');
+    console.log('  hikvision-cli config set key 你的AppKey');
+    console.log('  hikvision-cli config set secret 你的AppSecret\n');
+    console.log('配置完成后重新运行命令。\n');
+  }
+}
+
+// 导出单例
+export const config = new ConfigManager();

package/src/utils/output.ts

@@ -0,0 +1,181 @@
+/**
+ * CLI 输出格式化
+ */
+
+import Table from 'cli-table3';
+import { config } from './config';
+
+export type OutputFormat = 'table' | 'json' | 'yaml';
+
+export interface TableOptions {
+  title?: string;
+  columns?: string[];
+  rows?: any[][];
+}
+
+/**
+ * 格式化输出
+ */
+export function formatOutput(data: any, format?: OutputFormat): string {
+  const cfg = config.get();
+  const outputFormat = format || (cfg?.outputFormat || 'table');
+  
+  switch (outputFormat) {
+    case 'json':
+      return JSON.stringify(data, null, 2);
+    case 'yaml':
+      return formatYaml(data);
+    case 'table':
+    default:
+      return formatTable(data);
+  }
+}
+
+/**
+ * 表格输出
+ */
+export function formatTable(data: any): string {
+  if (!data || typeof data !== 'object') {
+    return String(data);
+  }
+
+  // 处理数组数据（直接返回数组）
+  if (Array.isArray(data)) {
+    if (data.length === 0) {
+      return '📭 暂无数据';
+    }
+    
+    const columns = Object.keys(data[0]);
+    const table = new Table({
+      head: columns,
+      style: { head: ['cyan'], border: ['gray'] },
+    });
+    
+    data.forEach((item: any) => {
+      const row = columns.map((col) => item[col] ?? '');
+      table.push(row);
+    });
+    
+    return table.toString();
+  }
+
+  // 处理分页数据
+  if (data.list && Array.isArray(data.list)) {
+    const title = data.total 
+      ? `📊 共 ${data.total} 条记录 (当前 ${data.list.length} 条)`
+      : '';
+    
+    if (data.list.length === 0) {
+      return '📭 暂无数据';
+    }
+    
+    const columns = Object.keys(data.list[0]);
+    const table = new Table({
+      head: columns,
+      style: { head: ['cyan'], border: ['gray'] },
+    });
+    
+    data.list.forEach((item: any) => {
+      const row = columns.map((col) => item[col] ?? '');
+      table.push(row);
+    });
+    
+    const output = table.toString();
+    return title ? `${title}\n\n${output}` : output;
+  }
+
+  // 处理包含 data 数组的对象（如 { data: [...] }）
+  if (data.data && Array.isArray(data.data)) {
+    if (data.data.length === 0) {
+      return '📭 暂无数据';
+    }
+    
+    const columns = Object.keys(data.data[0]);
+    const table = new Table({
+      head: columns,
+      style: { head: ['cyan'], border: ['gray'] },
+    });
+    
+    data.data.forEach((item: any) => {
+      const row = columns.map((col) => item[col] ?? '');
+      table.push(row);
+    });
+    
+    return table.toString();
+  }
+
+  // 处理对象数据
+  return JSON.stringify(data, null, 2);
+}
+
+/**
+ * YAML 输出（简化版）
+ */
+function formatYaml(data: any): string {
+  if (data === null || data === undefined) {
+    return 'null';
+  }
+  
+  if (typeof data !== 'object') {
+    return String(data);
+  }
+  
+  if (Array.isArray(data)) {
+    return data.map((item: any, i: number) => `- ${formatYaml(item)}`).join('\n');
+  }
+  
+  return Object.entries(data)
+    .map(([key, value]: [string, any]) => `${key}: ${formatYaml(value)}`)
+    .join('\n');
+}
+
+/**
+ * 成功消息
+ */
+export function success(message: string): void {
+  console.log(`✅ ${message}`);
+}
+
+/**
+ * 错误消息
+ */
+export function error(message: string): void {
+  console.error(`❌ ${message}`);
+}
+
+/**
+ * 警告消息
+ */
+export function warn(message: string): void {
+  console.warn(`⚠️ ${message}`);
+}
+
+/**
+ * 信息消息
+ */
+export function info(message: string): void {
+  console.log(`ℹ️ ${message}`);
+}
+
+/**
+ * 批量操作结果输出
+ */
+export function formatBatchResult(result: { success: number; failed: number; details?: any[] }): string {
+  const lines = [
+    `📊 批量操作完成`,
+    `  ✅ 成功: ${result.success}`,
+    `  ❌ 失败: ${result.failed}`,
+  ];
+  
+  if (result.failed > 0 && result.details) {
+    lines.push('');
+    lines.push('失败详情:');
+    result.details.forEach((detail: any, i: number) => {
+      if (!detail.success) {
+        lines.push(`  ${i + 1}. ${detail.message || '未知错误'}`);
+      }
+    });
+  }
+  
+  return lines.join('\n');
+}

package/src/utils/validation.ts

@@ -0,0 +1,160 @@
+/**
+ * CLI 输入验证工具
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+export interface ValidationResult {
+  valid: boolean;
+  content: string;
+  error?: string;
+}
+
+export interface JsonValidationOptions {
+  requiredFields?: string[];
+  maxSize?: number;
+  maxItems?: number;
+}
+
+/**
+ * 验证 JSON 文件内容
+ * @param content 文件内容字符串
+ * @param options 验证选项
+ * @returns 验证结果
+ */
+export function validateJsonFile(content: string, options: JsonValidationOptions = {}): ValidationResult {
+  const { requiredFields = [], maxSize = 10 * 1024 * 1024, maxItems } = options;
+
+  // 1. 大小验证
+  if (content.length > maxSize) {
+    return {
+      valid: false,
+      content,
+      error: `文件内容过大：${(content.length / 1024).toFixed(2)}KB，最大支持 ${(maxSize / 1024).toFixed(2)}KB`,
+    };
+  }
+
+  // 2. JSON 格式验证
+  let parsed: any;
+  try {
+    parsed = JSON.parse(content);
+  } catch (e: any) {
+    return {
+      valid: false,
+      content,
+      error: `无效的 JSON 格式：${e.message}`,
+    };
+  }
+
+  // 3. 必需字段验证
+  for (const field of requiredFields) {
+    if (!parsed.hasOwnProperty(field)) {
+      return {
+        valid: false,
+        content,
+        error: `缺少必需字段：${field}`,
+      };
+    }
+  }
+
+  // 4. 数组大小验证
+  if (maxItems) {
+    for (const field of requiredFields) {
+      if (Array.isArray(parsed[field]) && parsed[field].length > maxItems) {
+        return {
+          valid: false,
+          content,
+          error: `${field} 数组项数量超出限制：${parsed[field].length} > ${maxItems}`,
+        };
+      }
+    }
+  }
+
+  return {
+    valid: true,
+    content,
+  };
+}
+
+/**
+ * 验证文件路径是否安全（防止路径遍历）
+ * @param filePath 文件路径
+ * @param allowedDir 允许的基础目录
+ * @returns 是否安全
+ */
+export function isPathSafe(filePath: string, allowedDir?: string): boolean {
+  const resolved = path.resolve(filePath);
+
+  // 如果提供了允许目录，检查路径是否在允许范围内
+  if (allowedDir) {
+    const allowedResolved = path.resolve(allowedDir);
+    return resolved.startsWith(allowedResolved);
+  }
+
+  // 基本检查：路径不能包含 .. （上级目录）
+  return !filePath.includes('..');
+}
+
+/**
+ * 验证输入字符串是否包含危险字符
+ * @param input 输入字符串
+ * @returns 是否安全
+ */
+export function isInputSafe(input: string): boolean {
+  // 检查是否有潜在的命令注入
+  const dangerousPatterns = [
+    /[;&|`$]/,           // 命令分隔符和管道
+    /\${.*}/,            // 命令替换
+    /\$\(.*\)/,          // 命令替换
+  ];
+
+  return !dangerousPatterns.some(pattern => pattern.test(input));
+}
+
+/**
+ * 验证手机号格式（中国大陆）
+ * @param phone 手机号
+ * @returns 是否有效
+ */
+export function isValidPhone(phone: string): boolean {
+  return /^1[3-9]\d{9}$/.test(phone);
+}
+
+/**
+ * 验证身份证号格式（中国大陆）
+ * @param idCard 身份证号
+ * @returns 是否有效
+ */
+export function isValidIdCard(idCard: string): boolean {
+  // 18位身份证号
+  if (!/^\d{17}[\dXx]$/.test(idCard)) {
+    return false;
+  }
+
+  // 校验位验证
+  const weights = [7, 9, 10, 5, 8, 4, 2, 1, 6, 3, 7, 9, 10, 5, 8, 4, 2];
+  const checkCodes = ['1', '0', 'X', '9', '8', '7', '6', '5', '4', '3', '2'];
+
+  let sum = 0;
+  for (let i = 0; i < 17; i++) {
+    sum += parseInt(idCard[i]) * weights[i];
+  }
+
+  const checkCode = checkCodes[sum % 11];
+  return idCard[17].toUpperCase() === checkCode;
+}
+
+/**
+ * 验证车牌号格式（中国大陆）
+ * @param plateNo 车牌号
+ * @returns 是否有效
+ */
+export function isValidPlateNo(plateNo: string): boolean {
+  // 普通车牌：省+城市字母+5位数字/字母
+  // 新能源车牌：6位
+  const pattern = /^[京津沪渝冀豫云辽黑湘皖鲁新苏浙赣鄂桂甘晋蒙陕吉闽贵粤青藏川宁琼使领][A-Z][A-Z0-9]{4,5}[A-Z0-9挂学警港澳]$/;
+  const newEnergyPattern = /^[京津沪渝冀豫云辽黑湘皖鲁新苏浙赣鄂桂甘晋蒙陕吉闽贵粤青藏川宁琼使领][DF]$[A-Z0-9]{5}$/;
+
+  return pattern.test(plateNo) || newEnergyPattern.test(plateNo);
+}

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}