# 股票估值每日台账

创建人员：`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. 命令

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

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

每日更新：

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

查询与导出：

```powershell
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`：

```powershell
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
powershell -NoProfile -ExecutionPolicy Bypass `
  -File dev/project-dev/stock_valuation_ledger/run_daily.ps1 `
  -AsOf latest `
  -Database stock_valuation
```

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

```powershell
$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 秒；正式日更的后续运维时延由计划任务运行记录持续观察。