@lichidental/saas-cli 0.0.0-stage → 1.0.1

package/lib/http.mjs

@@ -0,0 +1,106 @@
+// lib/http.mjs — HTTP 传输层:环境地址、请求头、版本号、统一响应解包
+import { CliError, EXIT_CODES, mapApiError } from "./errors.mjs"
+
+export const ENV_BASE_URLS = {
+  test: "https://test.saas.lichidental.com",
+  pre: "https://pre.saas.lichidental.com",
+  prod: "https://saas.lichidental.com",
+}
+
+const TIMEOUT_MS = 15000
+
+// 版本号缓存:每个环境只解析一次
+const versionCache = new Map()
+
+/**
+ * 从 <环境地址>/index.html 解析 <meta name="version"> 的值。
+ * 请求头 Version 用于后端版本校验(不一致会返回 status 999),解析失败返回 null(省略该头继续请求)。
+ * @param {string} baseUrl
+ * @returns {Promise<string|null>}
+ */
+export async function fetchVersion(baseUrl) {
+  if (versionCache.has(baseUrl)) return versionCache.get(baseUrl)
+  let version = null
+  try {
+    const res = await fetch(`${baseUrl}/index.html`, { signal: AbortSignal.timeout(TIMEOUT_MS) })
+    const html = await res.text()
+    const m =
+      html.match(/<meta[^>]*\sname=["']version["'][^>]*\scontent=["']([^"']+)["']/i) ||
+      html.match(/<meta[^>]*\scontent=["']([^"']+)["'][^>]*\sname=["']version["']/i)
+    if (m) version = m[1]
+  } catch {
+    // 忽略:拿不到版本号时不带 Version 头
+  }
+  versionCache.set(baseUrl, version)
+  return version
+}
+
+function maskToken(token) {
+  if (!token || token.length <= 8) return "****"
+  return `${token.slice(0, 4)}****${token.slice(-4)}`
+}
+
+/**
+ * 创建请求器(所有接口均为 POST + JSON,统一响应 {status, code, message, data})
+ * @param {{env: string, token: string, verbose?: boolean, log?: (...args: any[]) => void}} options
+ * @returns {import("./types.mjs").Http}
+ */
+export function createHttp({ env, token, verbose = false, log = () => {} }) {
+  const baseUrl = ENV_BASE_URLS[env]
+  if (!baseUrl) {
+    throw new CliError(`未知环境「${env}」,可选:${Object.keys(ENV_BASE_URLS).join(" / ")}`, {
+      exitCode: EXIT_CODES.USAGE,
+    })
+  }
+
+  async function post(path, body) {
+    const version = await fetchVersion(baseUrl)
+    const url = `${baseUrl}${path}`
+    const headers = {
+      "Content-Type": "application/json;charset=UTF-8",
+      token,
+    }
+    if (version) {
+      headers.Version = version
+      headers.channel = "html"
+    }
+    if (verbose) {
+      log(`→ POST ${url}`)
+      log(`  请求头: token=${maskToken(token)}${version ? `, Version=${version}, channel=html` : ""}`)
+      log(`  请求体: ${JSON.stringify(body ?? {})}`)
+    }
+    let res
+    try {
+      res = await fetch(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body ?? {}),
+        signal: AbortSignal.timeout(TIMEOUT_MS),
+      })
+    } catch (err) {
+      throw new CliError(`网络请求失败:${err?.message ?? err}`, {
+        exitCode: EXIT_CODES.NETWORK,
+        hint: `请求地址:${url}`,
+      })
+    }
+    let payload
+    try {
+      payload = await res.json()
+    } catch {
+      throw new CliError(`响应不是合法 JSON(HTTP ${res.status})`, {
+        exitCode: EXIT_CODES.NETWORK,
+        hint: `请求地址:${url}`,
+      })
+    }
+    if (verbose) log(`← HTTP ${res.status} ${JSON.stringify(payload)}`)
+    if (payload && typeof payload === "object" && "status" in payload) {
+      if (payload.status === 200) return payload
+      throw mapApiError(payload)
+    }
+    throw new CliError(`响应格式异常(缺少 status 字段):${JSON.stringify(payload).slice(0, 200)}`, {
+      exitCode: EXIT_CODES.NETWORK,
+    })
+  }
+
+  return { post, baseUrl, env }
+}

package/lib/match.mjs

@@ -0,0 +1,39 @@
+// lib/match.mjs — 名称 → 唯一候选解析(重名时不瞎猜,列候选让使用者指定)
+import { CliError, EXIT_CODES } from "./errors.mjs"
+
+/**
+ * 从候选列表中挑出唯一一项:
+ * 先精确匹配(全等),没有再模糊匹配(包含);命中 0 条或多条都报错
+ * @template T
+ * @param {T[]} items 候选列表
+ * @param {object} opts
+ * @param {(item: T) => Array<string | number | null | undefined>} opts.match 参与匹配的字段取值函数
+ * @param {(item: T) => string} opts.describe 多命中时展示候选行的函数
+ * @param {string} opts.input 使用者输入
+ * @param {string} opts.label 名词(如 "患者" / "医生")
+ * @param {string} [opts.hint] 报错时的补充提示
+ * @returns {T}
+ */
+export function pickOne(items, { match, describe, input, label, hint }) {
+  const norm = (v) => String(v ?? "").trim()
+  const target = norm(input)
+  const exact = items.filter((it) => match(it).some((v) => norm(v) === target))
+  const hit = exact.length
+    ? exact
+    : items.filter((it) =>
+        match(it).some((v) => {
+          const vv = norm(v)
+          return vv !== "" && vv.includes(target)
+        })
+      )
+
+  if (hit.length === 1) return hit[0]
+  if (hit.length === 0) {
+    throw new CliError(`未找到${label}「${input}」`, { exitCode: EXIT_CODES.USAGE, hint })
+  }
+  const lines = hit.map((it) => `    - ${describe(it)}`).join("\n")
+  throw new CliError(`${label}「${input}」匹配到 ${hit.length} 条,无法确定是哪一条:\n${lines}`, {
+    exitCode: EXIT_CODES.USAGE,
+    hint,
+  })
+}

package/lib/options.mjs

@@ -0,0 +1,32 @@
+// lib/options.mjs — 每个命令共用的全局选项(--env / --token / --json / --verbose)
+import { CliError, EXIT_CODES } from "./errors.mjs"
+
+/**
+ * 给命令挂上通用选项。挂在命令级而不是 program 级,这样选项可以出现在命令后的任意位置,
+ * 例如:saas-cli reservation create --env test --patient 张三
+ * @param {import("commander").Command} cmd
+ * @returns {import("commander").Command}
+ */
+export function addCommonOptions(cmd) {
+  return cmd
+    .option("--env <env>", "环境:test | pre | prod", "test")
+    .option("--token <token>", "接口 token(默认读环境变量 SAAS_TOKEN 或配置文件)")
+    .option("--json", "输出结构化 JSON(默认输出人读摘要)")
+    .option("--verbose", "打印请求/响应详情(token 脱敏)")
+}
+
+/**
+ * 校验"需要值"的选项的取值是否像另一个选项。
+ * commander 会把紧跟选项的下一个 token 当作它的值(如 `--remark --dry-run` 时 remark 取到 "--dry-run"),
+ * 以 - 开头说明使用者很可能漏写了值,提前拦下,避免静默用错值(如 --dry-run 被吞后变成真实创建)。
+ * @param {string|undefined|null} value 使用者传入的值
+ * @param {{option: string, hint?: string}} opts option 为选项名(如 "--doctor-id")
+ */
+export function assertValueNotOptionLike(value, { option, hint }) {
+  if (typeof value === "string" && value.startsWith("-")) {
+    throw new CliError(`${option} 的值看起来是另一个选项(「${value}」),请检查是否漏写了它的值`, {
+      exitCode: EXIT_CODES.USAGE,
+      hint: hint ?? `用法:${option} <值>;选项后面要紧跟自己的值,不能接其他选项`,
+    })
+  }
+}

package/lib/output.mjs

@@ -0,0 +1,31 @@
+// lib/output.mjs — 输出约定:stdout 只放数据(人读摘要 / JSON),日志一律走 stderr
+
+/**
+ * 创建输出器
+ * @param {{json?: boolean, verbose?: boolean}} [options]
+ * @returns {import("./types.mjs").Output}
+ */
+export function createOutput({ json = false, verbose = false } = {}) {
+  const log = (...args) => console.error(...args)
+  const verboseLog = verbose ? (...args) => console.error(...args) : () => {}
+
+  return {
+    log,
+    verboseLog,
+    isJson: json,
+    /**
+     * 成功输出
+     * @param {string} command 命令名(如 "reservation create")
+     * @param {string} env 环境
+     * @param {object} data 结构化数据(JSON 模式下的 data 字段)
+     * @param {string} [humanText] 人读摘要(默认模式输出;JSON 模式忽略)
+     */
+    success(command, env, data, humanText) {
+      if (json) {
+        console.log(JSON.stringify({ ok: true, env, command, data }, null, 2))
+      } else if (humanText) {
+        console.log(humanText)
+      }
+    },
+  }
+}

package/lib/time.mjs

@@ -0,0 +1,41 @@
+// lib/time.mjs — 时间解析与格式化(统一以本机本地时区为准)
+import { CliError, EXIT_CODES } from "./errors.mjs"
+
+const pad = (n) => String(n).padStart(2, "0")
+
+/** Date → "YYYY-MM-DD HH:mm:ss" @param {Date} d @returns {string} */
+export function formatDateTime(d) {
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`
+}
+
+/** Date → "YYYY-MM-DD HH:mm" @param {Date} d @returns {string} */
+export function formatMinute(d) {
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}`
+}
+
+/** Date → "YYYY-MM-DD" @param {Date} d @returns {string} */
+export function formatDate(d) {
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`
+}
+
+/**
+ * 解析使用者传入的时间,支持:
+ * - 省略 → 当前时间
+ * - "YYYY-MM-DD HH:mm"
+ * - "YYYY-MM-DD HH:mm:ss"
+ * @param {string|undefined} input
+ * @returns {Date}
+ */
+export function parseUserTime(input) {
+  if (!input) return new Date()
+  const s = String(input).trim()
+  const m = s.match(/^(\d{4})-(\d{2})-(\d{2})[ T](\d{2}):(\d{2})(?::(\d{2}))?$/)
+  if (!m) {
+    throw new CliError(`时间格式不正确:「${input}」`, {
+      exitCode: EXIT_CODES.USAGE,
+      hint: '正确格式:--time "2026-10-15 10:00" 或 "2026-10-15 10:00:00";省略则用当前时间',
+    })
+  }
+  const [, y, mo, d, h, mi, se] = m
+  return new Date(Number(y), Number(mo) - 1, Number(d), Number(h), Number(mi), Number(se ?? 0))
+}

package/lib/types.mjs

@@ -0,0 +1,51 @@
+// lib/types.mjs — 核心数据结构类型定义(纯 JSDoc,无运行代码)
+// 供各文件通过 import("./types.mjs").Xxx 引用,提升 IDE 的跳转 / 提示 / 重构体验。
+
+/**
+ * 统一响应包装(所有后端接口返回的结构)
+ * @typedef {{status: number, code?: string, message?: string, data?: any}} ApiResponse
+ */
+
+/**
+ * 请求器(由 lib/http.mjs 的 createHttp 返回)
+ * @typedef {{post: (path: string, body?: object) => Promise<ApiResponse>, baseUrl: string, env: string}} Http
+ */
+
+/**
+ * 医生 / 员工(getStoreUserListByParam 返回元素)
+ * @typedef {{userUid: string | number, storeUserName?: string, userName?: string,
+ *   storeUserPostIds?: string[], delFlag?: number}} Doctor
+ */
+
+/**
+ * 患者(customParamPageList 的 data.list 元素)
+ * @typedef {{customCode: string, customName?: string, customPhone?: string,
+ *   codeNum?: string, sex?: number}} Patient
+ */
+
+/**
+ * 预约记录(customMarkListByCustom 返回的 data.cmList 元素)
+ * @typedef {{id: number, clinicId?: number, customCode?: string, codeNum?: string,
+ *   customName?: string, customPhone?: string, doctorId?: string | number,
+ *   boolFirst?: number, markDate?: string, markStartTime?: string, markEndTime?: string,
+ *   markTimeLength?: number, treatItemJson?: string, remark?: string, status?: number}} CustomMark
+ */
+
+/**
+ * 预约项目(getTreatItemList 返回元素)
+ * @typedef {{id: number, treatItemName: string, treatItemTitle?: string,
+ *   upTreatItemId?: number, level?: number}} TreatItem
+ */
+
+/**
+ * treatItemJson 字符串解析后的元素
+ * @typedef {{up_id: number, up_title: string, id: number, title: string}} TreatItemJsonItem
+ */
+
+/**
+ * 命令的输出器(由 lib/output.mjs 的 createOutput 返回)
+ * @typedef {{log: (...args: any[]) => void, verboseLog: (...args: any[]) => void,
+ *   isJson: boolean, success: (command: string, env: string, data: object, humanText?: string) => void}} Output
+ */
+
+export {}

package/lib/update-check.mjs

@@ -0,0 +1,112 @@
+// lib/update-check.mjs — 版本更新提醒(对齐 lark-cli:24h 缓存 + 一行 stderr 提示,全程静默失败)
+// 机制:启动时同步读本地缓存(毫秒级)决定是否提示;缓存过期时后台发起刷新(socket unref,不阻塞进程退出)
+import fs from "node:fs"
+import path from "node:path"
+import http from "node:http"
+import https from "node:https"
+import { getConfigPath } from "./config.mjs"
+
+const PKG_NAME = "@lichidental/saas-cli"
+const DEFAULT_REGISTRY = "https://registry.npmjs.org"
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000
+const FETCH_TIMEOUT_MS = 2500
+
+/** 更新状态缓存文件(与配置文件同目录) @returns {string} */
+export function getUpdateStatePath() {
+  return path.join(path.dirname(getConfigPath()), "update-state.json")
+}
+
+/**
+ * 版本号比较(仅支持 x.y.z 数字段)
+ * @param {string} a
+ * @param {string} b
+ * @returns {number} a<b 返回 -1,a=b 返回 0,a>b 返回 1;格式非法时返回 0(视为相等,不提示)
+ */
+export function compareVersions(a, b) {
+  const pa = String(a ?? "").split(".").map((n) => parseInt(n, 10))
+  const pb = String(b ?? "").split(".").map((n) => parseInt(n, 10))
+  if (pa.length === 0 || pb.length === 0 || pa.some(Number.isNaN) || pb.some(Number.isNaN)) return 0
+  const len = Math.max(pa.length, pb.length)
+  for (let i = 0; i < len; i++) {
+    const x = pa[i] ?? 0
+    const y = pb[i] ?? 0
+    if (x < y) return -1
+    if (x > y) return 1
+  }
+  return 0
+}
+
+/** 读取更新状态缓存,失败返回空对象 */
+function readState() {
+  try {
+    const s = JSON.parse(fs.readFileSync(getUpdateStatePath(), "utf8"))
+    return s && typeof s === "object" ? s : {}
+  } catch {
+    return {}
+  }
+}
+
+/** 写入更新状态缓存(失败静默) */
+function writeState(state) {
+  try {
+    const file = getUpdateStatePath()
+    fs.mkdirSync(path.dirname(file), { recursive: true })
+    fs.writeFileSync(file, JSON.stringify(state) + "\n")
+  } catch {
+    // 缓存写失败不影响任何功能
+  }
+}
+
+/** 后台刷新版本缓存:socket unref 不阻塞进程退出;任何失败静默 */
+function refreshInBackground() {
+  try {
+    const registry = (process.env.SAAS_CLI_REGISTRY || DEFAULT_REGISTRY).replace(/\/+$/, "")
+    const url = `${registry}/${encodeURIComponent(PKG_NAME)}/latest`
+    const mod = url.startsWith("https:") ? https : http
+    const req = mod.get(url, { timeout: FETCH_TIMEOUT_MS, headers: { accept: "application/json" } }, (res) => {
+      if (res.statusCode !== 200) {
+        res.resume()
+        return
+      }
+      let body = ""
+      res.on("data", (c) => (body += c))
+      res.on("end", () => {
+        try {
+          const latest = JSON.parse(body)?.version
+          if (latest) writeState({ checkedAt: Date.now(), latestVersion: String(latest) })
+        } catch {
+          // 静默
+        }
+      })
+    })
+    req.on("socket", (s) => s.unref())
+    req.on("timeout", () => req.destroy())
+    req.on("error", () => {})
+  } catch {
+    // 静默
+  }
+}
+
+/**
+ * 版本更新检查(启动时调用):
+ * 1) 用本地缓存同步提示(毫秒级,不联网):发现新版本时向 stderr 打一行提示
+ * 2) 缓存超过 24h 时后台刷新(不阻塞)
+ * 永不抛出、永不阻塞。SAAS_CLI_NO_UPDATE_CHECK=1 可整体关闭。
+ * @param {string} currentVersion 当前版本(来自 package.json)
+ */
+export function checkForUpdate(currentVersion) {
+  try {
+    if (process.env.SAAS_CLI_NO_UPDATE_CHECK === "1") return
+    const state = readState()
+    const latest = state.latestVersion
+    if (latest && compareVersions(currentVersion, latest) < 0) {
+      console.error(`提示:发现新版本 ${latest}(当前 ${currentVersion}),升级: npm i -g ${PKG_NAME}@latest`)
+    }
+    const checkedAt = Number(state.checkedAt ?? 0)
+    if (!Number.isFinite(checkedAt) || Date.now() - checkedAt > CHECK_INTERVAL_MS) {
+      refreshInBackground()
+    }
+  } catch {
+    // 检查永不阻塞主流程
+  }
+}

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@lichidental/saas-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "励齿 SaaS 数据操作 CLI:新建预约、查询医生/患者/预约项目等",
+  "type": "module",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "bin": {
+    "saas-cli": "./cli.mjs"
+  },
+  "files": [
+    "cli.mjs",
+    "commands",
+    "lib",
+    "api",
+    "README.md",
+    "AGENTS.md",
+    "docs/CLI使用手册.md",
+    "docs/开发指南.md",
+    "docs/api/openapi.yaml",
+    "docs/api/接口说明.md"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://lichigit.lichidental.com/sass/create-saas-cli.git"
+  },
+  "dependencies": {
+    "commander": "^15.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.5"
+  }
+}