Project

General

Profile

Actions
Copy link

Feature #35

closed
RA

Feature #105: [TAK-170] サンプルアプリ作成

[TAK-241] サンプルプログラムの配信・選択・プロジェクト追加機能を整備する

Feature #35: [TAK-241] サンプルプログラムの配信・選択・プロジェクト追加機能を整備する

Added by Redmine Admin about 3 hours ago. Updated about 3 hours ago.

Status:
Closed
Priority:
Normal
Assignee:
-
Start date:
09/30/2026
Due date:
% Done:

0%

Estimated time:
(Total: 0:00 h)

Description

Linear migration metadata

Original description

背景

サンプルプログラムを利用者が扱いやすくするため、別プロジェクトで作成した sample.epaa.jp のサンプルカタログを EPAA Core GUI から参照し、一覧から選んだサンプルアプリのテンプレート定義を現在のプロジェクトへ追加できるようにする。

決定事項

  • サンプル配信元 FQDN は sample.epaa.jp とする。
  • sample.epaa.jp は EPAA 本体とは別 GitHub リポジトリ / 別 Codex プロジェクトで管理する。
  • Core 側は sample.epaa.jp の JSON カタログを取得してサンプル一覧を表示する。
  • Core 側の入口は アプリ一覧 画面上部のボタンとする。
  • ボタン名は サンプルからアプリを追加 とする。
  • サンプル一覧上の各サンプルには インストール ボタンを表示する。ただし意味はアプリ実行環境のインストールではなく、テンプレート定義の読み込み / 追加である。
  • サンプル実体は samples.json に YAML を直接埋め込まず、カタログ JSON + テンプレート ZIP で配信する。
  • ZIP には manifest.json と、取り込み対象の metadata / i18n / seed / 帳票テンプレート等を含める。
  • Notion には登録せず、Linear で管理する。

要件

  • sample.epaa.jp などの配信元からサンプルカタログ JSON を取得できる。
  • Core GUI の アプリ一覧 に サンプルからアプリを追加 ボタンを追加する。
  • ボタン押下でサンプル選択画面またはダイアログを開き、利用可能なサンプルアプリを一覧表示できる。
  • 一覧ではカテゴリ、シナリオ、アプリ名、概要、バージョン、リリース日、更新日、スクリーンショット、タグ、公開状態を確認できる。
  • 見積など同一カテゴリに複数パターンがある前提で、カテゴリとシナリオを別項目として扱う。
  • 過去バージョンを保持し、ユーザーが最新バージョンと過去バージョンを区別できる。
  • サンプル選択後、テンプレート ZIP を取得し、manifest と checksum を検証できる。
  • インストール 押下後、即時保存せず、追加されるアプリ / 項目 / 設定 / ファイル差分をプレビューする。
  • サンプル追加時に、追加対象、既存プロジェクトへの影響、必要な生成・ビルド・反映処理が分かる。
  • プレビュー承認後、既存 YAML 管理と同じ考え方で Core の下書き状態へ反映し、validate-metadata が通った場合に保存可能にする。
  • 追加済みサンプルや同名リソースがある場合の扱いを定義する。
  • サンプル配信元、サンプル一覧、追加操作は EPAA GUI から管理・実行できるようにする。ただし配信元 URL を user-editable にする場合は GUI で作成・編集・削除できる正式管理経路を設計する。
  • サンプル由来情報として、取り込んだ sampleSourceId、sampleVersion、sampleInstalledAt、samplePackageChecksum、管理対象ファイル/リソース/項目の情報を記録できるようにする。
  • インストール済みの同一バージョンは インストール済み と表示し、通常の インストール は実行しない。
  • インストール済みより新しいバージョンがある場合は 更新あり と表示し、更新プレビューへ進める。
  • 更新は 3-way merge を前提にする。
    • A: インストール済みバージョンのデフォルトテンプレート
    • B: 現在のプロジェクト定義
    • C: 更新先バージョンのデフォルトテンプレート
  • 更新時は A と C の差分を、B に対して適用する。
  • A と B が同じ箇所はユーザー未変更として C を反映する。
  • A と B が異なる箇所はユーザー変更として扱い、原則 B を維持して上書きしない。
  • 更新プレビューでは、〇〇と〇〇の設定がデフォルトから変わっています。この項目は元に戻さず更新します のように、ユーザー変更を保持することを明示する。
  • ユーザーが追加した独自項目は保持する。
  • ユーザーがテンプレート由来項目の物理名を変更して追跡不能になった場合は、自動更新をブロックまたは手動更新扱いにする。
  • サンプル側のアップデート規約として、物理名変更、既存項目削除、型変更、キー変更など破壊的変更は同一 sampleId の通常更新では避ける。
  • 必須化が必要な場合は、既存ブランクを補完するための migrationDefaultValue または同等の移行方針をテンプレート manifest に持たせる。
  • サンプルテンプレート更新で既存データを壊さないため、DB移行や業務データ上書きは自動実行しない。
  • 自動更新が安全でない、または更新後に問題が見つかった場合に備え、インストール済みテンプレートのバージョンダウン / ロールバック方針を設計する。
  • バージョンダウンは、更新前スナップショットへ戻すことを基本とし、ユーザー変更済み箇所や独自追加項目を不用意に失わない。
  • 破壊的更新や移行を伴う更新では、逆方向の rollbackPlan または手動復旧手順がない限り、自動バージョンダウンを許可しない。
  • seed は既存データを不用意に上書きしない。業務データ直接投入は今回対象外とする。
  • sample.epaa.jp の将来機能としてコメント / 評価を想定するが、Core 側では今回投稿機能を実装しない。必要なら集計表示のみ将来拡張とする。

サンプル配信形式

samples.json

一覧表示用の軽量カタログとする。YAML本文は持たせない。

主な項目候補:

  • schemaVersion
  • updatedAt
  • samples[].id
  • samples[].title
  • samples[].description
  • samples[].category
  • samples[].scenario
  • samples[].version
  • samples[].releasedAt
  • samples[].updatedAt
  • samples[].status
  • samples[].tags
  • samples[].screenshots[]
  • samples[].packageUrl
  • samples[].checksum
  • samples[].minCoreVersion
  • samples[].maxCoreVersion
  • samples[].generatorVersion

テンプレート ZIP

取り込み対象の定義一式を ZIP にまとめる。

主な内容候補:

  • manifest.json
  • metadata/<resource>/<resource>.resource.yaml
  • metadata/<resource>/<resource>.i18n.yaml
  • metadata/<resource>/<resource>.seed.yaml
  • 帳票テンプレート YAML
  • 帳票 PDF テンプレートなどの関連アセット

ZIP内 manifest の主な項目候補:

  • sample id / version / releasedAt
  • 対応 Core / Generator バージョン
  • 追加されるアプリ一覧
  • 追加・変更対象ファイル一覧
  • 依存関係
  • checksum / size
  • migration plan
  • 必須化時の default value / 補完方針
  • インストール後に必要な生成・ビルド・反映手順

安全性・検証要件

  • remote sample content は未信頼として扱う。
  • ZIP slip を防止する。
  • 許可拡張子と許可ディレクトリを制限する。
  • ZIP サイズ、ファイル数、展開後サイズの上限を設ける。
  • checksum を検証する。
  • 将来の署名検証に拡張できる構造にする。
  • 秘密値、接続文字列、APIキー、パスワード等をテンプレートに含めない。
  • 書き込み範囲は選択中プロジェクトの許可された metadata / template 領域に限定する。
  • manifest/package 不正、checksum 不一致、配信元取得失敗、検証失敗、書き込み失敗を区別して表示する。
  • 失敗時には原因と次の操作が分かるエラー表示にする。
  • sample.epaa.jp が利用できない場合のオフライン / キャッシュ / 再試行方針を設計で決める。

受け入れ条件

  • 利用者が Core GUI の アプリ一覧 から サンプルからアプリを追加 を開ける。
  • 利用者が GUI 上で sample.epaa.jp のサンプル一覧を確認できる。
  • 利用者がカテゴリ / シナリオ / バージョン / リリース日 / スクリーンショットを見てサンプルを選べる。
  • 利用者が任意のサンプルを選択して、現在のプロジェクトへ追加できる。
  • インストール 前に、追加される定義・設定・ファイル・衝突・既存プロジェクトへの影響が表示される。
  • サンプル追加後、プロジェクト側に必要な定義・設定・ファイルが反映される。
  • 既存定義との衝突、上書き、スキップ、名称変更、ブロックなどの扱いが画面上で分かる。
  • インストール済みサンプルは同一バージョンなら インストール済み、新バージョンがある場合は 更新あり と分かる。
  • 更新時、デフォルトから変更されたユーザー設定は上書きされず、プレビューで保持対象として明示される。
  • 更新時、インストール済みバージョンのデフォルトと最新バージョンのデフォルト差分だけが、現在プロジェクトへ安全に適用される。
  • 必須化など移行を伴う変更は、manifest の移行方針に基づいてプレビュー表示される。
  • 更新前のテンプレート由来スナップショットを保持し、必要に応じて前バージョンへ戻せる。
  • バージョンダウン時も差分プレビューを表示し、削除・型戻し・必須解除・選択肢戻しなど既存データに影響しうる変更は自動適用しない。
  • 追跡不能な物理名変更、破壊的変更、危険な変更は自動更新されず、手動対応またはブロックとして分かる。
  • 失敗時には原因と次の操作が分かるエラー表示になる。
  • ウェブ配信が利用できない場合のオフライン・キャッシュ・再試行方針が設計で明確になる。

非対象

  • sample.epaa.jp サイト本体の実装・移行。
  • 個別サンプルアプリの中身の詳細設計・実装。
  • すべてのサンプルテンプレートを同時に完成させること。
  • Core 側でコメント / 評価の投稿機能を実装すること。
  • YAML直接編集だけで運用する仕組み。
  • Core から生成アプリDBへ業務データを直接投入すること。
  • 破壊的テンプレート変更を自動で安全に解決すること。

影響範囲メモ

  • FE: アプリ一覧 への サンプルからアプリを追加 ボタン、サンプル一覧、カテゴリ/シナリオ/バージョン表示、スクリーンショット表示、インストール/更新プレビュー、結果表示、エラー表示。
  • BE: サンプルカタログ取得、テンプレートZIP取得、manifest/checksum検証、サンプル追加/更新プレビュー、衝突検出、3-way merge、下書き反映、生成・反映処理連携。
  • DB: Core側DBは初期必須ではない。サンプル取得履歴やカタログキャッシュを永続化する場合は設計で検討する。sample側DBは別プロジェクト管理。
  • OpenAPI: 固定APIが必要な場合は実装前に契約定義が必要。WebView2 bridge のみで閉じる場合は bridge 型を契約として扱う。
  • GUI管理: サンプル配信元や有効/無効設定を導入する場合は、作成・編集・削除できるGUIを先に設計する。
  • Browser/WebView2: GUI操作のブラウザ表示確認に加え、公開済み WebView2 exe で確認する。
  • Docs: adoc/manuals/lowcode-project-flow.adoc、adoc/manuals/resource-yaml.adoc、adoc/manuals/manual.adoc の更新要否を設計で確認する。
  • Linear: TAK-241で管理する。子Issueは必要に応じてユーザー確認後に作成する。
  • Notion: 使用しない。

子Issue候補（未作成）

  • FE: アプリ一覧への導線、サンプルカタログ一覧・選択・追加/更新プレビューUI。
  • BE: サンプルカタログ取得、テンプレートZIP検証、追加API/bridge、衝突検出、3-way merge。
  • Test: サンプル取得、追加成功、インストール済み表示、更新あり表示、ユーザー変更保持、衝突、失敗時表示、WebView2操作確認。
  • Docs: サンプル配信・追加・更新手順のドキュメント化。

注意事項

  • メタデータやアプリ設定が生成動作に影響する場合、YAML直接編集のみを正式管理パスにしない。
  • 既存プロジェクトへ追加・更新するため、上書き・差分適用・ロールバック方針は設計時に要確認。
  • アップデート安全性は100%保証できないため、安全判定できる差分だけを自動適用し、必要に応じてバージョンダウン / 手動復旧できる設計にする。
  • 実装時は EPAA の C# + React + Vite + MUI / PostgreSQL 前提に従う。
  • 現在の作業ブランチが TAK-241 ではない場合、実装前に develop 起点の codex/tak-241-sample-catalog-import などの issue branch を作成する。

管理メモ

  • 要件登録: 2026-08-26
  • 要件更新: 2026-08-29
  • 子Issueは候補のみ記載し、未作成。分割は設計開始時に確認する。

2026-08-29 追加決定・スコープ調整

  • 初期スコープは 新規インストールができること に絞る。
  • アップデート適用、バージョンダウン、ロールバックは次フェーズとする。ただし初期実装でも将来対応できるよう、サンプル由来情報とスナップショット保存方針は設計する。
  • サンプル配信元は当面 https://sample.epaa.jp の1つに固定する。複数配信元管理や配信元URLのユーザー編集は初期対象外。
  • sample.epaa.jp は当面公開サイトとして扱い、Core側は公開JSONカタログと画像を直接参照する。
  • インストール記録はCore専用DB/操作ログが現時点でない前提で、既存の実行履歴またはプロジェクト管理ファイルへの保存を設計する。
  • ZIP manifest の Core / Generator 互換バージョンが現在のCoreより新しい場合、インストールせず Core を最新化するよう促す。
  • アップデートは将来的にアプリ単位とするが、請求書と商品アプリのような依存関係がある場合、manifest に依存アプリIDと要求バージョン範囲を持たせる。
  • 依存バージョンが不足する場合は、〇〇、〇〇のバージョンアップが必要になりますがよろしいですか？ のように一括で必要な更新候補を提示する。
  • 同名リソースが存在する場合、初期スコープではエラーとしてブロックする。rename / skip / merge は初期対象外。
  • seed は初回のみの想定とし、初期フェーズではテンプレートインストール時に取り込まない。Coreから生成アプリDBへ業務データを直接投入しない。
  • ユーザー向け失敗表示は低めの粒度に抑え、取得失敗・インストール不可・検証失敗など理解しやすい概要と次の操作を出す。
  • 詳細な技術情報はCore GUIのログ/実行履歴に出力し、サポート時にそのログ提供を促せる導線を用意する。

2026-08-29 追加決定・設計論点2

  • Core共通のアプリケーションログ機能は別Issue TAK-243 として扱う。
  • ログとスナップショットは、ユーザーが指定した対象プロジェクトディレクトリ配下に保存する。
  • ログは対象プロジェクト配下の logs ディレクトリへテキストで出力する。
  • 初期ログローテーションは必須にしない。容量が増えた場合はユーザーが logs 配下を削除できる前提。ただし単一ファイル肥大化を避けるため、日付別または実行単位のログファイル名を設計する。
  • ログは成功/失敗を問わず同じ経路で出力し、検索しやすいよう ERROR、WARNING、INFO などの識別子を含める。
  • サポート時には、エラー画面からログ提供を促せるようにする。
  • スナップショットは、インストール/更新/リリースなどの節目で、その時点に戻すためのテンプレート由来状態またはプロジェクト状態を保存するものとして扱う。
  • バージョンダウンを可能にするには、過去バージョンのテンプレート情報だけでなく、対象プロジェクト側の更新前状態を戻せるスナップショットが必要になる。
  • dev/stg/prod の流れでは、dev は頻繁にスナップショットから戻す可能性があるため、スナップショット復元を次フェーズの重要要件として扱う。
  • 初期インストール時、依存アプリは一括でインストールする。
  • 依存アプリが既にインストール済みだが要求バージョンに足りない場合は、必要なアップデート対象をまとめて警告表示する。
  • Core本体が最新でない、またはテンプレート要求バージョンを満たさない場合はエラーとし、Coreを最新化するよう促す。
  • インストールプレビューでは、インストール対象アプリの情報、依存関係により同時にインストールされるアプリ、将来アップデートが必要になるアプリ一覧を表示する。
  • インストール時はAI YAML変更案と同じく、即時保存ではなく下書き反映とし、ユーザーが内容を確認して保存する動きにする。
  • samples.json は sample.epaa.jp に登録されているサンプルアプリ一覧のカタログである。
  • manifest.json は各テンプレートZIPの中に入る取扱説明書/契約情報であり、そのZIPに何が入っていて、どのCore/Generatorバージョンに対応し、どのファイルを書き込み、どの依存関係や注意事項があるかをCoreが安全に判定するために使う。

2026-08-29 追加決定・設計論点3

  • スナップショットは設定ファイル全体をバックアップし、リリース単位で保存する。
  • スナップショットはログと同様に、ユーザーが指定した対象プロジェクトディレクトリ配下に保存する。
  • インストール後の導線はAI YAML変更案に揃え、即時保存ではなく下書き反映・確認・保存の流れにする。
  • manifest は初期フェーズでは最小構成にする。主な項目は sampleId、version、apps、dependencies、files、checksum 程度とする。
  • 依存関係解決失敗はレアケースとして扱い、初期フェーズではブロックする。
  • 同名リソース判定は resource名とtable名を最低限確認する。table名重複は生成後DB衝突につながるためブロックする。
  • スクリーンショットはCoreが撮影するものではなく、sample.epaa.jp側で用意するカタログ表示用の画像をCoreが表示する意味とする。画像取得失敗時は一覧を止めず代替表示にする。
  • seed はユーザー作成のマスタデータにもなり得るため、テンプレート定義とは扱いを分ける。サンプルデータとして提供することは可能だが、初期インストールで自動取り込みするかは設計で明確化する。
  • 現時点のCoreにはseed作成専用機能がない前提で、seedを扱う場合はテンプレートZIP同梱・プレビュー・取り込み可否・生成アプリ側投入経路を設計する。

Linear attachments

Subtasks 1 (1 open — 0 closed)

Feature #33: [TAK-243] Core: プロジェクト配下にアプリケーションログを出力するNew09/30/2026

Actions
Actions
Copy link

Also available in: PDF Atom