edit | blame | history | raw

股票估值每日台账

创建人员：dev.developer.project.secondary / infodev-2

文件职责：说明股票估值每日台账 MVP 的 MySQL 数据口径、命令、失败边界和日常运行方式。

需求入口：../../ana-doc/股票估值/股票估值每日台账业务需求_v1.0.md。

代码入口：../../dev/project-dev/stock_valuation_ledger/。

测试入口：../../dev/project-dev/test/stock_valuation_ledger/。

1. 用途与边界

本工具从正式股票估值 JSON 结果包重建本机 MySQL 台账，并用前复权专表 trading_xuntou.cn_stock_kline_1d_front 中证据完整的日 K 生成每日四档判定。估值区间只在再次执行 init 并发现新正式版本时变化；daily 不修改估值版本或历史判定。

首版只有单进程 CLI、一个目标库和四张业务表，不提供 GUI、API、服务、ORM、连接池服务、多用户权限、付费来源、盘中估值、事件监控或交易指令。stock_valuation 是唯一可写库；trading_xuntou 只执行 SELECT；工具不读写 tianxia。

2. 数据库与凭据

运行目标固定为本机 MySQL stock_valuation，行情库固定为 trading_xuntou。生产库不得由业务命令静默创建；init 只在已存在的目标库内应用版本化 schema.sql，并校验四表、字段和 InnoDB 引擎。

连接参数只可来自以下环境变量或不进入仓库的本机 JSON 配置：

  • STOCK_VALUATION_MYSQL_HOST
  • STOCK_VALUATION_MYSQL_PORT
  • STOCK_VALUATION_MYSQL_USER
  • STOCK_VALUATION_MYSQL_PASSWORD
  • STOCK_VALUATION_MYSQL_DATABASE
  • STOCK_VALUATION_MARKET_DATABASE
  • STOCK_VALUATION_MYSQL_CONFIG

JSON 配置只允许保存在用户本机受限目录，结构键为 host、port、user、password、database、market_database。口令不得出现在仓库、命令示例、日志、异常、证据或原生交接中。异常只返回 MySQL errno/sqlstate，不回显连接串。

四张业务表固定为：

  • security：证券身份和日更开关；
  • valuation_version：不可变正式估值版本及有效期；
  • daily_price：证券与交易日唯一的前复权完整日收盘价；
  • daily_judgement：证券与交易日唯一、绑定估值版本的判定快照。

可复现 schema 位于 ../../dev/project-dev/stock_valuation_ledger/schema.sql。不使用 SQLite，不保留双后端或旧数据库迁移逻辑。

3. 估值导入合同

  • 只读取 *估值快照_*.json、同包 calculation/valuation_results.json 和对应正式报告路径，不从 Markdown 正文抓数字。
  • 当前正式结果包基线为 125 只证券、136 个估值版本，包含六张图片批次 83 只。
  • source_hash 保持正式快照 SHA-256，valuation_id 由证券、估值日和该哈希稳定生成。
  • 重复身份必须逐项比较所有不可变字段，包括从 valuation_results.json 取得的六档区间、指标、机构字段和两个路径；任何差异记录 E_IMMUTABLE_VERSION_CONFLICT，不能计为 unchanged。
  • 第一版估值从自身估值日起可用；同证券后续复评在估值日次日生效。后续版本 active_from=valuation_date+1，前一版本 active_to=后续 valuation_date，历史判定不回写。
  • 同证券同估值日的低优先级重复正式包进入 import_gaps.csv，不产生重叠有效期。

四档边界与 V1 price_position 完全一致：

  • close < base_low：偏低；
  • base_low <= close <= base_high：基本合理；
  • base_high < close <= optimistic_high：偏贵；
  • close > optimistic_high：明显偏贵。

4. 生产行情合同

生产 daily 不调用或回退 V2 网络 provider。唯一来源是 trading_xuntou 的以下只读合同：

  • 前复权日 K：cn_stock_kline_1d_front；
  • 证券身份：专表 symbol 必须与台账 security.ticker 精确相等，且后缀为合法 A 股市场 SH/SZ/BJ；
  • 正式交易日：formal_trading_calendar_days；
  • 日历水位：formal_trading_calendar_assets。

前复权口径由用户指定的专表身份 cn_stock_kline_1d_front 唯一化。schema gate 必须确认该专表存在 id、symbol、trade_date、close、source、updated_at；不得读取通用 cn_stock_kline_1d，不得依赖 dividend_type 推断，也不得回退 V2/network。cn_stock_instrument_static 仅可用于诊断，不是 schema、身份或日更运行的硬依赖。

完整日由以下证据共同证明：证券代码/交易所身份一致、正式日历 is_open=1、日历资产 status='current' 且 is_current=1、window_end 覆盖请求 as-of、行日期等于“请求日以前最大开市日”、日 K updated_at 不早于该交易日上海时间 15:05；同日运行还必须已过 15:05。缺一项即拒绝该行。current 标签但 window_end < as-of 的日历资产仍视为陈旧，必须在任何逐股处理前整体失败关闭。

每条入库价格保存原始 trade_date、正数有限 close、币种、固定来源 ID trading_xuntou.cn_stock_kline_1d_front:xtquant:front 和来源时间。专表缺少请求日历水位对应行时拒绝该证券，不得用旧价写入或改标请求日。港股当前不在该 A 股专表合同内，逐股报告 E_MARKET_UNSUPPORTED。

若行情连接或 schema 证明失败，本次 daily 在任何 stock_valuation 写入和 latest 发布前整体失败；若仅个别行失败，该证券零写入，其他证据完整证券可在同一目标事务中提交并显式报告缺口。价格 INSERT 前必须完成有效估值版本、有限正数区间、区间顺序和 V1 判定校验；daily_price 与 daily_judgement 不会出现价格半状态。

5. 命令

在项目根目录设置模块路径和本机连接环境后执行：

$env:PYTHONPATH = (Resolve-Path dev/project-dev).Path
python -m stock_valuation_ledger init `
  --results-root ana-data/result/股票估值 `
  --database stock_valuation

每日更新：

python -m stock_valuation_ledger daily `
  --as-of latest `
  --database stock_valuation

查询与导出：

python -m stock_valuation_ledger list --date latest --database stock_valuation
python -m stock_valuation_ledger list --label 偏贵 --database stock_valuation
python -m stock_valuation_ledger list --ticker 300450.SZ --database stock_valuation
python -m stock_valuation_ledger show --ticker 300450.SZ --database stock_valuation
python -m stock_valuation_ledger export --date latest --database stock_valuation

开发验收可显式传入无秘密的离线完整日 fixture；该入口不会查询 trading_xuntou：

python -m stock_valuation_ledger daily `
  --as-of 2026-08-06 `
  --prices dev/project-dev/test/stock_valuation_ledger/fixtures/prices_four_labels.json `
  --database stock_valuation_test_example `
  --output-dir dev/tmp/stock-valuation-ledger-demo

隔离测试库必须以 stock_valuation_test_ 开头，并由 STOCK_VALUATION_ALLOW_TEST_DATABASE=1 显式开启。不得对生产 stock_valuation 使用测试清库流程。

6. latest 双文件发布

latest.csv 与 latest.md 先分别写入同目录临时文件并 flush/fsync，再将已有双文件移到独立备份，最后替换两个正式目标。staging 的创建、写入、flush、fsync 和正式首/次替换均在同一 BaseException 状态机中；任一普通/非普通异常都会清除 stage/backup、新半成品并恢复两份旧文件，回滚次生异常通过原异常 note 保留。

daily 只有在本次至少存在一条可信新判定或已验证的幂等判定时才发布。全失败首次运行保持双文件不存在；全失败后续运行保持原双文件字节不变。成功后的备份清理失败只保留警告，不改写正式内容。

7. 返回状态与失败边界

  • IMPORTED：正式版本导入完成；输出 discovered/inserted/unchanged/gap_count。
  • COMPLETE：所有输入行处理成功并生成判定。
  • COMPLETE_WITH_GAPS：至少一条成功，另有逐股失败。
  • NO_NEW_TRADING_DAY：可信输入均为已存在且完全一致。
  • FAILED：没有可信判定成功，或数据库/schema/输入整体失败。

同交易日价格、来源和判定均不可变；冲突分别返回 E_PRICE_IMMUTABLE 或 E_JUDGEMENT_IMMUTABLE。数据库底层错误回滚整批。所有输出仅是对正式估值区间的机械映射，不构成买卖、持有、仓位或收益指令。

8. 单次脚本与计划任务示例

run_daily.ps1 只运行一次，不安装计划任务：

powershell -NoProfile -ExecutionPolicy Bypass `
  -File dev/project-dev/stock_valuation_ledger/run_daily.ps1 `
  -AsOf latest `
  -Database stock_valuation

验收通过后，用户可按本机运维规则手工创建每日计划；以下只是示例，不由开发或测试执行：

$script = (Resolve-Path dev/project-dev/stock_valuation_ledger/run_daily.ps1).Path
$action = New-ScheduledTaskAction -Execute "powershell.exe" `
  -Argument "-NoProfile -ExecutionPolicy Bypass -File `"$script`""
$trigger = New-ScheduledTaskTrigger -Daily -At "16:30"
Register-ScheduledTask -TaskName "StockValuationLedgerDaily" `
  -Action $action -Trigger $trigger -Description "股票估值每日台账"

计划任务运行账户必须自行获得本机受限配置读取权；示例不包含口令。本事项未创建、修改或运行任何系统计划任务。

9. 正式运行现状与已知限制

  • 需求 owner 已于 2026-08-05 按本合同完成一次生产 daily：专表覆盖 124/124 只 A 股，正式 daily_price/daily_judgement 各 124 行；本开发线程没有重复执行或改写这些历史行。
  • 当前生产行情合同只覆盖 A 股；09880.HK 明确作为 E_MARKET_UNSUPPORTED 缺口，港股需未来经需求和评审新增正式数据合同。
  • 正式 latest.md、latest.csv 与 latest_gaps.csv 已由该次运行发布；开发线程仅做只读哈希与行数核验。
  • 200 行暖查询已在本机 MySQL 隔离库验证小于 1 秒；正式日更的后续运维时延由计划任务运行记录持续观察。