# 设计文档：Phase 1 里程碑 1（项目骨架 + 数据模型 + 配置加载）

> 版本: v1.0 | 日期: 2026-08-08 | 状态: 已批准
>
> 本文档是 `docs/implementation-plan.md` 阶段 1（项目基盘）**里程碑 1** 的实现设计，覆盖任务 1.1（项目结构/打包）与 1.2（共通数据模型定义），并前置 config 加载（对应 `docs/config-design.md` 的落地）。

---

## 1. 目标与范围

**本里程碑交付**：
- 可运行的 Python 项目骨架（src 布局 + pyproject 打包 + pytest 就绪）
- 全部业务数据模型 `data_models.py`（design §3 + §9.4）
- 配置加载 `config.py`（app / inference / rag 三 yaml + .env + 环境变量）

**不包含**（后续里程碑）：FileReader / CodeParser / ImageAnalyzer / InferenceEngine / ToolExecutor / 状态机 / 记忆 / 可观测性。

**完成门槛**：`pytest` 全绿；`pip install -e .` 后 `import genesis` 可用。

---

## 2. 项目结构与打包

```
Genesis/
├── pyproject.toml
├── src/genesis/
│   ├── __init__.py            # __version__ = "0.1.0"
│   ├── data_models.py
│   └── config.py
├── tests/
│   ├── __init__.py
│   ├── fixtures/
│   │   ├── app_min.yaml
│   │   ├── inference_min.yaml
│   │   ├── rag_min.yaml
│   │   └── .env.test
│   ├── test_data_models.py
│   └── test_config.py
├── .gitignore
└── README.md                  # 空壳占位（README 在成果物阶段补全）
```

### pyproject.toml 要点

```toml
[build-system]
requires = ["setuptools>=69"]
build-backend = "setuptools.build_meta"

[project]
name = "genesis"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
  "pydantic>=2.13",
  "pydantic-settings>=2.15",
  "pyyaml>=6.0",
  "openpyxl>=3.1",
  "python-docx>=1.0",
]

[project.optional-dependencies]
dev = ["pytest>=8.0"]

[tool.setuptools.packages.find]
where = ["src"]

[tool.pytest.ini_options]
testpaths = ["tests"]
```

### .gitignore 要点

`.env`、`data/`、`*.egg-info/`、`__pycache__/`、`.pytest_cache/`、`.venv/`

---

## 3. data_models.py

**约定**：
- 文件顶部 `from __future__ import annotations`（design §9.4.6，P0-1 落地）
- 全部 `@dataclass`，字段名/默认值与 design §9.4 一一对应
- 不做自写序列化；`dataclasses.asdict` 即可 JSON 化（后续里程碑按需）
- runtime 层类型（ChatResult 等）不在本文件，避免重复定义

### 3.1 枚举

```python
class SheetType(Enum):       FUNCTION / SCREEN / REPORT / DATABASE / INTERFACE / BATCH / MASTER / GENERIC
class ElementType(Enum):     FUNCTION="機能" / SCREEN="画面" / REPORT="帳票" / DB="DB" / IF="IF" / BATCH="バッチ"
class RelationType(Enum):    USE="利用" / REFER="参照" / UPDATE="更新" / OUTPUT="输出" / INPUT="输入" / DEPEND="依赖"
class Confidence(Enum):      HIGH="high" / MEDIUM="medium" / LOW="low"
class ExtractionMethod(Enum): OPENPYXL="openpyxl" / LLM_FROM_FREE_TEXT="llm_from_free_text"
```

### 3.2 基础类型

```python
Provenance(file_name, sheet_name, row:int, column:str, column_header:str)
CellFormatting(strikethrough=False, font_color=None, bg_color=None)
CellComment(author, text, source_uri)
CellValue(value, provenance, formatting=None, comment=None)
```

### 3.3 Parser 输出类型

```python
ExcelTable(name, detected_type: SheetType, extraction_method: str, headers: list[str], rows: list[dict[str, CellValue]])
ChapterMarker(type: str, name: str, level: int)
ParsedTemplate(file_name, sections: list[ChapterMarker], placeholders: dict[str,str], styles: dict)
RuleDocument(file_name, category, markdown_content, source_path, file_type, hash)
ImageAnalysis(image_ref, description, confidence, source_uri, sheet_name, anchor_cell, status, nearby_text="")
ControllerInfo(name, class_name, path, base_path, endpoints, source_uri)
ServiceInfo(name, class_name, path, methods, source_uri)
EntityInfo(name, class_name, path, table_name, fields, source_uri)
EndpointInfo(method, path, controller, description, source_uri)
ExistingSystemInfo(controller_layer, service_layer, entity_layer, api_endpoints, source_path)
```

### 3.4 工具层与汇聚

```python
UnifiedDocument(file_name, file_type, source_path, content_type,
                tables=None, sheet_names=None, paragraphs=None, slides=None, text=None, encoding=None)
CodeStructure(root_path, language, modules, classes,
              controllers, services, entities, endpoints, raw_imports)
ImageDescription(image_ref, description, objects, ocr_text, confidence, model)

StructuredSource(tables: list[ExcelTable], template: ParsedTemplate,
                 rule_docs: list[RuleDocument], image_analyses: list[ImageAnalysis],
                 existing_system: ExistingSystemInfo|None, comments: list[CellComment])
```

---

## 4. config.py

**设计依据**：config-design §1（优先级：环境变量 > yaml > 默认值）、§7（校验与脱敏）。

### 4.1 结构

```python
# 三个 yaml 对应模型
class ServerConfig(BaseModel): max_upload_mb=100; allowed_extensions=[...]
class AppConfig(BaseModel): app; server: ServerConfig; session; paths; task_queue
class InferenceConfig(BaseModel): models(primary/fallback/vision); llm_calls; structured_output; prompt_registry
class RagConfig(BaseModel): embedding; vector_store; chunking; retrieval

# 根 Settings
class Settings(BaseSettings):
    model_config = SettingsConfigDict(env_prefix="GENESIS_", env_file=".env", extra="ignore")
    app: AppConfig
    inference: InferenceConfig
    rag: RagConfig

    @classmethod
    def from_dir(cls, config_dir: Path) -> Settings: ...   # 读三 yaml 构造；缺失→默认
    def get_redacted(self) -> dict: ...                    # key/secret/token → "***"
```

### 4.2 行为约定

- yaml 文件缺失/字段缺失 → 用模型默认值兜底，不阻塞启动
- 非法类型/越界值 → pydantic 校验失败并抛出带原因的异常（config-design §7）
- API Key 等敏感项从 `.env`/环境变量读，**不入 yaml**；缺失不阻塞启动
- `get_redacted()` 供 `/api/settings` 脱敏展示

---

## 5. 测试策略

### test_data_models.py
- 枚举成员与值断言（SheetType 8 个、ElementType 等）
- 关键 dataclass 可用关键字实例化（覆盖**前向引用**：ExcelTable 引用 SheetType、StructuredSource 引用各 Parser 类型）
- 默认值生效（CellFormatting、ImageAnalysis.nearby_text）
- `dataclasses.asdict` 序列化冒烟

### test_config.py
- fixtures 最小 yaml → Settings.from_dir 构造 → 字段映射断言
- 最小 yaml（几乎空）→ 默认值兜底
- 环境变量覆盖（monkeypatch `GENESIS_APP__SERVER__MAX_UPLOAD_MB` 等）
- `get_redacted()` 脱敏（api_key/secret/token → ***）

---

## 6. 里程碑完成门槛

- [ ] `pip install -e ".[dev]"` 成功，`import genesis` 可用
- [ ] `pytest` 全绿
- [ ] 数据模型字段与 design §9.4 一一对应（无遗漏/无多余）
- [ ] config 三 yaml + env + 脱敏行为符合 config-design §1/§7

---

## 7. 提交策略

- git init 后：设计文档单独 commit → 骨架/打包 commit → data_models + 测试 commit → config + 测试 commit
- 每个 commit 前跑 pytest 确保绿