Webアプリケーションの引継ぎ備忘録

転職やフリーランスで保守していたシステムを後任のエンジニアに引継ぎする際、引き継ぐシステムの概要・コード・構築方法などの必要な情報をまとめておくと、引継ぎに使う工数が削減でき、引継ぎ中・後に起こるトラブルを減らすことができる。

しかし、他者のための資料作成は往々にして面倒。なのでできるだけ簡単に作成できるよう下記にまとめてみた。

Webアプリの引継ぎの際に必要な情報

必要な主な情報。最低限この情報があれば、僕はいいかなと思う。

• システム全体の概要(Draw.ioと文書)
• サーバー・サーバレスのコードやシステムの概要(Git)
• データベース構造(ER図)
• その他のシステム(ドメイン・DNS、SSL/TSL証明書等)(文書)
• ロギング確認方法(手順書)
• 保守・運用方法(手順書)

1. システム全体の概要把握
   システムの全体構成図（アーキテクチャ図）
   技術スタック一覧（言語・フレームワーク・ライブラリ・データベース・クラウドサービス等）
   主要機能の一覧・概要（ユーザー認証、API連携、バッチ処理など）
   依存関係のある外部サービス・API
2. コード・リポジトリの引き継ぎ
   Gitリポジトリ（GitHub, GitLab, Bitbucketなど）のリンクとアクセス権限
   ソースコードのコード規約の順守
   README.mdの充足
   • ブランチ戦略（main/dev/featureブランチの運用ルール）
   • コードのビルド・デプロイ手順
   • 環境ごとの設定（本番・ステージング・ローカル環境の違い）
3. 開発環境の準備
   ローカル開発環境のセットアップ手順
   必要な環境変数（.env ファイルやシークレットキー管理）
   依存ライブラリのインストール方法（package.json, requirements.txt など）
   Docker や仮想環境の使用有無
4. データベース管理
   データベースの種類（MySQL, PostgreSQL, MongoDBなど）
   スキーマ設計の概要と管理方法（マイグレーションツールの使用有無）
   データバックアップ・リストア手順
   SQLクエリやORMの使用方針
5. インフラ・サーバー管理
   使用しているクラウド（AWS, GCP, Azure, Vercel など）
   サーバー構成（EC2, Lambda, Cloud Functions, Kubernetesなど）
   CI/CD（GitHub Actions, Jenkins, CircleCIなど）
   ドメイン・DNS設定（Cloudflare, Route 53 など）
   SSL証明書の管理
6. セキュリティ対策
   認証・認可（OAuth, JWT, Session管理）
   シークレット情報の管理（環境変数、AWS Secrets Manager など）
   セキュリティ対策（CORS設定、SQLインジェクション防止、XSS対策など）
7. ログ・モニタリング
   ログ管理（CloudWatch, ELK, Datadog, Sentry など）
   エラートラッキングの仕組み
   パフォーマンスモニタリング（New Relic, Prometheus など）
8. 保守・運用
   バグ・課題管理（JIRA, Trello, Notion など）
   定期的なメンテナンスのスケジュール
   緊急対応時の連絡フロー
   ドキュメントの管理場所と最新化のルール
9. ドキュメントの整備
   システム仕様書・設計書
   API仕様（OpenAPI, Swagger, Postmanコレクションなど）
   運用マニュアル
   よくあるトラブルと対処方法
10. 権限・アカウント管理
    必要なアクセス権限の付与（Git, サーバー, DB, クラウドサービスなど）
    退職・異動したメンバーのアカウント削除・整理
    共有アカウントの管理方法

実際の引継ぎ資料

AWSを利用したWebアプリケーションの引継ぎ資料を作成した。

1. システム全体の概要把握

   • システムの全体構成図
     
   • 技術スタック
     フロントエンド：Next.js
     バックエンド：Python
     サーバー・データベース：AWS EC2/Lambda/DynamoDB/S3
     サーバーソフト：Nginx
     Web API：Python Fast API/AWS API gateway+Lambda
   • 主要機能の概要
     ユーザー認証：CognitoとReactライブラリ(aws-amplify/aws-amplify-react)
     API連携：API gateway(Cognito認証付き)
     バックエンド処理：Fast API on EC2/Python on Lambda
     定期処理：Event Bridge+Lambda
     キューイング：SQS+Lambda
   • 依存関係のある外部サービス・API
     外部API利用: Amazon SP-API/Yahooショッピング API/Keepa API

2. コード・リポジトリ・開発環境方法の引き継ぎ
   ・EC2内のコードはGitを共有(詳細をReadmeに記載)
   　フロントエンド：リンク
   　バックエンド：リンク
   
   ・サーバレスのコード

   Lambda関数/
   　├ Check-APIKey
   　├ Get-Auto-Result
   　├ Get-Listing-Result
   　├ Get-Result
   　├ Get-NonListing-Result
   　├ ASIN-Input-Product
   　├ Delete-Listing-Result
   　├ Exhibit-Listing-Result
   　├ Initial-SetUp
   　├ Setting-APIKey
   　├ Setting-Admin
   　├ Setting-AutoPrice
   　├ Setting-Exhibit
   　├ Setting-Filtering
   　├ Setting-Profit
   　├ Periodic-execution-Check-APIKey
   　├ Periodic-execution-SQS
   　├ Periodic-execution-SetListingResult
   　├ Periodic-execution-AutoExhibitProcess
   　├ Periodic-execution-ExhibitProcess
   　└ Periodic-execution-NonListingDelete

   ・EventBridge スケジューラ

   EventBridge スケジューラ/
   　├ Periodic-execution-SQS-Scheduler
   　├ Periodic-execution-AutoExhibitProcess
   　├ Periodic-execution-Check-APIKey
   　├ Periodic-execution-ExhibitProcess
   　├ Periodic-execution-NonListingDelete
   　└ Periodic-execution-SetListingResult

   

3. データベース構造
   データベースの種類：DynamoDB/S3
   ユーザーごとにデータベーステーブル・S3 Bucketを作成。
   データベース設計：

   DynamoDB/
   　├ UserID1/
   　├ UserID2/
   　├ UserID3/
   　│　├ UserID3-API-Key
   　│　├ UserID3-AutoPrice-Setting
   　│　├ UserID3-Filtering-Setting
   　│　├ UserID3-Get-Auto-Result
   　│　├ UserID3-Get-Listing-Result
   　│　├ UserID3-Get-NonListing-Result
   　│　├ UserID3-Get-Result
   　│　├ UserID3-Parameter-Setting
   　│　├ UserID3-Profit-Setting
   　│　└ UserID3-SP-API-Checking
   　 ..............................
   　 ..............................
   　 ..............................
   　└ UserID999/

   S3/
   　├ UserID1-bucket/
   　├ UserID2-bucket/
   　├ UserID3-bucket/
   　│　├ ListingList.csv
   　│　├ ProductList.csv
   　│　└ Result_**********.csv
   　 ..............................
   　 ..............................
   　 ..............................
   　└ UserID999-bucket/

   データバックアップ・リストア機能：なし

4. インフラ・サーバー管理
   インフラ：AWS(オンデマンドのみ)
   サーバー構成：Web&アプリサーバー=EC2、短時間処理のWebアプリ=Lambda
   CI/CD：なし
   ドメイン・DNS設定：Route 53にて発行。EC2付与のElastic IPへルーティング設定。
   SSL証明書の管理：Let's Encryptで発行。EC2内のcronにて定期更新。

5. セキュリティ対策
   認証・認可：Cognitoで認証。API gatewayも認証を付与
   シークレット情報の管理：特になし
   セキュリティ対策：特になし

6. ログ・モニタリング
   ログ管理：CloudWatch, EC2の/tmpフォルダ内のテキストログ
   エラートラッキングの仕組み：例外処理でエラーをログへ出力
   パフォーマンスモニタリング：EC2のCPU・メモリ・ストレージ使用量をCloudWatchにてモニタリング

7. 運用・保守
   EC2のFast APIのアプリ：
   　ログを確認->実行処理がないこと確認->Webアプリの更新(本番適用)
   Lambda/フロントエンドのアプリ：
   　修正したらすぐに更新(本番適用)

8. ドキュメントの整備
   システム仕様書・設計書
   API仕様書作成（OpenAPI/Swagger）

9. 権限・アカウント管理
   AWSのadminuser権限のIAMユーザーを作成
   rootユーザーによるコスト閲覧権限の付与

実際に引き継いでみて

実際に引き継ぐ相手にどのような情報が欲しいか聞くと、保守・運用している実際の画面を操作して、見せながら説明してほしいと言われた。確かに実際に操作しているところを見るのが早いなと思った。上記の情報を送った後に、リモート会議で実際の画面を操作して説明するのがいいのかなと思う。