lhl
becd3e1f57
按《参赛成果物提交规范·赛道一》§6 红线： - samples/ 目录改名 sample/（git mv，保留历史） - 10 个中日文样本文件 + docs 参赛手册 PDF 重命名为 ASCII （requirements_*/template_*/rules_*/contestant-handbook.pdf） - tests/test_zh_template.py 硬编码绝对路径 D:\00_project\Genesis 改为相对路径 - 全局更新 21 个活动文件引用；历史日志/审查文档不改（追加说明记录） 全量 pytest 431 passed / 99.15%
130 lines
7.1 KiB
Markdown
130 lines
7.1 KiB
Markdown
# 样本数据规格（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 确认标题层级与占位符完整
|