dbdoc_engine 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ad5cf22e63a4897073d62ad296bdcc483188b40abd451443bcb1d241d2b35af4
+  data.tar.gz: 9888d8b12daf05eeb54a337237dbfa8a29f05d2b7ef1b82bc725f9428e77cbcb
+SHA512:
+  metadata.gz: 88e5f52c5cc8672aede21cc46c0c379c8a1fee3bc380bc1d79aa6bf0b0cb569654ad37796d87ba99c0c678bf51179c82db88f433f90adea4cb0df87ca5bba6c9
+  data.tar.gz: 85ac752291498feae0667069603bec63a72dae67ef48de1ca05105d646f67c790f57cc6e86c58b1d8edc0febb0988082bf73fd1badff704b631f2b9ae7002265

data/README.md

@@ -0,0 +1,331 @@
+# DbdocEngine
+
+A mountable Rails engine for **database design documentation**. Provides a full-featured web interface to document, visualize, and collaborate on your database schema — tables, columns, relationships, constraints, and change history.
+
+---
+
+## Features
+
+- **Table & Column Documentation** — Document every table and column with logical/physical names, data types, constraints (PK, FK, NOT NULL, unique, indexed), default values, and descriptions.
+- **Table Groups** — Organize tables into color-coded logical groups (e.g., "User Management", "Orders", "Master Data").
+- **Interactive Schema Diagram** — Auto-generated ER diagram with group-based highlighting and FK relationship lines.
+- **Changelog & Audit Trail** — Every create, update, and delete is automatically logged with timestamp, user, and before/after values.
+- **Excel Export** — Export full documentation as `.xlsx` (all tables or single table) with proper formatting and i18n support.
+- **JSON Import/Export** — Backup and restore all documentation data as JSON.
+- **Schema.rb Import** — Auto-import table/column definitions from your project's `schema.rb` or an uploaded file.
+- **Role-Based Access Control** — Three roles: `user` (read-only), `admin` (edit), `superadmin` (full control including import/export/delete).
+- **Soft Delete & Restore** — Safely delete and restore tables and groups.
+- **i18n Support** — Full English and Japanese localization.
+- **Modern Dashboard** — Stats overview, recent activity, action chart, and quick-access import/export tools.
+
+---
+
+## Requirements
+
+| Dependency | Version |
+|------------|---------|
+| Ruby | >= 3.0 |
+| Rails | >= 7.0, < 9.0 |
+| PostgreSQL | >= 12 |
+
+---
+
+## Installation
+
+### 1. Add to Gemfile
+
+```ruby
+gem "dbdoc_engine"
+```
+
+### 2. Install
+
+```bash
+bundle install
+bin/rails generate dbdoc_engine:install
+```
+
+The installer will automatically:
+
+1. Copy the appropriate migrations (Rails 7 or Rails 8)
+2. Run `db:migrate` to create all DbdocEngine tables
+3. Seed three default users
+4. Mount the engine at `/dbdoc` in `config/routes.rb`
+5. Configure importmap pins in `config/importmap.rb`
+6. Add the JS import to `app/javascript/application.js`
+7. For Rails 7: install importmap/turbo/stimulus if missing, update `manifest.js`
+
+### 3. Start your server
+
+```bash
+bin/rails server
+```
+
+Visit **http://localhost:3000/dbdoc** and log in.
+
+---
+
+## Default Users
+
+After installation, three users are created in the `dbdoc_engine_users` table (isolated from your app's `users` table):
+
+| Username | Password | Role |
+|----------|----------|------|
+| `user` | `password123` | user (read-only) |
+| `admin` | `password123` | admin (can edit) |
+| `superadmin` | `password123` | superadmin (full control) |
+
+> **Important:** Change the default passwords in production.
+
+---
+
+## Configuration
+
+### Mount Path
+
+By default the engine is mounted at `/dbdoc`. To change it:
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  mount DbdocEngine::Engine => "/dbdoc"
+end
+```
+
+### Locale
+
+DbdocEngine supports English (`en`) and Japanese (`ja`). The locale can be switched from the UI or by appending `?locale=ja` to any URL.
+
+---
+
+## Roles & Permissions
+
+| Role | View Docs | Edit Tables/Columns | Manage Groups | Delete | Import/Export |
+|------|-----------|---------------------|---------------|--------|---------------|
+| `user` | Yes | No | No | No | No |
+| `admin` | Yes | Yes | Yes | No | No |
+| `superadmin` | Yes | Yes | Yes | Yes | Yes |
+
+---
+
+## Database Tables
+
+All tables are namespaced to avoid conflicts with your application:
+
+| Table | Purpose |
+|-------|---------|
+| `db_design_table_groups` | Logical groups with color codes |
+| `db_design_dynamic_tables` | Documented tables (logical + physical names) |
+| `db_design_dynamic_columns` | Column definitions with full constraint metadata |
+| `db_design_changelogs` | Audit log of all documentation changes |
+| `dbdoc_engine_users` | Engine-specific authentication (does NOT touch your app's `users` table) |
+
+---
+
+## Routes Reference
+
+### Public Routes
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/dbdoc` | Documentation home |
+| GET | `/dbdoc/login` | Login form |
+| POST | `/dbdoc/login` | Authenticate |
+| DELETE | `/dbdoc/logout` | Logout |
+| GET | `/dbdoc/group_details/:id` | Group detail view |
+| GET | `/dbdoc/table_details/:id` | Table detail view |
+| GET | `/dbdoc/changelogs` | Change history |
+| GET | `/dbdoc/schema_diagram` | Interactive ER diagram |
+
+### Admin Routes (requires login)
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/dbdoc/admin/dashboard` | Admin dashboard |
+| CRUD | `/dbdoc/admin/db_design_dynamic_tables` | Table management |
+| CRUD | `/dbdoc/admin/db_design_table_groups` | Group management |
+| GET | `/dbdoc/admin/export_data` | Export documentation as JSON |
+| POST | `/dbdoc/admin/import_data` | Import documentation from JSON |
+| POST | `/dbdoc/admin/import_schema` | Import from schema.rb |
+| GET | `/dbdoc/admin/.../export_to_excel` | Export single table as Excel |
+| GET | `/dbdoc/admin/.../export_all_to_excel` | Export all tables as Excel |
+
+---
+
+## Architecture
+
+```
+dbdoc_engine/
+├── app/
+│   ├── controllers/dbdoc_engine/
+│   │   ├── application_controller.rb      # Auth, i18n, layout
+│   │   ├── home_controller.rb             # Public documentation pages
+│   │   ├── schema_diagram_controller.rb   # ER diagram + JSON API
+│   │   ├── db_doc_sessions_controller.rb  # Login/logout
+│   │   └── admin/
+│   │       ├── base_controller.rb         # Admin authorization
+│   │       ├── dashboard_controller.rb    # Dashboard stats & chart
+│   │       ├── db_design_dynamic_tables_controller.rb
+│   │       ├── db_design_table_groups_controller.rb
+│   │       └── data_transfer_controller.rb  # Import/export
+│   ├── models/dbdoc_engine/
+│   │   ├── user.rb
+│   │   ├── db_design_table_group.rb
+│   │   ├── db_design_dynamic_table.rb
+│   │   ├── db_design_dynamic_column.rb
+│   │   ├── db_design_changelog.rb
+│   │   └── concerns/soft_deletable.rb
+│   ├── services/dbdoc_engine/
+│   │   ├── schema_rb_parser_service.rb    # Parse schema.rb DSL
+│   │   └── schema_rb_import_service.rb    # Bulk-import tables/columns
+│   ├── queries/dbdoc_engine/              # Query objects (no N+1)
+│   ├── helpers/dbdoc_engine/
+│   ├── views/dbdoc_engine/                # ERB templates
+│   ├── javascript/dbdoc_engine/           # Stimulus controllers
+│   └── assets/
+│       ├── stylesheets/dbdoc_engine/      # CSS
+│       └── images/dbdoc_engine/           # Icons, logos
+├── config/
+│   ├── routes.rb                          # Engine routes
+│   ├── locales/
+│   │   ├── en.yml                         # English translations
+│   │   └── ja.yml                         # Japanese translations
+│   └── importmap.rb
+├── db/
+│   ├── migrate/
+│   │   ├── rails7/                        # Migrations for Rails 7.x
+│   │   └── rails8/                        # Migrations for Rails 8.x
+│   └── seeds.rb                           # Default user seeds
+└── lib/
+    ├── dbdoc_engine.rb
+    ├── dbdoc_engine/
+    │   ├── engine.rb
+    │   └── version.rb
+    ├── generators/dbdoc_engine/
+    │   ├── install/install_generator.rb    # Install generator
+    │   └── uninstall/uninstall_generator.rb # Uninstall generator
+    └── tasks/dbdoc_engine_tasks.rake
+```
+
+---
+
+## Manual Setup (if not using the generator)
+
+### Routes
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  mount DbdocEngine::Engine => "/dbdoc"
+end
+```
+
+### Importmap
+
+```ruby
+# config/importmap.rb
+if defined?(DbdocEngine)
+  pin_all_from DbdocEngine::Engine.root.join("app/javascript/dbdoc_engine"),
+    under: "dbdoc_engine",
+    to: "dbdoc_engine"
+end
+```
+
+### JavaScript
+
+```javascript
+// app/javascript/application.js
+import "dbdoc_engine/application";
+```
+
+### Migrations
+
+```bash
+bin/rails dbdoc_engine:install:migrations
+bin/rails db:migrate
+```
+
+### Seeds
+
+```bash
+bin/rails dbdoc_engine:install:seeds
+bin/rails dbdoc_engine:db:seed
+```
+
+---
+
+## Uninstallation
+
+To completely remove DbdocEngine from your project:
+
+```bash
+bin/rails generate dbdoc_engine:uninstall
+```
+
+The uninstaller will ask for confirmation before:
+
+1. **Dropping all DbdocEngine tables** (with a separate confirmation — you can choose to keep them)
+2. Removing the engine route from `config/routes.rb`
+3. Removing importmap pins from `config/importmap.rb`
+4. Removing the JS import from `app/javascript/application.js`
+5. Deleting the seed file `db/dbdoc_engine_seeds.rb`
+6. Cleaning up migration files and `schema_migrations` entries
+
+After running the uninstaller, remove `gem "dbdoc_engine"` from your `Gemfile` and run `bundle install`.
+
+---
+
+## Import / Export
+
+### JSON Export & Import
+
+From the Admin Dashboard, superadmins can:
+
+- **Export** all documentation data (groups, tables, columns) as a single `.json` file
+- **Import** a previously exported `.json` file to restore or migrate documentation
+
+### Schema.rb Import
+
+Two options to quickly bootstrap documentation from an existing database:
+
+- **This Project** — Reads the current project's `db/schema.rb` and imports all table/column definitions
+- **Upload File** — Upload any `schema.rb` file (from another project) via drag-and-drop or file picker
+
+The import uses bulk `insert_all!` for fast performance (1500+ columns in under 1 second).
+
+### Excel Export
+
+Export documentation as a formatted `.xlsx` file:
+
+- **All Tables** — Generates a workbook with a table index sheet and one detail sheet per table
+- **Single Table** — Export a specific table's column definitions
+
+All Excel content is fully internationalized (English/Japanese).
+
+---
+
+## Development
+
+### Running the test app
+
+```bash
+cd dbdoc_engine
+bundle install
+cd test/dummy
+bin/rails db:create db:migrate
+bin/rails dbdoc_engine:db:seed
+bin/rails server
+```
+
+### Running tests
+
+```bash
+cd dbdoc_engine
+bundle exec rspec
+```
+
+---
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+load "rails/tasks/statistics.rake"
+
+require "bundler/gem_tasks"