docs: Phase1 里程碑1 实现设计（骨架+数据模型+config 加载）
This commit is contained in:
+31
@@ -0,0 +1,31 @@
|
||||
# ---- 环境与密钥 ----
|
||||
.env
|
||||
.env.*
|
||||
|
||||
# ---- 运行时数据 ----
|
||||
data/
|
||||
|
||||
# ---- Python 构建产物 ----
|
||||
__pycache__/
|
||||
*.py[cod]
|
||||
*.egg-info/
|
||||
dist/
|
||||
build/
|
||||
.eggs/
|
||||
|
||||
# ---- 测试缓存 ----
|
||||
.pytest_cache/
|
||||
.coverage
|
||||
htmlcov/
|
||||
|
||||
# ---- 虚拟环境 ----
|
||||
.venv/
|
||||
venv/
|
||||
|
||||
# ---- 工具内部操作产物（不入库） ----
|
||||
conversations/
|
||||
.aura/
|
||||
|
||||
# ---- IDE / 编辑器 ----
|
||||
.vscode/
|
||||
.idea/
|
||||
@@ -0,0 +1,199 @@
|
||||
# 设计文档：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 确保绿
|
||||
Reference in New Issue
Block a user