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

Last updated at 2025-04-19Posted at 2025-03-24

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

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

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

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

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

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

実際の引継ぎ資料

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

システム全体の概要把握
- システムの全体構成図
- システムの概要
  
  AWSサービスを使用して、サーバー、データベース、認証、定期実行、キューイング、ドメイン取得をしている。サーバーはEC2にApacheをインストールして、Reactの静的ビルドしたファイルを置いて、Webサイトを公開している。長時間かかる処理は同じEC2にFast APIをlocalhostでたてて、Apacheのproxy設定でルーティングして、APIを公開している。ReactのフロントエンドからのAPIリクエストは全てLambdaへ送っている。Fast APIへは、一度Lambdaへ送り、lambdaからFast APIへリクエストしている。バックエンドは全てPythonで実装しており、短時間の処理はLambdaで、長時間かかる処理はFast APIで実装している。それぞれのソースコードはS3に置いている。LambdaはAWSから参照可能。ドメインはLet's Encryptで取得して、Route 53にNSをルーティングしている。EC2は1年間の予約購入をしており、期日になったら、再購入しないとオンデマンド料金でEC2が実行されてしまう。データベースはDynamoDBとS3を使用している。定期実行はEvent BridgeスケジューラとLambdaを使用している。キューイングはSQSを使用して、キューの処理はEvent Briodgeとlambdaで処理をしている。
- クラウドやサーバーへのログイン方法
  ログインURLや各種キーやコマンド
- 技術スタック
  フロントエンド：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
コード・リポジトリ・開発環境方法の引き継ぎ
・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
データベース構造
データベースの種類：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/

データバックアップ・リストア機能：なし
インフラ・サーバー管理
インフラ：AWS(オンデマンドのみ)
サーバー構成：Web&アプリサーバー=EC2、短時間処理のWebアプリ=Lambda
CI/CD：なし
ドメイン・DNS設定：Route 53にて発行。EC2付与のElastic IPへルーティング設定。
SSL証明書の管理：Let's Encryptで発行。EC2内のcronにて定期更新。
セキュリティ対策
認証・認可：Cognitoで認証。API gatewayも認証を付与
シークレット情報の管理：特になし
セキュリティ対策：特になし
ログ・モニタリング
ログ管理：CloudWatch, EC2の/tmpフォルダ内のテキストログ
エラートラッキングの仕組み：例外処理でエラーをログへ出力
パフォーマンスモニタリング：EC2のCPU・メモリ・ストレージ使用量をCloudWatchにてモニタリング
運用・保守
EC2のFast APIのアプリ：
　ログを確認->実行処理がないこと確認->Webアプリの更新(本番適用)
Lambda/フロントエンドのアプリ：
　修正したらすぐに更新(本番適用)
ドキュメントの整備
システム仕様書・設計書
API仕様書作成（OpenAPI/Swagger）
権限・アカウント管理
AWSのadminuser権限のIAMユーザーを作成
rootユーザーによるコスト閲覧権限の付与

実際に引き継いでみて

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

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up