# 样本数据规格（sample/）

> 版本: v1.0 | 日期: 2026-07-30 | 状态: 初版
>
> 本文档定义 `sample/` 目录下**脱敏样本数据**的规格。样本用于：
> 1. 开发期单元/集成测试（implementation-plan §2.9 / §5.9 / §9.3）
> 2. 端到端演示与验收（implementation-plan §9「3 个实样本正常动作」）
>
> 样本全部为 **AI 虚构业务数据**（以「员工管理系统」为示例业务），不含任何真实客户信息。

---

## 1. 样本集文件清单

| 文件 | 格式 | 对应输入类型（design §3.3） | 用途 |
|------|------|---------------------------|------|
| `requirements_newdev.xlsx` | .xlsx | 要件定义（表格型） | 新规开发场景 |
| `requirements_enhancement.xlsx` | .xlsx | 要件定义（混合型：表格+取消线+变更区分） | 追加改修场景 |
| `requirements_freetext.xlsx` | .xlsx | 要件定义（自由记述型） | LLM 结构化场景 |
| `template_design_ja.docx` | .docx | 概要设计模板 | 输出结构/样式 |
| `rules_design_ja.docx` | .docx | 做成说明书 | 各章作成指引 |
| `rules_entry_ja.docx` | .docx | 记入规则 | 写法规范 |
| `rules_diagram_ja.xlsx` | .xlsx | 图表规则 | 图表书写规范 |

---

## 2. 脱敏原则

- 业务领域选用通用虚构主题「**员工管理系统**」（社員管理システム），不使用任何真实公司/产品/人名
- ID 编号虚构（EMP001 / SC001 / TB001 等）
- 不得包含真实地址、电话、邮箱、金额以外的敏感信息（金额亦为虚构）
- 文件内部元数据（作者/公司名）清空或使用虚构值

---

## 3. 要件定义规格（3 类型）

### 3.1 通用 Sheet 约定

- Sheet 名：機能一覧 / 画面一覧 / 帳票一覧 / DB定義 / IF定義 / バッチ一覧（对应 `SheetType`：FUNCTION / SCREEN / REPORT / DATABASE / INTERFACE / BATCH）
- 表头行：第 1 行为大标题（Sheet 名），第 2 行起为列头（合并单元格层级表头仅用于验证合并单元格解析，见 3.4）
- 每个单元格需可产生 Provenance 定位（design §9.4.5：`file.xlsx#SheetName!CellRef`）

### 3.2 类型 A：新规开发型（表格型 / テーブル型）

全 Sheet 为规则表格，无自由记述。Sheet 与列头如下：

| Sheet（SheetType） | 列头 |
|------|------|
| 機能一覧（FUNCTION） | 機能ID / 機能名 / 概要 / 利用画面 / 参照DB / 更新DB |
| 画面一覧（SCREEN） | 画面ID / 画面名 / 遷移元 / 遷移先 / 対応機能 / 備考 |
| 帳票一覧（REPORT） | 帳票ID / 帳票名 / 出力媒体 / 出力条件 / 対応機能 / 備考 |
| DB定義（DATABASE） | テーブルID / テーブル名 / 列名 / 型 / PK / 備考 |
| IF定義（INTERFACE） | IF_ID / IF名 / 相手先 / 電文形式 / 送受信 / 備考 |
| バッチ一覧（BATCH） | バッチID / バッチ名 / 起動条件 / 処理概要 / 備考 |

**数据量**：機能 8 件、画面 6 件、帳票 4 件、DB テーブル 5 件（各 3-6 列）、IF 2 件、バッチ 2 件。

### 3.3 类型 B：追加改修型（混合型）

在类型 A 基础上：
- **变更区分列**：機能一覧 / 画面一覧 追加「変更区分」列（`新規` / `変更` / `削除`）
- **取消线单元格**：被「删除/削除」的要素，其行首单元格（如機能ID）设置取消线（strikethrough）
- 局部混合：DB定義 之后插入一个「改修ポイント」自由记述块（文本段落，说明改修要点）
- 用于验证：`FormattingDetector`（取消线检测）、`FreeTextParser`（自由记述块）、`Impact Agent` 追加改修场景（implementation-plan §5.9）

### 3.4 类型 C：自由记述型（自由記述型）

- 全部 Sheet 为**文本段落式**记述（非表格），例如：
  - Sheet「機能要件」：每行为一段自然语言需求（「新入社員を登録できる。氏名・所属・入社日を入力する…」）
  - Sheet「画面要件」：画面要件描述
- 用于验证：Sheet 性质判定（表格型 vs 自由记述型 vs 混合型，design §3.5.2）、`FreeTextParser` LLM 结构化（ExtractionMethod.LLM_FROM_FREE_TEXT）
- 若需验证合并单元格，可在类型 A 的「DB定義」中加入**纵向合并单元格**的列头（例：テーブルID 合并 2 行）

---

## 4. 模板 / 说明书 / 规则文档规格

### 4.1 概要设计书模板（docx）

- 章结构（Heading 层级，与 `ChapterMarker` 对应）：
  - H1 `1. はじめに`、`2. 機能一覧`、`3. 画面一覧`、`4. 帳票一覧`、`5. DB設計`、`6. IF定義`、`7. バッチ一覧`
  - H2 各章下设节（例：`3.1 画面遷移図`、`5.1 テーブル一覧`、`5.2 ER図`）
- **占位符**：使用 docxtpl 语法 `{{section:xxx}}`（design §6.6）插入章节内容位置；封面含 `{{doc_title}}` / `{{version}}` / `{{created_at}}`
- **样式**：定义 Normal / Heading 1-3 / Table Grid / List Bullet 样式（供渲染器 style_map 引用）
- 包含至少 1 个书签（bookmark）验证锚点注入

### 4.2 做成说明书（docx）

- 纯文本 + 标题结构（解析难度 ★☆☆）
- 按章给出作成指引：每章「目的 / 输入情報 / 記載内容 / 記載例」小节
- 内容与模板章结构一一对应

### 4.3 记入规则（docx）

- 标题层级清晰（H1/H2），章节按「章ごとの書き方ルール」组织
- 包含可被 RAG 检索的规则条目，例如：
  - 「機能一覧の書き方」：機能ID は F001 から連番 / 省略記号禁止
  - 「画面遷移図の書き方」：状態遷移表との整合性
  - 「用語の統一」：略語は初出時に正式名称と併記
- 供 RAG 层测试：`rules_entry_ja.docx # 章タイトル` 检索命中（rag-layer §5.2）

### 4.4 图表规则（xlsx）

- Excel 表格型规则（ExcelChunker 按「表头+数据行组」切分）
- Sheet「図表書き方」：列头 `項目 / 規則 / 適用対象`
- 规则条目例如：表ヘッダーは太字のみ（下線なし）/ テーブルには枠線を付ける / ER図の表記法
- 供 RAG 冲突测试（rag-layer §7.1）：图表规则与记入规则对「表ヘッダー」的表述可构造为冲突对

---

## 5. 与实现计划的对应关系

| implementation-plan 任务 | 对应样本 |
|-------------------------|---------|
| §2.9 ExcelParser 統合テスト（テーブル型/自由記述型/混合型/取消線/結合セル） | 3.1-3.4 全部 |
| §5.9 Impact 統合テスト（新規開発/追加改修/自由記述型） | 类型 A / B / C |
| §9.3 性能テスト（1000 行以上 Excel） | 类型 A 扩展（需另行生成大数据样本，不在本集内）|
| §9 验收「3 个实样本正常动作」 | 类型 A / B / C |
| RAG 检索测试 | §4.3 / §4.4 |
| Writer 章节生成测试 | §4.1 模板 + 要件定义 |

---

## 6. 造样方法

- 造样脚本使用 `openpyxl`（xlsx）与 `python-docx`（docx）编程生成，**不手工编辑**
- 脚本执行后产物落盘 `sample/`；脚本本身为一次性开发工具，不纳入版本库（如后续需重建，按本文档规格重新编写即可）
- 生成后校验：打开所有 xlsx 确认 Sheet 名/单元格可读；打开所有 docx 确认标题层级与占位符完整