Optima CLI 套件架构设计

版本: v1.0.0 | 更新: 2025-10-29

概览

Optima CLI 套件由五个独立仓库组成，采用"共享核心 + 独立工具"的架构模式：

Optima CLI Suite
├── optima-cli-docs           → 统一文档中心（本仓库）
├── optima-cli-core           → 共享核心库
├── optima-merchant-cli       → 商户 BI 工具 ⭐ 优先
├── optima-platform-cli       → 平台运营 BI 工具
└── optima-ops-cli            → 系统运维工具

设计原则

1. 关注点分离

商户层: 商户管理自己的店铺（销售、商品、订单、财务）
平台层: 运营查看平台全局数据（GMV、商户健康度、市场趋势）
系统层: 技术团队监控基础设施（服务健康、性能、日志）

2. 代码复用

认证、HTTP 客户端、格式化等通用功能抽取到 cli-core
避免在三个业务 CLI 中重复实现

3. 独立演进

每个 CLI 独立发布和版本管理
按需安装，互不影响

4. 权限隔离

商户只能访问自己的数据（merchant_id 过滤）
平台运营需要 admin 角色
系统运维需要 ops 角色或系统级访问

仓库详情

1. optima-cli-docs（本仓库）

定位: 统一文档中心内容:

整体架构设计
用户指南、API 参考
开发者文档、发布流程

优势: 避免文档在多个仓库中重复维护

2. optima-cli-core

项目信息	内容
NPM 包	`@optima-chat/cli-core`
定位	被其他 CLI 依赖的公共库
GitHub	https://github.com/Optima-Chat/optima-cli-core

核心功能:

// 1. 认证管理
export class AuthManager {
  // OAuth 2.0 Device Flow
  // Token 自动刷新
  // 复用 optima-cli 配置
}

// 2. HTTP 客户端
export class BaseApiClient {
  // 自动认证、错误处理、重试
}

// 3. 输出格式化
export class OutputFormatter {
  // JSON（默认）、Pretty、Chart、CSV
}

// 4. 配置管理
export class ConfigManager {
  // 加密存储、环境变量支持
}

// 5. 工具函数
export { DateUtils, NumberUtils, TableRenderer, ChartRenderer }

技术栈:

TypeScript 5.3+ (ES Modules)
Axios, Conf, Chalk, cli-table3, asciichart

3. optima-merchant-cli ⭐ 优先开发

项目信息	内容
NPM 包	`@optima-chat/merchant-cli`
命令名	`optima-merchant` (简写: `om`)
用户	商户/卖家
权限	只能访问自己的店铺数据
GitHub	https://github.com/Optima-Chat/optima-merchant-cli

功能模块 (20+ 命令):

1. 销售分析 (`sales/`)

optima-merchant sales summary --month 2025-10    # 销售概况
optima-merchant sales today                      # 今日实时销售
optima-merchant sales compare --from 2025-09     # 时间对比
optima-merchant sales trend --days 30            # 趋势图

关键指标: 总销售额、订单数、AOV、增长率

2. 商品分析 (`products/`)

optima-merchant products top-selling --limit 10  # 畅销商品
optima-merchant products slow-moving --days 60   # 滞销商品
optima-merchant products out-of-stock            # 缺货预警
optima-merchant products inventory               # 库存周转率
optima-merchant products views                   # 浏览次数

关键指标: 销量排行、库存周转、浏览转化

3. 订单运营 (`orders/`)

optima-merchant orders pending                   # 待处理订单
optima-merchant orders fulfillment --period 30d  # 履约效率
optima-merchant orders status                    # 状态分布
optima-merchant orders cancellation              # 取消率

关键指标: 处理时长、履约率、取消率

4. 财务对账 (`finance/`)

optima-merchant finance summary --month 2025-10  # 财务汇总
optima-merchant finance pending-transfers        # 待转账
optima-merchant finance platform-fees            # 平台费用
optima-merchant finance export --format csv      # 导出报表

关键指标: 收入、转账、费用、退款

5. 客户分析 (`customers/`)

optima-merchant customers analyze                # 客户分析
optima-merchant customers high-value             # 高价值客户
optima-merchant customers retention              # 留存率
optima-merchant customers segmentation           # 客户分层

关键指标: LTV、复购率、RFM 分层

数据源:

主要: Commerce Backend REST API（现有）
扩展: 可能需要新增聚合端点
- GET /api/analytics/merchant/sales-summary
- GET /api/analytics/merchant/product-performance

依赖:

{
  "dependencies": {
    "@optima-chat/cli-core": "^0.1.0",
    "commander": "^12.0.0",
    "inquirer": "^9.0.0"
  }
}

4. optima-platform-cli

项目信息	内容
NPM 包	`@optima-chat/platform-cli`
命令名	`optima-platform` (简写: `op`)
用户	平台运营团队
权限	Admin（可查看所有商户聚合数据）
GitHub	https://github.com/Optima-Chat/optima-platform-cli

功能模块:

1. 平台销售

optima-platform sales gmv --period 30d           # 平台 GMV
optima-platform sales growth                     # 增长率
optima-platform sales by-category                # 按品类
optima-platform sales by-region                  # 按地区

2. 商户分析

optima-platform merchants active                 # 活跃商户
optima-platform merchants new                    # 新增商户
optima-platform merchants churn                  # 流失商户
optima-platform merchants ranking                # 商户排行
optima-platform merchants health                 # 健康度

3. 用户分析

optima-platform users growth                     # 用户增长
optima-platform users retention                  # 留存率
optima-platform users acquisition                # 获客渠道
optima-platform users lifetime-value             # LTV

4. 平台收入

optima-platform revenue summary                  # 收入概况
optima-platform revenue platform-fees            # 平台费用收入
optima-platform revenue forecast                 # 收入预测

5. 市场分析

optima-platform market trends                    # 市场趋势
optima-platform market categories                # 品类热度
optima-platform market competition               # 竞争分析

数据源（混合模式）:

方案	适用场景	说明
Analytics 服务	复杂聚合	新建 `optima-analytics` 后端服务
直连数据库	灵活查询	PostgreSQL 客户端直接查询 RDS
预聚合表	历史数据	利用 `shop_stats` 表（已有）

推荐组合:

简单查询 → 直连 RDS
复杂聚合 → Analytics 服务
历史数据 → shop_stats 表

5. optima-ops-cli

项目信息	内容
NPM 包	`@optima-chat/ops-cli`
命令名	`optima-ops` (简写: `oo`)
用户	技术运维团队
权限	系统级（SSH、AWS API、Docker API）
GitHub	https://github.com/Optima-Chat/optima-ops-cli

功能模块:

1. 服务健康

optima-ops services health                       # 所有服务健康度
optima-ops services response-time                # API 响应时间
optima-ops services error-rate                   # 错误率
optima-ops services uptime                       # SLA 可用性

2. 数据库监控

optima-ops database connections                  # 连接池状态
optima-ops database slow-queries                 # 慢查询
optima-ops database locks                        # 锁等待
optima-ops database size                         # 数据库大小

3. 基础设施

optima-ops infra ec2                             # EC2 资源使用
optima-ops infra docker                          # Docker 容器状态
optima-ops infra disk                            # 磁盘使用
optima-ops infra network                         # 网络流量

4. 日志分析

optima-ops logs errors --last 1h                 # 错误日志
optima-ops logs anomaly                          # 异常检测
optima-ops logs search --query "timeout"         # 日志搜索

5. MCP 工作区

optima-ops workspace containers                  # 运行中的 workspace
optima-ops workspace resources                   # 资源占用
optima-ops workspace quota                       # 配额使用

6. 告警与部署

optima-ops alerts summary                        # 告警统计
optima-ops deployments history                   # 部署历史
optima-ops deployments rollback                  # 回滚操作

数据源（多源集成）:

数据源	用途	示例
AWS CloudWatch	基础设施监控	EC2 CPU、ALB 请求数
Docker API	容器管理	`docker stats`, `docker ps`
服务健康端点	应用状态	`/health`, `/metrics`
PostgreSQL 系统视图	数据库性能	`pg_stat_statements`

架构图

依赖关系

┌────────────────────────────────────────┐
│         optima-cli-docs                │
│     （统一文档，不被依赖）              │
└────────────────────────────────────────┘

┌────────────────────────────────────────┐
│         optima-cli-core                │
│  (Auth, HTTP, Formatter, Config)       │
└────────────────────────────────────────┘
                ▲
                │ depends on
      ┌─────────┼──────────┐
      │         │          │
┌─────┴────┐  ┌─┴────────┐  ┌──────────┴─┐
│merchant  │  │platform  │  │    ops     │
│  -cli    │  │  -cli    │  │   -cli     │
└──────────┘  └──────────┘  └────────────┘
      │            │              │
      │            │              │
      ▼            ▼              ▼
┌─────────┐  ┌──────────┐  ┌─────────────┐
│Commerce │  │Analytics │  │CloudWatch   │
│Backend  │  │Service   │  │Docker API   │
│REST API │  │+ RDS     │  │Health Checks│
└─────────┘  └──────────┘  └─────────────┘

数据流

1. 用户执行命令
   ↓
2. CLI 入口 (Commander.js)
   ↓
3. 认证检查 (cli-core/AuthManager)
   ├→ 读取 Token (~/.config/optima-cli/config.json)
   └→ 自动刷新（如过期）
   ↓
4. API 调用 (cli-core/BaseApiClient)
   ├→ Commerce API (merchant-cli)
   ├→ Analytics Service (platform-cli)
   └→ CloudWatch/Docker (ops-cli)
   ↓
5. 数据处理（各 CLI 的业务逻辑）
   ↓
6. 输出格式化 (cli-core/OutputFormatter)
   ├→ JSON 模式（默认，AI 友好）
   ├→ Pretty 模式（--pretty，人类友好）
   ├→ Chart 模式（--chart，趋势可视化）
   └→ Export 模式（--export，CSV/JSON）

技术栈

共同技术栈

语言: TypeScript 5.3+ (ES Modules)
Node.js: >= 18
包管理器: pnpm（推荐）或 npm
CLI 框架: Commander.js 12+
HTTP 客户端: Axios
测试框架: Jest + ts-jest
代码质量: ESLint + Prettier
CI/CD: GitHub Actions

cli-core 特有

conf - 配置加密存储
chalk - 终端颜色
cli-table3 - 表格渲染
asciichart - ASCII 图表
date-fns - 日期处理
numeral - 数字格式化

platform-cli 特有

pg - PostgreSQL 客户端（直连数据库）
csv-writer - CSV 导出

ops-cli 特有

@aws-sdk/client-cloudwatch - CloudWatch 监控
@aws-sdk/client-logs - 日志查询
ssh2 - SSH 远程执行（可选）

输出格式规范

JSON 模式（默认）

{
  "success": true,
  "data": {
    "period": "2025-10",
    "metrics": {
      "total_revenue": 125000.50,
      "total_orders": 342,
      "avg_order_value": 365.50,
      "growth_rate": 15.3
    }
  },
  "generated_at": "2025-10-29T10:30:00Z"
}

用途: Claude Code、脚本自动化、数据管道

Pretty 模式（`--pretty`）

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  销售概况 - 2025年10月
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  总销售额      $125,000.50  ↑ 15.3%
  订单数        342          ↑ 8.2%
  平均订单价值   $365.50      ↑ 6.5%

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

用途: 终端直接查看、视觉化呈现

Chart 模式（`--chart`）

销售趋势 (2025-10-01 至 2025-10-29)

    $8,000 ┤        ╭╮
    $7,000 ┤    ╭─╮ ││╭╮
    $6,000 ┤  ╭─╯ ╰─╯╰╯│
    $5,000 ┤╭─╯        ╰─╮
    $4,000 ┼╯             ╰─
         1  5  10 15 20 25 29

用途: 趋势可视化、快速模式识别

Export 模式（`--export <file>`）

CSV: --export sales.csv
JSON: --export sales.json

用途: Excel 分析、数据存档

认证与配置

认证方式

复用 optima-cli 的 OAuth 配置:

配置文件 (主要方式)
```
~/.config/optima-cli/config.json
```

环境变量 (优先级最高)

export OPTIMA_TOKEN=<token>
export OPTIMA_API_URL=https://api.optima.shop

自动刷新
- Token 过期前 5 分钟自动刷新
- 失败后提示重新登录

配置层级

环境变量（最高）
    ↓
CLI 参数（--api-url）
    ↓
配置文件（~/.config/optima-*/）
    ↓
默认值（代码中定义）

开发流程

本地开发

# 1. 克隆 core
git clone https://github.com/Optima-Chat/optima-cli-core.git
cd optima-cli-core
pnpm install && pnpm build && pnpm link

# 2. 克隆业务 CLI
git clone https://github.com/Optima-Chat/optima-merchant-cli.git
cd optima-merchant-cli
pnpm install
pnpm link @optima-chat/cli-core  # 链接本地 core
pnpm dev  # watch 模式开发

发布流程

# 更新版本
pnpm version patch  # 0.1.0 → 0.1.1
pnpm version minor  # 0.1.1 → 0.2.0
pnpm version major  # 0.2.0 → 1.0.0

# 构建和发布
pnpm build
pnpm publish --access public

# 推送 tag
git push origin --tags

CI/CD

GitHub Actions 自动化:

PR: 代码检查、测试、构建
主分支: 自动测试
Tag: 自动发布 NPM

测试策略

测试层级

单元测试 (目标 >80%)
- 工具函数
- 格式化器
- 计算逻辑
集成测试
- API 客户端（Mock）
- 认证流程
端到端测试
- 完整命令执行
- 输出验证

命令

pnpm test              # 运行所有测试
pnpm test:coverage     # 覆盖率报告
pnpm test:watch        # watch 模式

性能优化

1. 缓存策略

// 缓存商户信息（15 分钟 TTL）
const cache = new Map();
const CACHE_TTL = 15 * 60 * 1000;

async function getMerchant(id: string) {
  const cached = cache.get(id);
  if (cached && Date.now() - cached.ts < CACHE_TTL) {
    return cached.data;
  }
  const data = await api.getMerchant(id);
  cache.set(id, { data, ts: Date.now() });
  return data;
}

2. 并发请求

// 并行请求
const [orders, products, stats] = await Promise.all([
  api.getOrders(),
  api.getProducts(),
  api.getStats()
]);

3. 分页加载

// 大数据量分页
async function* fetchOrders() {
  let page = 1;
  while (true) {
    const { data, hasMore } = await api.getOrders({ page, limit: 100 });
    yield data;
    if (!hasMore) break;
    page++;
  }
}

安全考虑

1. Token 安全

✅ 使用 conf 加密存储
✅ 不在日志中输出 Token
✅ 环境变量不提交 Git

2. API 权限

✅ 商户 CLI: 后端强制 merchant_id 过滤
✅ 平台 CLI: 需要 admin 角色验证
✅ 运维 CLI: 需要 ops 角色或系统权限

3. 数据脱敏

✅ 邮箱部分隐藏（us***@example.com）
✅ 手机号脱敏（138****5678）

路线图

阶段 1: 基础设施（第 1 周）

创建仓库和目录结构
编写架构文档
实现 cli-core 核心功能
发布 cli-core@0.1.0

阶段 2: 商户 CLI MVP（第 2-3 周）

阶段 3: 商户 CLI 完善（第 4 周）

客户分析模块
用户行为分析
完善测试（>80% 覆盖率）

阶段 4: 平台运营 CLI（第 5-6 周）

评估 Analytics 服务需求
实现核心分析功能
发布 platform-cli@1.0.0

阶段 5: 系统运维 CLI（第 7-8 周）

集成 CloudWatch SDK
实现监控和告警功能
发布 ops-cli@1.0.0

贡献指南

提交规范

使用 Conventional Commits:

feat: 新功能
fix: 修复 bug
docs: 文档更新
style: 代码格式
refactor: 重构
test: 测试
chore: 构建/工具

Pull Request

Fork 仓库
创建功能分支: git checkout -b feat/my-feature
提交代码: git commit -m "feat: add something"
推送分支: git push origin feat/my-feature
创建 PR

参考资料

联系方式

GitHub: https://github.com/Optima-Chat
Issues: 各仓库的 Issues 页面
Discussions: GitHub Discussions

维护者: Optima Development Team 最后更新: 2025-10-29

FilesExpand file tree

ARCHITECTURE.md

Latest commit

History