sino-bc-cli 1.0.0

package/README.md

@@ -0,0 +1,311 @@
+# sino-bc-cli
+
+BeyondClick 命令行工具集合 - 提供快捷访问 BeyondClick 平台的命令行接口。
+
+---
+
+## 📚 技术栈说明
+
+| 技术/依赖      | 版本要求     | 用途说明                                                |
+| :------------- | :----------- | :------------------------------------------------------ |
+| **Node.js**    | `>= v24.0.0` | CLI 运行时环境，要求使用 v24 及以上版本                 |
+| **TypeScript** | `^v5.5.0`    | 开发语言，提供静态类型检查和更好的可维护性              |
+| **lodash**     | `^4.17.21`   | 工具函数库，提供对象/数组/字符串处理等高效方法          |
+| **dayjs**      | `^1.11.11`   | 轻量级日期处理库，替代 Moment.js 处理日期时间格式化     |
+| **axios**      | `^1.7.0`     | HTTP 客户端库，用于网络请求、连通性检测等               |
+| **crypto-js**  | `^4.2.0`     | 加密算法库，提供 MD5、SHA-256、AES、Base64 等加解密能力 |
+| **commander**  | `^12.1.0`    | 命令行参数解析框架（预留，当前采用自研注册器模式）      |
+| **chalk**      | `^4.1.2`     | 终端彩色输出库，用于美化日志和帮助信息                  |
+| **open**       | `^8.4.2`     | 跨平台文件/URL 打开工具（兼容备用方案）                 |
+
+### 开发依赖
+
+| 依赖               | 版本      | 用途                              |
+| :----------------- | :-------- | :-------------------------------- |
+| `@types/node`      | `^22.0.0` | Node.js 类型声明                  |
+| `@types/lodash`    | `^4.17.5` | lodash 类型声明                   |
+| `@types/crypto-js` | `^4.2.2`  | crypto-js 类型声明                |
+| `ts-node`          | `^10.9.2` | 开发阶段直接运行 TypeScript 代码  |
+| `rimraf`           | `^5.0.7`  | 跨平台目录清理工具，替代 `rm -rf` |
+
+---
+
+## 📁 项目结构说明
+
+项目采用 **模块化、低耦合、高内聚** 的分层设计，便于后续扩展和维护。
+
+```
+sino-bc-cli/
+├── src/                          # 源代码目录（TypeScript）
+│   ├── index.ts                  # 🚀 CLI 入口文件，bin 关联点
+│   │
+│   ├── core/                     # 🧠 核心模块层
+│   │   ├── index.ts              # 核心模块统一导出
+│   │   ├── cli-app.ts            # CLI 应用主类（参数解析、帮助展示、命令分发）
+│   │   └── command-registry.ts   # 命令注册器（注册、查找、执行、注销命令）
+│   │
+│   ├── commands/                 # 📦 命令实现层（每命令一个文件，可独立扩展）
+│   │   ├── index.ts              # 命令批量注册入口
+│   │   ├── homepage.command.ts   # /homepage 命令实现（打开业务平台主页）
+│   │   └── nexus-swagger.command.ts # /nexus-swagger 命令实现（打开 Nexus Swagger 文档页）
+│   │
+│   ├── utils/                    # 🛠 工具类层（高内聚的可复用工具）
+│   │   ├── index.ts              # 工具模块统一导出
+│   │   ├── logger.ts             # 日志工具（多级别彩色输出 + 时间戳）
+│   │   ├── browser.ts            # 浏览器工具（跨平台 URL 打开，兼容 Win/macOS/Linux）
+│   │   ├── crypto.ts             # 加密工具（MD5、SHA-256、AES、Base64、签名生成）
+│   │   ├── http.ts               # HTTP 工具（axios 封装：请求/响应拦截、自动重试）
+│   │   └── common.ts             # 通用工具（日期、深拷贝、防抖节流、ID 生成等）
+│   │
+│   ├── types/                    # 📝 类型定义层
+│   │   └── index.ts              # 全局接口、枚举定义（ICommand、LogLevel 等）
+│   │
+│   └── constants/                # 🔧 常量配置层
+│       └── index.ts              # CLI 配置、URL 配置、命令名称、默认值
+│
+├── dist/                         # 📤 编译输出目录（编译后自动生成）
+│   └── ...                       # JavaScript 编译产物 + 类型声明 + SourceMap
+│
+├── package.json                  # 📄 项目配置（依赖、脚本、bin 命令）
+├── tsconfig.json                 # 📄 TypeScript 编译配置
+├── .gitignore                    # 📄 Git 忽略配置
+└── README.md                     # 📖 项目说明文档
+```
+
+### 架构设计原则
+
+1. **分层清晰**：`core → commands → utils → types/constants`，上层依赖下层，单向依赖无循环
+2. **低耦合**：命令之间互相独立，通过注册器统一管理；新增命令只需在 `commands/` 下新建文件并加入 `commands/index.ts` 数组
+3. **高内聚**：每个工具类只负责单一职责（如 `BrowserUtils` 只处理浏览器打开，`CryptoUtils` 只处理加解密）
+4. **可扩展**：
+   - 新增命令：实现 `ICommand` 接口 → 放入 `commands/index.ts` 数组即可自动注册
+   - 新增工具：在 `utils/` 下新建类，通过 `utils/index.ts` 导出
+   - 命令注册器支持运行时动态注册/注销命令
+
+---
+
+## 🚀 项目使用说明
+
+### 1. 环境要求
+
+确保已安装 **Node.js v24** 或更高版本：
+
+```bash
+# 查看 Node.js 版本
+node -v
+# 要求输出 v24.x.x 或更高
+
+# 查看 npm 版本
+npm -v
+```
+
+> 如果 Node.js 版本不符合要求，建议通过 [nvm (Node Version Manager)](https://github.com/nvm-sh/nvm) 或 [nvm-windows](https://github.com/coreybutler/nvm-windows) 进行安装和版本管理。
+
+### 2. 安装依赖
+
+在项目根目录下执行：
+
+```bash
+npm install
+```
+
+依赖安装完成后，`node_modules/` 目录将生成。
+
+### 3. 编译项目
+
+项目使用 TypeScript 编写，需要编译为 JavaScript 后才能运行：
+
+```bash
+# 编译（生成 dist/ 目录）
+npm run build
+
+# 清理旧的编译产物并重新编译
+npm run rebuild
+```
+
+编译完成后，`dist/` 目录将包含：
+
+- `*.js` — 编译后的 JavaScript 代码
+- `*.d.ts` — TypeScript 类型声明文件
+- `*.js.map` — SourceMap 调试映射文件
+
+### 4. 开发模式（免编译运行）
+
+开发阶段可使用 `ts-node` 直接运行 TypeScript 代码，无需手动编译：
+
+```bash
+# 直接运行 TypeScript 源码
+npm run dev -- [参数]
+
+# 示例：查看帮助
+npm run dev -- --help
+
+# 示例：执行 /homepage 命令
+npm run dev -- /homepage
+```
+
+### 5. 全局安装（推荐）
+
+将 CLI 工具链接为全局命令，可在任意目录下直接使用 `sino-bc-cli`：
+
+```bash
+# 方式一：从源码目录全局链接（开发/测试场景）
+cd d:\Project\demo\sino-bc-cli
+npm run build      # 必须先编译
+npm link           # 全局链接（Windows 下需要管理员权限）
+
+# 方式二：后续发布到 npm 后
+npm i sino-bc-cli -g
+```
+
+安装完成后，即可在任意终端直接使用：
+
+```bash
+sino-bc-cli --help
+sino-bc-cli /homepage
+```
+
+> 卸载全局链接：`npm unlink` 或 `npm uninstall -g sino-bc-cli`
+
+---
+
+## 📖 命令说明
+
+### 可用命令一览
+
+| 命令             | 说明                                                                                                               |
+| :--------------- | :----------------------------------------------------------------------------------------------------------------- |
+| `/homepage`      | 使用默认浏览器打开 BeyondClick 业务平台主页 (`https://business.beyondclick.com/`)                                  |
+| `/nexus-swagger` | 使用默认浏览器打开 BeyondClick Nexus Swagger 文档页 (`https://o-test-sino-bc-nexus.meetsocial.com/doc.html#/home`) |
+
+### 全局选项
+
+| 选项        | 短选项 | 说明                                      |
+| :---------- | :----- | :---------------------------------------- |
+| `--version` | `-v`   | 显示版本信息                              |
+| `--help`    | `-h`   | 显示帮助信息                              |
+| `--debug`   | `-d`   | 启用 Debug 日志模式，输出更详细的运行信息 |
+
+### 使用示例
+
+#### ① 查看版本和帮助
+
+```bash
+# 查看版本号
+sino-bc-cli --version
+sino-bc-cli -v
+
+# 查看帮助文档（含所有可用命令列表）
+sino-bc-cli --help
+sino-bc-cli -h
+```
+
+#### ② 打开 BeyondClick 业务平台主页
+
+```bash
+sino-bc-cli /homepage
+```
+
+执行效果：自动调用系统默认浏览器打开 `https://business.beyondclick.com/`。
+
+#### ③ 打开 BeyondClick Nexus Swagger 文档页
+
+```bash
+sino-bc-cli /nexus-swagger
+```
+
+执行效果：自动调用系统默认浏览器打开 Nexus Swagger 文档页。
+
+#### ④ 启用 Debug 模式运行
+
+```bash
+sino-bc-cli --debug /homepage
+# 或使用短选项
+sino-bc-cli -d /nexus-swagger
+```
+
+Debug 模式会输出详细的日志，包括参数解析、命令注册、URL 打开过程等信息，便于排查问题。
+
+---
+
+## 🌐 跨平台兼容性
+
+本工具已针对以下操作系统进行兼容性处理：
+
+| 操作系统                     | 测试状态 | 打开浏览器方式                                                     |
+| :--------------------------- | :------- | :----------------------------------------------------------------- |
+| **Windows** (10/11)          | ✅ 支持  | 使用 `cmd /c start "" "url"`，已处理 URL 中 `&`/`^` 等特殊字符转义 |
+| **macOS**                    | ✅ 支持  | 使用系统 `open` 命令                                               |
+| **Linux** (Ubuntu/CentOS 等) | ✅ 支持  | 使用 `xdg-open` 命令                                               |
+
+> 所有平台均通过 Node.js 内置 `child_process.exec` 调用，**不依赖任何 native 模块**，确保跨平台一致性。
+
+---
+
+## 📦 NPM 脚本说明
+
+在 `package.json` 中预定义了以下脚本：
+
+```bash
+# 编译 TypeScript 为 JavaScript（输出到 dist/）
+npm run build
+
+# 开发模式：直接运行 TypeScript 源码（ts-node）
+npm run dev -- [参数]
+
+# 运行已编译的 CLI（需要先 build）
+npm start -- [参数]
+
+# 清理编译产物（删除 dist/ 目录）
+npm run clean
+
+# 清理后重新编译
+npm run rebuild
+```
+
+---
+
+## 🔧 扩展新命令（开发者指南）
+
+### 步骤
+
+1. **新建命令文件**：在 `src/commands/` 下创建 `xxx.command.ts`
+2. **实现 ICommand 接口**：编写 `name`、`description` 和 `execute()` 方法
+3. **注册命令**：在 `src/commands/index.ts` 的 `commands` 数组中添加实例
+
+### 示例
+
+```typescript
+// src/commands/example.command.ts
+import { ICommand } from "../types";
+import { logger, BrowserUtils } from "../utils";
+
+export class ExampleCommand implements ICommand {
+  public readonly name = "example";
+  public readonly description = "示例命令 - 打开示例网站";
+
+  public async execute(args: string[]): Promise<void> {
+    logger.info("执行示例命令，参数：", args);
+    await BrowserUtils.openUrl("https://example.com/");
+  }
+}
+```
+
+```typescript
+// src/commands/index.ts
+import { ExampleCommand } from "./example.command"; // 新增导入
+
+export const commands: ICommand[] = [
+  new HomepageCommand(),
+  new NexusSwaggerCommand(),
+  new ExampleCommand(), // 新增注册
+];
+```
+
+完成后执行 `npm run build` 即可使用 `sino-bc-cli /example`。
+
+---
+
+## 📄 License
+
+MIT License