LOG-RA（terra-kennsyuu-app）

山林・製材工場での丸太検収に特化した、オフラインファーストのPWAです。 炎天下・重機騒音下・手袋着用の現場で、説明を読まずに使えることを最優先に設計しています。

---

1. すぐに動かす（開発者向け）

npm run dev     # http://localhost:5173 が立ち上がります
npm test        # JAS材積計算エンジンのテスト（12件）
npm run icons   # アイコンPNGを作り直すとき

ビルド作業は 一切不要 です。素のHTML/CSS/JavaScript（ESモジュール）だけで動くので、 npm install もいりません（開発サーバーとアイコン生成もNode標準機能のみで書いてあります）。 現場での起動速度を最優先した結果、この構成になっています。

2. 公開（Vercel）

このリポジトリはビルド不要の静的サイトです。vercel.json に設定を書いてあるので、 Vercelの画面で細かい指定をする必要はありません。

手順

1. https://vercel.com にGitHubアカウントでログインする
2. 「Add New...」→「Project」を押す
3. terra-kennsyuu-app を選んで「Import」を押す
4. 設定画面はそのままでよい（Framework Preset が「Other」になっていることだけ確認）
5. 「Deploy」を押す。1分ほどで https://terra-kennsyuu-app.vercel.app のようなURLが発行される

以後、GitHubにpushするたびに自動で再公開されます。

スマホへのインストール

発行されたURLをスマホのブラウザで開き、 Chrome: メニュー →「ホーム画面に追加」／Safari: 共有 →「ホーム画面に追加」 を押せば完了です。アプリストアの審査は不要で、URLを送るだけで配布できます。

アプリを更新したとき

sw.js の VERSION を上げてからpushしてください。上げ忘れると、 利用者の端末に古い画面がキャッシュされたまま残ります。

注意（オフライン動作を壊さないために）

Vercelの cleanUrls は有効にしないでください。/index.html が別URLへリダイレクトされ、 リダイレクト経由の応答はキャッシュから配信できないため、圏外でアプリが真っ白になります。 実際に再現して確認済みです。現在は vercel.json で無効にしたうえ、 Service Worker側でもリダイレクトされた応答を作り直して二重に防いでいます。

3. 公開前に設定するもの

src/js/config.js の1ファイルだけを書き換えてください。

項目	説明
stripe.checkoutUrl	Stripeの決済リンク（Payment Link）のURL。いまはテスト用（test_ を含む）なので、本番公開前に本番のリンクへ差し替える
stripe.priceLabel	アプリ内に表示する価格。特商法表記と必ず一致させる
googleDrive.clientId	Google CloudのOAuthクライアントID（未設定ならバックアップ機能は自動で無効表示）
cacheVersion / sw.js の VERSION	アプリを更新したら必ず上げる（古いキャッシュが残らないように）

googleDrive.clientId は未設定のままでもアプリは動きます（「未設定」と表示されます）。

Vercelの環境変数（サブスク確認に必須）

Vercelのプロジェクト設定 → Settings → Environment Variables に、次の2つを登録します。

名前	値
STRIPE_SECRET_KEY	Stripeダッシュボードのシークレットキー（sk_test_... / 本番は sk_live_...）。絶対にGitにコミットしない
LICENSE_SECRET	ライセンスコードの署名に使う自前のランダム文字列（32文字以上を推奨）。一度決めたら変更しない（変更すると既存のコードが全部無効になる）
ALLOW_EMAIL_ACTIVATION	任意。false にすると、メールアドレスでの復旧を止められる

未登録のままだと、購入しても有効化できません（試用期間中はアプリ自体は動きます）。

Stripe側で用意するもの

1. 商品と価格（年額 9,800円 / JPY / 税込）
2. 決済リンク（Payment Link）。完了後の遷移先を https://<アプリのURL>/?checkout=success&session_id={CHECKOUT_SESSION_ID} にしておくと、決済が終わったら自動でアプリに戻って有効化されます
3. カスタマーポータル（設定 → 請求 → カスタマーポータル）を一度保存する。 「支払い・プラン管理」ボタンと、特商法表記に書いた解約手続きがこれに当たります

有効化のしくみ

• 決済完了 → 自動でアプリに戻り、その端末で使えるようになる
• 機種変更・再インストール → メニューの入力欄にライセンスコードか購入時のメールアドレスを入れる
• アプリが保存するのは署名付きのライセンスコードだけ。カード情報は一切扱いません

配色を変えたいときは src/css/tokens.css の :root だけを書き換えれば全画面に反映されます。 文言を変えたいときは src/js/locales/<言語>.js を書き換えます。

4. JAS材積計算について（最重要）

素材の日本農林規格（末口二乗法）どおりに計算します。

L < 6m : V = D² × L ÷ 10000                （補正なし。径級によりません）
L ≥ 6m : V = (D + (L′− 4)/2)² × L ÷ 10000  （長さ補正）
         L′ = 長さ(m)の整数部（1mに満たない端数を切り捨て）
         (L′− 4)/2 が負になる場合は 0 とする

• 計算は src/js/jas.js に集約。浮動小数点(Number)を一切使わず BigInt（整数） だけで行うため、 何万本積み上げても1mm³の誤差も出ません
• 径級の刻みはJAS準拠で 14cm未満＝1cm刻み／14cm以上＝2cm刻み
• 端数処理は小数第4位の四捨五入です（src/js/jas.js の ROUNDING_MODE 1か所で切り替え可能）。 JASは材積の端数処理を定めていないため、工場が引く丸太材積表と同じ四捨五入に合わせています

正確性の担保

tests/table.test.js が、長野県「林業積算基準 丸太材積表」の全1578セル （長さ3.2〜12.8m × 直径4〜56cm）と計算結果を毎回突き合わせます。不一致は0件です。 テストは丸め前の厳密値を四捨五入して比較するため、アプリ側の端数処理方針を変えても 「計算式そのものの正しさ」を検証し続けます。

tests/jas.test.js には、かつて誤って径級補正 (D-12)/2 を加えていた式に 戻っていないことを確認する回帰テストも入っています。

コードを変更したら、必ず npm test が通ることを確認してから他の変更を進めてください。

5. ファイル構成

index.html              画面の骨組み（全画面ぶん）
manifest.webmanifest    ホーム画面に追加したときの見た目
sw.js                   Service Worker（オフライン動作）
src/css/tokens.css      配色・寸法（ここだけで全体の色を変えられる）
src/css/app.css         レイアウト
src/js/jas.js           JAS材積計算エンジン（最重要）
src/js/app.js           画面制御
src/js/db.js            IndexedDB（入力の都度、即保存）
src/js/i18n.js          多言語（日本語・ベトナム語・タガログ語・タイ語・マレー語）
src/js/csv.js           CSV生成・Web Share API共有
src/js/voice.js         音声入力（Web Speech API・オンライン時のみ）
src/js/feedback.js      発光／振動／操作音／画面消灯防止
src/js/subscription.js  年額サブスク判定（Stripe。圏外のときは猶予期間で判断）
src/js/backup.js        Googleドライブ自動バックアップ
tests/jas.test.js       材積計算のテスト
tests/table.test.js     公的な丸太材積表との全セル照合
tests/csv.test.js       集計・CSV出力のテスト
tests/license.test.js   ライセンスコードの署名検証・Stripe応答の読み取り
api/_lib.js             Stripe呼び出しとライセンスコードの署名（共通処理）
api/activate.js         有効化（決済完了の戻り／コード／メールアドレス）
api/verify.js           有効期限の再確認
api/portal.js           Stripeカスタマーポータルを開くURLの発行

6. オフライン時の動き

現場での操作は一切ブロックしません。

• 入力した瞬間に端末内（IndexedDB）へ確定保存。通信の有無に関係なく必ず成功します
• 出力した伝票も全件ローカルに保存し、メニューの「伝票履歴」からいつでも再出力できます
• 通信が戻った時に、裏でGoogleドライブへ自動同期します（☁️＝同期待ち／✅＝同期済み）
• 未同期のデータは件数に関わらず保持し続けます。72時間以上圏外でも消えません
• サブスク確認はオンライン時のみ。最後に確認できてから30日間は圏外のままでも使えます
• 音声入力だけは通信が必要です。 圏外ではボタンが自動的に無効になり、 「壊れた」と誤解されないようタップ入力を促すメッセージが出ます

7. 将来の予定

音声入力のオフライン化（限定語彙のキーワードスポッティングモデルの内製）は 初版では着手しません。まずタップ入力中心で運用し、音声へのニーズの強さを見てから判断します。 利用者の明示的な同意に基づく音声データ収集の同意スイッチだけ、メニューに用意してあります。