🔧 chore(repository): 统一主页剩余文件元数据 (#126)

Author: ZhaoXingPeng

.dockerignore

@@ -34,7 +34,7 @@ venv
 .vscode
 *.swp
 
-# Node (npm wrapper 不进运行镜像)
+# Node（运行镜像直接启动 Python CLI，npm wrapper 不进入构建上下文）
 node_modules
 package*.json
 index.js

CONTRIBUTING.md

@@ -21,6 +21,9 @@ uv pip install -e ".[dev]"
 PYTHONPATH=src uv run pytest tests/unit/ -q
 uv run ruff check src/ tests/
 uv run ruff format --check src/ tests/
+
+# 验证 sb35-java21 模板的代表性 Maven 编译路径（需要 Java 21 与 Maven）
+PYTHONPATH=src uv run python scripts/verify_java_compile.py
 ```
 
 数据库集成测试需要显式配置 `DBJAVAGENIX_TEST_*` 环境变量，详见 [`tests/README.md`](tests/README.md)。

README.es-ES.md

@@ -15,18 +15,19 @@ graph LR
     Skills[".claude/skills/<br/>java-codegen-from-db<br/>springboot-migration"]
     Skills -->|Llamada según necesidad| MCP
 
-    subgraph MCP[Servidor MCP 29 herramientas]
+    subgraph MCP[Servidor MCP 33 herramientas]
         direction TB
         DB[db_* conexión / consulta / descripción]
-        Atom[codegen_build_context<br/>codegen_render_entity/dao/service/<br/>controller/mapper]
+        Atom[codegen_build_context<br/>codegen_render_entity/dao/service/<br/>controller/dto/mapper]
+        Graph[schema_topo_order<br/>schema_cluster_tables<br/>schema_check_cycles]
         AI[ai_infer_business_names<br/>ai_recommend_template<br/>ai_summarize_schema]
         Vis[db_render_er_diagram]
         Obs[server_metrics / server_health<br/>ai_metrics / search_tools]
     end
 
     MCP -->|Retorna _meta| Apps[Renderizado MCP Apps]
     Apps -->|mermaid / dashboard / code-diff / tree| Client
-    MCP -->|Lee| Data[MySQL / SQLite + plantillas Mustache]
+    MCP -->|Lee| Data[MySQL / PostgreSQL / SQLite + plantillas Mustache]
 ```
 
 ## ¿Qué problema resuelve?
@@ -36,7 +37,7 @@ Generar ingeniería inversa de tablas de bases de datos a proyectos Spring Boot
 | Dimensión | Herramientas antiguas | DBJavaGenix v0.2 |
 |------|--------|------------------|
 | ¿Quién define el flujo? | El usuario hace clic en paneles de configuración en el IDE | **Orquestación explícita mediante archivos Skill** (el LLM no llama erróneamente) |
-| Granularidad de llamada | Un solo botón hace todo de golpe | **6 herramientas atómicas** (build_context + 5 render_*), el LLM permite al usuario modificar el contexto para regenerar |
+| Granularidad de llamada | Un solo botón hace todo de golpe | **7 herramientas atómicas** (build_context + 6 render_*), el LLM permite al usuario modificar el contexto para regenerar |
 | Sobrecarga de inicio | (Plugin, residente) | Predeterminado ~3300 tok / modo progresivo **~985 tok** (ahorro del 70%) |
 | Nomenclatura | Mapeo mecánico de prefijos de tabla | **15 reglas + API de Claude**, identifica patrones RBAC/ecommerce/CMS |
 | Visualización de salida | Texto dentro del IDE | **MCP Apps**: Diagrama ER Mermaid / panel de dependencias / code-diff / árbol de estructura de paquetes |
@@ -95,7 +96,7 @@ En el cliente LLM, di "**Genera código Spring Boot a partir de las tres tablas
 
 ### Fase 2: Capa de Skills y herramientas atómicas
 - `.claude/skills/java-codegen-from-db/SKILL.md` define explícitamente el flujo de trabajo de 5 fases
-- `db_codegen_generate` se divide en 6 herramientas atómicas, con contexto transferido explícitamente
+- `db_codegen_generate` se divide en 7 herramientas atómicas, con contexto transferido explícitamente
 - La herramienta `search_tools` implementa descubrimiento progresivo, ahorrando un 70.2% de tokens de inicio
 - Segunda Skill `springboot-migration` (lista de verificación de actualización 2.7→3.x)
 - [token usage benchmark](docs/benchmarks/token-usage.md)
@@ -125,13 +126,14 @@ En el cliente LLM, di "**Genera código Spring Boot a partir de las tres tablas
 - Logs estructurados: `DBJAVAGENIX_LOG_FORMAT=json` permite salida de JSON en una sola línea, ideal para Loki/ELK
 - [Manual de despliegue](docs/deployment.md): 3 modos de despliegue + 6 escenarios de troubleshooting
 
-## Resumen de herramientas (29 en total)
+## Resumen de herramientas (33 en total)
 
 | Categoría | Herramienta |
 |------|------|
 | Conexión / Consulta | db_connect_test / db_query_databases / db_query_tables / db_query_table_exists / db_query_execute |
 | Estructura de tabla | db_table_describe / db_table_columns / db_table_primary_keys / db_table_foreign_keys / db_table_indexes |
-| Generación de código (atómica) | codegen_build_context / codegen_render_entity / codegen_render_dao / codegen_render_service / codegen_render_controller / codegen_render_mapper |
+| Algoritmos de grafo de schema | schema_topo_order / schema_cluster_tables / schema_check_cycles |
+| Generación de código (atómica) | codegen_build_context / codegen_render_entity / codegen_render_dao / codegen_render_service / codegen_render_controller / codegen_render_dto / codegen_render_mapper |
 | Generación de código (legada) | db_codegen_analyze / db_codegen_generate |
 | Proyectos Spring Boot | springboot_validate_project / springboot_analyze_dependencies / springboot_read_config |
 | Visualización | db_render_er_diagram |
@@ -145,7 +147,7 @@ En el cliente LLM, di "**Genera código Spring Boot a partir de las tres tablas
 |------|------------------|----------|----------------------|-----------------|
 | Motor de ejecución | LLM + MCP | Plugin para IDEA | Línea de comandos / Plugin Maven | Interfaz Web |
 | Orquestación de flujo | Skill explícita de 5 fases | Panel de configuración | Código único | Formulario |
-| Granularidad de herramienta | 6 atómicas (permite corrección intermedia) | Botón único | Comando único | Botón único |
+| Granularidad de herramienta | 7 atómicas (permite corrección intermedia) | Botón único | Comando único | Botón único |
 | Nomenclatura IA | ✅ 15 reglas + LLM opcional | ❌ Solo plantillas | ❌ | ❌ |
 | Extensión de plantillas | ✅ Mustache + 4 categorías (incluye sb35-java21) | ✅ Velocity | ⚠️ Solo MybatisPlus | ⚠️ Solo freemarker |
 | Renderizado de diagrama ER | ✅ Mermaid (MCP App) | ❌ | ❌ | ⚠️ Estático |
@@ -160,7 +162,7 @@ Consulta [`iteration-plan/01-target-architecture.md`](iteration-plan/01-target-a
 ```
 [ Capa Skills ]  Define "cómo hacerlo" — .claude/skills/*.md  Flujo de 5 fases explícito
        ↓
-[ Capa MCP ]     Proporciona "qué se puede hacer" — 29 herramientas atómicas  Contexto transferido explícitamente
+[ Capa MCP ]     Proporciona "qué se puede hacer" — 33 herramientas  Contexto transferido explícitamente
        ↓
 [ Capa Apps ]    Hace los resultados "visibles" — 4 componentes de UI (mermaid/dashboard/code-diff/tree)
 ```
@@ -177,6 +179,7 @@ Cada capa practica "contención de ingeniería":
 | [iteration-plan/](iteration-plan/) | Plan de refactorización en 6 fases (arquitectura objetivo / roadmap / registro de decisiones / historias de demostración) |
 | [docs/deployment.md](docs/deployment.md) | Modos de despliegue / Variables de entorno / Health check / Solución de problemas |
 | [docs/benchmarks/token-usage.md](docs/benchmarks/token-usage.md) | Medición de tokens del schema de herramientas |
+| [docs/roadmap-v0.3.md](docs/roadmap-v0.3.md) | Plan de cierre para arquitectura, integración, calidad y publicación |
 | [docs/screenshots/README.md](docs/screenshots/README.md) | Compatibilidad del cliente con 4 componentes MCP Apps |
 | [docs/algorithms-overview.md](docs/algorithms-overview.md) | Algoritmos de gráficos de schema v0.2.1 (topo / cluster / cycle) |
 | [docs/design-patterns-catalog.md](docs/design-patterns-catalog.md) | Patrones de diseño en el generador y en el código generado |
@@ -195,12 +198,9 @@ Cada capa practica "contención de ingeniería":
 - [x] **v0.2.1**: Completado de ingeniería Java (3 algoritmos de schema / generador de configuración de estándares / catálogo de patrones)
 - [x] **v0.2.2**: MCP v3 + Ingeniería de IA (formularios de elicitation / sampling con LLM / caché de prompts 1h / agentic-runner)
 
-Próximos pasos (candidato v0.3):
-- Expansión de backend DB: soporte completo para PostgreSQL / Oracle
-- Captura de capturas de pantalla de Claude Desktop / Cursor al repositorio (cierre de P3.5)
-- Pruebas de integración: levantar MySQL con Testcontainers para ejecutar end-to-end
-- Rendimiento: fusionar la inferencia de reglas y la ruta de LLM en un mismo schema de retorno (el formato actual de la ruta LLM difiere ligeramente de las reglas)
-- Agregar soporte para subagentes en agentic-runner (SDK de Agent ya está listo)
+Próximos pasos (v0.3):
+- Las prioridades, requisitos previos y evidencias de aceptación se mantienen en [`docs/roadmap-v0.3.md`](docs/roadmap-v0.3.md).
+- La lista describe candidatos; no comunica mejoras de rendimiento ni soporte de base de datos no verificados.
 
 ## Modos de inicio
 

README.ja-JP.md

@@ -13,18 +13,19 @@ graph LR
     Skills[".claude/skills/<br/>java-codegen-from-db<br/>springboot-migration"]
     Skills -->|必要に応じて呼び出し| MCP
 
-    subgraph MCP[MCP Server 29 ツール]
+    subgraph MCP[MCP Server 33 ツール]
         direction TB
         DB[db_* 接続 / クエリ / 説明]
-        Atom[codegen_build_context<br/>codegen_render_entity/dao/service/<br/>controller/mapper]
+        Atom[codegen_build_context<br/>codegen_render_entity/dao/service/<br/>controller/dto/mapper]
+        Graph[schema_topo_order<br/>schema_cluster_tables<br/>schema_check_cycles]
         AI[ai_infer_business_names<br/>ai_recommend_template<br/>ai_summarize_schema]
         Vis[db_render_er_diagram]
         Obs[server_metrics / server_health<br/>ai_metrics / search_tools]
     end
 
     MCP -->|_meta を返却| Apps[MCP Apps レンダリング]
     Apps -->|mermaid / dashboard / code-diff / tree| Client
-    MCP -->|読み込み| Data[MySQL / SQLite + Mustache テンプレート]
+    MCP -->|読み込み| Data[MySQL / PostgreSQL / SQLite + Mustache テンプレート]
 ```
 
 ## 解決する課題
@@ -34,7 +35,7 @@ graph LR
 | 観点 | 従来のツール | DBJavaGenix v0.2 |
 |------|-------------|------------------|
 | ワークフローの定義者 | IDE の設定画面をユーザーが操作 | **Skill ファイルで明示的に編成**（LLM の誤呼び出しを防止） |
-| 呼び出し単位 | 1 つのボタンですべてを一括実行 | **6 つのアトミックツール**（build_context + 5 つの render_*）。途中で context を修正して再生成可能 |
+| 呼び出し単位 | 1 つのボタンですべてを一括実行 | **7 つのアトミックツール**（build_context + 6 つの render_*）。途中で context を修正して再生成可能 |
 | 起動コスト | プラグインを常駐 | 通常約 3,300 tok / Progressive モード **約 985 tok**（70% 削減） |
 | 命名 | テーブル接頭辞の機械的な変換 | **15 のルール + Claude API** で RBAC / EC / CMS パターンを認識 |
 | 出力の可視化 | IDE 内のテキスト | **MCP Apps**: Mermaid ER 図 / 依存関係ダッシュボード / code-diff / パッケージツリー |
@@ -96,7 +97,7 @@ LLM クライアントで、例えば **「myapp データベースの sys_user
 ### Phase 2: Skills 層とアトミックツール
 
 - `.claude/skills/java-codegen-from-db/SKILL.md` が 5 段階のワークフローを明示
-- `db_codegen_generate` を 6 つのアトミックツールへ分割し、context を明示的に受け渡し
+- `db_codegen_generate` を 7 つのアトミックツールへ分割し、context を明示的に受け渡し
 - `search_tools` が Progressive Discovery を実装し、起動時のトークンを 70.2% 削減
 - 2 つ目の Skill `springboot-migration`（2.7 → 3.x 移行チェックリスト）
 - [トークン使用量ベンチマーク](docs/benchmarks/token-usage.md)
@@ -129,13 +130,14 @@ LLM クライアントで、例えば **「myapp データベースの sys_user
 - 構造化ログ: `DBJAVAGENIX_LOG_FORMAT=json` で Loki / ELK に適した 1 行 JSON を出力
 - [デプロイガイド](docs/deployment.md): 3 つのデプロイ方式 + 6 つのトラブルシューティング事例
 
-## ツール一覧（29 個）
+## ツール一覧（33 個）
 
 | カテゴリ | ツール |
 |------|------|
 | 接続 / クエリ | db_connect_test / db_query_databases / db_query_tables / db_query_table_exists / db_query_execute |
 | テーブル構造 | db_table_describe / db_table_columns / db_table_primary_keys / db_table_foreign_keys / db_table_indexes |
-| コード生成（アトミック） | codegen_build_context / codegen_render_entity / codegen_render_dao / codegen_render_service / codegen_render_controller / codegen_render_mapper |
+| スキーマグラフアルゴリズム | schema_topo_order / schema_cluster_tables / schema_check_cycles |
+| コード生成（アトミック） | codegen_build_context / codegen_render_entity / codegen_render_dao / codegen_render_service / codegen_render_controller / codegen_render_dto / codegen_render_mapper |
 | コード生成（レガシー） | db_codegen_analyze / db_codegen_generate |
 | Spring Boot プロジェクト | springboot_validate_project / springboot_analyze_dependencies / springboot_read_config |
 | 可視化 | db_render_er_diagram |
@@ -149,7 +151,7 @@ LLM クライアントで、例えば **「myapp データベースの sys_user
 |------|------------------|----------|----------------------|-----------------|
 | 実行方式 | LLM + MCP | IDEA プラグイン | CLI / Maven plugin | Web UI |
 | ワークフロー編成 | 5 段階の明示的な Skill | 設定画面 | 一括生成 | フォーム |
-| ツール粒度 | 6 つのアトミックツール（途中修正可能） | 1 ボタン | 1 コマンド | 1 ボタン |
+| ツール粒度 | 7 つのアトミックツール（途中修正可能） | 1 ボタン | 1 コマンド | 1 ボタン |
 | AI 命名 | ✅ 15 ルール + オプション LLM | ❌ テンプレートのみ | ❌ | ❌ |
 | テンプレート拡張 | ✅ Mustache + 4 カテゴリ（sb35-java21 を含む） | ✅ Velocity | ⚠️ MybatisPlus のみ | ⚠️ freemarker のみ |
 | ER 図の描画 | ✅ Mermaid（MCP App） | ❌ | ❌ | ⚠️ 静的 |
@@ -164,7 +166,7 @@ LLM クライアントで、例えば **「myapp データベースの sys_user
 ```
 [ Skills 層 ]  「方法」を定義 — .claude/skills/*.md  明示的な 5 段階ワークフロー
        ↓
-[ MCP 層 ]     「できること」を提供 — 29 のアトミックツール  context を明示的に受け渡し
+[ MCP 層 ]     「できること」を提供 — 33 ツール  context を明示的に受け渡し
        ↓
 [ Apps 層 ]    結果を「見える化」 — 4 つの UI コンポーネント（mermaid/dashboard/code-diff/tree）
 ```
@@ -182,6 +184,7 @@ LLM クライアントで、例えば **「myapp データベースの sys_user
 | [iteration-plan/](iteration-plan/) | 6 段階のリファクタリング計画（目標アーキテクチャ / ロードマップ / 意思決定記録 / デモストーリー） |
 | [docs/deployment.md](docs/deployment.md) | デプロイ方式 / 環境変数 / ヘルスチェック / トラブルシューティング |
 | [docs/benchmarks/token-usage.md](docs/benchmarks/token-usage.md) | ツールスキーマのトークン測定 |
+| [docs/roadmap-v0.3.md](docs/roadmap-v0.3.md) | アーキテクチャ、統合、品質、リリースの収束計画 |
 | [docs/screenshots/README.md](docs/screenshots/README.md) | 4 つの MCP Apps コンポーネントのクライアント互換性 |
 | [docs/algorithms-overview.md](docs/algorithms-overview.md) | v0.2.1 スキーマグラフアルゴリズム（topo / cluster / cycle） |
 | [docs/design-patterns-catalog.md](docs/design-patterns-catalog.md) | ジェネレーターと生成コードのデザインパターン |
@@ -202,11 +205,8 @@ LLM クライアントで、例えば **「myapp データベースの sys_user
 
 次の候補（v0.3）:
 
-- DB バックエンドの拡張: PostgreSQL / Oracle の完全サポート
-- Claude Desktop / Cursor のスクリーンショットをリポジトリに追加（P3.5 の仕上げ）
-- 統合テスト: Testcontainers で MySQL を起動し、エンドツーエンドで実行
-- パフォーマンス: ルール推論と LLM 経路の返却 schema を統一
-- agentic-runner のサブエージェント対応（Agent SDK は準備済み）
+- 優先順位、前提条件、受け入れ証拠は [`docs/roadmap-v0.3.md`](docs/roadmap-v0.3.md) で管理します。
+- この一覧は候補であり、未検証の性能改善やデータベース対応を表明するものではありません。
 
 ## 起動モード
 

docker-compose.yml

@@ -1,5 +1,3 @@
-version: "3.9"
-
 # 本地开发: 跑一个连着 MCP server 的 stdio 容器, 同时提供一个 MySQL
 # 测试数据库便于集成测试。
 #

index.js

@@ -12,14 +12,15 @@
 const { spawn } = require('child_process');
 const path = require('path');
 const fs = require('fs');
+const { version } = require('./package.json');
 
 const projectDir = __dirname;
 const srcDir = path.join(projectDir, 'src');
 
 // 用 stderr 输出启动信息, stdout 留给 MCP JSON-RPC.
 const log = (...args) => process.stderr.write(args.join(' ') + '\n');
 
-log('DBJavaGenix MCP Server v0.1.0');
+log(`DBJavaGenix MCP Server v${version}`);
 log('Starting Python backend in stdio mode...');
 
 if (!fs.existsSync(srcDir) || !fs.existsSync(path.join(srcDir, 'dbjavagenix'))) {

iteration-plan/README.md

@@ -1,3 +1,7 @@
-# README.md
+# iteration-plan 归档说明
 
-(content saved separately - see git history)
+本目录保留项目早期迭代计划和草稿，作为已完成阶段的历史资料；它不是当前功能承诺的来源。
+
+当前架构、集成、质量与发布的优先级、前置条件和验收证据见
+[`docs/roadmap-v0.3.md`](../docs/roadmap-v0.3.md)。已采纳的架构决策见
+[`docs/adr/`](../docs/adr/)。

package.json

@@ -1,7 +1,7 @@
 {
   "name": "dbjavagenix-mcp-server",
   "version": "0.1.1",
-  "description": "DBJavaGenix MCP Server (Node wrapper around the Python backend). For containerized usage prefer the Docker image.",
+  "description": "Node.js stdio wrapper for the DBJavaGenix Python MCP server. For containerized usage prefer the Docker image.",
   "main": "index.js",
   "bin": {
     "dbjavagenix-mcp": "./index.js"

pyproject.toml

@@ -9,8 +9,9 @@ description = "AI-enhanced Java code generator based on MCP service architecture
 authors = [
     {name = "ZXP", email = "2638265504@qq.com"}
 ]
-readme = "README.md"
-license = {text = "MIT"}
+readme = "README.md"
+# Package metadata remains in this file; requirements-dev.txt supports pip-only workflows.
+license = {text = "MIT"}
 requires-python = ">=3.11"
 keywords = ["mcp", "code-generation", "java", "database", "ai", "skills", "mcp-apps"]
 classifiers = [

requirements-dev.txt

@@ -1,4 +1,5 @@
 # DBJavaGenix 开发环境依赖
+# `pyproject.toml` 是规范依赖入口；本文件保留给使用 pip 的开发环境。
 
 -r requirements.txt