candidate-pool 2.0.0

package/scaffold.js

@@ -0,0 +1,199 @@
+'use strict';
+/*
+ * scaffold.js —— 首次运行脚手架（Phase 1）
+ * ---------------------------------------------------------------------------
+ * 解决什么问题：
+ *   「拉代码运行」时仓库里什么都有；但装成 npm 包（或 npx）后，工作目录是空的，
+ *   首跑会直接因为缺 candidates.json 报错，或者跑出来「全市场塌成一个未分类」。
+ *   本模块在入口处做一次幂等的补齐，让空目录也能跑起来。
+ *
+ * 三条不可动摇的规则（都是为了向后兼容）：
+ *   1. **只创建缺失的目录，绝不覆盖任何已存在的文件**。
+ *      老仓库里已有的 candidates.json / notify_config.json / db/.env 一个字都不会动。
+ *   2. **不生成任何含凭据的配置文件**。
+ *      notify_config.json / db/.env 一旦被写入占位值，程序会从「未配置 → 跳过」
+ *      变成「配了但值是假的 → 真的去发/去连」，行为静默改变。这两份**只提示不创建**。
+ *   3. 重复调用零副作用（幂等），失败也只降级为提示、不阻断主流程。
+ *
+ * 补什么（全部可从包内模板/资产取得）：
+ *   <HOME>/data、reports、eod/data、eod/reports、db        目录
+ *   <HOME>/candidates.json    ← 包内 candidates.example.json（硬阻塞项，缺它直接报错）
+ *   eod/data/industry-map.json 不复制 —— eod/lib/sector.js 会直接回退读包内那份种子
+ *
+ * 不补什么（只打印提示，交给用户决定）：
+ *   notify_config.json  ← notify_config.example.json（推送凭据）
+ *   db/.env            ← db/.env.example（Cloudflare D1 凭据）
+ * ---------------------------------------------------------------------------
+ */
+
+const fs = require('fs');
+const path = require('path');
+const paths = require('./paths');
+
+/** 需要在工作目录里存在的目录（缺则建） */
+function dirs() {
+  return [
+    paths.dataDir(),
+    paths.reportsDir(),
+    paths.eodDataDir(),
+    paths.eodReportsDir(),
+    path.dirname(paths.localDb()),
+  ];
+}
+
+/**
+ * 播种文件：目标 ← 包内模板。
+ * 只放「缺失即硬报错」的项；candidates.json 是唯一一个。
+ */
+function seeds() {
+  return [
+    {
+      to: paths.candidatesFile(),
+      from: paths.codeAsset('candidates.example.json'),
+      label: '候选观察池',
+      required: true,
+      note: '来自示例模板（52 只，覆盖 26 个行业）。建议用 `node build_universe.js` 按自己的市值门槛重建。',
+    },
+  ];
+}
+
+/** 只提示、不创建的配置文件（含凭据，占位值会改变程序行为） */
+function hints() {
+  return [
+    {
+      to: paths.notifyConfigFile(),
+      from: paths.codeAsset('notify_config.example.json'),
+      label: '微信 / 邮件推送配置',
+      when: '需要跑完自动推送时',
+    },
+    {
+      to: paths.dbEnvFile(),
+      from: paths.codeAsset('db', '.env.example'),
+      label: 'Cloudflare D1 凭据（写入线上库用）',
+      when: '需要把结果同步到网页/D1 时',
+    },
+  ];
+}
+
+/** 是否处于「被当作依赖安装」的目录里（node_modules / npx 缓存） */
+function looksInstalled(dir = paths.home()) {
+  return /[\\/]node_modules[\\/]/.test(dir + path.sep);
+}
+
+/**
+ * 补齐工作目录。幂等、不覆盖、不抛错（内部错误降级为 warning）。
+ *
+ * @param {object} [o]
+ * @param {boolean} [o.force]  即使没有任何缺失也返回完整报告（`--init` 用）
+ * @returns {{home:string, source:string, relocated:boolean, installed:boolean,
+ *            createdDirs:string[], createdFiles:Array, hints:Array, missing:Array}}
+ */
+function ensureWorkspace({ force = false } = {}) {
+  const home = paths.home();
+  const createdDirs = [];
+  const createdFiles = [];
+  const missing = [];
+
+  for (const d of dirs()) {
+    if (fs.existsSync(d)) continue;
+    try {
+      fs.mkdirSync(d, { recursive: true });
+      createdDirs.push(d);
+    } catch (e) {
+      missing.push({ path: d, reason: String((e && e.message) || e) });
+    }
+  }
+
+  for (const s of seeds()) {
+    if (fs.existsSync(s.to)) continue;
+    if (!fs.existsSync(s.from)) {
+      // 包内模板都不在（例如被 --ignore-files 裁掉）→ 不阻断，交给上游报错
+      missing.push({ path: s.to, reason: `包内模板缺失：${s.from}` });
+      continue;
+    }
+    try {
+      fs.copyFileSync(s.from, s.to);
+      createdFiles.push(s);
+    } catch (e) {
+      missing.push({ path: s.to, reason: String((e && e.message) || e) });
+    }
+  }
+
+  return {
+    home,
+    source: paths.homeSource(),
+    relocated: paths.isRelocated(),
+    installed: looksInstalled(home),
+    createdDirs,
+    createdFiles,
+    hints: hints().filter((h) => !fs.existsSync(h.to)),
+    missing,
+    force,
+  };
+}
+
+/** 把报告渲染成若干行日志（没有任何变化时返回空数组，保持静默） */
+function renderReport(r) {
+  const lines = [];
+  const changed = r.createdDirs.length + r.createdFiles.length;
+  if (!changed && !r.missing.length) return lines;
+
+  lines.push('── 首次运行脚手架 ──');
+  for (const d of r.createdDirs) lines.push(`  新建目录 ${d}`);
+  for (const f of r.createdFiles) {
+    lines.push(`  创建文件 ${f.to}`);
+    lines.push(`          ↳ ${f.label}：${f.note}`);
+  }
+  for (const m of r.missing) lines.push(`  ⚠ 未能创建 ${m.path}（${m.reason}）`);
+
+  if (r.installed) {
+    lines.push('');
+    lines.push('  ⚠ 当前工作目录在 node_modules 里 —— 产物会随重装/npx 清缓存一起丢失。');
+    lines.push('    建议显式指定工作目录，例如：');
+    lines.push('      npx candidate-pool --cwd ~/my-pool');
+    lines.push('      # 或 export CANDIDATE_POOL_HOME=~/my-pool');
+  }
+  return lines;
+}
+
+/** 提示可选配置（只在用户显式 `--init` 时打印，避免日常刷屏） */
+function renderHints(r) {
+  if (!r.hints.length) return [];
+  const lines = ['', '── 可选配置（未自动创建，需要时手动复制）──'];
+  for (const h of r.hints) {
+    lines.push(`  ${h.label}（${h.when}）：`);
+    lines.push(`    cp "${h.from}" "${h.to}"`);
+  }
+  return lines;
+}
+
+/**
+ * 入口处调用：补齐工作目录并按需打印。
+ * 日常运行只在实际创建了东西时才有输出（正常情况下完全静默）。
+ *
+ * @param {object} [o]
+ * @param {(s:string)=>void} [o.log]  日志函数（默认 console.log）
+ * @param {boolean} [o.init]          显式 `--init`：无条件打印报告 + 可选配置提示
+ */
+function autoInit({ log = console.log, init = false } = {}) {
+  let r;
+  try {
+    r = ensureWorkspace({ force: init });
+  } catch (e) {
+    log(`⚠ 工作目录初始化失败（已忽略，继续运行）：${(e && e.message) || e}`);
+    return null;
+  }
+  // `--init` 是「我想确认一下环境」的显式请求 → 无论有没有变化都要有回音；
+  // 日常运行则完全静默（只在实际创建了东西时出声）。
+  if (init) {
+    const report = renderReport(r);
+    if (report.length) for (const l of report) log(l);
+    else log(`── 工作目录已就绪（无需创建任何文件）──  ${r.home}  [${r.source}]`);
+    for (const l of renderHints(r)) log(l);
+    return r;
+  }
+  for (const l of renderReport(r)) log(l);
+  return r;
+}
+
+module.exports = { ensureWorkspace, autoInit, renderReport, renderHints, dirs, seeds, hints, looksInstalled };

package/scaffold.selftest.js

@@ -0,0 +1,153 @@
+'use strict';
+/*
+ * scaffold.selftest.js —— 首次运行脚手架的回归自测
+ * ---------------------------------------------------------------------------
+ * 为什么必须自测：脚手架是**唯一会往用户目录写文件**的自动流程。它一旦越界
+ * （覆盖已有配置、写出占位凭据），后果是「用户的数据没了」或「程序行为静默改变」，
+ * 而且只在首次运行时发生 —— 手工测一次根本触发不到第二次。
+ *
+ * 覆盖：创建 / 不覆盖 / 幂等 / 不造凭据 / 包内安装判定 / 静默输出。
+ * 用法：node scaffold.selftest.js
+ * ---------------------------------------------------------------------------
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const paths = require('./paths');
+const scaffold = require('./scaffold');
+
+let failed = 0;
+const tmpDirs = [];
+
+function check(name, ok, detail) {
+  if (ok) console.log(`  OK   ${name}`);
+  else { failed++; console.log(`  FAIL ${name}${detail === undefined ? '' : `  → ${detail}`}`); }
+}
+
+function mkTmp(tag) {
+  const d = fs.mkdtempSync(path.join(os.tmpdir(), `cp-scaffold-${tag}-`));
+  tmpDirs.push(d);
+  return d;
+}
+
+function cleanup() {
+  for (const d of tmpDirs) {
+    try { fs.rmSync(d, { recursive: true, force: true }); } catch { /* 忽略 */ }
+  }
+}
+
+const read = (p) => fs.readFileSync(p, 'utf8');
+
+console.log('[1] 空目录（重定位）：应补齐目录与观察池');
+{
+  const H = mkTmp('empty');
+  paths.setHome(H);
+  const r = scaffold.ensureWorkspace();
+
+  for (const [k, p] of Object.entries({
+    data: paths.dataDir(), reports: paths.reportsDir(),
+    'eod/data': paths.eodDataDir(), 'eod/reports': paths.eodReportsDir(), db: path.dirname(paths.localDb()),
+  })) {
+    check(`创建目录 ${k}`, fs.existsSync(p), p);
+  }
+  check('candidates.json 已从示例模板生成', fs.existsSync(paths.candidatesFile()), paths.candidatesFile());
+  const j = JSON.parse(read(paths.candidatesFile()));
+  check('生成的观察池结构正确（stocks 非空）', Array.isArray(j.stocks) && j.stocks.length > 0, `stocks=${j.stocks && j.stocks.length}`);
+  check('生成的观察池带示例说明', /示例/.test(String(j.note || '')), j.note);
+  check('createdFiles 记录 1 项', r.createdFiles.length === 1, String(r.createdFiles.length));
+  check('relocated=true（HOME 不是包根）', r.relocated === true, String(r.relocated));
+  check('source=setHome()', r.source === 'setHome()', r.source);
+  check('installed=false（临时目录不在 node_modules 下）', r.installed === false, String(r.installed));
+}
+
+console.log('\n[2] 绝不写入含凭据的配置文件');
+{
+  const H = mkTmp('creds');
+  paths.setHome(H);
+  scaffold.ensureWorkspace();
+  check('未创建 notify_config.json', !fs.existsSync(paths.notifyConfigFile()), paths.notifyConfigFile());
+  check('未创建 db/.env', !fs.existsSync(paths.dbEnvFile()), paths.dbEnvFile());
+  const r = scaffold.ensureWorkspace();
+  check('两份凭据以「提示」形式给出', r.hints.length === 2, JSON.stringify(r.hints.map((h) => path.basename(h.to))));
+  check('提示里带可复制的命令', scaffold.renderHints(r).some((l) => /^\s+cp "/.test(l)), 'no cp line');
+}
+
+console.log('\n[3] 绝不覆盖已存在的文件（向后兼容的核心）');
+{
+  const H = mkTmp('keep');
+  paths.setHome(H);
+  fs.mkdirSync(H, { recursive: true });
+  const mine = JSON.stringify({ name: '我的观察池', stocks: [{ code: 'sh600519', name: '贵州茅台', sector: '食品饮料' }] }, null, 2);
+  fs.writeFileSync(paths.candidatesFile(), mine);
+  fs.writeFileSync(paths.notifyConfigFile(), '{"wechat":{"key":"MY_REAL_KEY"}}');
+
+  const r = scaffold.ensureWorkspace();
+  check('已有 candidates.json 内容未被改写', read(paths.candidatesFile()) === mine, 'content changed');
+  check('已有 candidates.json 未被重新生成', r.createdFiles.length === 0, String(r.createdFiles.length));
+  check('已有 notify_config.json 原样保留', /MY_REAL_KEY/.test(read(paths.notifyConfigFile())), 'changed');
+  check('已有的那份不再出现在提示里', !r.hints.some((h) => h.to === paths.notifyConfigFile()), 'still hinted');
+}
+
+console.log('\n[4] 幂等：重复调用零副作用');
+{
+  const H = mkTmp('idem');
+  paths.setHome(H);
+  const a = scaffold.ensureWorkspace();
+  const before = read(paths.candidatesFile());
+  const b = scaffold.ensureWorkspace();
+  const c = scaffold.ensureWorkspace();
+  check('第二次调用不创建任何目录', b.createdDirs.length === 0, String(b.createdDirs.length));
+  check('第二次调用不创建任何文件', b.createdFiles.length === 0, String(b.createdFiles.length));
+  check('第三次调用同样为空', c.createdDirs.length + c.createdFiles.length === 0, 'not empty');
+  check('文件内容稳定', read(paths.candidatesFile()) === before, 'content drift');
+  check('首次确实创建了东西（对照）', a.createdDirs.length + a.createdFiles.length > 0, 'nothing created at all');
+}
+
+console.log('\n[5] 输出：无事发生时保持静默');
+{
+  const H = mkTmp('quiet');
+  paths.setHome(H);
+  scaffold.ensureWorkspace();
+  const silent = scaffold.ensureWorkspace();
+  check('无变化 → renderReport 为空数组', scaffold.renderReport(silent).length === 0, JSON.stringify(scaffold.renderReport(silent)));
+  const lines = [];
+  scaffold.autoInit({ log: (s) => lines.push(s) });
+  check('无变化 → autoInit 不打任何日志', lines.length === 0, lines.join(' | '));
+
+  const lines2 = [];
+  scaffold.autoInit({ log: (s) => lines2.push(s), init: true });
+  check('--init 即使无变化也有输出', lines2.length > 0, 'silent');
+  check('--init 输出含「已就绪」', lines2.some((l) => /已就绪/.test(l)), lines2.join(' | '));
+}
+
+console.log('\n[6] node_modules 安装场景：应给出重定位警告');
+{
+  const H = path.join(mkTmp('nm'), 'node_modules', 'candidate-pool');
+  fs.mkdirSync(H, { recursive: true });
+  paths.setHome(H);
+  const r = scaffold.ensureWorkspace();
+  check('installed=true', r.installed === true, String(r.installed));
+  const report = scaffold.renderReport(r).join('\n');
+  check('报告里出现重定位警告', /node_modules/.test(report) && /--cwd/.test(report), report);
+}
+
+console.log('\n[7] 默认（包根）行为：本仓库已有全部文件 → 不创建、不改动');
+{
+  paths.setHome(null);
+  check('HOME 回到包根', paths.home() === paths.PKG_ROOT, paths.home());
+  const before = fs.existsSync(paths.candidatesFile()) ? read(paths.candidatesFile()) : null;
+  const r = scaffold.ensureWorkspace();
+  check('未创建任何文件（仓库里都齐了）', r.createdFiles.length === 0, JSON.stringify(r.createdFiles.map((f) => f.to)));
+  if (before !== null) {
+    check('仓库里的 candidates.json 未被改动', read(paths.candidatesFile()) === before, 'changed');
+    check('仓库里的 candidates.json 不是示例模板', !/示例模板/.test(read(paths.candidatesFile())), 'overwritten by template');
+  } else {
+    check('仓库里的 candidates.json 跳过（不存在，不适用）', true);
+  }
+  check('PKG_ROOT 下没有 node_modules 判定', scaffold.looksInstalled(paths.PKG_ROOT) === false, 'misdetected');
+}
+
+cleanup();
+console.log(failed ? `\n自我检查失败：${failed} 项` : '\n全部通过');
+process.exit(failed ? 1 : 0);

package/time.js

@@ -0,0 +1,17 @@
+'use strict';
+// 统一时间处理：所有业务时间一律走 dayjs（全局规则）。
+// 业务时区锁定 Asia/Shanghai，落库/展示统一用北京时间字符串（YYYY-MM-DD HH:mm:ss，无 Z），
+// 根治裸 new Date().toISOString() 带来的 +8h 时差问题。
+const dayjs = require('dayjs');
+const utc = require('dayjs/plugin/utc');
+const tz = require('dayjs/plugin/timezone');
+dayjs.extend(utc);
+dayjs.extend(tz);
+dayjs.tz.setDefault('Asia/Shanghai');
+
+// 当前北京时间字符串（YYYY-MM-DD HH:mm:ss），无 Z
+function now() {
+  return dayjs.tz().format('YYYY-MM-DD HH:mm:ss');
+}
+
+module.exports = { now, dayjs };