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の画面で細かい指定をする必要はありません。
手順
- https://vercel.com にGitHubアカウントでログインする
- 「Add New...」→「Project」を押す
terra-kennsyuu-app を選んで「Import」を押す- 設定画面はそのままでよい（Framework Preset が「Other」になっていることだけ確認）
- 「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側で用意するもの
- 商品と価格（年額 9,800円 / JPY / 税込）
- 決済リンク（Payment Link）。完了後の遷移先を
https://<アプリのURL>/?checkout=success&session_id={CHECKOUT_SESSION_ID}
にしておくと、決済が終わったら自動でアプリに戻って有効化されます
- カスタマーポータル（設定 → 請求 → カスタマーポータル）を一度保存する。
「支払い・プラン管理」ボタンと、特商法表記に書いた解約手続きがこれに当たります
有効化のしくみ
- 決済完了 → 自動でアプリに戻り、その端末で使えるようになる
- 機種変更・再インストール → メニューの入力欄にライセンスコードか購入時のメールアドレスを入れる
- アプリが保存するのは署名付きのライセンスコードだけ。カード情報は一切扱いません
配色を変えたいときは 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. 将来の予定
音声入力のオフライン化（限定語彙のキーワードスポッティングモデルの内製）は
初版では着手しません。まずタップ入力中心で運用し、音声へのニーズの強さを見てから判断します。
利用者の明示的な同意に基づく音声データ収集の同意スイッチだけ、メニューに用意してあります。
