開発者ガイド

このページは、OSS のコントリビュータや統合を考えている開発者に向けた、公開しているエンジニアリングドキュメントの入口です。社内向けの運用手順、ハードニング設定、運用シークレットはここには含めていません。

一人社長のドキュメントハブ：左にカテゴリ別の目次、右に各章のカード一覧が並ぶ

ヒント 「セットアップ」を一通り読み終えたら、次のグループから進んでください。

セットアップ / 全体像

バックエンド概要

開発者ガイド（このページ）

命名規則

API

API リファレンス

エンドポイント早見表

API ベストプラクティス · エラーハンドリング · 冪等性

ドメイン

データの流れ · ロジックマップ

データモデル · 仕訳ロジック

月次精算の書類の作り方とつなぎ方 · 経費精算ウィザード仕様

テスト戦略

リポジトリの構成

リポジトリ	役割
`solo-boss-cloud-documentation`	フロントエンド (Vite 8 + React 19 + Tailwind 4 + Capacitor 8)、98 feature domains、PWA、公開 `/docs` ハブ
`solo-boss-cloud_backend`	API (Express 5.2 + Prisma 7.4 + Node 22)、943 OpenAPI 操作 / 805 パス、224 Prisma モデル、AI・税務・役員社宅 API

両リポジトリとも .nvmrc で Node 22 を宣言しています。新しい Node では片方だけ動かないことがあるので、リポジトリごとに nvm use してください。

必要環境

Node.js
- フロントエンド: 22.x (.nvmrc 参照)
- バックエンド: 22.x (.nvmrc 参照; engines.node は >=20 <25)
npm 10.x
Git
推奨: VS Code または Cursor、Chrome (DevTools MCP 利用時は --remote-debugging-port=9222)

リポジトリの関係

フロントエンドとバックエンドは別リポジトリで、両方を立てると本格的に動かせます。最低限フロントだけでもデモは動きます。

flowchart TB
    subgraph Frontend [solo-boss-cloud-documentation]
      FE[Vite + React 19<br/>port 5174]
    end
    subgraph Backend [solo-boss-cloud_backend]
      API[Express 5 + Prisma<br/>port 8080]
    end
    subgraph Data [Supabase]
      DB[(PostgreSQL + RLS)]
      Auth[Auth + Storage]
    end
    Browser((ブラウザ)) --> FE
    FE -->|"REST + SSE"| API
    API -->|"prisma client"| DB
    API -->|"service role"| Auth

クイックスタート（フロントエンド）

依存関係は package-lock.json で固定しています。npm（npm ci）を使ってください。

git clone https://github.com/<org>/solo-boss-cloud-documentation.git
cd solo-boss-cloud-documentation
npm ci
npm run dev

主要スクリプト:

スクリプト	用途
`npm run dev`	Vite 開発サーバー (port 5174)
`npm run build`	本番ビルド (型チェック + Vite ビルド)
`npm run typecheck`	`tsc --noEmit`
`npm run lint`	ESLint
`npm run lint:strict`	ESLint (`--max-warnings 0` — CI ラチェット)
`npm run lint:fix`	ESLint auto-fix
`npm run format`	Prettier 整形
`npm run cap:sync`	Capacitor 同期 (Node 22 必須)
`npm run sync:openapi`	バックエンドの `public-artifacts/openapi.json` を取り込み
`npm run check:openapi`	CI 用: 取り込み済み OpenAPI がバックエンドと一致するか検証
`npm run generate:api-types`	OpenAPI 仕様から `src/types/api-schema.ts` を再生成
`npm run check:api-types`	CI 用: 生成済み API 型が最新かを検証
`npm run docs-stats`	README / ARCHITECTURE / 公開 docs の統計を表示
`npm run check:docs-stats`	CI 用: ドキュメント内の数値が実装と一致するか検証

クイックスタート（バックエンド）

git clone https://github.com/<org>/solo-boss-cloud_backend.git
cd solo-boss-cloud_backend
npm ci
npx prisma generate
npm run dev

主要スクリプト:

スクリプト	用途
`npm run dev`	`nodemon` + `tsx` で API を起動 (port 8080)
`npm test`	Vitest 単体テスト
`RUN_LIVE_API_TESTS=1 npm test`	Live API smoke / integration テスト
`npm run type-check`	TypeScript 型チェック
`npm run lint`	ESLint
`npm run test:coverage`	カバレッジ計測
`npm run export:openapi`	OpenAPI 仕様を `public-artifacts/openapi.json` にエクスポート
`npm run check:openapi`	CI 用: コミット済み OpenAPI が `swagger.ts` と一致するかを検証

ブランチ戦略 / コミット

全ての変更は main から切る Feature ブランチで実装し、PR を経てマージします。
コミットメッセージは命令形・小文字始まりを推奨（例: fix vitest globals conflict on test files）。
1 PR に詰め込み過ぎないこと。CI レビューが追従できないサイズになると Copilot レビューがスキップされます（フロントエンドは ~300 ファイル、バックエンドは ~20,000 行が目安）。

CI

フロントエンド: .github/workflows/production-ci.yml、capacitor-sync.yml、本番デプロイ .github/workflows/deploy-aws.yml（S3 + CloudFront → https://solo-boss.kensaur.us）。
バックエンド: .github/workflows/test.yml、本番デプロイ .github/workflows/deploy-aws.yml（Lambda → https://solo-boss.kensaur.us/api）。
両方とも Node 22 を .nvmrc から読みます。
ESLint の警告ゼロラチェットは npm run lint:strict（--max-warnings 0）。日常は npm run lint。

貢献するときの原則

既存パターンに合わせる 既存のコードベースのパターンに合わせてください。新しい抽象を入れるのは、既存パターンが本当に当てはまらないときだけにします。
環境変数 .env.example に載っている VITE_* を使う。存在しない @/config/env モジュールは想定しないでください。
共通ユーティリティを使う 数値・通貨・日付のフォーマットは既存のユーティリティ（formatJPYFull、formatDate など）を使ってください。
テキストは UI_LABELS から アプリ内のテキストは、原則として UI_LABELS 経由の日本語表記を使います。
デバッグは Logger で console.log は CI でブロックされます。デバッグには src/lib/mushi.ts を使ってください。

ドキュメント用ルート（リダイレクト）

かつての /docs/dev カタログとライブ・デザインシステム・ショーケースは削除済みです。 /docs/dev・/docs/dev/*・/design-system・/design-system/* は開発・本番とも開発者ガイド（このページ）へリダイレクトします。

トークンと UI パターンは公開のデザインシステムを参照してください。リポジトリ内の詳細 SSOT は docs/_design-system.md（§2.4 z-index ラダーを含む）です。

公開サイトでアーキテクチャと実装の全体像を読む場合は、以下の章を参照してください。

バックエンド概要 — 三層構成と公開／非公開 API の境界
データの流れ — 認証・CSRF・ケース変換・バリデーション
ロジックマップ — ドメイン別の主要エンドポイント
エンドポイント早見表 — 19 グループの API 地図
データモデル — Prisma スキーマ要約
デザインシステム — トークンと UI パターン（公開向け）
API リファレンス — OpenAPI 3.2 ブラウザ
公開 /docs/* = ドメイン・API・コンプライアンス中心（ソースパス非掲載）
旧 /docs/dev / /design-system = /docs/developer-guide へリダイレクト

API ドキュメントの更新フロー

仕様の真実は solo-boss-cloud_backend/src/docs/swagger.ts です。流れは次のとおり。

ルート・コントローラを実装し、src/docs/<area>.swagger.ts のパス・スキーマを更新
バックエンドで npm run export:openapi を実行し、public-artifacts/openapi.json を生成・コミット
フロントエンドで npm run sync:openapi を実行し、public/openapi/solo-boss-cloud.openapi.json を更新・コミット
必要に応じて npm run generate:api-types で TypeScript 型を再生成

CI では npm run check:openapi (両方) と npm run check:api-types (フロント) でドリフトを検出します。