200 lines
7.1 KiB
Markdown
200 lines
7.1 KiB
Markdown
# 设计文档：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 确保绿
|