7.1 KiB
7.1 KiB
设计文档：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 要点
[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 枚举
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 基础类型
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 输出类型
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 工具层与汇聚
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 结构
# 三个 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 确保绿