Merge pull request #32 from kstm-su/feat/add-docs

ドキュメントの充実

.github/workflows/backend-lint.yml

@@ -0,0 +1,47 @@
+name: Backend Lint
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    paths:
+      - 'member-portal-backend/**'
+
+permissions:
+  statuses: write
+  contents: read
+  pull-requests: write
+
+
+jobs:
+  golangci:
+    name: lint
+    runs-on: ubuntu-latest
+    steps:
+      - name: Set commit status as pending
+        uses: myrotvorets/set-commit-status-action@master
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          status: pending
+          context: Check pull request (Backend)
+
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version: stable
+
+      - name: golangci-lint
+        uses: golangci/golangci-lint-action@v6
+        with:
+          working-directory: member-portal-backend
+          version: v1.60
+
+      - name: Set final commit status
+        uses: myrotvorets/set-commit-status-action@master
+        if: always()
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          status: ${{ job.status }}
+          context: Check pull request (Backend)

.github/workflows/build.yml

@@ -36,7 +36,7 @@ jobs:
           platforms: linux/amd64
           push: true
           tags: |
-            ghcr.io/kstm-su/member-portal/${{ matrix.tag }}:latest
-            ghcr.io/kstm-su/member-portal/${{ matrix.tag }}:${{ env.GITHUB_SHA_SHORT }}
+            ghcr.io/${{GITHUB_REPOSITORY_OWNER}}/member-portal/${{ matrix.tag }}:latest
+            ghcr.io/${{GITHUB_REPOSITORY_OWNER}}/member-portal/${{ matrix.tag }}:${{ env.GITHUB_SHA_SHORT }}
           cache-from: type=gha,scope=member-portal-${{ matrix.tag }}
           cache-to: type=gha,mode=max,scope=member-portal-${{ matrix.tag }}

.github/workflows/docs-deploy.yml

@@ -15,21 +15,12 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
         with:
-          python-version: "3.12"
-      - name: install pipenv
-        run: |
-          python -m pip install --upgrade pip
-          python -m pip install pipenv
-
-      - name: lock package version
-        run: pipenv lock
-
-      - name: install packages
-        run: pipenv sync --dev
+          python-version: 3.12
+      - run: |
+          pip install mkdocs-material
 
       - name: copy swagger
         run: |
-          rm -r docs/docs/swagger 2> /dev/null
-          cp -r -f swagger docs/docs/swagger
+          cp -r -f ./swagger ./docs/docs/swagger
 
-      - run: pipenv shell mkdocs gh-deploy --force --config-file ./docs/mkdocs.yml
+      - run: mkdocs gh-deploy --config-file ./docs/mkdocs.yml

.github/workflows/lint.yml → .github/workflows/front-lint.yml

@@ -1,4 +1,4 @@
-name: Check pull request
+name: Frontend Lint
 
 on:
   workflow_dispatch:
@@ -15,11 +15,17 @@ defaults:
   run:
     working-directory: member-portal-frontend
 
-
 jobs:
   eslint:
     runs-on: ubuntu-latest
     steps:
+      - name: Set commit status as pending
+        uses: myrotvorets/set-commit-status-action@master
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          status: pending
+          context: Check pull request (Frontend)
+
       - uses: actions/checkout@v4
 
       - uses: actions/setup-node@v4
@@ -33,6 +39,14 @@ jobs:
       - uses: reviewdog/action-eslint@v1
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          reporter: github-pr-review # Change reporter.
+          reporter: github-pr-review
           workdir: member-portal-frontend
-          fail_on_error: 'true'
+          fail_on_error: 'true'
+
+      - name: Set final commit status
+        uses: myrotvorets/set-commit-status-action@master
+        if: always()
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          status: ${{ job.status }}
+          context: Check pull request (Frontend)

.gitignore

@@ -2,4 +2,7 @@
 docs/docs/swagger
 docs/site
 
-.idea
+.idea
+
+member-portal-backend/app/**
+member-portal-backend/app-local/**

README.md

@@ -1,6 +1,8 @@
 # member-portal
 kstmメンバーであることを確認し、また事務処理を簡潔化するためのポータルサイト
 
+[Wiki](https://kstm-su.github.io/member-portal/)
+
 ## Frontend
 ### Docker起動方法
 1. Dockerfileのあるディレクトリに移動
@@ -10,7 +12,7 @@ kstmメンバーであることを確認し、また事務処理を簡潔化す
 
 ※ ローカルで起動する場合は、`npm run dev` を実行
 
-## Backend 
+## Backend
 
 ### Docker起動方法
 1. Dockerfileのあるディレクトリに移動
@@ -29,4 +31,7 @@ kstmメンバーであることを確認し、また事務処理を簡潔化す
 ### Mockサーバーの立て方
 1. `swagger/README.md` の "Getting started" の手順を行う
 2. "Mock API" の手順を `documentation.yml` と同じディレクトリにて行う
-3. `http://localhost:4010`にモックサーバーが立つ
+3. `http://localhost:4010`にモックサーバーが立つ
+
+
+

docs/docs/backend/config.md

@@ -0,0 +1,38 @@
+# コンフィグの設定について
+
+```yaml
+database:
+  type: sqlite  
+  sqlite:
+    path: /app/data/db.sqlite3
+file:
+  base: /app/data
+jwt:
+  issuer: localhost
+  key:
+    private_key: private.pem
+    public_key: public.pem
+  key_id: key
+  realm: localhost
+password:
+  algorithm: argon2
+  pepper: <random_pepper> #自動で生成されるため、設定不要
+server:
+  host: localhost
+  port: 8080
+```
+
+## database
+postgresqlを利用する場合、以下のように設定を変更してください。
+
+```yaml
+database:
+  type: postgres
+  postgres:
+    host: db
+    port: 5432
+    user: <user>
+    password: <password>
+```
+
+

docs/docs/backend/feature.md

@@ -0,0 +1,21 @@
+# 実装機能
+
+- [x] OAuth2認可
+    - [x] 認可コード取得
+    - [x] アクセストークン取得
+    - [x] リフレッシュトークン取得
+    - [ ] トークン削除
+    - [ ] トークン情報取得
+    - [ ] トークン有効性確認
+    - [ ] クライアント作成
+- [ ] OpenID Connect認証
+    - [x] クライアント情報取得
+    - [ ] ユーザー情報取得
+    - [ ] ユーザー情報更新
+- [ ] ユーザー情報取得API
+    - [x] プロフィール取得(OIDC クライアント情報取得と同一)
+    - [ ] ユーザー情報更新
+    - [ ] 新規ユーザー登録
+    - [ ] ユーザーリスト取得
+    - [ ] お知らせ取得
+    - [ ] お知らせ更新

docs/docs/backend/index.md

@@ -0,0 +1,27 @@
+# バックエンドについて
+
+## バックエンドの概要
+
+バックエンドはGo言語で実装されています。
+OAuth2およびOpenID Connectを使用して認可・認証を行い、ユーザー情報を渡すAPIを提供します。
+
+## 起動方法
+
+### Dockerでの起動方法
+#### Localでビルドする場合
+
+1. Dockerfileのあるディレクトリに移動
+2. `docker build -t <image_name> .` を実行（image_nameは自由に設定）
+3. `docker run -p 3001:8080 -d <image_name>` を実行
+4. `http://localhost:3001` にアクセス
+
+#### GitHub container registryからpullする場合
+1. `docker pull ghcr.io/kstm-su/member-portal/backend:latest` を実行
+2. `docker run -p 3001:8080 -d ghcr.io/kstm-su/member-portal/backend:latest` を実行
+3. `http://localhost:3001` にアクセス
+
+### Goでローカルで起動する場合
+1. `cd member-portal-backend` でディレクトリに移動
+2. `go run main.go` を実行
+3. `http://localhost:8080` にアクセス
+

docs/docs/backend/technology-stack.md

@@ -0,0 +1,41 @@
+# 技術スタック
+
+## 採用ライブラリ
+
+Web framework: [echo](https://echo.labstack.com/) <br>
+採用理由: openapi-generatorを利用することを想定し、親和性の高いechoを採用。
+
+ORM: [gorm](https://gorm.io/) <br>
+採用理由: GitHubのスター数が多く、開発者が多いため。
+
+Command line tool: [cobra](https://cobra.dev/) <br>
+採用理由: サブコマンドの実装が容易であるため また、k8sでも採用されているため、
+
+Config: [viper](https://github.com/spf13/viper) <br>
+採用理由: cli toolとして採用した、cobraとの親和性が高いため、
+
+## 依存ソフトウェア
+
+Language: [Go](https://golang.org/) <br>
+採用理由: 本プロジェクトの言語として採用。
+
+Linter & Formatter: [golangci-lint](https://golangci-lint.run/) <br>
+採用理由: GitHubのスター数が多く、開発者が多いため。また、複数のlinterを統合しているため。
+
+Database: [PostgreSQL](https://www.postgresql.org/) [Optional]<br>
+採用理由: 慣習的に利用されるため。 また、ORMのgormが対応しているため。 (ConfigでSQLite3を利用することも可能)
+
+Secret Manager(検討中): [Hashicorp Vault](https://www.vaultproject.io/)　<br>
+採用理由: シークレット管理のため<br>
+利用場面: パスワードハッシュ化時のpepperの管理および、OAuth2クライアントのシークレット管理の際に利用のため。<br>
+その他の候補: [Cyber Ark conjur](https://www.conjur.org/), [Infisical](https://infisical.com/)
+
+Object storage: [MinIO](https://min.io/) [Optional]<br>
+採用理由: S3互換のため。
+
+
+
+
+
+
+

docs/docs/common/about-this.md

@@ -0,0 +1,43 @@
+# 当ドキュメントについて
+
+このドキュメントは、[MkDocs-material](https://squidfunk.github.io/mkdocs-material/)を使用して作成されました。
+
+## 目的
+
+今後の開発の参入障壁を低くするために、どのような技術スタックを利用し、何を目的としているかを示すため。
+
+## 編集するには
+`docs/docs`にドキュメントの本体が配置されているため、そちらを編集してください。<br>
+また、新たにファイルを追加する場合は、`mkdocs.yml`にある`nav`に追加してください。
+
+## 表示方法
+
+### ローカルでの表示
+
+以下のコマンドを実行することで、ローカルでの表示が可能です。
+
+#### 事前準備
+
+```bash
+pip install mkdocs-material
+```
+
+#### Linux
+
+```bash
+cd docs
+./start.sh
+```
+
+#### Windows
+
+`docs/docs`に`swagger`をコピーしたのち、以下のコマンドを実行してください。
+
+```bash
+cd docs
+mkdocs serve
+```
+
+### GitHub Pagesでの表示
+
+GitHub Pagesでの表示は、[こちら](https://kstm-su.github.io/member-portal/)からご覧いただけます。

docs/docs/common/api-docs.md

@@ -0,0 +1,24 @@
+# APIドキュメントについて
+
+## 目的
+OpenAPIを利用してAPIドキュメントを作成することで、フロントエンドとバックエンドの実装を隠蔽し、APIの定義をインターフェースとして利用することにより、開発効率を向上させる。
+
+## 仕様
+- OpenAPI 3.0.0
+- ファイル形式: YAML
+- ファイル名: documentation.yaml
+- ファイルの配置場所: /swagger
+
+## ファイル構成
+`/components`: OpenAPIのコンポーネントを定義する <br>
+`/paths`: APIのエンドポイントを定義する <br>
+`documentation.yaml`: OpenAPIの定義を記述するファイル
+
+## APIドキュメントの確認方法
+### Github Pagesで確認する方法
+masterブランチのAPIドキュメントについては[こちら](/member-portal/redoc/index.html)で確認できます。
+
+### ローカルで確認する方法
+1. `cd swagger`で`swagger`ディレクトリに移動します
+2. `npx @redocly/cli preview-docs documentation.yml`を実行します
+3. `http://localhost:8080/`にアクセス