Skip to content

Commit 20fe760

Browse files
ut42techut42tech
committed
docs: Update requirements document to reflect version 1.3 and current operational status
1 parent 631d162 commit 20fe760

7 files changed

Lines changed: 404 additions & 396 deletions

File tree

‎CLAUDE.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -116,7 +116,7 @@ APIサーバ（`apps/api`）は Cloudflare Workers で動作します。以下
116116
- ⚠️ `ctx.waitUntil()` は「レスポンス送信後にバックグラウンド処理を走らせる場合」に使う。現状の auth 経路（`routes/auth.ts` / `middleware/auth.ts`）は Better Auth の DB 書き込みを `await` で完結させているため**未配線**。今後カスタム非同期フックや secondary storage などで遅延処理を足すときは、必ず `c.executionCtx.waitUntil()` を通すこと
117117
- ❌ グローバルスコープに auth instance を保持しない（接続ロックの問題）
118118

119-
詳細: [`docs/mvp.md` 11.1節](./docs/mvp.md#111-better-auth-on-workers-でハマったら)
119+
詳細: [`docs/mvp.md` 10.1節](./docs/mvp.md#101-better-auth-on-workers-でハマったら)
120120

121121
### 3. Google Sheets API の実装方針
122122

@@ -273,7 +273,7 @@ npx wrangler secret put <SECRET_NAME>
273273
| APIのリクエスト/レスポンス形式 | `docs/mvp.md` 6章 |
274274
| 画面遷移・UI仕様 | `docs/mvp.md` 7章 |
275275
| 既知のリスク・対策 | `docs/requirements.md` 12章 |
276-
| トラブルシュート | `docs/mvp.md` 11章 |
276+
| トラブルシュート | `docs/mvp.md` 10章 |
277277
| 設計判断の根拠 | `docs/requirements.md` 付録A |
278278

279279
判断に迷うことがあれば、まず上記を確認してから提案・実装してください。

‎README.md‎

Lines changed: 52 additions & 85 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<p align="center">
2-
<strong>tec-nova Nagasaki 統合管理プラットフォーム</strong>
2+
<img src="./docs/images/tecnova-platform-header.png" alt="tec-nova Nagasaki Platform — Designed for Makerspaces" width="100%" />
33
</p>
44

55
<p align="center">
@@ -19,10 +19,22 @@
1919

2020
---
2121

22-
長崎大学 NUTIC で開催される子ども向けファブリケーション活動 **「テクノバながさき」** の運営基盤プラットフォーム。
22+
## 📖 概要
2323

24-
参加者のチェックイン / アウト、活動ログ記録、研究データ収集を統合的に支える内製システム。
25-
API-first なアーキテクチャで、複数のクライアント（iPad チェックイン機 ・ メンタースマホ ・ 管理 PC）を同一バックエンドから提供します。
24+
`tecnova-platform` は、**メイカースペース向けに設計したモダンな Web プラットフォーム**です。子どもたちが自由に創作・ものづくりに取り組む施設の運営を、**受付（チェックイン / アウト）・参加者管理・研究データ収集** まで一気通貫で支えます。
25+
26+
最初の導入先は **tec-nova Nagasaki**（長崎市と長崎大学による共同事業）。小学 1 年〜高校 3 年の子どもが 3D プリンタ・プログラミング・ロボット・3D モデリングなどに自由来場で取り組むファブリケーション活動です。
27+
28+
- 🎯 **解決する課題** — 紙とスプレッドシートに依存していた受付・名簿照合・二重登録の混乱を、構造的に解消する
29+
- 🧩 **システム構成** — 1 つの API（Hono on Cloudflare Workers）＋ クライアント（iPad 受付 / 管理 PC）を同一バックエンドから提供する API-first 設計
30+
- 🔐 **プライバシー設計** — 住所・連絡先などの機微情報は内製 DB に持たず運営側の管理下に限定。保持するのは氏名・ニックネーム・学年のみ
31+
32+
### 受付のしくみ
33+
34+
1. 子どもがネームカードの **QR / バーコード** を iPad にかざす
35+
2. API が参加者 DB（Cloudflare D1）を照合し、**チェックイン / チェックアウトを自動判定**
36+
3. 初回来場者は事前登録情報からその場で **アクティベート（内製 ID 採番）**
37+
4. 管理 PC のダッシュボードで **当日の来場状況をリアルタイムに把握**
2638

2739
---
2840

@@ -34,9 +46,7 @@ API-first なアーキテクチャで、複数のクライアント（iPad チ
3446

3547
---
3648

37-
## ✨ Features
38-
39-
### Phase 1 — MVP（✅ 実装済み）
49+
## ✨ 主な機能
4050

4151
| 機能 | 説明 |
4252
| -------------------------------- | ------------------------------------------------------- |
@@ -50,17 +60,39 @@ API-first なアーキテクチャで、複数のクライアント（iPad チ
5060
| 📋 受付履歴 & 一括チェックアウト | 当日の全操作ログとワンタップ一括退場 |
5161
| 📂 Drive 自動連携 | アクティベート時に GAS 経由で Drive フォルダ自動生成 |
5262

53-
### Phase 1.5 — 運用開始後
63+
> 今後のロードマップ・フェーズ計画は [`docs/requirements.md`](./docs/requirements.md)（スコープとフェーズ計画）と [`docs/handoff.md`](./docs/handoff.md)（進捗・残タスク）を参照してください。
64+
65+
---
66+
67+
## 🛠️ Tech Stack
5468

55-
- 📝 メンタースマホアプリ（30 分グリッドのログ記入・未記入ハイライト）
56-
- 🏷️ 活動カテゴリ・機材マスタ管理
57-
- 📤 ログ CSV エクスポート
69+
### Backend
5870

59-
### Phase 2 — 中長期
71+
| Technology | Purpose |
72+
| ------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
73+
| ![Hono](https://img.shields.io/badge/Hono-4-E36002?logo=hono&logoColor=white) | Ultrafast web framework for the edge |
74+
| ![Cloudflare Workers](https://img.shields.io/badge/Cloudflare_Workers-F38020?logo=cloudflare&logoColor=white) | Edge runtime |
75+
| ![D1](<https://img.shields.io/badge/Cloudflare_D1_(SQLite)-F38020?logo=cloudflare&logoColor=white>) | Workers-native database |
76+
| ![Drizzle](https://img.shields.io/badge/Drizzle_ORM-0.45-C5F74F?logo=drizzle&logoColor=black) | TypeScript-first ORM |
77+
| ![Better Auth](https://img.shields.io/badge/Better_Auth-1.6-000?logoColor=white) | Framework-agnostic authentication |
6078

61-
- 🔍 振り返りシートの Vision LLM 経由 OCR 取り込み
62-
- 🌐 公開 API（混雑状況配信）
63-
- 📈 分析ダッシュボード（クラスター分析支援）
79+
### Frontend
80+
81+
| Technology | Purpose |
82+
| ---------------------------------------------------------------------------------------------------- | ---------------------------- |
83+
| ![Next.js](https://img.shields.io/badge/Next.js-16-000?logo=next.js) | React framework (App Router) |
84+
| ![React](https://img.shields.io/badge/React-19-61DAFB?logo=react&logoColor=black) | UI library |
85+
| ![shadcn/ui](https://img.shields.io/badge/shadcn%2Fui-000?logo=shadcnui&logoColor=white) | Component library |
86+
| ![Tailwind CSS](https://img.shields.io/badge/Tailwind_CSS-4-06B6D4?logo=tailwindcss&logoColor=white) | Utility-first CSS |
87+
| ![Vercel](https://img.shields.io/badge/Vercel-000?logo=vercel&logoColor=white) | Hosting & deployment |
88+
89+
### Tooling
90+
91+
| Technology | Purpose |
92+
| -------------------------------------------------------------------------------------------- | ------------------------ |
93+
| ![pnpm](https://img.shields.io/badge/pnpm-10-F69220?logo=pnpm&logoColor=white) | Monorepo package manager |
94+
| ![Turborepo](https://img.shields.io/badge/Turborepo-2-0F0F0F?logo=turborepo&logoColor=white) | Build orchestration |
95+
| ![Biome](https://img.shields.io/badge/Biome-2.4-60A5FA?logo=biome&logoColor=white) | Lint & format |
6496

6597
---
6698

@@ -72,13 +104,11 @@ API-first なアーキテクチャで、複数のクライアント（iPad チ
72104
graph TB
73105
subgraph Clients["🖥️ クライアント"]
74106
C1["📱 Checkin<br/><small>iPad PWA</small>"]
75-
C2["📱 Mentor<br/><small>スマホ PWA</small><br/><small>(Phase 1.5)</small>"]
76107
C3["💻 Admin<br/><small>PC ブラウザ</small>"]
77108
end
78109
79110
subgraph Hosting["☁️ Vercel"]
80111
V1["Next.js<br/>:3000"]
81-
V2["Next.js<br/>(未着手)"]
82112
V3["Next.js<br/>:3001"]
83113
end
84114
@@ -94,11 +124,9 @@ graph TB
94124
end
95125
96126
C1 --> V1
97-
C2 --> V2
98127
C3 --> V3
99128
100129
V1 -- "REST (type-safe)" --> API
101-
V2 -. "REST" .-> API
102130
V3 -- "REST (type-safe)" --> API
103131
104132
API --> D1
@@ -124,43 +152,11 @@ sequenceDiagram
124152
GS-->>API: 参加者情報
125153
API->>D1: participants INSERT + 採番
126154
D1-->>API: 新規 ID (5桁)
127-
API-->>iPad: { participantId, displayId }
155+
API-->>iPad: { participantId, nickname, checkedInAt }
128156
```
129157

130158
---
131159

132-
## 🛠️ Tech Stack
133-
134-
### Backend
135-
136-
| Technology | Purpose |
137-
| ------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
138-
| ![Hono](https://img.shields.io/badge/Hono-4-E36002?logo=hono&logoColor=white) | Ultrafast web framework for the edge |
139-
| ![Cloudflare Workers](https://img.shields.io/badge/Cloudflare_Workers-F38020?logo=cloudflare&logoColor=white) | Edge runtime |
140-
| ![D1](<https://img.shields.io/badge/Cloudflare_D1_(SQLite)-F38020?logo=cloudflare&logoColor=white>) | Workers-native database |
141-
| ![Drizzle](https://img.shields.io/badge/Drizzle_ORM-0.45-C5F74F?logo=drizzle&logoColor=black) | TypeScript-first ORM |
142-
| ![Better Auth](https://img.shields.io/badge/Better_Auth-1.6-000?logoColor=white) | Framework-agnostic authentication |
143-
144-
### Frontend
145-
146-
| Technology | Purpose |
147-
| ---------------------------------------------------------------------------------------------------- | ---------------------------- |
148-
| ![Next.js](https://img.shields.io/badge/Next.js-16-000?logo=next.js) | React framework (App Router) |
149-
| ![React](https://img.shields.io/badge/React-19-61DAFB?logo=react&logoColor=black) | UI library |
150-
| ![shadcn/ui](https://img.shields.io/badge/shadcn%2Fui-000?logo=shadcnui&logoColor=white) | Component library |
151-
| ![Tailwind CSS](https://img.shields.io/badge/Tailwind_CSS-4-06B6D4?logo=tailwindcss&logoColor=white) | Utility-first CSS |
152-
| ![Vercel](https://img.shields.io/badge/Vercel-000?logo=vercel&logoColor=white) | Hosting & deployment |
153-
154-
### Tooling
155-
156-
| Technology | Purpose |
157-
| -------------------------------------------------------------------------------------------- | ------------------------ |
158-
| ![pnpm](https://img.shields.io/badge/pnpm-10-F69220?logo=pnpm&logoColor=white) | Monorepo package manager |
159-
| ![Turborepo](https://img.shields.io/badge/Turborepo-2-0F0F0F?logo=turborepo&logoColor=white) | Build orchestration |
160-
| ![Biome](https://img.shields.io/badge/Biome-2.4-60A5FA?logo=biome&logoColor=white) | Lint & format |
161-
162-
---
163-
164160
## 📁 Repository Structure
165161

166162
```
@@ -192,7 +188,8 @@ tecnova-platform/
192188
│ └── ui/ # 共通 UI (api-client / MeProvider / JST utils)
193189
├── docs/
194190
│ ├── requirements.md # 全体要件定義書
195-
│ ├── mvp.md # MVP 実装ガイド
191+
│ ├── mvp.md # MVP 実装仕様リファレンス
192+
│ ├── architecture.md # 全体システム構成図・拡張ロードマップ
196193
│ └── handoff.md # セッション引き継ぎノート
197194
├── biome.json
198195
├── turbo.json
@@ -207,7 +204,8 @@ tecnova-platform/
207204
| ドキュメント | 内容 |
208205
| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
209206
| 📘 [`docs/requirements.md`](./docs/requirements.md) | プロジェクトの背景・目的、ステークホルダー、データモデル、API 設計方針、非機能要件、リスク管理、設計判断の根拠を網羅した全体要件定義書 |
210-
| 📗 [`docs/mvp.md`](./docs/mvp.md) | 最初の 2 週間で何をどう実装するかに集中した実装ガイド。Drizzle スキーマ、API 仕様、画面仕様、Google Sheets API 連携の詳細実装、セットアップ手順、トラブルシュートを含む |
207+
| 📗 [`docs/mvp.md`](./docs/mvp.md) | MVP（Phase 1）の実装仕様リファレンス。Drizzle スキーマ、API 仕様、画面仕様、Google Sheets API 連携の詳細実装、セットアップ手順、トラブルシュートを含む |
208+
| 📐 [`docs/architecture.md`](./docs/architecture.md) | 全体システム構成図と拡張ロードマップ。現行コンポーネントの責務分担と Phase 1.5 以降の拡張計画を俯瞰する |
211209
| 📙 [`docs/handoff.md`](./docs/handoff.md) | 開発引き継ぎノート。進捗ステータス・既知の罠と回避策・残タスクをまとめた実装者向けドキュメント |
212210

213211
---
@@ -310,37 +308,6 @@ graph LR
310308
311309
---
312310

313-
## 🗺️ Roadmap
314-
315-
- [x] 設計・要件定義
316-
- [x] **Phase 1: MVP チェックインシステム**
317-
- [x] モノレポ・CI/CD 基盤構築
318-
- [x] Drizzle スキーマ + D1 マイグレーション
319-
- [x] Google Sheets API 連携
320-
- [x] Better Auth（Google OAuth）認証基盤
321-
- [x] チェックイン iPad PWA アプリ
322-
- [x] 「初めての方」フロー + 自動採番
323-
- [x] QR スキャン + 手入力 + 名前検索
324-
- [x] 受付履歴 + 一括チェックアウト
325-
- [x] 管理ダッシュボード + 参加者一覧 + メンター管理
326-
- [x] 事前登録管理（admin）
327-
- [x] GAS Drive webhook 連携
328-
- [x] shadcn/ui テーマ統一
329-
- [x] 本番デプロイ（Workers + Vercel）
330-
- [ ] フロントエンド UX の最終調整
331-
- [ ] 本番運用手順の確定（リハーサル / Wi-Fi 断フォールバック）
332-
- [ ] 昨年度データの D1 反映
333-
- [ ] **Phase 1.5: メンター業務支援**
334-
- [ ] メンタースマホアプリ（`apps/mentor`）
335-
- [ ] 活動ログ記入機能
336-
- [ ] CSV エクスポート
337-
- [ ] **Phase 2: 中長期改善**
338-
- [ ] 振り返りシート OCR
339-
- [ ] 公開 API
340-
- [ ] 分析ダッシュボード
341-
342-
---
343-
344311
## 🤝 Contributing
345312

346313
このプロジェクトはテクノバながさき固有の運用要件に基づいて設計されていますが、類似の教育・ファブリケーション活動の運営基盤として参考にしていただけます。

‎docs/architecture.md‎

Lines changed: 9 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,14 @@
11
# Tecnova Platform Architecture
22

3-
This document captures the current Tecnova Nagasaki operations platform and its
4-
planned expansion scope.
5-
6-
The first diagram is a compact current-state overview. The detailed map below it
7-
keeps the broader current and planned scope in one Mermaid `architecture-beta`
8-
diagram. Mermaid brand logos require renderer-level icon-pack registration, so
9-
the portable diagrams use text labels and the brand logos are shown as badges.
3+
This document maps the current Tecnova Nagasaki operations platform and its
4+
planned expansion scope. The first diagram is a compact current-state overview;
5+
the detailed map below it keeps the full current and planned scope in one Mermaid
6+
`architecture-beta` diagram. Brand logos are shown as badges because Mermaid
7+
icon packs require renderer-level registration.
8+
9+
See also: [`requirements.md`](./requirements.md) for design rationale,
10+
[`mvp.md`](./mvp.md) for implementation specs, and [`handoff.md`](./handoff.md)
11+
for current progress.
1012

1113
## Current Implementation Overview
1214

0 commit comments

Comments
 (0)