# 实验存储体系

创建人员：Codex  
文件职责：记录 project A 实验数据、结果包、图片、表 schema 和读取追踪方式。  
管理规范/模板：../../common/exp-doc/实验存储体系创建指南.md  
引用文件：实验总纲.md；实验设计.md；实验执行日志.md；实验审计报告.md；实验问题记录.md。

## 1. 数据存储目标和范围

本存储体系用于 project A 的轻量实验环境验证。

目标是保证实验数据、结果包、图片和审计证据能从实验总纲追到结果包，再追到原始输入和中间数据。

## 2. 目录结构

```text
project A/
  exp-doc/
  exp-data/
    raw/
    result/
    img/
    tmp/
```

## 3. 数据流

```text
raw source
-> feature/intermediate
-> result package
-> summary/readout/manifest
-> audit report
```

`exp-data/tmp/` 只放临时脚本和临时缓存，不作为正式结论入口。

## 4. 结果包组织规则

结果包路径：

```text
exp-data/result/<run_id>/
```

结果包至少包含：

| 文件 | 作用 |
|---|---|
| summary.json | 关键状态和计数 |
| readout.md | 人读版结果和边界 |
| output_manifest.csv | 结果包资产清单和 hash |
| input_manifest.csv | 输入快照索引 |
| intermediate/feature_panel.csv | 中间特征面 |

## 5. 图片和图表存储规则

图片路径：

```text
exp-data/img/<experiment_id>/<run_id>/
```

图片文件名应包含对象 ID 和实验图形类型。

## 6. 表清单

| table_name | storage_backend | storage_path_or_table | table_role | row_grain | primary_key | unique_key | producer | consumer | update_mode | official_flag | retention_policy |
|---|---|---|---|---|---|---|---|---|---|---|---|
| signal_cross_input.csv | csv | exp-data/raw/<run_id>/signal_cross_input.csv | raw | object + event_date | experiment_id + object_id + event_date | experiment_id + object_id + event_date | runner | feature step | overwrite_snapshot | 是 | keep |
| volume_spike_input.csv | csv | exp-data/raw/<run_id>/volume_spike_input.csv | raw | object + event_date | experiment_id + object_id + event_date | experiment_id + object_id + event_date | runner | feature step | overwrite_snapshot | 是 | keep |
| feature_panel.csv | csv | exp-data/result/<run_id>/intermediate/feature_panel.csv | intermediate | object + event_date | experiment_id + run_id + object_id + event_date | experiment_id + run_id + object_id + event_date | runner | result step / auditor | overwrite_snapshot | 是 | keep |
| signal_cross_result.csv | csv | exp-data/result/<run_id>/signal_cross_result.csv | output | signal event | experiment_id + run_id + object_id + event_date | experiment_id + run_id + object_id + event_date | runner | auditor | overwrite_snapshot | 是 | keep |
| volume_spike_result.csv | csv | exp-data/result/<run_id>/volume_spike_result.csv | output | signal event | experiment_id + run_id + object_id + event_date | experiment_id + run_id + object_id + event_date | runner | auditor | overwrite_snapshot | 是 | keep |
| output_manifest.csv | csv | exp-data/result/<run_id>/output_manifest.csv | manifest | artifact | run_id + artifact | run_id + artifact | runner | auditor / AI | overwrite_snapshot | 是 | keep |
| summary.json | json | exp-data/result/<run_id>/summary.json | summary | run | run_id | run_id | runner | human / auditor | overwrite_snapshot | 是 | keep |
| readout.md | markdown | exp-data/result/<run_id>/readout.md | readout | run | run_id | run_id | runner | human / auditor | overwrite_snapshot | 是 | keep |

## 7. 字段 schema

### 7.1 raw input

| field_name | data_type | required | nullable | enum_values | meaning | source | time_semantics | example | notes |
|---|---|---|---|---|---|---|---|---|---|
| experiment_id | string | 是 | 否 |  | 实验事项 ID | runner | generated-time | EXP-20260601-PROJA-SIGNAL-CROSS-001 | 追踪字段 |
| object_id | string | 是 | 否 |  | 对象 ID | runner | generated-time | OBJECT001 | 合成对象 |
| event_date | string | 是 | 否 |  | 事件日期 | runner | event-time | 2026-01-01 | ISO 日期 |
| value | number | 是 | 否 |  | 观测值 | runner | event-time | 10 | 通用时序值 |
| volume | number | 否 | 是 |  | 观测量 | runner | event-time | 100 | 仅 volume_spike 输入使用 |

### 7.2 feature_panel.csv

| field_name | data_type | required | nullable | enum_values | meaning | source | time_semantics | example | notes |
|---|---|---|---|---|---|---|---|---|---|
| experiment_id | string | 是 | 否 |  | 实验事项 ID | runner | generated-time | EXP-20260601-PROJA-SIGNAL-CROSS-001 | 追踪字段 |
| object_id | string | 是 | 否 |  | 对象 ID | raw input | event-time | OBJECT001 | 追踪字段 |
| event_date | string | 是 | 否 |  | 日期 | raw input | event-time | 2026-01-04 | 追踪字段 |
| value | number | 是 | 否 |  | 观测值 | raw input | event-time | 14 |  |
| trailing_ma3 | number | 否 | 是 |  | 前序 value 均值 | runner | as-of previous rows | 11.0000 | signal_cross 使用 |
| volume | number | 否 | 是 |  | 观测量 | raw input | event-time | 260 | volume_spike 使用 |
| volume_ma3 | number | 否 | 是 |  | 前序 volume 均值 | runner | as-of previous rows | 101.0000 | volume_spike 使用 |
| signal_flag | integer | 是 | 否 | 0/1 | 是否命中 | runner | generated-time | 1 |  |

### 7.3 result tables

| field_name | data_type | required | nullable | enum_values | meaning | source | time_semantics | example | notes |
|---|---|---|---|---|---|---|---|---|---|
| experiment_id | string | 是 | 否 |  | 实验事项 ID | runner | generated-time | EXP-20260601-PROJA-SIGNAL-CROSS-001 | 追踪字段 |
| design_id | string | 是 | 否 |  | 设计 ID | runner | generated-time | DESIGN-20260601-PROJA-SIGNAL-CROSS-001 | 追踪字段 |
| run_id | string | 是 | 否 |  | run ID | runner | generated-time | RUN-20260601-PROJA-SIGNAL-CROSS-001 | 追踪字段 |
| object_id | string | 是 | 否 |  | 对象 ID | raw input | event-time | OBJECT001 |  |
| event_date | string | 是 | 否 |  | 命中日期 | feature_panel | event-time | 2026-01-04 |  |
| signal_reason | string | 是 | 否 |  | 命中原因 | runner | generated-time | value_gt_trailing_ma3_by_8pct |  |

### 7.4 output_manifest.csv

| field_name | data_type | required | nullable | enum_values | meaning | source | time_semantics | example | notes |
|---|---|---|---|---|---|---|---|---|---|
| artifact | string | 是 | 否 |  | 资产名 | runner | generated-time | summary |  |
| path | string | 是 | 否 |  | 项目相对路径 | runner | generated-time | exp-data/result/... | 不写本机绝对路径 |
| artifact_role | string | 是 | 否 | raw/intermediate/output/summary/readout/image/manifest | 资产角色 | runner | generated-time | output |  |
| row_count_or_count | integer | 是 | 否 |  | 行数或数量 | runner | generated-time | 8 |  |
| sha256 | string | 是 | 否 |  | 文件 hash | runner | generated-time | abc... |  |

## 8. 读取方式

人读路径：

```text
目录导读
-> 实验总纲
-> 实验设计
-> 实验执行日志
-> 结果包 summary/readout
-> 图片
-> 实验审计报告
```

AI 读路径：

```text
实验总纲
-> 实验设计
-> output_manifest.csv
-> feature_panel.csv / result table
-> summary.json
-> 实验审计报告
```