Skip to content

About

Personal asset management for Japanese brokerage and bank accounts (NISA, iDeCo). Rust (Axum, SQLx) + PostgreSQL + React.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

shisan-api

CI

NISA・iDeCo・特定口座・一般口座を横断して、資産・損益・収益率を管理する資産管理サービス。

証券会社ごとにアプリを開いて残高を確認する手間をなくし、「制度をまたいだ資産全体で、実際にいくら増えたのか」を一箇所で把握することを目的としています。

デモ

URL
アプリ https://shisan-web.onrender.com
API ドキュメント(Swagger UI) https://shisan-api.onrender.com/docs

アプリはトップの新規登録からアカウントを作成すればそのまま試せます。API を直接叩く場合は Swagger UI の POST /auth/register でアカウントを作成し、返却されたトークンを右上の Authorize に入力してください。

API は無料プランで稼働しているため、アクセスがない間はインスタンスが停止します。最初のリクエストは応答まで数十秒かかることがあります(フロントエンドは CDN 配信のため停止しません)。

ポートフォリオプロジェクトです。 バックエンド16タスク・フロントエンド8タスクのロードマップを完了し、CI・自動デプロイ・日次バッチが稼働しています。

📝 開発記事(Zenn):Rust(axum + sqlx)で NISA・iDeCo を横断する資産管理アプリを作った話 設計で迷ったところ・実際にハマったところ・AI(Claude Code)との分担を、記事にまとめています。

スクリーンショット

保有一覧 資産推移・資産配分 CSV インポート
保有一覧 分析 CSV インポート
口座・銘柄ごとの評価額と評価損益(総平均法) 口座種別ごとの資産推移と資産配分 本登録の前に検証。1行でもエラーがあれば全体を取り込まない

なぜ作ったか

既存の家計簿アプリでも残高の合算はできますが、以下が扱いにくいと感じました。

NISA の非課税枠が制度どおりに管理されない。 2024年以降の新NISAは「つみたて投資枠」と「成長投資枠」で年間上限が異なるため、枠を区別せずに集計すると意味をなしません。

枠 年間上限
つみたて投資枠 120万円
成長投資枠 240万円
年間合計 360万円
生涯投資枠 1,800万円

制度仕様: 金融庁 NISA特設ウェブサイト

収益率が単純な損益率でしか出ない。 積立のように入金タイミングがばらつく場合、単純な損益率では実質的なパフォーマンスがわかりません。金額加重収益率(XIRR)が必要です。

税引後のリターンが見えない。 特定口座と非課税口座が混在していると、額面の損益と手元に残る額が乖離します。

これらを扱うには、口座種別と取引履歴を制度に即した形でモデリングする必要があります。その設計自体がこのプロジェクトの主題です。


Features

機能 エンドポイント
認証(JWT) POST /auth/register POST /auth/login
口座管理(6種の口座種別) /accounts
銘柄・価格 /assets /prices /prices/{asset_id}
取引履歴(総平均法で取得単価を算出) /transactions
保有一覧・評価損益 GET /holdings
資産推移 GET /analytics/asset-history
資産配分 GET /analytics/allocation
CSV インポート(dry-run 対応) POST /import/transactions POST /import/transactions/dry-run
為替換算(ECB レート) 外部 API 連携
日次スナップショット POST /snapshots/run
API 仕様 GET /openapi.json /docs

上記すべてに対応する画面をフロントエンド(React SPA)で提供しています。


Architecture

レイヤードアーキテクチャを採用し、計算ロジックを I/O から分離しています。

        handler          HTTP の入出力のみ。リクエスト検証とレスポンス整形
           ↓
        service          ユースケースの組み立て
           ↓
       repository        DB アクセス。SQL はここに閉じる
           ↓
       PostgreSQL

        domain           純粋関数。総平均法による取得単価、評価損益
                         (I/O を持たないため単体でテスト可能)

        provider         外部依存を trait で抽象化
           ├── FxRateProvider   (Frankfurter / ECB レート)
           └── PriceProvider

デプロイ構成

フロントエンドと API は別オリジンの独立したサービスとして運用しています。

  ブラウザ
     │
     ├──────────────→  Render Static Site(CDN 配信)
     │                  shisan-web.onrender.com
     │                  ビルド済みの React SPA
     │
     └──────────────→  Render Web Service(Docker)
        (CORS)          shisan-api.onrender.com
                              │
                              ↓
                        Neon(PostgreSQL)

ディレクトリ構成

shisan-api/
├── CLAUDE.md                 # AI エージェント向けの作業ガイド(.cursor/rules/ も同じ内容の要約)
├── compose.yaml              # Postgres + API
├── .env                      # Compose 用の環境変数(gitignore 対象)
├── .github/workflows/        # ci.yml / deploy.yml / snapshot.yml
├── web/                      # フロントエンド(Vite + React + TypeScript)
│   ├── .node-version         # Node のバージョン(ローカル / CI / Render で共有)
│   └── src/
│       ├── api/              # fetch ラッパ / Problem Details の解釈
│       ├── assets/           # 画像などの静的ファイル
│       ├── components/       # 画面横断の共通コンポーネント
│       ├── features/         # ドメインごとの画面部品
│       ├── lib/              # 金額フォーマットなどの純粋関数
│       ├── pages/            # ルーティングの単位となる画面
│       ├── routes/           # レイアウトと認証ガード
│       └── stores/           # 認証セッションの状態管理
└── asset-log/                # バックエンド(Rust)
    ├── Dockerfile
    ├── .env                  # sqlx CLI 用の DATABASE_URL(gitignore 対象)
    ├── .sqlx/                # オフラインクエリキャッシュ
    ├── migrations/           # sqlx マイグレーション
    ├── docs/                 # 設計メモ / 残タスク一覧 / openapi.json / images(README 用スクリーンショット)
    ├── tests/                # 統合テスト
    └── src/
        ├── main.rs           # clap CLI + axum 起動
        ├── lib.rs            # ルータ組み立て(統合テストからも参照)
        ├── config.rs         # 環境変数
        ├── state.rs          # AppState / PgPool
        ├── error.rs          # AppError → IntoResponse(RFC 9457)
        ├── cors.rs           # CORS レイヤ
        ├── openapi.rs        # OpenAPI 定義(ApiDoc / セキュリティスキーム)
        ├── domain/           # position / money / account_type
        ├── handler/
        ├── service/
        ├── repository/
        ├── provider/         # 為替レート(fx の trait とキャッシュ)
        ├── middleware/       # auth
        └── job/              # daily_snapshot

Domain Model

口座種別(account_type ENUM)

値 意味 課税
tokutei 特定口座 課税
ippan 一般口座 課税
nisa_tsumitate NISA つみたて投資枠 運用益非課税
nisa_growth NISA 成長投資枠 運用益非課税
ideco iDeCo 掛金控除・運用益非課税・受取時課税
bank 待機資金(現金) —

Position(保有ポジション)

取引履歴から総平均法で取得単価を算出します。同一銘柄でも口座が異なれば別ポジションとして扱います(非課税枠の管理単位が口座だから)。

  • 買い増し → 加重平均で取得単価を再計算
  • 一部売却 → 取得単価は維持し、実現損益を計上
  • 全売却後の再購入 → 取得単価をリセット

Key Design Decisions

設計判断の詳細は asset-log/docs/ にタスクごとのメモとして残しています。以下は主要なものの要約です。

なぜ ORM ではなく sqlx なのか

コンパイル時に SQL を検証できるため。query! マクロが実際のスキーマに対してクエリを検証し、カラム名の誤りや型の不一致をビルド時に検出します。CI では cargo sqlx prepare --check を実行し、保存しているクエリ情報(.sqlx)がスキーマとずれていないかも確かめています。

もう一つは、発行される SQL を自分で把握したかったためです。資産推移では generate_series と LEFT JOIN LATERAL を組み合わせた集計を書いています。こうしたクエリは ORM の書き方に置き換えるより、SQL のまま書くほうが実行計画を確認しやすいと判断しました。

SQL を書く負担は残りますが、リポジトリ層に閉じ込めることで影響範囲を限定しています。

ただし、コンパイル時の検証も万能ではありません。外部結合の nullable は推論できないことがあります(後述の「ハマったところ」)。

なぜ NISA を1種類ではなく2種類の ENUM にしたのか

非課税枠の消費状況を枠ごとに集計する必要があるため。つみたて投資枠は年120万円、成長投資枠は年240万円と上限が異なり、合算しても制度上の意味を持ちません。

nisa という単一の値にして「枠の種別」を別カラムで持つ設計も考えられますが、その場合「NISA 以外の口座で枠種別が NULL」という状態を別途制約する必要が出ます。ENUM を分けることで、口座種別だけで枠が一意に決まります。

なぜ withholding を ENUM ではなく Option<bool> にしたのか

特定口座の源泉徴収区分を account_type に含めて tokutei_withholding / tokutei_no_withholding と分割する案もありましたが、採用しませんでした。源泉徴収は「特定口座の属性」であって口座種別そのものではなく、ENUM に混ぜると口座種別の意味が二重になります。

accounts.withholding BOOLEAN を nullable + CHECK 制約とし、「特定口座なら必須、それ以外なら NULL」を DB レベルで強制しています。

NOT NULL DEFAULT false にしなかった理由が重要です。その場合 iDeCo 口座の withholding = false が「源泉徴収なしの特定口座」と区別できなくなります。「値がない」と「false という値がある」は違うという区別を、型と制約の両方で表現しています。Rust 側では Option<bool> として受け取り、型が意図を語る形にしています。

なぜ日次スナップショットを正本にしないのか

資産推移の正本はあくまで取引履歴からの再計算です。スナップショットはキャッシュに過ぎません。

過去の取引が後から追加・修正されることが実際にあるため(証券会社の CSV を後日まとめて取り込むなど)、スナップショットを正本にすると過去の値が永久に誤ったままになります。取引が変更された場合は影響する日以降のキャッシュを失効させ、次回参照時に再計算します。

レスポンスの source フィールドで、キャッシュとフォールバックのどちらを経由したかが分かるようにしています。

なお「未計算」と「保有ゼロ」を区別するため、計算済みマーカーを別テーブル(snapshot_days)に分離しています。値が 0 であることと、まだ計算していないことは別の状態です。

なぜ GitHub Actions から snapshot を起動するのか

アプリケーション内に常駐スケジューラを持たないため。Render の無料プランはアクセスがないとインスタンスが停止するので、プロセス内 cron は動作を保証できません。

GitHub Actions の schedule から HTTP で起動する方式なら、インスタンスを起こしてからバッチを叩けます。認証はユーザー JWT とは分離したバッチ専用トークン(SNAPSHOT_JOB_TOKEN)を使い、未設定時は 503 で拒否します。

なぜフロントエンドを Web Service ではなく Static Site にしたのか

ビルド成果物が静的ファイルのみで、サーバサイドの処理を必要としないため。Static Site は CDN から配信されるので、無料プランでもインスタンスのスピンダウンが起きません。API 側の起動待ちは発生しますが、少なくとも画面は即座に表示されます。

代償として、SPA のクライアントサイドルーティングにはリライト設定が必要です。/holdings を直接開いたときにファイルが存在せず 404 になるため、/* → /index.html の Rewrite ルールを設定しています。Render はリソースが存在するパスにはルールを適用しないため、/assets/*.js などのバンドルがワイルドカードに巻き込まれることはありません。

なぜ Render の auto-deploy を無効にしたのか

Render の auto-deploy は main への push を検知して即座にビルドを始めるため、テストの結果を待ちません。テストが落ちるコードでもデプロイされてしまいます。

auto-deploy を切り、GitHub Actions の workflow_run イベントで統合 CI の完了と結果を受け取り、main ブランチかつ成功時に限って Deploy Hook を叩く構成にしました。CI が green のときだけ、同じ deploy.yml からバックエンドとフロントエンドをデプロイします。

なぜ外部 API を trait で抽象化したのか

為替レートの取得(Frankfurter)を FxRateProvider trait として定義し、テスト時にモックへ差し替えられるようにしています。

これにより、外部 API の 5xx 応答・タイムアウト時にキャッシュへフォールバックする挙動まで、実際のネットワークなしでテストできます。外部サービスの障害時の振る舞いは本来テストが難しい領域なので、ここは意図的に抽象化の対価を払っています。

なぜ OpenAPI とルート定義を同じ場所に置くのか

utoipa-axum の OpenApiRouter を使い、ルート登録とドキュメント生成をまとめています。

OpenApiRouter::with_openapi(ApiDoc::openapi())
    .routes(routes!(handler::accounts::create, handler::accounts::list))
    .split_for_parts()

routes!() に渡したハンドラがそのまま axum のルートになり、同時に #[utoipa::path] の情報から仕様が組み立てられます。ルートを追加したのにドキュメントを書き忘れる、パスを変更したのに仕様が古いまま、といった乖離が構造的に起きません。

統合テストでもパス数の完全一致を検証しており、エンドポイントを追加すると仕様の更新を促してテストが落ちます。


技術スタック

領域 技術
バックエンド Rust 1.96 / axum 0.8
DB PostgreSQL 17
DB アクセス sqlx 0.9(ORM 不使用)
認証 Argon2 0.6 / jsonwebtoken 11(HS256)
API 仕様 utoipa 6 / utoipa-axum 0.3(OpenAPI 3.1)/ Swagger UI(CDN 配信 + SRI)
フロントエンド Vite / React / TypeScript / Tailwind CSS v4 / TanStack Query / Recharts
Node 24(Active LTS。web/.node-version で固定)
コンテナ Docker(マルチステージ + distroless)
外部 API Frankfurter(ECB 為替レート)
ホスティング Render(API: Docker / フロント: Static Site)/ Neon(Postgres)
CI / CD GitHub Actions / Dependabot

実装上の工夫

エラーレスポンス(RFC 9457)

AppError を IntoResponse に実装し、Problem Details 準拠の JSON を返します。Postgres のエラーコードを HTTP ステータスにマッピングしています。

コード 意味 HTTP
23514 CHECK 制約違反 422
23505 UNIQUE 制約違反 409
23503 外部キー違反 404 / 422

制約名とメッセージの対応表を持っており、どのフィールドが原因かをクライアントに返します。5xx では内部情報を露出させず、trace_id のみを返します。

distroless でのヘルスチェック

ランタイムイメージに gcr.io/distroless/cc-debian12:nonroot を使っているため、curl もシェルも存在しません。そこで clap で healthcheck サブコマンドを実装し、バイナリ自身が /health を叩く方式に統一しました。

HEALTHCHECK CMD ["./asset-log", "healthcheck"]

reqwest の blocking フィーチャーは有効化せず、current-thread のランタイムを起こして非同期クライアントを使っています。TLS も default-features = false + rustls-tls として OpenSSL への依存を持たず、sqlx と同一の rustls / ring を共有しています。

CORS

フロントエンド(Render Static Site)と API(Web Service)を別オリジンで運用するため、tower-http の CorsLayer をルータの最外層に適用しています。

最外層に置くことで、401 などのエラーレスポンスにも CORS ヘッダが付きます。ここが抜けると、ブラウザ側では認証エラーがネットワークエラーとして見え、原因究明が困難になります。

許可オリジンは CORS_ALLOWED_ORIGINS(カンマ区切り)から読み、スキームの有無と末尾スラッシュを起動時に検証します。値が空のときはブラウザからのリクエストが全て拒否されるため、起動時に警告を出します。設定漏れでも API は正常に起動してしまい、症状が「フロントからだけ動かない」という形で出るためです。

環境変数の設定漏れをビルド時ではなく起動時に検出する

Vite の import.meta.env.VITE_* はビルド時にバンドルへ焼き込まれます。設定を忘れたままビルドすると、リクエスト先が undefined/auth/login になった成果物が出来上がり、画面を触るまで気づけません。

API クライアントの初期化時にガードを置き、未設定のバンドルは読み込み時点で落とすようにしています。

認証系依存の major update を回帰テストで守る

Dependabot が作成した argon2 0.6 と jsonwebtoken 11 の major update は、API 変更へ追従したうえで取り込みました。Argon2 は salt を内部生成する新 API へ移行し、jsonwebtoken は使用する暗号バックエンドを aws_lc_rs に固定しています。

パスワードハッシュは DB に永続化されるため、新規ハッシュの round trip だけでなく、旧バージョンが生成した PHC 文字列を引き続き検証できることもテストしています。依存更新によって既存ユーザーがログインできなくなる退行を検知するためです。

マイグレーションを起動時に適用する

API は DB への接続後、sqlx::migrate!() でバイナリに埋め込んだマイグレーションを起動時に適用します。適用に失敗した場合はリクエストを受け付けずに起動を中止するため、テスト環境だけ最新でローカルや本番のスキーマが古いままになる状態を防ぎます。

401 を API クライアントで一元検知する

フロントエンドは認証トークンを付けたリクエストが 401 を返した場合、共通の API クライアントから auth:expired イベントを発火します。認証ストアがこのイベントを1箇所で購読してセッションを破棄するため、エンドポイントを追加しても個別のログアウト処理は不要です。

ApiError は RFC 9457 の表示用情報と JSON 本文の原形を分けて保持します。CSV import の ImportReport のように Problem Details ではないエラー本文も、型を偽らず個別処理へ渡せます。

mutation 後のキャッシュ整合性を共通化する

React Query のルートキーと失効処理を web/src/lib/queryKeys.ts に集約しています。取引、価格、口座、CSV import の変更後は、一覧だけでなく保有評価と分析結果もまとめて再取得し、画面間で古い評価額が残らないようにしています。


ハマったところ

詳細は各タスクのメモと開発記事にあります。

sqlx が LEFT JOIN LATERAL の nullable を推論できない

LEFT JOIN LATERAL (
    SELECT price, priced_on FROM asset_prices
    WHERE asset_id = h.asset_id AND priced_on <= sp.on_date
    ORDER BY priced_on DESC LIMIT 1
) p ON true

sqlx は外部結合であることを考慮せず、asset_prices.price の NOT NULL をそのまま引き継いで Decimal 型にします。コンパイルは通り、テストデータに価格がそろっていればテストも通り、価格未登録の銘柄に当たった瞬間に実行時エラーになります。 p.price AS "price?" のように、NULL になりうることを明示して解決しました(task-11)。

rust:*-slim と distroless で OS の世代がずれる

ベース OS
builder: rust:1.96-slim Debian 13(trixie)
runtime: distroless/cc-debian12 Debian 12(bookworm)

-slim は軽量版という意味だけで、OS の世代は固定されません。GLIBC は新しい環境でビルドしたものが古い環境で動く保証がないため、builder 側も -bookworm に明示的にそろえました(task-25)。

Dependabot が utoipa 系を別々に上げてビルドが壊れる

utoipa 6.0 が出たとき、Dependabot は utoipa / utoipa-axum / utoipa-swagger-ui を別々の PR で作りました。1つだけ上げると依存関係の中に 5.x と 6.x が混在し、expected utoipa::openapi::OpenApi, found a different utoipa::openapi::OpenApi という分かりにくいエラーになります。3つまとめて上げるとコードを変えずに通ったので、dependabot.yml に utoipa 系をまとめるグループを追加しました。utoipa-swagger-ui は、その後 zip の脆弱性対応で依存から外しています(task-34)。


Testing

cd asset-log
cargo test --all-targets

現在 119 件のテスト(ユニット・統合)があります。

統合テストは #[sqlx::test(migrations = "./migrations")] により、テストごとに独立した一時 DB を作成してマイグレーションを適用します。テスト間の状態共有がないため、並列実行しても干渉しません。

tower::ServiceExt::oneshot でルータへ直接リクエストを投げる方式を採り、HTTP サーバを起動せずにハンドラからリポジトリまでを通しで検証しています。

外部 API(Frankfurter)は wiremock でスタブ化し、正常系に加えて 5xx 応答・タイムアウト時のキャッシュフォールバックまでテストしています。

認証では Argon2 の生成・検証、不正 PHC の拒否、旧 PHC との互換性に加え、JWT の発行・期限切れ・改ざん・異なる署名鍵・アルゴリズム不一致を回帰テストに固定しています。


CI / CD

ci.yml と deploy.yml をそれぞれ1本に統合しています。ci.yml の backend / frontend 両ジョブが成功したときだけ、deploy.yml が両方の Render Deploy Hook を起動します。

push / pull_request
        │
        └──→  ci.yml
              ├── Backend (Rust)
              │   fmt / clippy / test / cargo audit / sqlx prepare --check
              └── Frontend (React)
                  npm audit / lint / OpenAPI 型同期 / build
                         │ 両ジョブ成功(main)
                         ↓
                    deploy.yml
                      ├── Deploy backend(Render Web Service)
                      └── Deploy frontend(Render Static Site)

GitHub Actions cron(JST 07:00)
        └──→  Daily Snapshot
ワークフロー トリガー 内容
ci.yml push / PR(main)、手動 backend と frontend の検証を並列実行
deploy.yml 統合 CI の成功(main)、手動 backend / frontend の Render Deploy Hook を実行。手動時は対象を選択可能
snapshot.yml cron / 手動 インスタンスを起こしてから POST /snapshots/run

main のブランチ保護では Backend (Rust) と Frontend (React) の両ジョブを必須にしています。paths フィルタは置かず、どちらのチェックも PR ごとに実行します。

Dependabot は Cargo・npm・GitHub Actions を毎週確認し、minor / patch はグループ化、major は個別 PR として作成します。例外として utoipa 系(utoipa / utoipa-axum / utoipa-swagger-ui)は、1つだけ上げると 5.x と 6.x が混在してビルドできないため、major も含めて1本にまとめています。自動マージは行わず、破壊的変更の確認と CI を経て取り込みます。

cargo sqlx prepare --check により、.sqlx のオフラインクエリキャッシュが実際のスキーマと乖離していないかを検証しています。これがないと、マイグレーションを変更したのにキャッシュを再生成し忘れたまま Docker ビルド(SQLX_OFFLINE=true)が通ってしまいます。


Setup

必要なもの

  • Docker / Docker Compose
  • Node 24.20.0(フロントエンドを動かす場合。web/.node-version で固定)
  • Rust 1.96.0(ローカルでビルドする場合。asset-log/rust-toolchain.toml で固定)

起動

git clone https://github.com/CaltDeepL/shisan-api.git
cd shisan-api
cp .env.example .env

.env の JWT_SECRET はサンプル値のままだと32バイト未満で起動時にエラーになります。以下で生成した値に置き換えてください(POSTGRES_PASSWORD 等はローカル専用なのでサンプル値のままで構いません)。

openssl rand -base64 32
docker compose up --build -d
curl http://localhost:8080/health

POSTGRES_PASSWORD は DB の初期化時にボリュームへ永続化されます。一度起動したあとに .env の値を変更しても既存のボリュームには反映されないため、変更する場合は docker compose down -v が必要です。

フロントエンド

web/.node-version に対応バージョンを記載しています。fnm を使っている場合は cd で自動的に切り替わります。

cd web
npm ci
cp .env.example .env.local    # VITE_API_BASE_URL を設定
npm run dev                   # http://localhost:5173

ローカル開発ではフロント(5173)と API(8080)が別オリジンになるため、ルートの .env の CORS_ALLOWED_ORIGINS に http://localhost:5173 が含まれている必要があります(.env.example の既定値に含まれています)。

マイグレーション

API は DB への接続後、組み込み済みの全マイグレーションを sqlx::migrate!() で自動適用します。通常の docker compose up や本番デプロイで、事前に sqlx CLI を実行する必要はありません。

状態確認や手動適用、マイグレーション開発を行う場合だけ sqlx CLI をホスト側で使います。接続先は asset-log/.env の DATABASE_URL から自動的に読まれます。

cd asset-log
cargo install sqlx-cli --version 0.9.0 --no-default-features --features rustls,postgres --locked

cp .env.example .env    # 値を編集(DATABASE_URL のユーザー・パスワードはルートの .env と揃える)
sqlx migrate run
sqlx migrate info

マイグレーションはすべて .up.sql / .down.sql の可逆形式です。追加するときは sqlx migrate add -r <name> で組として作り、sqlx migrate revert → sqlx migrate run を往復してスキーマが元に戻ることを確認してください。適用済みのマイグレーションの本文は変更しないでください(チェックサムが変わり、起動時の適用が失敗して API が起動しなくなります)。

.env が2つある理由

接続先のホスト名が実行主体によって異なるため、用途ごとにファイルを分けています。

ファイル 用途 ホスト名
asset-log/.env ホストのシェル → db コンテナ(sqlx CLI・cargo test) localhost:5432
shisan-api/.env api コンテナ → db コンテナ(Compose の変数展開) db:5432

db は Compose ネットワーク内部のサービス名なので、ホストのシェルからは解決できません。逆に、ホスト用の DATABASE_URL をシェルで export すると、Compose の変数展開がシェルの環境変数を優先するため、API コンテナが自分自身の 5432 を見に行って起動に失敗します。


API Documentation

起動後、Swagger UI から全エンドポイントの仕様を確認し、その場でリクエストを試せます。

Swagger UI は utoipa-swagger-ui を使わず、CDN(jsDelivr)の swagger-ui-dist を読み込む静的 HTML で配信しています(src/docs.rs)。バージョンは完全一致で固定し、SRI(integrity)で配信内容を検証します。ビルド時依存の zip に修正版のない advisory が出たため、依存ごと外しました(task-34)。

http://localhost:8080/docs

OpenAPI 3.1 の仕様は /openapi.json で配信しており、asset-log/docs/openapi.json にもコミットしています。


開発の進め方と AI(Claude Code)の使い方

バックエンド16タスク → フロントエンド8タスク → 運用・保守、の順に、1タスク = 1作業メモで進めました。各タスクの「ゴールと完了条件 / 設計判断とその理由 / つまずいた点」を asset-log/docs/ に残しています(2026-08-17 着手 → 09-04 にフロントエンドまで完成 → 以降は CI 整備と依存更新の運用)。2026-10-24 以降のタスクは GitHub Issue で管理し、作業メモもその Issue に書いています。

開発には Claude Code を使っています。

工程 担当
何を作るか・要件を決める 自分
技術選定、要件を設計とタスクに落とし込む AI(内容を確認してから採用)
実装 基本は自分。時間がなく重要度が低い作業は AI
書かれたコードの確認 自分
コードレビュー Claude Code

AI を「発注先」として使い、何を作るか、そして出てきたものを受け入れるかどうかは自分で決める、という分担です。AI が書いたコードも、差分を自分で読み、テストを実行して動きを確かめてからマージしています。

たとえば cargo audit で zip の脆弱性が見つかったとき、AI からは「.cargo/audit.toml で ignore する」案と「依存ごと外す」案の2つが出ました。ignore は理由がなくなった後も設定が残り続けるため、依存ごと外す案を採用し、utoipa-swagger-ui を CDN の静的 HTML に置き換えました(Cargo.lock から13クレート減)。

振り返ると、設計・テスト・CI/CD まで1人でも短期間でそろえられた一方、AI に任せた部分は自分で書いた部分よりも身につきにくいという課題もあります。そのため、作業メモで判断の理由を残すこと、動作確認は自分で行い使った技術をその都度調べることを続けています。


Implementation Status

バックエンド(完了)

# タスク
1 プロジェクト雛形 / /health / Docker Compose
2 マイグレーション 0001(users / accounts)
3 AppError 整備
4 認証(register / login / JWT)
5 口座 CRUD
6 銘柄・価格
7 domain::position(総平均法・評価損益)
8 取引 CRUD
9 /holdings エンドポイント
10 FxRateProvider(Frankfurter)
11 資産推移(GET /analytics/asset-history)
12 資産配分(GET /analytics/allocation)
13 CSV インポート
14 日次スナップショット(バッチ)
15 OpenAPI(utoipa / Swagger UI)
16 デプロイ・GitHub Actions

フロントエンド(完了)

# タスク
17 CORS 設定 + React SPA 雛形
18 認証画面
19 口座 CRUD 画面
20 銘柄・取引の登録画面
21 保有一覧・評価損益
22 資産推移・資産配分のグラフ
23 CSV インポート画面
24 Static Site へのデプロイ

メンテナンス(完了)

項目 内容
Dependabot Cargo / npm / GitHub Actions の週次更新(minor / patch はグループ化)
認証依存更新 argon2 0.6 / jsonwebtoken 11 対応、旧 PHC 互換・JWT 境界テスト
CI / リポジトリ保護 ci.yml / deploy.yml への統合、ブランチ保護、cargo audit / npm audit
マイグレーション・CI 設定の見直し 0005 / 0006 を可逆形式へ統一、@types の major を個別化、workflow の入力を env 経由に、デプロイを push 起点に限定
Rust 依存脆弱性対応 rustls 0.23.44 の RUSTSEC-2026-0285 を lockfile のみで 0.23.45 へ更新
Rust 依存脆弱性対応(2) rustls を 0.23.46 へ、zip の advisory は utoipa-swagger-ui を外して CDN + SRI の静的 HTML へ置き換え
認証・API 契約 パスワード上限と denylist、401 セッション破棄、全 4xx / 5xx の OpenAPI schema 検証
ビルド再現性 Rust toolchain の固定、builder / runtime の Debian 12 統一
クライアント整合性 mutation 後の関連キャッシュ失効と、Problem Details 以外のエラー本文処理を共通化

Future Work

過去の設計メモと現行コードを横断した監査結果・残タスクの完全版は asset-log/docs/task-31-full-audit.md にまとめています。

優先 項目 内容
1 API エラー形式の統一 axum の JSON rejection も Problem Details に変換する
2 CSV の上限・性能 サーバー側のサイズ / 行数上限と、行ごとの DB 往復を一括取得へ変更
3 取引一覧のページング API 既定100件を超える取引へ UI から到達可能にする
4 XIRR 入金タイミングを考慮した金額加重収益率を提供
5 Google ログイン(OIDC) 現行 JWT 認証の上に追加し、Cookie / refresh token 方針も再検討
6 コールドスタート対策 API 起動待ちを通常の通信中と区別して表示し、再試行を案内

License

MIT

About

Personal asset management for Japanese brokerage and bank accounts (NISA, iDeCo). Rust (Axum, SQLx) + PostgreSQL + React.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages