README.md

---
title: Chibafes Website API
emoji: 🚀
colorFrom: blue
colorTo: green
sdk: docker
app_port: 7860
pinned: false
---

# 千葉大祭団体企画情報の提供&検索システム
## 目次
* [APIの仕様](#apiの仕様)
* [ローカル作業の準備](#ローカル作業の準備)
    * [1. リポジトリをクローン](#1-リポジトリをクローン)
    * [2. ローカルで`.env`ファイルを作成](#2-ローカルで-env-ファイルを作成)
    * [3. 適切なバージョンのPythonを入手する](#3-適切なバージョンのpythonを入手する)
    * [4. Pythonの仮想環境を作成・有効化](#4-pythonの仮想環境を作成有効化)
    * [5. ライブラリをインストール](#5-ライブラリをインストール)
* [開発用サーバーの起動](#開発用サーバーの起動)
* [仕組み・企画データ更新](#仕組み・企画データ更新)

## APIの仕様
[`docs/システムガイド.md`](./docs/システムガイド.md) のセクション7「APIの使い方」を参照してください。

## ローカル作業の準備
### 1. リポジトリをクローン
```bash
git clone https://github.com/chibafes-dev/circle-search-26-api.git
```
> クローンのためには `Read` 以上のリポジトリ権限が必要です。また、作業をしてプッシュをするには `Write` 以上のリポジトリ権限が必要です。

---

### 2. ローカルで `.env` ファイルを作成

以下の`...`部分を適切な値に変更する。（なんらかの方法で引き継いでもらう。）
```sh
# API側 GitHub の secrets と HF Spaces の Secrets の両方に登録
HF_TOKEN=...
# HF Spaces の secrets に登録
API_SECRET_KEY=...
HF_EMBEDDINGS_REPO_ID=...
```

> **!!! 注意 !!!**  
> .envは機密情報なので絶対にリポジトリにプッシュしないこと！！.gitignoreに含まれていることを確認してください。

---

### 3. 適切なバージョンのPythonを入手する

やり方はいくつかありますが、筆者は `pyenv` を使用しました。適切なバージョンがインストールできればなんでもいいですが、ここでは `pyenv` を紹介します。  
英語が読める人は [公式リポジトリ](https://github.com/pyenv/pyenv?tab=readme-ov-file#a-getting-pyenv) を参考にしてインストールしてください。

---

#### 英語が読めないWindowsユーザー向け（WSL2はLinux向けを確認）
<details>

残念ながら `pyenv` はWindowsに対応していないので、代わりに `pyenv-win` を使いましょう。

参考：https://github.com/pyenv-win/pyenv-win/blob/master/docs/installation.md#powershell

1. Powershellで以下のコマンドを実行
    ```powershell
    Invoke-WebRequest -UseBasicParsing -Uri "https://raw.githubusercontent.com/pyenv-win/pyenv-win/master/pyenv-win/install-pyenv-win.ps1" -OutFile "./install-pyenv-win.ps1"; &"./install-pyenv-win.ps1"
    ```

    もし `UnauthorizedAccess` エラーが出たら、以下のコマンドを「管理者権限で」実行したのち、上のコマンドを再度試してください。
    ```powershell
    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine
    ```

2. インストールができたことを確認する

    以下のコマンドを実行：
    ```powershell
    pyenv --version
    ```
    バージョン情報が出れば成功。
</details>

#### 英語が読めないMacユーザー向け
<details>

参考：https://github.com/pyenv/pyenv/blob/master/README.md#macos

1. どうにかしてHomebrewを入れる

    やり方はググってください。

2. Homebrew経由で `pyenv` をインストール

    ```bash
    brew update
    brew install pyenv
    ```

3. シェル環境を整える

    `zsh` を使っている人向けの説明。自分が何を使っているかわからない人は `echo $SHELL` を実行。
    > 最近のMacだと `zsh` がデフォルトらしいです。敢えて `bash` とか `fish` にするような方には私の説明は不要だと思うので、[公式リポジトリ](https://github.com/pyenv/pyenv/blob/master/README.md#b-set-up-your-shell-environment-for-pyenv) を見てご自身でうまいことやってほしいです。

    以下の3つのコマンドを1行ずつ順に実行する。
    ```bash
    echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
    echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
    echo 'eval "$(pyenv init - zsh)"' >> ~/.zshrc
    ```

4. シェルを再起動する

    ```bash
    exec "$SHELL"
    ```
</details>

#### 英語が読めないLinuxユーザー向け（WSL2含む）
<details>

参考：https://github.com/pyenv/pyenv/blob/master/README.md#linuxunix

1. 自動インストーラを使用する

    ```bash
    curl -fsSL https://pyenv.run | bash
    ```
</details>

---

#### <全OS共通> Python をインストールする
1. `.python-version` に記載された Python のバージョンを確認

    以下例として `3.12.11` の場合を仮定します。

2. `pyenv` で Python をインストールする
    ```bash
    pyenv install 3.12.11
    ```

3. Python のバージョンを切り替え

    `pyenv` が `.python-version` を自動で読み取って切り替えてくれるので操作は不要です。

    以下のコマンドで Python のバージョンを確認しましょう。
    ```bash
    pyenv version
    ```
    （`versions`ではない）

<details>
<summary>手動で切り替えたい場合</summary>

このリポジトリ `circle-search-26-api` があるフォルダに移動し、以下のコマンドを実行
```bash
pyenv local 3.12.11
```
これを実行すると、そのフォルダの中で `3.12.11` が有効化されます。
> 全部のフォルダで有効化したい場合は `local` の代わりに `global` としてください。
</details>

---

### 4. Pythonの仮想環境を作成・有効化
```bash
python -m venv .venv
source .venv/bin/activate
```

---

### 5. ライブラリをインストール
```bash
pip install --upgrade pip
pip install -r requirements.txt
```

## 開発用サーバーの起動
### （初回のみ）必要ファイルの作成
> **!!! 注意 !!!**  
> **大容量（約6GB）のダウンロードが発生するので、必ずWiFi環境で行うこと！！**
```bash
python scripts/build_all.py
```

### サーバー起動
```bash
uvicorn app.main:app --reload
```

`http://localhost:8000`からアクセスできます（デフォルトポート）。Hugging Face Spacesでは7860ポートで起動します。

## 仕組み・企画データ更新
企画データ更新のためには以下のステップを実行してください。
1. Google Spreadsheets でデータの整理 → CSVファイルのダウンロード
2. CSVファイルを `resources/` に設置
3. `config/files.json` 内 `circles > original_csv` を実際のパス・ファイル名に変更
    ```json
    {
        ...
        "circles": {
            "original_csv": "resources/original_circles.csv", // ここを変更
            "circles_json": "data/generated/circles.json"
        },
        ...
    }
    ```
4. `python scripts/build_all.py` を実行 → ローカルで動作確認
5. GitHubにプッシュ（`main` ブランチにマージ）

詳細な仕組み等は [`docs/`](./docs) を確認してください。