// 技術ノート
作って、壊して、また作る。
バックエンド／フルスタック開発の記録です。作ったもの、壊れたもの、そこから学んだことを残しています。
// technical notebook
Learning out loud.
Notes from a backend and full-stack developer: what I build, what breaks, and what I learn fixing it.
プロジェクトから学んだ短い記録です。各ログでは、問題、修正方法、学んだことをまとめています。
別のPartsPilot v3ブランチで、OpenAPIのセキュリティ修正を既存のテストとエンドポイント回帰チェックで検証しました。
問題: OpenAPIのセキュリティ修正が、既存のエンドポイントの動作に影響していないか確認する必要がありました。
原因: セキュリティ関連の変更は、APIのほかの部分でリグレッションを引き起こすおそれがあります。
修正: 別のv3ブランチで修正を検証し、70件のテストと55件のエンドポイント回帰チェックがすべて成功しました。変更はコミットしてプッシュ済みですが、まだmainにはマージしていません。
学んだこと: セキュリティに関わる変更は、API全体の回帰テストスイートで確認することが大切です。
Bloomの操作モードの仕様を確定し、アプリの情報設計とルートに反映しました。
問題: Bloomのモードを、アプリの情報設計とルートに反映する必要がありました。
原因: ルート構成を確定する前に、モードの仕様を固める必要がありました。
修正: モードの仕様を完成させて確定し、情報設計とルートに反映したうえで、ルートをQAチェックしました。
学んだこと: ルートを確定する前に体験モードを定義しておくと、アプリの構成が意図した体験に沿ったものになります。
PartsPilot v3への移行作業中にGitの変更に表示されていた、.NETの生成ファイルを整理しました。
問題:
bin/ と obj/ フォルダの生成ファイルがソースの変更と一緒に表示され、リポジトリの状態を確認しにくくなっていました。
原因: 生成されたビルド出力が、Gitの追跡対象から完全には除外されていませんでした。
修正: ignoreルールを更新し、生成ファイルをGitの追跡対象から外しました。この作業はリポジトリの内容の整理に絞ったもので、PartsPilot v3への移行が完了したわけではありません。
学んだこと:
ビルド出力は早い段階で除外しておくべきです。生成ファイルがすでに追跡されている場合、.gitignore を更新するだけでは不十分です。インデックスから削除し、ソースの変更をステージする前にGitの状態を確認します。
parts配列ではなく、APIレスポンスのラッパーオブジェクトをstateに保存していたことによるReactの表示エラーを修正しました。
問題:
PartsPilotのフロントエンドはバックエンドからデータを受け取れていましたが、parts.map() を実行しようとしたところで画面がエラーになりました。Reactは parts が配列であることを前提にしていましたが、stateにはレスポンスオブジェクト全体が入っていました。
原因:
FastAPIのエンドポイントは配列を直接返すのではなく、items プロパティを持つオブジェクトを返していました。フロントエンドでは setParts(data) を使っていたため、そのラッパーオブジェクトがstateに保存されていました。map などの配列メソッドは、このオブジェクトには使えません。
修正:
返されたJSONの構造を確認し、stateの更新を setParts(data.items) に変更しました。JSXで表示する前に、オブジェクト、プロパティ、配列のインデックス、各要素のプロパティという順にレスポンスをたどり、データの参照パスを確認しました。
学んだこと: APIリクエストが成功しても、返ってきたデータがコンポーネントの想定どおりの形とは限りません。Reactのstateを更新する前にレスポンスの構造を確認し、画面に必要な値だけを保存することが大切です。
コンテナ内部のポートとホストに公開されたポートを区別し、バックエンドのCORS設定を修正して、ReactからFastAPIへの接続エラーを解決しました。
問題:
ReactのフロントエンドからFastAPIのバックエンドのパーツを読み込めませんでした。DockerはAPIをホストのポート8001で公開していたのに、リクエストは localhost:8000 に送られていました。また、ブラウザからのリクエストには、フロントエンドのオリジンからバックエンドのオリジンへアクセスするための許可も必要でした。
原因:
Dockerのマッピング 8001:8000 では、FastAPIはコンテナ内のポート8000で待ち受け、ホストのブラウザからはポート8001を通してアクセスします。さらに、フロントエンドとバックエンドが異なるオリジンで動いていたため、ブラウザがCORSの制限を適用していました。
修正:
フロントエンドのリクエストURLを http://localhost:8001/api/parts に変更し、FastAPIでフロントエンドの開発用オリジンからのリクエストを許可するよう設定しました。ブラウザのエラーとHTTPレスポンスの種類から、接続、ルート、認証、サーバー、CORSのどこで失敗しているのかを切り分けました。
学んだこと: Dockerのポートマッピングには、コンテナ側とホスト側があります。ブラウザで動くフロントエンドのコードはホスト側のポートを使う必要があります。また、クロスオリジンの許可はフロントエンドで回避するのではなく、バックエンドで設定するものです。
分離したテスト用データベースとFastAPIの依存関係オーバーライドを導入し、Docker専用のPostgreSQLホスト名からテスト環境を切り離しました。
問題:
ホストマシンから直接バックエンドのテストを実行すると、アプリケーションがホスト名 db でPostgreSQLに接続しようとして失敗しました。
原因:
db はDocker Composeのサービス名でした。Composeネットワーク上のコンテナからは名前解決できますが、Mac上で直接実行するpytestのプロセスにとっては、有効なPostgreSQLのホスト名ではありませんでした。
修正: テストでは分離したSQLiteデータベースを使うように設定し、テスト実行中はアプリケーションのデータベース依存関係をオーバーライドしました。これにより、開発用のPostgreSQLコンテナに接続したりそのデータを変更したりせずに、エンドポイントのテストを独立して実行できるようになりました。
学んだこと: アプリケーションとテストの環境は、表に見えないインフラの前提を共有するべきではありません。依存性注入を使えば、開発と本番ではPostgreSQLを使い続けながら、管理されたデータベースに対してFastAPIのルートをテストできます。
ダッシュボードの合計が、在庫全体ではなく、ページネーションされた10件分のデータから計算されていました。
問題: Inventory Management System の商品数を増やしている際に、ダッシュボードの 統計情報が PostgreSQL に保存されている在庫データと一致していないことに 気づきました。新しい商品を追加しても、ダッシュボードは10件分のデータだけを 使用して合計を表示していました。
修正:
バックエンド API を確認し、/items エンドポイントが意図的に
10件までのデータを返すページネーション設定になっていることを確認しました。
次に、/items/stats、/items/category-summary、
/items/category-value をテストし、データベース全体を対象に
集計していることを確認しました。React フロントエンドを修正し、
ダッシュボードの統計には集計専用エンドポイントを使用しながら、
在庫一覧にはページネーションを残しました。
学び: ページネーションされた一覧データを、ダッシュボード全体の統計計算に 使用するべきではありません。React の UI から API、データベースまで データの流れを確認したことで、問題がバックエンドの計算ではなく、 フロントエンドのデータ取得方法にあることを特定できました。
CORSのオリジン不足と、辞書型の値に対するロール確認が原因で、管理者ページがユーザー一覧を取得できませんでした。
問題: JWT Authentication Dashboard ではログインはできましたが、 管理者ページからユーザー一覧を取得できませんでした。 ブラウザでは CORS エラー、接続エラー、500 Internal Server Error が表示されました。
原因:
FastAPI バックエンドの CORS 設定に、ローカル開発用の
http://localhost:5175 が含まれていませんでした。
さらに、管理者チェックでは current_user.role を使っていましたが、
実際の current_user は辞書型でした。
修正:
CORS の許可リストにローカルフロントエンドのURLを追加し、
管理者ロールの確認を current_user.get("role") に変更しました。
学んだこと: フロントエンドに表示されるエラーでも、原因がバックエンドにある場合があります。 CORS、認証、認可、デプロイログを順番に確認することが重要だと学びました。
現在のスキルと最新の作業内容が伝わるように、ポートフォリオの注目プロジェクトを更新しました。
問題: ポートフォリオの注目プロジェクトが、現在のスキルや最新の作業内容を 十分に反映していませんでした。
修正: ホームページの注目プロジェクトを4つに増やし、 Inventory Management System、Bloom、Mini User API、 JWT Authentication Dashboard を中心に表示するようにしました。
学んだこと: ポートフォリオはプロジェクト一覧ではなく、 「それぞれのプロジェクトで何を証明できるか」を伝える場所です。
Alembicが、想定していた create_table を含まないマイグレーションファイルを生成しました。
問題： Alembic がマイグレーションファイルを生成しましたが、以下が含まれていませんでした： op.create_table(「tickets」, ...)
解決策： プロジェクトルートおよび Backend フォルダ内の正しいコマンドの場所を使用して、 マイグレーションファイルを再生成します。
教訓： Alembicは、SQLAlchemyのモデルを現在のデータベースの状態と比較します。 テーブルがすでに存在する場合、Alembicは空のマイグレーションを生成することがあります。
フロントエンドがバックエンドのCRUD関数を呼び出していなかったため、作成したルーティンがほかのページに表示されませんでした。
問題： ログインユーザーがRoutinesページで作成したルーティンが、 HomeページやProgressページに表示されず、再読み込み後も正しく保存されていませんでした。 バックエンドAPIはすでに存在していましたが、複数のルーティン機能が動作していないように見える状態でした。
修正： フロントエンドのデータフローを調査し、Routines.jsxがバックエンドのCRUD関数を インポートしているにもかかわらず、実際には呼び出していないことを確認しました。 認証済みユーザー向けのバックエンド永続化、ページ間同期イベント、 ローディング表示、エラー表示、Homeページの自動再読み込みを実装しました。
学び： 複数の不具合が、実際には1つの根本原因から発生している場合があります。 個別の症状だけを修正するのではなく、UIからAPI、データベースまで データの流れ全体を追跡することが重要だと学びました。
pytest.ini で探し始める場所を指定するまで、pytest が app パッケージを見つけられませんでした。
問題:
app/__init__.py は存在していたのに、
pytest が app パッケージを見つけられませんでした。
修正:
pytest.ini を追加し、pythonpath = . と
testpaths = tests を設定しました。
学んだこと:
__init__.py はフォルダを Python パッケージとして扱えるようにします。
しかし、pytest がどこから探し始めるかは pytest.ini で指定します。
重要な表示設定を、深い設定ページからヘッダーの小さなメニューへ移すことについてのメモです。
問題: アクセシビリティ設定が深い設定ページにあると、ユーザーが見つけにくくなります。
修正: フォントサイズや読みやすいフォント設定など、重要な表示設定を ヘッダーの小さなメニューに移動します。
学んだこと: アクセシビリティ設定は、プロフィール設定だけでなく、 公開ページやログイン後のページからも簡単に使えるべきです。
Short notes from my projects. Each entry explains the problem, the fix, and the lesson learned.
Verified an OpenAPI security fix on the separate PartsPilot v3 branch against the existing tests and endpoint regression checks.
Problem: The OpenAPI security fix needed to be checked against existing endpoint behaviour.
Cause: A security-related change can risk introducing regressions elsewhere in the API.
Fix: Verified the fix on the separate v3 branch; all 70 tests and 55 endpoint regression checks passed. The change has been committed and pushed, but hasn’t been merged into main.
Lesson: Check security changes against the broader API regression suite.
Locked Bloom’s interaction mode specification and mapped it into the app’s information architecture and routes.
Problem: Bloom’s modes needed to be reflected in the app’s information architecture and routes.
Cause: The mode specification needed to be settled before the route structure could be finalised.
Fix: Completed and locked the mode specification, mapped it into the information architecture and routes, then QA-checked the routes.
Lesson: Define the experience modes before finalising routes, so the app’s structure follows the intended experience.
Cleaned up generated .NET build files that were appearing in Git changes during the ongoing PartsPilot v3 migration.
Problem:
Generated files in the bin/ and obj/ folders were showing up
alongside the source changes, making the repository status harder to review.
Cause: The generated build output was not fully excluded from Git tracking.
Fix: Updated the ignore rules and removed the generated files from Git tracking. This kept the cleanup focused on repository contents; it did not complete the PartsPilot v3 migration.
Lesson:
Ignore build output early. If generated files are already tracked, updating
.gitignore alone is not enough; remove them from the index, then check Git
status before staging source changes.
Fixed a React rendering failure caused by storing an API response wrapper object in state instead of the parts array contained inside it.
Problem:
The PartsPilot frontend successfully received data from the backend, but the interface
failed when it attempted to run parts.map(). React expected
parts to be an array, but the state contained the complete response object.
Cause:
The FastAPI endpoint returned an object containing an items property rather
than returning an array directly. The frontend used setParts(data), which
stored the wrapper object in state. Array methods such as map could not be
used on that object.
Fix:
Inspected the returned JSON structure and changed the state update to
setParts(data.items). Confirmed the data path by working through the
response as object, property, array index, and item property before rendering it in JSX.
Lesson: A successful API request does not guarantee that the returned data has the shape a component expects. Before updating React state, inspect the response structure and store the specific value the interface needs.
Diagnosed a failed React-to-FastAPI connection by separating the container’s internal port from the port exposed to the host and then correcting the backend CORS configuration.
Problem:
The React frontend could not load parts from the FastAPI backend. Requests targeted
localhost:8000 even though Docker exposed the API to the host on port 8001.
Browser requests also required permission to cross from the frontend origin to the
backend origin.
Cause:
The Docker mapping 8001:8000 meant FastAPI listened on port 8000 inside its
container but was accessed through port 8001 from the host browser. The frontend and
backend also ran on different origins, so the browser applied CORS restrictions.
Fix:
Changed the frontend request URL to use http://localhost:8001/api/parts and
configured FastAPI to allow requests from the frontend development origin. Used the
browser error and HTTP response type to distinguish connection, route, authentication,
server, and CORS failures.
Lesson: Docker port mappings have a container side and a host side. Browser-based frontend code must use the host port, while cross-origin permission must be configured by the backend rather than bypassed in the frontend.
Separated the PartsPilot test environment from its Docker-only PostgreSQL hostname by introducing an isolated test database and FastAPI dependency overrides.
Problem:
Backend tests failed when they were run directly from the host machine because the
application attempted to connect to PostgreSQL using the hostname db.
Cause:
The hostname db was the Docker Compose service name. It could be resolved by
containers on the Compose network, but it was not a valid PostgreSQL hostname for pytest
processes running directly on the Mac.
Fix: Configured the tests to use an isolated SQLite database and overrode the application’s database dependency during test execution. This allowed endpoint tests to run independently without connecting to the development PostgreSQL container or changing its data.
Lesson: Application and test environments should not share hidden infrastructure assumptions. Dependency injection makes it possible to test FastAPI routes against a controlled database while preserving PostgreSQL for development and production.
Dashboard totals were being calculated from a paginated ten-item response instead of the full inventory.
Problem: While expanding the Inventory Management System, I noticed the dashboard statistics did not match the inventory stored in PostgreSQL. New products were added, but the dashboard continued to display totals based on only ten items.
Fix:
I reviewed the backend API and confirmed that the /items
endpoint intentionally limits results to ten records. I then tested the
/items/stats, /items/category-summary, and
/items/category-value endpoints and confirmed that they
calculated data across the full database. I updated the React frontend to
use these aggregation endpoints for dashboard statistics while keeping the
inventory list paginated.
Lesson: Paginated operational data should not be used to calculate global dashboard metrics. Tracing data from the React UI through the API and database helped identify that the issue was caused by the frontend data flow rather than the backend calculations.
The Admin page could not load users because of a missing CORS origin and a role check written for an object instead of a dictionary.
Problem: The JWT Authentication Dashboard login flow worked, but the Admin page could not load users from the deployed Mini User API backend. The browser showed CORS errors, connection errors, and a 500 Internal Server Error.
Cause:
The deployed FastAPI backend did not allow the local frontend origin
http://localhost:5175. The admin route also tried to use
current_user.role, but current_user was actually
a dictionary returned from the auth dependency.
Fix:
I added the local frontend origin to the backend CORS allow list and changed
the admin role check to use current_user.get("role").
Lesson: A frontend error is not always a frontend problem. In this case, the visible error appeared in React, but the real causes were backend CORS configuration, deployed API behaviour, and role-checking logic.
Updated the portfolio’s featured projects so the homepage reflects the strongest and most current work.
Problem: The portfolio homepage did not fully reflect my strongest and most current projects after recent updates to the JWT Authentication Dashboard and backend API.
Fix: I updated the featured project data, changed the homepage from three featured projects to four, refreshed the tags, and added new screenshots for the JWT Authentication Dashboard.
Lesson: A portfolio should not only list projects. It should clearly show what each project proves, such as authentication, backend API design, deployment, CI/CD, accessibility, or full-stack integration.
Alembic generated a migration file without the expected create_table call.
Problem: Alembic created a migration file but this did not include: op.create_table("tickets", ...)
Fix: Using the correct command locations in the Project Root and Backend folder to regenerate the migration file.
Lesson: Alembic compares SQLAlchemy models against the current database state. If the table already exists, Alembic may generate an empty migration.
Routines created on one page did not appear elsewhere because the frontend never called the backend CRUD functions.
Problem: Routines created by logged-in users appeared on the Routines page but did not appear on Home, Progress, or after refresh. Several routine-related features seemed broken despite the backend APIs already existing.
Fix: Investigated the frontend data flow and discovered that Routines.jsx never called the backend CRUD functions. Added authenticated backend persistence, routine synchronisation events, loading states, and automatic Home page refreshes after routine changes.
Lesson: Multiple bugs can often share a single root cause. Following data from the UI through the API and database is often more effective than fixing symptoms individually.
pytest could not find the app package until pytest.ini set where to start looking.
Problem:
pytest could not find the app package, even though
app/__init__.py existed.
Fix:
Added a pytest.ini file with pythonpath = .
and testpaths = tests.
Lesson:
__init__.py makes a folder a Python package, but
pytest.ini tells pytest where to start looking from.
Moving important display controls out of a deep settings page and into a small header menu.
Problem: Accessibility controls can be difficult to find if they are hidden deep inside a settings page.
Fix: Move important display controls, such as font size and readable font options, into a small header menu.
Lesson: Accessibility settings should be easy to reach from public and logged-in pages, not only from profile settings.
自動車業界のオペレーション分野から、ソフトウェアエンジニアリングへ移行中です。
仕事で身についた考え方、つまり体系的に、丁寧に、「何を」だけでなく「なぜ」まで残すことを、そのまま開発にも活かしています。
このノートには、うまくいったことだけでなく、つまずいた理由とその乗り越え方も記録していきます。
My background is in automotive operations, and I’m moving into software engineering. I build the way that work taught me to think: systematically, carefully, and with documentation that explains the why, not just the what.
This notebook is the honest record: the decisions, the bugs, and how I got past them.