2026Technology-Competition/docs/sample-spec.md

样本数据规格（samples/）

版本: v1.0 | 日期: 2026-07-30 | 状态: 初版

本文档定义 samples/ 目录下脱敏样本数据的规格。样本用于：

1. 开发期单元/集成测试（implementation-plan §2.9 / §5.9 / §9.3）
2. 端到端演示与验收（implementation-plan §9「3 个实样本正常动作」）

样本全部为 AI 虚构业务数据（以「员工管理系统」为示例业务），不含任何真实客户信息。

---

1. 样本集文件清单

文件	格式	对应输入类型（design §3.3）	用途
要件定義_新規開発.xlsx	.xlsx	要件定义（表格型）	新规开发场景
要件定義_追加改修.xlsx	.xlsx	要件定义（混合型：表格+取消线+变更区分）	追加改修场景
要件定義_自由記述.xlsx	.xlsx	要件定义（自由记述型）	LLM 结构化场景
概要設計書テンプレート.docx	.docx	概要设计模板	输出结构/样式
概要設計做成説明書.docx	.docx	做成说明书	各章作成指引
記入規則.docx	.docx	记入规则	写法规范
図表規則.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 层测试：記入規則.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）编程生成，不手工编辑
• 脚本执行后产物落盘 samples/；脚本本身为一次性开发工具，不纳入版本库（如后续需重建，按本文档规格重新编写即可）
• 生成后校验：打开所有 xlsx 确认 Sheet 名/单元格可读；打开所有 docx 确认标题层级与占位符完整