candidate-pool 2.0.0

package/notify.js

@@ -0,0 +1,236 @@
+'use strict';
+/*
+ * notify.js
+ * ---------------------------------------------------------------------------
+ * 实时结果推送（零外部依赖，仅用 Node 内置 https / tls）：
+ *   - 个人微信：Server酱 (sctapi.ftqq.com) 或 PushPlus (pushplus.plus)
+ *   - 163 邮箱：SMTP_SSL (smtp.163.com:465)，HTML 报告作为附件发送
+ *
+ * 配置来源（凭据不要写进脚本 / 不要提交）：
+ *   notify_config.json  或  环境变量（NOTIFY_WX_KEY / NOTIFY_WX_TOKEN /
+ *   NOTIFY_WX_PROVIDER / NOTIFY_MAIL_SENDER / NOTIFY_MAIL_AUTH /
+ *   NOTIFY_MAIL_RECEIVER / NOTIFY_MAIL_HOST / NOTIFY_MAIL_PORT）
+ *
+ * 用法（在 gen_candidates.js 中 require 后调用）：
+ *   const { notify } = require('./notify');
+ *   await notify({ title, content, htmlPath });
+ * ---------------------------------------------------------------------------
+ */
+const fs = require('fs');
+const path = require('path');
+const https = require('https');
+const tls = require('tls');
+const { URL } = require('url');
+const paths = require('./paths');
+
+// 配置位置跟随工作目录（见 paths.js）：默认 <仓库根>/notify_config.json，
+// 重定位后为 <HOME>/notify_config.json。
+function cfgPath() { return paths.notifyConfigFile(); }
+
+function loadCfg() {
+  const cfg = {};
+  const CFG_PATH = cfgPath();
+  if (fs.existsSync(CFG_PATH)) {
+    try { Object.assign(cfg, JSON.parse(fs.readFileSync(CFG_PATH, 'utf8'))); } catch (e) { /* 损坏则忽略 */ }
+  }
+  const wx = cfg.wechat || (cfg.wechat = {});
+  if (process.env.NOTIFY_WX_KEY) wx.key = process.env.NOTIFY_WX_KEY;
+  if (process.env.NOTIFY_WX_TOKEN) wx.token = process.env.NOTIFY_WX_TOKEN;
+  if (process.env.NOTIFY_WX_PROVIDER) wx.provider = process.env.NOTIFY_WX_PROVIDER;
+  const em = cfg.email || (cfg.email = {});
+  const map = {
+    sender: 'NOTIFY_MAIL_SENDER', auth_code: 'NOTIFY_MAIL_AUTH',
+    receiver: 'NOTIFY_MAIL_RECEIVER', smtp_host: 'NOTIFY_MAIL_HOST', smtp_port: 'NOTIFY_MAIL_PORT',
+  };
+  for (const k in map) if (process.env[map[k]]) em[k] = process.env[map[k]];
+  return cfg;
+}
+
+// ---------- HTTP POST ----------
+function postForm(urlStr, form, json) {
+  return new Promise((resolve, reject) => {
+    const u = new URL(urlStr);
+    const body = json
+      ? JSON.stringify(form)
+      : Object.keys(form).map(k => encodeURIComponent(k) + '=' + encodeURIComponent(form[k])).join('&');
+    const req = https.request({
+      hostname: u.hostname,
+      path: u.pathname + (u.search || ''),
+      method: 'POST',
+      headers: {
+        'Content-Type': json ? 'application/json' : 'application/x-www-form-urlencoded',
+        'Content-Length': Buffer.byteLength(body),
+      },
+    }, res => {
+      let data = '';
+      res.on('data', c => (data += c));
+      res.on('end', () => resolve({ status: res.statusCode, body: data }));
+    });
+    req.on('error', reject);
+    req.write(body);
+    req.end();
+  });
+}
+
+// ---------- 微信推送 ----------
+async function pushWechat(title, content, cfg) {
+  const w = cfg.wechat || {};
+  const provider = (w.provider || 'serverchan').toLowerCase();
+  try {
+    if (provider === 'serverchan') {
+      const key = w.key || process.env.NOTIFY_WX_KEY;
+      if (!key) return [false, '缺少 serverchan key'];
+      const r = await postForm(`https://sctapi.ftqq.com/${key}.send`, { title, desp: content });
+      let d; try { d = JSON.parse(r.body); } catch (e) { d = {}; }
+      return [(d.code === 0 || d.errno === 0), d];
+    } else if (provider === 'pushplus') {
+      const token = w.token || process.env.NOTIFY_WX_TOKEN;
+      if (!token) return [false, '缺少 pushplus token'];
+      const r = await postForm('https://www.pushplus.plus/send',
+        { token, title, content, template: 'markdown' }, true);
+      let d; try { d = JSON.parse(r.body); } catch (e) { d = {}; }
+      return [d.code === 200, d];
+    }
+    return [false, '未知 provider: ' + provider];
+  } catch (e) {
+    return [false, String(e && e.message || e)];
+  }
+}
+
+// ---------- 163 邮箱（最小 SMTP_SSL 客户端，无 nodemailer 依赖）----------
+function smtpSend({ host, port, user, pass, from, to, subject, text, htmlPath }) {
+  return new Promise((resolve, reject) => {
+    const socket = tls.connect({ host, port: Number(port), rejectUnauthorized: true });
+    let leftover = '';
+    let current = null;
+    let ready = false;
+
+    function send(cmd) { socket.write(cmd + '\r\n'); }
+    function next() {
+      current = queue.shift();
+      if (!current) { socket.end(); return resolve(true); }
+      send(current.cmd);
+    }
+    function onReady() { if (ready) return; ready = true; next(); }
+
+    socket.on('data', chunk => {
+      leftover += chunk.toString('binary');
+      let idx;
+      while ((idx = leftover.indexOf('\r\n')) >= 0) {
+        const line = leftover.slice(0, idx);
+        leftover = leftover.slice(idx + 2);
+        const code = parseInt(line.slice(0, 3), 10);
+        if (current === null) {
+          if (code === 220) onReady();           // 服务器招呼语
+          continue;
+        }
+        const final = line.length >= 4 && line[3] === ' ';
+        if (isNaN(code) || !final) continue;      // 多行续行 / 非响应，忽略
+        const ok = current.codes.includes(code) ||
+          current.codes.some(c => Math.floor(code / 100) === Math.floor(c / 100));
+        if (!ok) { socket.destroy(); return reject(new Error(`SMTP ${code}: ${line}`)); }
+        setTimeout(next, 30);
+      }
+    });
+    socket.on('error', reject);
+
+    // 组装邮件（multipart/mixed，HTML 报告作附件）
+    //
+    // 【重要】所有正文/附件一律 base64 + 76 字符折行。
+    // 原因：RFC 5321 规定 SMTP 单行不得超过 998 字节，而生成的报告 HTML 里
+    // 含有超长单行（双语数据块可达 10 万+ 字符），直接以 8bit 原文投递会被
+    // 服务端拒收或静默截断。base64 折行后天然满足行长限制，且不需要点填充。
+    const b64 = (buf) => Buffer.from(buf).toString('base64').replace(/.{76}/g, '$&\r\n');
+    const boundary = '----=_Part_' + Date.now();
+    let msg = '';
+    msg += `From: ${from}\r\n`;
+    msg += `To: ${to}\r\n`;
+    msg += `Subject: =?UTF-8?B?${Buffer.from(subject).toString('base64')}?=\r\n`;
+    msg += `Date: ${new Date().toUTCString().replace('GMT', '+0000')}\r\n`;
+    msg += `Message-ID: <${Date.now()}.${process.pid}@${String(from).split('@')[1] || 'localhost'}>\r\n`;
+    msg += `MIME-Version: 1.0\r\n`;
+    msg += `Content-Type: multipart/mixed; boundary="${boundary}"\r\n\r\n`;
+    msg += `--${boundary}\r\n`;
+    msg += `Content-Type: text/plain; charset=UTF-8\r\n`;
+    msg += `Content-Transfer-Encoding: base64\r\n\r\n`;
+    msg += b64(text || 'A股次日候选池报告，详见附件 HTML。') + `\r\n\r\n`;
+    if (htmlPath && fs.existsSync(htmlPath)) {
+      const fname = path.basename(htmlPath);
+      msg += `--${boundary}\r\n`;
+      msg += `Content-Type: text/html; charset=UTF-8; name="${fname}"\r\n`;
+      msg += `Content-Transfer-Encoding: base64\r\n`;
+      msg += `Content-Disposition: attachment; filename="${fname}"\r\n\r\n`;
+      msg += b64(fs.readFileSync(htmlPath)) + `\r\n\r\n`;
+    }
+    msg += `--${boundary}--\r\n`;
+
+    // SMTP 透明化：行首的 "." 改为 ".."（base64 不会以 "." 开头，此处仅作兜底）
+    msg = msg.replace(/(\r\n)\./g, '$1..');
+
+    const queue = [
+      { cmd: 'EHLO localhost', codes: [250] },
+      { cmd: 'AUTH LOGIN', codes: [334] },
+      { cmd: Buffer.from(user).toString('base64'), codes: [334] },
+      { cmd: Buffer.from(pass).toString('base64'), codes: [235] },
+      { cmd: `MAIL FROM:<${from}>`, codes: [250] },
+      { cmd: `RCPT TO:<${to}>`, codes: [250, 251] },
+      { cmd: 'DATA', codes: [354] },
+      { cmd: msg + '\r\n.', codes: [250] },
+      { cmd: 'QUIT', codes: [221, 250] },
+    ];
+    if (!ready) socket.on('secureConnect', () => {}); // 确保握手完成后再等 220
+  });
+}
+
+async function pushEmail(subject, htmlPath, cfg) {
+  const e = cfg.email || {};
+  const sender = e.sender, auth = e.auth_code;
+  if (!sender || !auth) return [false, '缺少 email sender/auth_code'];
+  const host = e.smtp_host || 'smtp.163.com';
+  const port = Number(e.smtp_port || 465);
+  const receiver = e.receiver || sender;
+  try {
+    await smtpSend({ host, port, user: sender, pass: auth, from: sender, to: receiver, subject, text: 'A股次日候选池报告，详见附件 HTML。', htmlPath });
+    return [true, `已发送至 ${receiver}`];
+  } catch (ex) {
+    return [false, String(ex && ex.message || ex)];
+  }
+}
+
+// ---------- 统一入口 ----------
+async function notify({ title, content, htmlPath, cfg }) {
+  cfg = cfg || loadCfg();
+  const res = [];
+  if (cfg.wechat && (cfg.wechat.key || cfg.wechat.token)) {
+    res.push(['wechat', await pushWechat(title, content, cfg)]);
+  }
+  if (cfg.email && cfg.email.sender && cfg.email.auth_code) {
+    res.push(['email', await pushEmail(title, htmlPath, cfg)]);
+  }
+  if (!res.length) res.push(['none', [false, '未配置任何推送渠道（notify_config.json 为空）']]);
+  return res;
+}
+
+module.exports = { loadCfg, notify, pushWechat, pushEmail };
+
+// CLI：
+//   node notify.js                      -> 自检，打印配置状态
+//   node notify.js --send "标题" "正文"  -> 直接发一条（供 CI 在任务失败时告警用）
+if (require.main === module) {
+  const argv = process.argv.slice(2);
+  if (argv[0] === '--send') {
+    const title = argv[1] || 'A股初筛告警';
+    const content = argv[2] || '（无正文）';
+    notify({ title, content }).then(res => {
+      for (const [ch, [ok, info]] of res) {
+        console.log(`[notify] ${ch}: ${ok ? 'OK' : '失败 ' + JSON.stringify(info)}`);
+      }
+      // 告警本身发不出去不应让 CI 再挂一次，恒定 0 退出
+    }).catch(e => console.log('[notify] 异常:', e && e.message || e));
+  } else {
+    const c = loadCfg();
+    console.log('wechat 配置:', !!(c.wechat && (c.wechat.key || c.wechat.token)));
+    console.log('email  配置:', !!(c.email && c.email.sender && c.email.auth_code));
+    console.log('notify_config.json 路径:', cfgPath());
+  }
+}

package/notify_config.example.json

@@ -0,0 +1,14 @@
+{
+  "wechat": {
+    "provider": "serverchan",
+    "key": "SCTxxxxxxxx此处替换为你的SendKey",
+    "token": ""
+  },
+  "email": {
+    "smtp_host": "smtp.163.com",
+    "smtp_port": 465,
+    "sender": "you@163.com",
+    "auth_code": "你的163邮箱授权码(非登录密码)",
+    "receiver": "you@163.com"
+  }
+}

package/package.json

@@ -0,0 +1,96 @@
+{
+  "name": "candidate-pool",
+  "version": "2.0.0",
+  "description": "A股短线选股工具包：次日候选池初筛（R01 量能验证突破 + R07 板块内补涨）与尾盘选股（14:50 口径），数据取自腾讯公开行情接口，输出单文件双语 HTML 报告",
+  "bin": {
+    "candidate-pool": "bin/candidate-pool.js",
+    "tail-screener": "bin/tail-screener.js"
+  },
+  "files": [
+    "bin/",
+    "paths.js",
+    "paths.selftest.js",
+    "scaffold.js",
+    "scaffold.selftest.js",
+    "time.js",
+    "gen_candidates.js",
+    "notify.js",
+    "build_universe.js",
+    "candidates.example.json",
+    "notify_config.example.json",
+    "eod/",
+    "db/",
+    "README.md",
+    "CHANGELOG.md",
+    "!eod/reports/",
+    "!eod/data/eod-*.json",
+    "!db/.env",
+    "!db/local.db*",
+    "!**/*.log"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GuoSirius/candidate-pool.git"
+  },
+  "keywords": [
+    "a-share",
+    "stock-screener",
+    "quant",
+    "选股",
+    "尾盘选股",
+    "量化"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "start": "node gen_candidates.js",
+    "run": "node gen_candidates.js",
+    "live": "node gen_candidates.js",
+    "offline": "node gen_candidates.js --offline",
+    "tail": "node eod/tail_screener.js",
+    "tail:intraday": "node eod/tail_screener.js --intraday",
+    "tail:replay": "node eod/tail_screener.js --replay",
+    "tail:selftest": "node eod/lib/trading.selftest.js",
+    "paths": "node gen_candidates.js --paths",
+    "paths:selftest": "node paths.selftest.js",
+    "init": "node gen_candidates.js --init",
+    "scaffold:selftest": "node scaffold.selftest.js",
+    "selftest": "npm run paths:selftest && npm run scaffold:selftest && npm run tail:selftest && npm run db:selftest",
+    "universe": "node build_universe.js",
+    "universe:dry": "node build_universe.js --dry",
+    "notify": "node notify.js",
+    "db:migrate": "node db/migrate.js",
+    "db:migrate:local": "node db/migrate.js --local",
+    "db:migrate:both": "node db/migrate.js --both",
+    "db:migrate:dry": "node db/migrate.js --dry-run",
+    "db:selftest": "node db/diff_selftest.js",
+    "db:sync": "node db/backfill.js --both",
+    "db:verify": "node db/verify_sync.js",
+    "db:local": "node db/backfill.js --local",
+    "deploy": "npm run deploy --prefix ./web",
+    "setup": "npm install && npm install --prefix ./worker && npm install --prefix ./web",
+    "typecheck": "npm run typecheck --prefix ./worker && npm run typecheck --prefix ./web",
+    "changelog": "changelogen",
+    "release": "node scripts/release.mjs",
+    "release:notes": "node scripts/release-notes.mjs",
+    "pack:dry": "npm pack --dry-run",
+    "verify:pack": "node scripts/verify-pack.mjs",
+    "commitlint": "commitlint --edit",
+    "prepare": "husky"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^21.2.3",
+    "@commitlint/config-conventional": "^21.2.3",
+    "changelogen": "^0.6.2",
+    "husky": "^9.1.7"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "dayjs": "^1.11.23",
+    "dotenv": "^18.0.1"
+  }
+}

package/paths.js

@@ -0,0 +1,127 @@
+'use strict';
+/*
+ * paths.js —— 工作目录（HOME）解析：把「代码」与「运行产物 / 配置」分开
+ * ---------------------------------------------------------------------------
+ * 为什么要有这一层：
+ *   本项目历史上所有路径都锚在 `__dirname`（= 仓库结构）。这在「拉代码运行」下完全
+ *   正确，但一旦装进 `node_modules/`（或 `npx` 的临时缓存目录），产物就会被写进**包目录
+ *   本身**——重装即丢、npx 场景下更是跑完就消失；配置也无处可放。故引入一个可覆盖的 HOME。
+ *
+ * 解析优先级（一次解析后缓存）：
+ *   1) setHome(dir)             —— 程序内显式指定（自测用）
+ *   2) CANDIDATE_POOL_HOME      —— 环境变量（推荐，所有脚本都认）
+ *   3) 命令行 --cwd <dir>        —— 入口脚本可直接传
+ *   4) 包根（= 本文件所在目录）  —— **默认，与历史行为逐字节一致**
+ *
+ * HOME 之下保持与仓库**同样的相对布局**，于是「拉代码」与「装包」两种用法指向同一套
+ * 相对路径，行为不会分叉：
+ *   <HOME>/candidates.json            观察池（可编辑）
+ *   <HOME>/data/snapshot-*.json       候选池快照
+ *   <HOME>/reports/*.html             候选池报告
+ *   <HOME>/notify_config.json         推送凭据
+ *   <HOME>/eod/data/*.json            尾盘归档 + industry-map.json 缓存
+ *   <HOME>/eod/reports/*.html         尾盘报告
+ *   <HOME>/db/local.db                本地 SQLite
+ *   <HOME>/db/.env                    D1 凭据
+ *   <HOME>/.env                       （预留：通用环境变量，当前未使用）
+ *
+ * **不随 HOME 移动的（代码资产，永远跟包走，见 codeAsset()）**：
+ *   db/schema.sql、db/migrations/、以及全部 .js —— 它们是程序的一部分，不是用户数据。
+ * ---------------------------------------------------------------------------
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/** 包 / 仓库根（= 本文件所在目录）。代码资产的锚点，**永不**随 HOME 移动。 */
+const PKG_ROOT = __dirname;
+
+/** 从 argv 里取 `--cwd <dir>`（不改动各脚本已有的参数解析；两个入口都零改动就能认） */
+function cwdFromArgv(argv = process.argv.slice(2)) {
+  const i = argv.indexOf('--cwd');
+  if (i < 0) return null;
+  const v = argv[i + 1];
+  return v && !v.startsWith('--') ? v : null;
+}
+
+let _home = null;
+let _source = null;
+
+/** 当前工作目录（绝对路径）。解析一次后缓存；setHome(null) 可重置。 */
+function home() {
+  if (_home) return _home;
+  const fromEnv = process.env.CANDIDATE_POOL_HOME;
+  const fromArg = cwdFromArgv();
+  _home = path.resolve(fromEnv || fromArg || PKG_ROOT);
+  _source = fromEnv ? 'env:CANDIDATE_POOL_HOME' : (fromArg ? 'argv:--cwd' : 'pkg-root');
+  return _home;
+}
+
+/** 显式指定 HOME；传 null / '' 清除覆盖并回到默认解析。返回生效值。 */
+function setHome(dir) {
+  _home = dir ? path.resolve(dir) : null;
+  _source = dir ? 'setHome()' : null;
+  return home();
+}
+
+/** HOME 的来源（诊断用）：pkg-root | env:CANDIDATE_POOL_HOME | argv:--cwd | setHome() */
+function homeSource() { home(); return _source; }
+
+/** 是否处于「重定位」状态（HOME 不是包根） */
+function isRelocated() { return home() !== PKG_ROOT; }
+
+const at = (...s) => path.join(home(), ...s);
+
+// ---------- 工作区（随 HOME 移动）----------
+const Home = {
+  candidatesFile: () => at('candidates.json'),
+  notifyConfigFile: () => at('notify_config.json'),
+  dataDir: () => at('data'),
+  reportsDir: () => at('reports'),
+  eodDir: () => at('eod'),
+  eodDataDir: () => at('eod', 'data'),
+  eodReportsDir: () => at('eod', 'reports'),
+  industryMapFile: () => at('eod', 'data', 'industry-map.json'),
+  localDb: () => at('db', 'local.db'),
+  dbEnvFile: () => at('db', '.env'),
+};
+
+// ---------- 代码资产（永远跟包走）----------
+/** 包内的程序文件路径（schema.sql / migrations / 任意 .js） */
+function codeAsset(...s) { return path.join(PKG_ROOT, ...s); }
+
+/** 建目录（递归），返回该目录路径，便于链式使用 */
+function ensureDir(dir) {
+  if (dir && !fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+/** 全部关键路径一览（`--paths` 与自测用） */
+function describe() {
+  return {
+    home: home(),
+    source: homeSource(),
+    relocated: isRelocated(),
+    pkgRoot: PKG_ROOT,
+    workspace: {
+      candidates: Home.candidatesFile(),
+      notifyConfig: Home.notifyConfigFile(),
+      data: Home.dataDir(),
+      reports: Home.reportsDir(),
+      eodData: Home.eodDataDir(),
+      eodReports: Home.eodReportsDir(),
+      industryMap: Home.industryMapFile(),
+      localDb: Home.localDb(),
+      dbEnv: Home.dbEnvFile(),
+    },
+    codeAssets: {
+      schemaSql: codeAsset('db', 'schema.sql'),
+      migrations: codeAsset('db', 'migrations'),
+    },
+  };
+}
+
+module.exports = {
+  PKG_ROOT, home, setHome, homeSource, isRelocated, cwdFromArgv,
+  ...Home, codeAsset, ensureDir, describe,
+};

package/paths.selftest.js

@@ -0,0 +1,142 @@
+'use strict';
+/*
+ * paths.selftest.js —— 工作目录解析的回归自测
+ * ---------------------------------------------------------------------------
+ * 为什么必须有：`paths.js` 的默认分支直接决定**全部数据文件读写的落点**。
+ * 一旦默认值被改错（例如有人「顺手」把默认从包根改成 process.cwd()），
+ * 本机定时任务与 CI 就会把快照/报告写到别处，表现为「跑了但 report 里找不到」——
+ * 这种故障不会报错，只会静默换目录。故用可重跑断言把默认行为钉死。
+ *
+ * 运行：node paths.selftest.js    （退出码非 0 = 失败）
+ * 纯函数 + 临时目录，不联网、不写真实工作区。
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const P = require('./paths');
+
+let failed = 0;
+function check(name, cond, detail) {
+  console.log(`${cond ? '  OK  ' : '    '}${name}${cond || detail === undefined ? '' : `  → ${detail}`}`);
+  if (!cond) failed++;
+}
+
+const PKG = P.PKG_ROOT;
+const TMP_A = fs.mkdtempSync(path.join(os.tmpdir(), 'cp-home-a-'));
+const TMP_B = fs.mkdtempSync(path.join(os.tmpdir(), 'cp-home-b-'));
+
+/** 每个用例前清掉解析缓存，保证互不污染 */
+function reset() { P.setHome(null); }
+function withEnv(val, fn) {
+  const bak = process.env.CANDIDATE_POOL_HOME;
+  if (val === undefined) delete process.env.CANDIDATE_POOL_HOME; else process.env.CANDIDATE_POOL_HOME = val;
+  reset();
+  try { return fn(); } finally {
+    if (bak === undefined) delete process.env.CANDIDATE_POOL_HOME; else process.env.CANDIDATE_POOL_HOME = bak;
+    reset();
+  }
+}
+function withArgv(extra, fn) {
+  const bak = process.argv;
+  process.argv = ['node', 'x.js', ...extra];
+  reset();
+  try { return fn(); } finally { process.argv = bak; reset(); }
+}
+
+console.log('\n[1] 默认行为必须与历史 __dirname 完全一致（改了就是静默换目录）');
+withEnv(undefined, () => withArgv([], () => {
+  check('home() === 包根', P.home() === PKG, P.home());
+  check('来源标记 pkg-root', P.homeSource() === 'pkg-root', P.homeSource());
+  check('未处于重定位状态', P.isRelocated() === false);
+  // 逐项对齐「老写法」的结果
+  const legacy = {
+    candidatesFile: path.join(PKG, 'candidates.json'),
+    notifyConfigFile: path.join(PKG, 'notify_config.json'),
+    dataDir: path.join(PKG, 'data'),
+    reportsDir: path.join(PKG, 'reports'),
+    eodDataDir: path.join(PKG, 'eod', 'data'),
+    eodReportsDir: path.join(PKG, 'eod', 'reports'),
+    industryMapFile: path.join(PKG, 'eod', 'data', 'industry-map.json'),
+    localDb: path.join(PKG, 'db', 'local.db'),
+    dbEnvFile: path.join(PKG, 'db', '.env'),
+  };
+  for (const [k, v] of Object.entries(legacy)) check(`默认 ${k} 与老写法一致`, P[k]() === v, `${P[k]()} vs ${v}`);
+  // 尾盘子目录的两个用法（store.js 用 eodDir + cfg.store.dataDir）
+  check('eodDir() + dataDir 名 = eod/data', path.join(P.eodDir(), 'data') === path.join(PKG, 'eod', 'data'));
+}));
+
+console.log('\n[2] CANDIDATE_POOL_HOME 必须整棵重定向');
+withEnv(TMP_A, () => withArgv([], () => {
+  check('home() === 环境变量值', P.home() === path.resolve(TMP_A), P.home());
+  check('来源标记 env', P.homeSource() === 'env:CANDIDATE_POOL_HOME', P.homeSource());
+  check('isRelocated() === true', P.isRelocated() === true);
+  check('dataDir 落在 HOME 下', P.dataDir() === path.join(TMP_A, 'data'), P.dataDir());
+  check('eodDataDir 落在 HOME 下', P.eodDataDir() === path.join(TMP_A, 'eod', 'data'), P.eodDataDir());
+  check('eodReportsDir 落在 HOME 下', P.eodReportsDir() === path.join(TMP_A, 'eod', 'reports'), P.eodReportsDir());
+  check('reportsDir 落在 HOME 下', P.reportsDir() === path.join(TMP_A, 'reports'), P.reportsDir());
+  check('localDb 落在 HOME 下', P.localDb() === path.join(TMP_A, 'db', 'local.db'), P.localDb());
+  check('dbEnvFile 落在 HOME 下', P.dbEnvFile() === path.join(TMP_A, 'db', '.env'), P.dbEnvFile());
+  check('candidatesFile 落在 HOME 下', P.candidatesFile() === path.join(TMP_A, 'candidates.json'), P.candidatesFile());
+  check('industryMapFile 落在 HOME 下', P.industryMapFile() === path.join(TMP_A, 'eod', 'data', 'industry-map.json'), P.industryMapFile());
+  // 关键不变式：代码资产**不**跟着走
+  check('schema.sql 仍在包内', P.codeAsset('db', 'schema.sql') === path.join(PKG, 'db', 'schema.sql'), P.codeAsset('db', 'schema.sql'));
+  check('schema.sql 不落在 HOME 下', !P.codeAsset('db', 'schema.sql').startsWith(TMP_A));
+}));
+
+console.log('\n[3] --cwd <dir> 必须生效');
+withEnv(undefined, () => withArgv(['--cwd', TMP_B], () => {
+  check('home() === --cwd 值', P.home() === path.resolve(TMP_B), P.home());
+  check('来源标记 argv', P.homeSource() === 'argv:--cwd', P.homeSource());
+  check('eodDataDir 落在 --cwd 下', P.eodDataDir() === path.join(TMP_B, 'eod', 'data'), P.eodDataDir());
+}));
+
+console.log('\n[4] 优先级：env > --cwd > 包根');
+{
+  const bakEnv = process.env.CANDIDATE_POOL_HOME;
+  const bakArgv = process.argv;
+  process.env.CANDIDATE_POOL_HOME = TMP_A;
+  process.argv = ['node', 'x.js', '--cwd', TMP_B];
+  reset();
+  check('同时给 env 与 --cwd → env 胜', P.home() === path.resolve(TMP_A) && P.homeSource() === 'env:CANDIDATE_POOL_HOME', P.homeSource());
+  if (bakEnv === undefined) delete process.env.CANDIDATE_POOL_HOME; else process.env.CANDIDATE_POOL_HOME = bakEnv;
+  process.argv = bakArgv; reset();
+}
+
+console.log('\n[5] cwdFromArgv 解析健壮性（不误吃下一个参数）');
+check('无 --cwd → null', P.cwdFromArgv(['--offline']) === null);
+check('--cwd 在末尾无值 → null', P.cwdFromArgv(['--cwd']) === null);
+check('--cwd 后跟另一个 flag → null', P.cwdFromArgv(['--cwd', '--offline']) === null);
+check('--cwd X → X', P.cwdFromArgv(['--cwd', 'X']) === 'X');
+check('--cwd X 混在其他参数里 → X', P.cwdFromArgv(['--intraday', '--cwd', 'X', '--json']) === 'X');
+check('--now 的值不会被误当 --cwd', P.cwdFromArgv(['--now', '2026-09-21 11:30']) === null);
+
+console.log('\n[6] setHome 显式覆盖与重置');
+P.setHome(TMP_A);
+check('setHome 生效', P.home() === path.resolve(TMP_A) && P.homeSource() === 'setHome()', P.homeSource());
+P.setHome(null);
+check('setHome(null) 回到包根', P.home() === PKG && P.homeSource() === 'pkg-root', `${P.home()} / ${P.homeSource()}`);
+
+console.log('\n[7] describe() 自述完整');
+withEnv(TMP_A, () => {
+  const d = P.describe();
+  check('describe 含 home/source/relocated', d.home === path.resolve(TMP_A) && d.relocated === true && !!d.source);
+  check('describe 列出 9 个工作区路径', Object.keys(d.workspace).length === 9, String(Object.keys(d.workspace).length));
+  check('describe 列出代码资产', d.codeAssets.schemaSql === path.join(PKG, 'db', 'schema.sql'));
+});
+
+console.log('\n[8] 自测自身不泄漏临时目录');
+{
+  const probe = fs.mkdtempSync(path.join(os.tmpdir(), 'cp-home-probe-'));
+  const ok = fs.existsSync(probe);
+  fs.rmSync(probe, { recursive: true, force: true });
+  check('临时目录可创建且可清理', ok && !fs.existsSync(probe));
+}
+
+// 收尾：把自己造的两个临时目录删掉（否则每跑一次泄漏两个）
+for (const d of [TMP_A, TMP_B]) {
+  try { fs.rmSync(d, { recursive: true, force: true }); } catch (e) { /* 已被占用则忽略 */ }
+}
+
+console.log(failed ? `\n自我检查失败：${failed} 项` : '\n全部通过');
+process.exit(failed ? 1 : 0);