コンテンツにスキップ

インポート・エクスポート機能仕様

  • 現況再確認: 2026-08-11
  • 実装状況: 初期実装済み

現在はrouters/data_transfers.pyとdata_transfer_service.pyで、クラス、家庭、園児、保護者アカウント、保護者・園児紐付けのCSV/Excelテンプレート、エクスポート、事前検証、確定処理を提供する。認可施設帳票の出力も同じ画面へ統合されている。

ベータ開始時にデモデータを本番データへ置き換える作業は、通常の追加・更新インポートとは異なる。新規DBへの移行、家庭共有プロフィールの同期、切替・ロールバックを含む要件はベータ開始時の本番データ移行仕様に定める。

ID列は移行元IDではない

現行テンプレートのID、家庭ID、保護者ID、園児IDは、すべて取込先のopen-hoikuict DB内部IDである。値を指定した場合、同じDBに対象レコードが既に存在する必要がある。空DBへ外部データを移行する際の旧システムIDとしては使用できない。

ベータ移行では、内部IDと独立した移行元ID列を追加し、CSV一式を一括検証・一括確定する拡張を使用する。この拡張は現在未実装であり、ベータ開始時の本番データ移行仕様の受け入れ条件を満たすまで、現行Web UIを空DBへの本番移行手段として扱わない。

現行実装は家庭内リンクを自動生成する

現行の家庭同期処理は、同じ家庭の全保護者アカウントと全園児を直積で紐づける。また、保護者ポータルは家庭所属から全園児を閲覧対象にする。部分紐づけを保持できず、CSVにない園児へのアクセスを付与し得るため、この処理を改修するまで現行Web UIの保護者・園児紐づけインポートを本番移行に使用しない。

目的

園児、家庭、保護者、クラスなどの基本情報を、CSV または Excel ファイルで取り込み・出力できるようにする。

初期実装では、日常運用で更新頻度が高く、かつ一般的な台帳形式で扱いやすいマスタ系データを対象にする。履歴、ログ、添付ファイル、パスワード、既読状態など、外部ファイルで一括登録・更新する必要性が低いデータは対象外とする。

基本方針

  • 1 回のエクスポートは 1 データ種別、1 ファイル、1 シートとする。
  • Excel ファイルは 1 シートのみを扱う。複数シートを含むファイルはインポート時にエラーとする。
  • CSV と Excel のどちらも、1 行目をヘッダー行とする。
  • インポート前に必ず事前検証を行い、エラーがある場合は登録しない。
  • インポートで削除は行わない。
  • 更新時の空欄は既存値を維持する。
  • 新規登録時の必須項目が空欄の場合はエラーとする。
  • 値を明示的に空にする操作は初期実装では対象外とする。
  • パスワード、パスワードハッシュ、ログイン履歴、内部通知、既読履歴、添付ファイル実体はインポート・エクスポート対象外とする。
  • Family.shared_profile は初期実装ではインポート・エクスポート対象外とする。家庭に紐づく保護者情報は、保護者アカウントと保護者・園児紐づけで扱う。

対象データ

初期実装対象

データ種別 エクスポート インポート 備考
クラス 対象 対象 クラス名と表示順を扱う
家庭 対象 対象 家庭名、住所、電話番号を扱う
園児 対象 対象 基本情報、在園状態、所属クラス、家庭を扱う
保護者アカウント 対象 対象 連絡先情報を扱う。パスワードは対象外
保護者・園児紐づけ 対象 対象 続柄、主連絡先フラグを扱う

初期実装対象外

データ種別 方針 理由
健康プロフィール 第 2 段階候補 個人情報の重みが大きく、入力検証を別途丁寧に設計する必要がある
アレルギー 第 2 段階候補 1 園児に複数行を持つため、初期実装後に別仕様として扱う
健診記録 第 2 段階候補 履歴データであり、更新ルールを慎重に決める必要がある
出欠 エクスポートのみ 既存の CSV / Excel 出力を利用する。インポートは初期対象外
アンケート回答 エクスポートのみ 既存の CSV 出力を利用する。設問構造が動的なためインポート対象外
日次連絡 対象外 日々の保護者入力データであり、台帳型の一括更新に向かない
お知らせ 対象外 本文、配信対象、公開期間の運用差が大きいため初期対象外
議事録 対象外 バイナリや本文データを含み、単純な台帳形式に向かない
職員室メッセージ 対象外 添付ファイルとスレッド構造を含むため対象外
カレンダー 対象外 繰り返し予定、例外予定、通知などを含むため別仕様とする
職員ユーザー 対象外 認証・権限と密接に関わるため初期対象外

ファイル形式

CSV

  • 文字コードは UTF-8 BOM 付きとする。
  • 改行コードは CRLF とする。
  • 区切り文字はカンマとする。
  • 文字列中のカンマ、改行、ダブルクォートは CSV 標準に従ってクォートする。
  • ファイル拡張子は .csv とする。

Excel

  • ファイル形式は .xlsx とする。
  • 1 ファイルに 1 シートのみを含める。
  • シート名はデータ種別名とする。
  • 数式、マクロ、ピボットテーブルは使用しない。
  • ヘッダー行は 1 行目とする。
  • インポート時は表示形式ではなくセル値を使用する。

共通データ形式

種別 形式
日付 YYYY-MM-DD
日時 YYYY-MM-DD HH:mm
真偽値 入力は true / false / 1 / 0 / はい / いいえ を受け付ける。出力は true / false とする
数値 半角数字を標準とする
列名 標準テンプレートの日本語ヘッダー名を使用する

画面仕様

一覧画面

管理画面に「インポート・エクスポート」画面を追加する。

画面には以下を表示する。

  • 表示するデータ種別の選択
  • データ種別の選択
  • エクスポート形式の選択
  • テンプレートダウンロード
  • インポートファイルのアップロード
  • 事前検証結果
  • インポート実行結果

データ種別の表示設定では、クラス、家庭、園児、保護者アカウント、保護者・園児紐づけを画面上で表示・非表示にできる。これは画面整理のための設定であり、権限制御ではない。初期実装ではブラウザごとに保存する。

エクスポート操作

  1. データ種別を選択する。
  2. CSV または Excel を選択する。
  3. 必要に応じて絞り込み条件を指定する。
  4. ダウンロードを実行する。

初期実装の絞り込み条件は以下とする。

データ種別 絞り込み条件
クラス なし
家庭 なし
園児 クラス、在園状態
保護者アカウント 状態
保護者・園児紐づけ クラス、在園状態

インポート操作

  1. データ種別を選択する。
  2. 必要に応じてテンプレートをダウンロードする。
  3. CSV または Excel ファイルをアップロードする。
  4. 事前検証を実行する。
  5. 検証結果を確認する。
  6. エラーがなければ確定インポートを実行する。

事前検証では、登録予定件数、更新予定件数、スキップ件数、エラー件数を表示する。

インポート更新ルール

新規登録

  • ID が空欄で、既存データにも一致しない場合は新規登録とする。
  • 必須項目が空欄の場合はエラーとする。
  • 任意項目が空欄の場合は空値として登録する。
  • 園児の在園状態が空欄の場合は enrolled として登録する。

既存更新

  • ID が指定されている場合は ID で既存データを検索する。
  • ID が空欄の場合はデータ種別ごとの照合キーで既存データを検索する。
  • 既存データが見つかった場合は更新とする。
  • 更新時に空欄の列は既存値を維持する。
  • 園児の在園状態が空欄の場合は既存値を維持する。
  • 値を空にする専用記法は初期実装では用意しない。

ここでいうIDは取込先DBの内部IDである。新規空DBへの取込ではID列を空欄にする。

参照列の衝突チェック

ID と名称のように同じ参照先を示す列が両方指定されている場合は、ID を優先して参照先を検索する。ただし、名称も入力されている場合は、ID で見つかったデータの名称と一致することを検証する。

以下の場合はエラーとする。

  • 園児インポートで、家庭IDと家庭名が両方指定され、家庭IDの家庭名と入力された家庭名が一致しない。
  • 保護者アカウントインポートで、家庭IDと家庭名が両方指定され、家庭IDの家庭名と入力された家庭名が一致しない。

削除

インポートによる削除は行わない。削除が必要な場合は既存画面で個別に操作する。

照合キー

データ種別 優先照合 ID がない場合の照合
クラス ID クラス名
家庭 ID 家庭名 + 電話番号
園児 ID 姓カナ + 名カナ + 生年月日
保護者アカウント ID メールアドレス
保護者・園児紐づけ ID 保護者メールアドレス + 園児

園児の照合では、園児 ID があれば ID を優先する。ID がない場合は「姓カナ + 名カナ + 生年月日」で照合する。

インポート順序

複数データ種別をまとめて 1 ファイルで取り込む機能は作らない。データをまとめて移行する場合は、以下の順に個別インポートする。

  1. クラス
  2. 家庭
  3. 園児
  4. 保護者アカウント
  5. 保護者・園児紐づけ

園児インポート時に指定されたクラスや家庭が存在しない場合はエラーとする。保護者・園児紐づけインポート時に指定された保護者または園児が存在しない場合もエラーとする。

列定義

クラス

列名 必須 更新可 備考
ID 任意 不可 既存更新時の照合に使用
クラス名 必須 可 重複不可
表示順 任意 可 空欄の場合、新規登録では 1

家庭

列名 必須 更新可 備考
ID 任意 不可 既存更新時の照合に使用
家庭名 必須 可 例: 田中家
住所 任意 可 既存の家庭住所に対応
電話番号 任意 可 既存の家庭電話に対応

Family.shared_profile は初期実装では対象外とする。保護者の氏名、続柄、連絡先は、保護者アカウントおよび保護者・園児紐づけで扱う。

園児

列名 必須 更新可 備考
ID 任意 不可 既存更新時の照合に使用
姓 必須 可
名 必須 可
姓カナ 必須 可 照合キーに使用
名カナ 必須 可 照合キーに使用
生年月日 必須 可 YYYY-MM-DD
入園日 必須 可 YYYY-MM-DD
退園日 任意 可 YYYY-MM-DD
在園状態 任意 可 在園 / 卒園 / 退園 または enrolled / graduated / withdrawn。新規登録時の空欄は enrolled、既存更新時の空欄は既存値を維持
クラス名 任意 可 既存クラス名と一致する必要がある
家庭ID 任意 可 家庭名より優先
家庭名 任意 可 家庭IDがない場合に使用
住所 任意 可 個別住所。家庭住所がある場合、表示上は家庭住所が優先される
電話番号 任意 可 個別電話。家庭電話がある場合、表示上は家庭電話が優先される

保護者アカウント

列名 必須 更新可 備考
ID 任意 不可 既存更新時の照合に使用
表示名 必須 可
メールアドレス 必須 可 重複不可。照合キーに使用
電話番号 任意 可
住所 任意 可
勤務先 任意 可
勤務先住所 任意 可
勤務先電話番号 任意 可
家庭ID 任意 可 家庭名より優先
家庭名 任意 可 家庭IDがない場合に使用
状態 任意 可 有効 / 停止中 または active / inactive

パスワードはインポート対象にしない。必要な場合は招待、再設定、または既存の認証フローで扱う。

保護者・園児紐づけ

各行は明示的な1組の保護者・園児関係を表す。同じ家庭に所属していても、CSVに行がない組を自動生成しない。部分紐づけを許可し、family_idだけを理由に他の園児への閲覧権限を付与しない。

列名 必須 更新可 備考
ID 任意 不可 既存更新時の照合に使用
保護者ID 任意 不可 メールアドレスより優先
保護者メールアドレス 条件付き必須 不可 保護者IDがない場合に必須
園児ID 任意 不可 園児の氏名・生年月日より優先
園児姓カナ 条件付き必須 不可 園児IDがない場合に使用
園児名カナ 条件付き必須 不可 園児IDがない場合に使用
園児生年月日 条件付き必須 不可 園児IDがない場合に使用
続柄 任意 可 空欄の場合、新規登録では 保護者
主連絡先 任意 可 真偽値形式

バリデーション

共通チェック

  • 必須列が存在すること。
  • 必須項目が入力されていること。
  • 日付、日時、数値、真偽値の形式が正しいこと。
  • ID 指定時に対象データが存在すること。
  • ファイル内で照合キーが重複していないこと。
  • 外部参照するデータが存在すること。
  • 保護者・園児紐づけの保護者と園児が同じ家庭に所属していること。
  • 家庭同期によって、ファイルにない保護者・園児リンクが自動生成されないこと。
  • 更新権限のないユーザーが実行していないこと。

エラー表示

エラーは以下の項目で表示する。

項目 内容
行番号 ヘッダーを 1 行目として数える
列名 エラー対象の列
入力値 問題になった値
エラー内容 何を修正すべきか分かる説明

エラーが 1 件でもある場合、インポート確定はできない。

警告

登録は可能だが確認したほうがよい内容は警告として表示する。

例:

  • 退園日が入力されているが在園状態が在園のままになっている。
  • 家庭名は一致したが電話番号が空欄で、同名家庭が複数存在する。
  • 主連絡先が同一園児に複数指定されている。

警告のみの場合はインポート確定できる。

権限

  • テンプレート取得、インポート、エクスポートは、職員ログイン済みかつ園児台帳管理権限can_manage_child_recordsを持つユーザーに限定する。
  • adminは園児台帳管理権限を常に持つ。can_editだけでは利用できない。
  • view_onlyには業務別権限を付与しないため利用できない。

実行履歴

インポート実行時は、最低限以下を記録する。

項目 内容
実行日時 インポート確定日時
実行者 職員ユーザー名
データ種別 クラス、園児など
ファイル名 アップロードされたファイル名
新規件数 新規登録された件数
更新件数 更新された件数
エラー件数 検証時のエラー件数
結果 成功 / 失敗

エクスポート履歴は初期実装では必須としない。ただし、本番運用時には個人情報の持ち出し履歴として追加を検討する。

API・ルーティング

画面と処理は専用ルータに分離する。

メソッド パス 用途
GET /data-transfers/ インポート・エクスポート画面
GET /data-transfers/templates/{file_name} CSV / Excelテンプレートダウンロード。file_nameは{dataset}.csvまたは{dataset}.xlsx
GET /data-transfers/export/{file_name} CSV / Excelエクスポート。file_nameは{dataset}.csvまたは{dataset}.xlsx
POST /data-transfers/import/{dataset}/preview インポート事前検証
POST /data-transfers/import/{dataset}/commit インポート確定
POST /data-transfers/ninka/export 認可施設帳票Excel出力

dataset は以下の値を使用する。

dataset データ種別
classrooms クラス
families 家庭
children 園児
parent_accounts 保護者アカウント
parent_child_links 保護者・園児紐づけ

ファイル名

エクスポートファイル名は以下の形式とする。

hoikuict-{dataset}-{YYYYMMDD-HHmm}.{ext}

例:

hoikuict-children-20260510-0930.csv
hoikuict-parent-accounts-20260510-0930.xlsx

受け入れ条件

  • クラス、家庭、園児、保護者アカウント、保護者・園児紐づけを CSV でエクスポートできる。
  • 同じ対象を Excel でエクスポートできる。
  • 各データ種別のテンプレートを CSV / Excel でダウンロードできる。
  • テンプレートに沿った CSV / Excel をアップロードして事前検証できる。
  • 検証エラーがある場合、行番号・列名・入力値・エラー内容を確認できる。
  • 検証エラーがあるファイルは登録されない。
  • 検証エラーがないファイルは新規登録または既存更新できる。
  • 既存更新時、空欄の列は既存値を維持する。
  • インポートによって削除は発生しない。
  • パスワードやログイン履歴などの認証情報は出力・入力されない。

将来拡張

  • 健康プロフィール、アレルギー、健診記録のインポート・エクスポート。
  • エラー付きファイルのダウンロード。
  • 値を明示的に空にする専用記法。
  • エクスポート履歴の記録。
  • 外部システム連携向けの英字ヘッダー形式。
  • カレンダー予定の iCalendar 形式インポート・エクスポート。