1Commonwealとは — 3つの層と自動連結

Commonwealは、業務の言葉(業務データ辞書)・業務の構造(EDM=業務概念モデル)・動いている実装(物理DBとアプリケーション)の3つを突き合わせ、設計の知識を担当者や部署に囲い込まず、読める形で共有し続けるための製品です。書くのは人、繋ぐのは製品。出力のたびに3つの層の対応関係が作り直されます。下の図は「顧客納期」という1つのデータドメインを例に、3つの層がどう繋がるかを示したものです。

3つの層はそれぞれ別々に育てられます。書くのは人、繋ぐのは製品です。図の色の付いた欄(EDMのドメイン欄・辞書の本文と物理属性名・DBコメント・画面の表示名)が人の書く場所で、矢印はすべて出力のたびに製品が作り直す繋がりです。手作業でリンクを維持する必要はありません。

• 概念の層(EDM) — 業務をエンティティ(受注・出荷・在庫など)と属性で描いた図。A5:SQL Mk-2で作った.a5erファイルを登録します。属性のドメイン欄(A5:SQL Mk-2の属性の「ドメイン」列)に辞書のデータドメイン名を書くと、そこが辞書との接点になります
• 意味の層(業務データ辞書) — 「顧客納期」「顧客コード」のようなデータドメインごとに、業務的定義・ビジネスルール・導出ルール・暗黙知・責任部門を蓄積します。データドメインには物理属性名をぶら下げ、これが実装との照合キーになります
• 実装の層(物理DBとTALON画面) — 実際に動いているテーブルの列と画面項目。出力のたびに、物理列は物理名と論理名(DBコメント)で、画面項目は表示名と物理名で辞書と照合されます

同じデータドメインは何箇所に配置してもかまいません。図の「顧客納期(予定)」「顧客納期(実績)」「初回回答納期」は別々の属性ですが、ドメイン欄がどれも「顧客納期」なので1つのデータドメインに集まります。属性名がまったく違っていてもかまいません。照合に使うのはドメイン欄だけだからです。役割は属性名が担い、意味はドメイン欄が担う。この分担があるので、意味の定義はデータドメインごとに1回書けば済みます。

名前がまったく違っていても、物理項目とEDM属性を直接繋ぐこともできます(図の破線)。この繋がりの両端は物理項目とEDM属性で、辞書はそれを書く場所です。図では物理列T_ORDER_H.F_NOKIを辞書の物理属性名F_NOKIとして登録し、その行のEDM属性欄に「受注.初回回答納期」と書いています。これで、名前の一致に頼らずにその物理列がどのEDM属性の実装かが確定します(ユーザーマニュアルの7章のEDM属性の宣言)。宣言した繋がりは設計書の4面(業務データ辞書索引・EDMページ・物理データベース・機能設計書)に表示され、物理列や画面項目の側にもEDM属性が併記されます。照合ルールの全体はリファレンスページの1章にまとめています。

これでできることは次の3つに集約されます。

• 設計書がいつでも最新 — TALONの設定そのものから生成するので、実装と食い違いません
• 項目の意味が設計書で読める — 画面項目や物理列に、辞書の業務的定義やルールが自動で対応付きます
• 抜けが見える — 辞書に載っていない項目、EDMにあるのに実装がないデータドメイン、などの突き合わせ結果が警告・マトリクスとして出ます

▦TALONとの関係(2つの層)

Commonwealは実行エンジンとしてTALON(ローコード開発基盤)を利用し、TALON上で動く機能群として提供されます。ここから2つの層に分かれます。

• TALONで開発したシステム — 機能設定(機能ID単位)を読んで、機能設計書までを自動生成します。画面ビジュアル・項目定義・SQL・依存関係の解析はこの機能設定から組み立てています
• TALONで開発していないシステム — 業務データ辞書・EDM・物理DBの突き合わせという中核機能はそのまま使えます。対象テーブルは、サブシステム単位に用意した台帳用の機能の備考に備考タグで列挙して伝えます(ユーザーマニュアルの8章)

どちらのケースで何が使えるかは、次の2章に整理しています。

▦プランと機能範囲

Commonwealは1つのモジュールで3つの販売プラン(エディション)に切り替わります。プランはライセンスファイル(配置の手順はセットアップガイド参照)で決まります。ライセンスの発行・更新は販売元へお問い合わせください。

プラン別の機能一覧(出力される成果物)

• 機能設計書本体(FuncDoc)の情報量は全プラン同一です — プランで削られるのは上の表で非出力になる成果物と、そこへ向かうリンクだけです(リンクは無効化されますが、依存関係タブのテーブル名などのテキスト情報はそのまま残ります)
• 業務データ辞書・EDMの管理画面は全プランで使えます — 登録したデータが設計書の出力に現れるのが③全機能版のときだけ、という違いです
• プランの判定は出力のたびに行われます — ライセンスファイルの差し替えは即時に反映され、TALONの再起動は不要です
• ライセンスが未配置・無効(改竄など)・期限切れ(有効期限の当日までは有効)の場合は、自動的に①無償版として動作します

▦どう動くか(アーキテクチャ)

CommonwealはTALONアプリケーションそのものです。TALONのリポジトリ移送(取込)で導入する機能群と共通JavaScriptライブラリとして提供され、追加のサーバー・エージェント・外部サービスは一切不要です。

[出力画面で機能を選択] → 「設計書出力」ボタン
   ↓ (TALONサーバー内で実行)
機能設定・実DBのスキーマを読み取り → 依存関係を解析 → HTML/Markdown/ER図を生成
   ↓
ZIP化してブラウザへ直接ダウンロード (サーバーにファイルは残りません)

• 生成はすべてサーバーサイドで完結します — TALONのサーバーサイドJavaScriptとして実行され、外部API・AIプロバイダー・インターネット接続は使いません
• ZIPはサーバーに残りません — 生成したZIPはファイルとして保存せず、ブラウザへ直接受け渡します(以降の取り扱いは利用者側で完結します)
• スタンドアロンHTML — 出力される各HTMLはCSSとJavaScriptを埋め込んだ単独のファイルです。Webサーバー不要で、ファイル共有・オフライン環境でもそのまま閲覧できます
• 作図ツールへ直結 — ER図の.a5erはA5:SQL Mk-2でそのまま開けるネイティブ形式で、実DBから取得した索引・外部キー・論理名コメントを含みます。.sqlはCREATE TABLE/ALTER TABLE(外部キー・ユニーク制約)/COMMENTとして実行できるDDLです
• 出力対象の選択・検索・実行は通常のTALON画面操作です。特別なクライアントソフトは要りません

▦何を読むか(一次情報)

設計書の情報源は動いている実装そのものです。手書きの中間ドキュメントや別管理のメタデータを持たないので、再出力すれば常に実装と同期した設計書になります。

画面ビジュアル(画面イメージ)も機能設定から組み立て直したものです。フリーレイアウトのセル配置、検索条件の集約、表示項目設定(列の順序・表示/非表示)、処理権限によるボタンの出し分けなど、実画面と同じ表示ルールを機能設定から再現します(ユーザーマニュアルの3章)。

「この機能がどのテーブルを読み書きするか」は、ブロックの更新テーブル設定・SELECT式・JavaScript内のSQL文字列・ストアドプロシージャ本体・他機能呼出まで遡って自動抽出し、実DBと突き合わせます。参照が検出されたのに実DBに存在しないテーブルは「DB未検出」として表示されるため、打ち間違いや廃止済みテーブルへの参照に気付けます。解析で拾えない依存(変数連結のテーブル名・プロシージャから呼ぶ別のプロシージャ・トリガ連動など)は備考タグで宣言できます(ユーザーマニュアルの8章)。抽出範囲と判定の細則はリファレンスページの1章の「#7 機能 → テーブル」にまとめています。

▦動作環境

• ストアドプロシージャ本体の解析は上記4つのデータベースに対応しています
• MySQLのときだけ、プロシージャ本体の読み取りにTALON接続ユーザーへのグローバルSHOW_ROUTINE権限が必要です(セットアップガイド参照)
• ZIPをブラウザへ直接受け渡す方式のため、運用はHTTPSを推奨します

▦セキュリティ設計

• データは外に出ません — 生成処理はTALONサーバー内で完結し、外部サービスへの送信はありません。生成AIとの連携も「出力されたZIPを利用者が渡す」形で、製品が自動で送信することはありません
• TALONの権限モデルに準拠します — 設計書を出力できるのは対象機能の参照権限を持つ利用者だけです。機能に「管理者」が設定されている場合の表示制限もTALON本体と同じ規則で働きます
• SQLインジェクション対策 — 利用者の入力を含むSQLはプレースホルダ(PreparedStatement)で実行します
• ライセンスはオフラインで検証します — 販売プランの判定はRSA署名付きライセンスファイルの検証で行います。製品に埋め込まれるのは公開鍵だけで、ライセンス認証のためのネットワーク接続は不要です

23つの利用パターン

使い方は、対象のシステムをTALONで開発しているかどうか、複数のプロジェクトを1つの環境で管理するかどうかで変わります。代表的な3つのケースです(組み合わせても構いません。TALONで開発した機能と、TALON外のサブシステムの台帳を同じ設計書にまとめられます)。

▦ケース1: TALONでシステムを開発している

• 向いている状況 — 設計書の更新が実装に追いつかない。改修のたびに「どの機能がどのテーブルを触るか」を調べ直している
• 使う機能 — 全機能。機能設計書(画面ビジュアル・検索条件・項目定義・全設定・SQL)の自動生成、依存関係の自動解析(機能→テーブル/機能→機能)、機能一覧・機能依存ツリー・差分設計書、物理DB(ER図・DDL)、業務データ辞書・EDMとの照合、マトリクス、AI向けMarkdown
• 最初の一歩 — リポジトリを取り込み、セットアップの「処理実行」を1回(セットアップガイド参照)。あとは機能を選んで「設計書出力」(ユーザーマニュアルの2章)。辞書とEDMは後から少しずつ育てられます

▦ケース2: TALONを使っていない(既存システム・パッケージ・SaaSが対象)

• 向いている状況 — 動いているシステムはあるが、用語の定義や項目の意味が人に閉じている。テーブルの棚卸しと、業務の言葉と実装の対応付けから始めたい。自社開発のシステム・パッケージ・SaaS(Salesforceなど)が混在していて、全体を通した用語の対応表が無い
• 使う機能 — 業務データ辞書とEDMの登録・維持、物理DBとの突き合わせ(ER図・DDL、物理列と辞書の照合、マトリクス、業務データ辞書索引、宿題一覧、整合性・ガバナンス警告)。対象テーブルの宣言は台帳用の機能+備考タグで行います(ユーザーマニュアルの8章)
• 対象外 — 機能設計書の自動生成・画面ビジュアル・検索条件や項目定義の抽出・機能間の呼出関係は、いずれもTALONの機能設定から組み立てるものです。TALONで開発していないシステムでは出力されません(台帳用機能の設計書は、機能名・機能概要・備考タグによる依存関係だけの最小限のものになります)
• 最初の一歩 — 対象システムのDBが主DBと別ならTALONの複数DB接続に登録(SaaSはCDataなどのJDBCドライバ経由で登録します) → サブシステム単位に台帳用の機能を作り備考タグでテーブルを宣言 → 出力してER図に定義が出ることを確認 → 業務データ辞書を数件のデータドメインから書き始めます(ユーザーマニュアルの4章)

▦ケース3: 複数プロジェクトを1つの環境で運用する

• 向いている状況 — 1つの環境で複数の案件・部門・システムの設計を管理していて、設計書にはその案件の辞書・EDMだけを載せたい
• 使う機能 — プロジェクト単位の出力制御(ユーザーマニュアルの10章)
• 最初の一歩 — 汎用コードTLN_FUNC_DOC_PROJECTにプロジェクトを登録(初期状態は画面上未登録。登録するまでチェックボックスは出ません) → 辞書・EDMの各行にプロジェクトをチェック(複数可、空欄=共通で常に出力) → 出力時に「出力対象プロジェクト」で絞ります

3はじめの流れ(クイックスタート)

1. セットアップを実行します — リポジトリ取込後、セットアップ画面の「処理実行」を1回押します(テーブル作成などが自動で行われます)。続けて「メニュー登録」を押し、ログインし直すとCommonwealの画面がメニューに並びます(詳しくはセットアップガイド参照)
2. 設計書を出力してみます — 「機能設計書出力」で機能を検索し、チェックして「設計書出力」。ZIPがダウンロードされます(ユーザーマニュアルの2章)
3. 業務データ辞書を書き始めます — 最初は数件のデータドメインで十分です。現場の方は「業務データ辞書記入」、IT側は「業務データ辞書メンテナンス」から(ユーザーマニュアルの4章・ユーザーマニュアルの5章)
4. EDMを登録します — A5:SQL Mk-2で描いた.a5erを「EDMメンテナンス」で登録します(ユーザーマニュアルの6章)
5. もう一度出力します — 辞書とEDMが設計書に織り込まれ、項目に意味が付きます