Bilingual README / 雙語說明： English · 中文

Rails app for budgeting and actual expenditure tracking. The UI uses Phlex views, RubyUI (Tailwind / shadcn-style) components, Propshaft for assets, and Importmap for JavaScript.

以 Rails 打造的預算與實際支出追蹤應用；介面使用 Phlex 視圖、RubyUI（Tailwind / shadcn 風格）元件、Propshaft 管理靜態資源，並以 Importmap 載入 JavaScript。

• Ruby 3.4.x (see .ruby-version; project uses ruby-3.4.8)
• Bundler
• Node is optional for this repo; Tailwind is built via the tailwindcss-rails gem (no npm run required for CSS)
• SQLite for local development (databases under storage/)
• The PostgreSQL gem is included for deployments that set DATABASE_URL; adjust config/database.yml if you use Postgres locally

bin/setup

This installs gems, runs bin/rails tailwindcss:build, prepares the database, then starts bin/dev (Rails + Tailwind watch).

Manual equivalent:

bundle install
bin/rails tailwindcss:build
bin/rails db:prepare
bin/devdev

Open http://localhost:3000.

1. bin/rails tailwindcss:build — generates app/assets/builds/tailwind.css. Without it, pages load but have almost no styling.
2. Prefer bin/dev over bin/rails server alone so tailwindcss:watch recompiles CSS when you edit app/assets/tailwind/application.css.

The layout uses stylesheet_link_tag :app, which links every app/assets/**/*.css that exists (including the Tailwind build under app/assets/builds/). That avoids Propshaft::MissingAssetError if tailwind.css has not been built yet (you only miss styles until you run tailwindcss:build).

Do not rely on stylesheet_link_tag "tailwind" unless you are sure app/assets/builds/tailwind.css exists in every environment (CI, Docker, new clones).

Theme tokens (colors, radius, sidebar variables) live in app/assets/tailwind/application.css.

• Shell: app/views/layouts/application.html.erb wraps content in RubyUI::Layout (app/components/ruby_ui/layout.rb): desktop sidebar, mobile sheet menu, flash, centered main column (same pattern as a typical RubyUI / hpees-style app).
• Pages: Phlex classes under app/views/ (e.g. Views::Dashboard::Index). Zeitwerk maps folder names like revenue_budgets/ to Views::RevenueBudget::Index (not RevenueBudgets) — see Rails inflection in config/application.rb.

Domain models live under app/models/ (e.g. actual expenditures, revenue/expenditure budgets). Wire them into the dashboard and section pages as you build features.

• Dockerfile builds the app; rails assets:precompile runs in the image and tailwindcss:build is hooked to assets:precompile by tailwindcss-rails.
• Kamal config: config/deploy.yml.

Run bin/rails tailwindcss:build or use bin/dev. Ensure you are not adding a bare stylesheet_link_tag "tailwind" without guaranteeing the file exists.

1. Confirm app/assets/builds/tailwind.css exists and is non-empty.
2. Restart the server after changing asset paths or initializers.
3. Clear browser cache if asset digests changed.

bin/spring stop

If the repo includes AGENTS.md, follow that for Git/PR workflow and tooling conventions.

See repository root for a LICENSE file if one is added; otherwise treat usage as defined by the project owner.

以下為繁體中文說明，與上方 English 章節對應。

• Ruby 3.4.x（見 .ruby-version；本專案使用 ruby-3.4.8）
• Bundler
• Node：此專案非必須；Tailwind 由 tailwindcss-rails 編譯（CSS 不必執行 npm run）
• 本機開發預設 SQLite（資料庫檔於 storage/）
• Gemfile 含 PostgreSQL 驅動，若部署使用 DATABASE_URL 可接 Postgres；本機若用 Postgres 請調整 config/database.yml

bin/setup

會安裝套件、執行 bin/rails tailwindcss:build、準備資料庫，並啟動 bin/dev（Rails + Tailwind 監聽）。

手動步驟：

bundle install
bin/rails tailwindcss:build
bin/rails db:prepare
bin/devdev

瀏覽 http://localhost:3000。

1. 執行 bin/rails tailwindcss:build，產生 app/assets/builds/tailwind.css。若略過此步驟，頁面可開啟但幾乎沒有樣式。
2. 開發時建議用 bin/dev，不要只跑 bin/rails server，否則修改 app/assets/tailwind/application.css 時不會自動重編譯 CSS（需有 tailwindcss:watch）。

版面使用 stylesheet_link_tag :app，會連結所有存在的 app/assets/**/*.css（含 app/assets/builds/ 下的 Tailwind 產出）。若尚未建置 tailwind.css，不會因此拋出 Propshaft::MissingAssetError（只是暫時沒有樣式，執行 tailwindcss:build 即可）。

請勿單獨使用 stylesheet_link_tag "tailwind"，除非你能保證每個環境（CI、Docker、新 clone）都有 app/assets/builds/tailwind.css。

主題色票、圓角、側欄等 CSS 變數定義在 app/assets/tailwind/application.css。

• 外殼： app/views/layouts/application.html.erb 以 RubyUI::Layout（app/components/ruby_ui/layout.rb）包住內容：桌面側欄、行動版抽屜選單、flash、置中主內容欄（與常見 RubyUI／hpees 風格相同）。
• 頁面： app/views/ 下的 Phlex 類別（例如 Views::Dashboard::Index）。Zeitwerk 會將 revenue_budgets/ 等資料夾對應到 Views::RevenueBudget::Index（不是 RevenueBudgets）— 見 config/application.rb 中的複數／單數設定。

網域模型在 app/models/（例如實際支出、收入／支出預算）。實作功能時再將其接到儀表板與各區塊頁面。

• Dockerfile 建置映像時會跑 rails assets:precompile；tailwindcss-rails 會在 assets:precompile 階段觸發 tailwindcss:build。
• Kamal 設定：config/deploy.yml。

執行 bin/rails tailwindcss:build 或改用 bin/dev。請勿在未保證檔案存在時單獨使用 stylesheet_link_tag "tailwind"。

1. 確認 app/assets/builds/tailwind.css 存在且非空檔。
2. 修改資源路徑或 initializer 後請重啟伺服器。
3. 若資源指紋變更，可清除瀏覽器快取。

bin/spring stop

若儲存庫含 AGENTS.md，請依其中說明進行 Git／PR 流程與工具約定。

若專案根目錄有 LICENSE 檔請依該檔；若無，則以專案擁有者定義之使用方式為準。