Imported from takahikouchida/shape-convert-web (
AGENTS.md). Install upstream withnpx skills add takahikouchida/shape-convert-web. Copyright stays with the author.
AGENTS.md
Goal
Dockerで起動できる、シェープファイル変換Webアプリを実装する。 ユーザーはZIP化したShapefileをアップロードし、地図可視化し、CSV/GeoJSONへ変換してダウンロードできること。
Scope
- このリポジトリ内で完結する実装を行うこと
- サーバー/API、フロントエンド、Docker構成、必要なテストを含む
- 既存ファイルの破壊的変更は避ける（必要時は理由を明記）
Functional Requirements
- ZIPアップロード
.zipのみ受け付ける- ZIP内に
.shp/.shx/.dbfが揃っていることを検証する - 座標系定義ファイル（
.prj）の有無を検証する - ZIP内に複数Shapefileがある場合の扱い（先頭採用または選択）を実装時に明示する
- 不正ファイル時はユーザーに分かるエラーを返す
- 可視化
- MapLibre GL JSでアップロード後データを地図上へ描画する
- 初期表示で全体が収まるようにfitする
- 背景地図（ベースマップ）を画面上でユーザーが切り替え可能にする
- オープンな地図タイルとオープンな航空写真タイルを複数種類用意する
- 各タイルの利用条件（利用規約・帰属表示）を満たす形で表示する
- 変換
- 変換は必ずサーバー側でGDAL（
ogr2ogr）を使用する - ShapefileをGeoJSONへ変換できる
- 属性データをCSVへ変換できる
- フロントエンドではShapefileの変換処理を行わない
- ダウンロード
- 生成した
GeoJSONとCSVをそれぞれダウンロード可能にする - CSVダウンロード時に出力カラムをユーザーが選択できるようにする（全選択/解除、主要カラム初期選択など）
- CSVダウンロード時に出力カラムの並び順をユーザーが指定できるようにする
- 未選択状態でのCSV出力は不可とし、ユーザーに選択を促す
- 文字コード
- Shapefile入力文字コードを指定可能にする（例:
AUTO,UTF-8,CP932） .cpgが存在する場合はその値を優先し、必要に応じてユーザー指定で上書き可能にする- GDAL実行時に入力文字コード指定を反映する（例:
--config SHAPE_ENCODING） - CSV出力文字コードを選択可能にする（
UTF-8,UTF-8 BOM,CP932） - 文字コード不一致時はユーザーに分かるエラー/警告を返す
- 座標系（CRS/EPSG）
.prjがある場合はその定義を使用する.prjがない場合、EPSGコードのユーザー指定を必須にする.prjがない状態でEPSG未指定の場合は、変換と可視化を実行せずエラーを返す- 必要に応じてGDALで入力座標系を付与してWGS84（
EPSG:4326）へ変換する（例:-a_srs EPSG:xxxx -t_srs EPSG:4326）
Non-Functional Requirements
- Dockerで
docker compose upにより起動可能にする - READMEにセットアップ・起動・利用手順を記載する
- エラーハンドリングを実装する（アップロード失敗、変換失敗、空データ等）
- 大きなファイルを考慮し、処理中状態をUIに表示する
- ベースマップ切替時の操作レスポンスを損なわない構成にする（タイル読込中表示など）
Tech Preferences
- 言語はTypeScriptを優先
- APIはNode.js系を優先（例: Fastify/Express）
- 地図表示は MapLibre GL JS を使用する
- 変換エンジンはGDAL（
ogr2ogr）を使用し、Dockerイメージに同梱する - 依存ライブラリは採用理由を短く記載する
Constraints
- 秘密情報をコードに埋め込まない
- 不要な大規模リファクタはしない
- 変更は最小単位で行い、動作確認を都度実施する
Output Format (for each task)
- 変更概要（3-5行）
- 変更ファイル一覧
- 実行コマンド
- 動作確認結果
- 未対応事項 / 次のステップ
Definition of Done
- Docker起動できる
- ZIPアップロード→可視化→CSV/GeoJSONダウンロードが通る
- Shapefile入力文字コード指定とCSV出力文字コード選択が動作する
- CSV出力時にカラム選択と並び順指定が可能で、指定内容が出力に正しく反映される
- 変換処理がGDAL経由で実行される
.prj欠落時にEPSG指定が必須として動作し、未指定時はエラーとなる- 背景地図をUIから切替でき、オープン地図・オープン航空写真の複数選択肢が利用できる
- READMEの手順で第三者が再現できる
- 最低限のテストが通る