commit 56da6c9917a501c27e5446069b8a39aca3ef204d Author: lhl Date: Sat Aug 8 15:16:19 2026 +0800 docs: Phase1 里程碑1 实现设计（骨架+数据模型+config 加载） diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..94cb8dd --- /dev/null +++ b/.gitignore @@ -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/ \ No newline at end of file diff --git a/docs/superpowers/specs/2026-08-08-phase1-foundation-design.md b/docs/superpowers/specs/2026-08-08-phase1-foundation-design.md new file mode 100644 index 0000000..8f2ee80 --- /dev/null +++ b/docs/superpowers/specs/2026-08-08-phase1-foundation-design.md @@ -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 确保绿