@cloud411716/fancy-webnovel 1.0.46 → 3.0.0

package/lib/error-codes.js

@@ -0,0 +1,104 @@
+/**
+ * lib/error-codes.js — 全插件统一错误码定义
+ *
+ * 所有 fancy-* 插件共享此文件，保证错误码命名一致。
+ *
+ * 使用：
+ *   import { EC, makeError } from '#error-codes';
+ *   console.log(JSON.stringify({ ok: false, error: makeError(EC.EC001_INVALID_PATH) }));
+ *
+ * 命名规则：
+ *   - ECxxx_NAME  全大写，下划线分隔
+ *   - code        数字（1-999）
+ *   - code_name   字符串 `ECxxx`，由 makeError 自动从 key 生成
+ *   - message     默认描述；调用方可用 makeError(EC.XXX, { message: '...' }) 覆盖
+ *
+ * 码段分配：
+ *   001-019  bootstrap    路径校验、初始化
+ *   020-039  scan         浏览器、采集、超时
+ *   040-059  topic        参数、phase、状态
+ *   060-079  bible        （预留）
+ *   080-099  outline      （预留）
+ *   100-119  write        （预留）
+ *   120-139  shared       通用（atomic-write、permission 等）
+ *   200+     system       致命错误
+ */
+
+export const EC = {
+  // ─── 001-019: bootstrap ───────────────────────────────────────
+  EC001_INVALID_PATH:        { code: 1,  message: '路径不合法（不能包含 .. 或 shell 特殊字符）。' },
+  EC002_ALREADY_INITIALIZED: { code: 2,  message: '项目已初始化，不能重复执行 init。' },
+  EC003_INVALID_PROJECT_ROOT:{ code: 3,  message: '项目根路径不是绝对路径，或不存在。' },
+  EC017_INIT_FAILED:         { code: 17, message: '初始化失败。' },
+  EC018_DIR_NOT_FOUND:       { code: 18, message: '目录不存在。' },
+  EC019_SENSITIVE_PATH:      { code: 19, message: '已拒绝访问系统受保护路径。' },
+
+  // ─── 020-039: scan ────────────────────────────────────────────
+  EC020_BROWSER_LAUNCH:      { code: 20, message: '浏览器启动失败' },
+  EC021_BROWSER_DISCONNECTED: { code: 21, message: '浏览器在采集过程中断开。' },
+  EC022_PAGE_GOTO_TIMEOUT:    { code: 22, message: '页面导航超时。' },
+  EC023_WAIT_RENDER_TIMEOUT:  { code: 23, message: '等待榜单渲染超时。' },
+  EC024_SCRAPER_TIMEOUT:      { code: 24, message: '采集子进程执行超时。' },
+  EC025_SCRAPER_NON_JSON:     { code: 25, message: '采集进程输出不是合法 JSON。' },
+  EC026_OCR_FAILED:           { code: 26, message: 'OCR 识别失败。' },
+  EC027_NO_OUTPUT_FILES:      { code: 27, message: '未找到采集输出文件。' },
+  EC028_INVALID_RANK:         { code: 28, message: '榜单 ID 无效或不受支持。' },
+  EC029_INVALID_PLATFORM_SCAN:{ code: 29, message: '平台不受支持。' },
+
+  // ─── 040-059: topic ───────────────────────────────────────────
+  EC040_INVALID_PLATFORM:    { code: 40, message: 'platform 参数无效。' },
+  EC041_INVALID_GENRE:       { code: 41, message: 'genre 参数无效。' },
+  EC042_MISSING_REQUIRED:    { code: 42, message: '缺少必填参数。' },
+  EC043_PHASE_NOT_TOPIC:     { code: 43, message: '当前工作区阶段不允许执行 fancy-topic。' },
+  EC044_TOPIC_STATE_MISSING: { code: 44, message: '未找到 _story_state.json。' },
+  EC045_TOPIC_WRITE_FAILED:   { code: 45, message: 'fancy-topic 写入文件失败。' },
+  EC046_INVALID_WORDS:        { code: 46, message: '目标字数无效，必须为正整数。' },
+  EC047_INVALID_CHAPTERS:     { code: 47, message: '目标章数无效，必须为正整数。' },
+  EC048_PLATFORM_NOT_FOUND:   { code: 48, message: 'topic_decision 中未找到该平台的内容块。' },
+
+  // ─── 120-139: shared ──────────────────────────────────────────
+  EC120_ATOMIC_WRITE_FAIL:   { code: 120, message: '原子写入文件失败。' },
+  EC121_PHASE_ADVANCE_FAIL:  { code: 121, message: '阶段状态推进失败。' },
+  EC122_PERMISSION_DENIED:   { code: 122, message: '权限不足。' },
+  EC123_JSON_PARSE_FAIL:     { code: 123, message: 'JSON 解析失败。' },
+  // "项目未初始化"与 EC002（项目已存在，不能重复 init）语义相反，
+  // 不能复用。此前 run-scan.js / select-topic.js 都把"未初始化"报成 EC002，
+  // 导致 code_name 与 message 自相矛盾（退出码 2 实际表示"未初始化"）。
+  EC124_PROJECT_NOT_INITIALIZED: { code: 124, message: '项目尚未初始化（.fancy-deployed 不存在）。' },
+
+  // ─── 200+: system ─────────────────────────────────────────────
+  EC200_SPAWN_FAIL:          { code: 200, message: '子进程启动失败。' },
+  EC201_SCRIPT_TIMEOUT:      { code: 201, message: '脚本执行超时。' },
+};
+
+/**
+ * 把 EC.XXX 引用转成标准 error 对象。
+ *
+ * @param {object} ec - EC.XXX 之一
+ * @param {object} [extra] - 额外字段：
+ *   - message: 覆盖默认 message
+ *   - 其他字段会合并进 error 对象
+ * @returns {{ code: number, code_name: string, message: string }}
+ */
+export function makeError(ec, extra = {}) {
+  if (!ec || typeof ec !== 'object' || typeof ec.code !== 'number') {
+    throw new Error('makeError: invalid EC reference');
+  }
+  // 自动从 EC 找到 key 名作为 code_name（如 'EC001_INVALID_PATH'）
+  const codeName = Object.keys(EC).find(k => EC[k] === ec) || `EC${String(ec.code).padStart(3, '0')}`;
+  return {
+    code: ec.code,
+    code_name: codeName,
+    message: extra.message || ec.message,
+    ...(extra && typeof extra === 'object' ? Object.fromEntries(
+      Object.entries(extra).filter(([k]) => k !== 'message')
+    ) : {}),
+  };
+}
+
+/**
+ * 便捷函数：直接拼出 ok:false 错误响应
+ */
+export function errorResponse(ec, extra = {}) {
+  return { ok: false, error: makeError(ec, extra) };
+}