{"id":26084113,"url":"https://github.com/nutfes/finansu","last_synced_at":"2025-07-07T19:08:47.936Z","repository":{"id":36952714,"uuid":"424629608","full_name":"NUTFes/FinanSu","owner":"NUTFes","description":"技大祭のお金の管理をするアプリケーション","archived":false,"fork":false,"pushed_at":"2025-04-11T05:12:44.000Z","size":37858,"stargazers_count":6,"open_issues_count":50,"forks_count":1,"subscribers_count":3,"default_branch":"develop","last_synced_at":"2025-04-11T06:23:32.148Z","etag":null,"topics":["docker","go","nextjs","typescript"],"latest_commit_sha":null,"homepage":"https://finansu.nutfes.net/","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NUTFes.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-11-04T14:41:28.000Z","updated_at":"2025-04-08T13:15:30.000Z","dependencies_parsed_at":"2024-03-19T05:26:24.375Z","dependency_job_id":"ea028389-b500-4351-9b48-847fde1b158d","html_url":"https://github.com/NUTFes/FinanSu","commit_stats":null,"previous_names":[],"tags_count":40,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NUTFes%2FFinanSu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NUTFes%2FFinanSu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NUTFes%2FFinanSu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NUTFes%2FFinanSu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NUTFes","download_url":"https://codeload.github.com/NUTFes/FinanSu/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248501960,"owners_count":21114681,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","go","nextjs","typescript"],"created_at":"2025-03-09T04:40:57.776Z","updated_at":"2025-07-07T19:08:47.931Z","avatar_url":"https://github.com/NUTFes.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FinanSu\n\nFinanSuは、NUTFes/NUTMegの財務管理システムです。OpenAPI駆動開発により、Go + Next.jsで構築されています。\n\n## 技術スタック (Tech Stack)\n\n### Backend (API)\n- **Language**: Go 1.23+ with Echo framework\n- **Database**: MySQL 8.0 + GORM\n- **Storage**: MinIO (S3-compatible)\n- **Code Generation**: oapi-codegen (OpenAPI)\n- **Testing**: Go test with testfixtures\n\n### Frontend (View)\n- **Framework**: Next.js 14 + React 18 + TypeScript\n- **UI**: Chakra UI + Tailwind CSS\n- **State Management**: Recoil with persistence\n- **Data Fetching**: SWR with generated hooks\n- **Code Generation**: Orval (OpenAPI to TypeScript)\n\n### Infrastructure\n- **Container**: Docker + Docker Compose\n- **Development**: Hot reload with Air (Go) + Next.js dev server\n- **API Documentation**: Swagger UI\n\n## 環境構築 (set up)\n\n### 基本セットアップ\n```bash\nmake run-db      # データベース起動 (MySQL + MinIO)\nmake build       # アプリケーションビルド\nmake run         # アプリケーション起動\n```\n\n### 全て一括起動\n```bash\nmake run-all     # DB + アプリ + Swagger UI\n```\n\n### 直接Docker Composeを使用する場合\n```bash\ndocker compose -f compose.db.yml up -d\ndocker compose build\ndocker compose up\n```\n\n## 開発コマンド (Development Commands)\n\n### コード生成 (重要)\n```bash\nmake gen         # OpenAPI仕様からAPI/フロントエンドコード生成\nmake gen-api     # Go serverコード生成\nmake gen-front-api # TypeScript hooks生成\n```\n\n### テスト・品質チェック\n```bash\nmake run-test    # Go APIテスト実行\nmake run-eslint  # フロントエンドLint実行\nmake format      # コードフォーマット\n```\n\n### その他の便利コマンド\n```bash\nmake run-sb      # Storybook起動\nmake ent-db      # MySQLシェルへ接続\nmake run-swagger # Swagger UI起動\nmake seed        # データベースシード実行\n```\n\n## 開発環境詳細\n\n### ポート設定\n- **Frontend**: http://localhost:3000\n- **API**: http://localhost:1323\n- **Database**: localhost:3306\n- **MinIO Console**: http://localhost:9001\n- **Storybook**: http://localhost:6006\n\n### システム設計図\n\n```mermaid\ngraph TB\n    subgraph \"Frontend (Next.js)\"\n        UI[React Components]\n        Store[Recoil Store]\n        Hooks[Generated API Hooks]\n        Pages[Next.js Pages]\n    end\n\n    subgraph \"Backend (Go)\"\n        subgraph \"Clean Architecture\"\n            Controllers[Controllers\u003cbr/\u003eHTTP Handlers]\n            UseCases[Use Cases\u003cbr/\u003eBusiness Logic]\n            Repositories[Repositories\u003cbr/\u003eData Access]\n            Domain[Domain Models]\n        end\n        Generated[Generated Code\u003cbr/\u003eOpenAPI]\n    end\n\n    subgraph \"Infrastructure\"\n        MySQL[(MySQL Database)]\n        MinIO[(MinIO\u003cbr/\u003eObject Storage)]\n        Swagger[Swagger UI]\n    end\n\n    subgraph \"Development\"\n        OpenAPI[OpenAPI Spec\u003cbr/\u003eopenapi.yaml]\n        Docker[Docker Compose]\n        Storybook[Storybook]\n    end\n\n    %% Frontend Flow\n    UI --\u003e Store\n    UI --\u003e Hooks\n    Pages --\u003e UI\n    Hooks --\u003e Controllers\n\n    %% Backend Flow\n    Controllers --\u003e UseCases\n    UseCases --\u003e Repositories\n    UseCases --\u003e Domain\n    Repositories --\u003e MySQL\n    Controllers --\u003e MinIO\n\n    %% Code Generation\n    OpenAPI --\u003e Generated\n    OpenAPI --\u003e Hooks\n    Generated --\u003e Controllers\n\n    %% Documentation\n    OpenAPI --\u003e Swagger\n    UI --\u003e Storybook\n\n    %% Infrastructure\n    Docker -.-\u003e MySQL\n    Docker -.-\u003e MinIO\n    Docker -.-\u003e UI\n    Docker -.-\u003e Controllers\n\n    classDef frontend fill:#e1f5fe\n    classDef backend fill:#f3e5f5\n    classDef infrastructure fill:#e8f5e8\n    classDef development fill:#fff3e0\n\n    class UI,Store,Hooks,Pages frontend\n    class Controllers,UseCases,Repositories,Domain,Generated backend\n    class MySQL,MinIO,Swagger infrastructure\n    class OpenAPI,Docker,Storybook development\n```\n\n### アーキテクチャの特徴\n\n1. **OpenAPI駆動開発**: 全ての型安全性がOpenAPI仕様から生成\n2. **Clean Architecture**: バックエンドは依存関係逆転により保守性を確保\n3. **型安全性**: フロントエンドからバックエンドまで一貫した型チェック\n4. **コンテナ化**: Docker Composeによる一貫した開発環境\n\n### プロジェクト構造\n```\n/api/               # Go backend (Clean Architecture)\n  ├── main.go       # エントリーポイント\n  ├── drivers/      # インフラ層 (DB, MinIO, server)\n  ├── externals/    # コントローラー・リポジトリ\n  ├── internals/    # ドメイン・ユースケース\n  └── generated/    # OpenAPI自動生成コード\n\n/view/next-project/ # Next.js frontend\n  ├── src/components/   # 機能別Reactコンポーネント\n  ├── src/pages/        # Next.js file-based routing\n  ├── src/generated/    # 自動生成APIフック\n  └── src/store/        # Recoil状態管理\n\n/openapi/           # OpenAPI仕様 (真の情報源)\n/mysql/db/          # データベーススキーマ・マイグレーション\n```\n\n## 開発ワークフロー\n\n### OpenAPI駆動開発\n1. `/openapi/openapi.yaml` を編集してAPI変更\n2. `make gen` でGo serverコードとTypeScript hooksを再生成\n3. サーバーサイドロジックをcontrollers/use casesで実装\n4. 生成されたhooksをReactコンポーネントで使用\n\n### 環境管理\n- **開発**: `compose.yml`\n- **ステージング**: `compose.stg.yml`\n- **本番**: `compose.prod.yml`\n- **DB のみ**: `compose.db.yml`\n\n## ドキュメント (Documents)\n\n### プロジェクト概要\n- [FinanSu について](https://www.notion.so/nutfes-nutmeg/FinanSu-6f207506947b475aad3610210016a8a3) - 背景・目的や技術仕様\n- [FinanSu 開発ガイド](https://www.notion.so/nutfes-nutmeg/FinanSu-OK-3a12e725374742608959b6bac61d702c) - 開発全般の情報\n\n### 開発ルール\n- [Git ワークフロー](https://www.notion.so/nutfes-nutmeg/git-clone-41a4a1a2df324c92a56b6d0b1b244747) - 開発時のGit使用手順\n- [Git/GitHub 基本操作](https://www.notion.so/nutfes-nutmeg/Git-Github-478cabf96e3e44909e35b3476fe08886)\n- [ブランチルール](https://www.notion.so/nutfes-nutmeg/9d1646b47e184ab1b85b35e02de76e3f)\n- [コミットルール](https://www.notion.so/nutfes-nutmeg/f4ace67ac1c14d849aee084327914c0f)\n\n### API・技術仕様\n- [API 一覧](https://www.notion.so/nutfes-nutmeg/FinanSu-API-92b657ec9ff64157be94486fbfc8382f)\n- [OpenAPI 仕様書](http://localhost:1323/swagger/index.html) - 開発中にアクセス可能\n- [Storybook](http://localhost:6006) - コンポーネントドキュメント\n\n### 関連記事\n- [FinanSu タグ記事一覧](https://www.notion.so/nutfes-nutmeg/FinanSu-db5914909df34786b7f1e4a205ebfea7)\n\n## AI 開発支援\n\nこのプロジェクトは AI アシスタント（Claude Code、GitHub Copilot）による開発を支援しています。\n\n- **CLAUDE.md** - Claude Code 用の開発ガイダンス\n- **GitHub Copilot** - カスタム指示付きコード支援（日本語ITギャル設定）\n\n## 重要な注意事項\n\n### コード生成の依存関係\n- OpenAPI仕様を変更したら必ず `make gen` を実行\n- 生成されたコードは手動で編集しない\n- 型安全性はOpenAPI仕様からバックエンド・フロントエンドに流れる\n\n### 品質管理\n- フロントエンドコミット前に `make run-eslint` と `make format` を実行\n- APIテストは `make run-test` で実行\n- PRは `.github/pull_request_template.md` テンプレートを使用\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnutfes%2Ffinansu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnutfes%2Ffinansu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnutfes%2Ffinansu/lists"}