Settings & Permissions

Permission Levels

Butler Tax features are gated by feature_key → min_role mappings that administrators can override. The defaults are:

Feature key	Min role (default)	What it gates
client_management	staff	Edit client master
journal_rule_settings	accounting	Edit journal entry rules
matching_rule_settings	accounting	Edit reconciliation rules
report_view	approver	View reports
budget_comparison_view	approver	View budget vs. actual
ai_chat_basic	staff	Use Butler Chat
ai_chat_accounting	accounting	Use Butler Chat for accounting ops

Administrators can change any of these at Master → Permissions.

Some features are hard-coded to specific roles via router meta:

• Outflow / inflow reconciliation, banking import, journal rule editing, client editing, etc. → accounting+
• User management, organization settings, approval rule editing, permission settings → admin only

Service Switcher (Butler Tax ↔ Butler Law)

If your company subscribes to both Butler Tax and Butler Law, a service switcher appears in the top-left corner of the sidebar. The Law button is shown only when Butler Law credits are detected (butler_law plan in the subscription record).

Clicking it navigates to Butler Law with your existing session, since both apps share the butler_session cookie under .saikoku-studio.com.

Tax Firm Impersonation

Tax firm users can directly access client company pages:

1. Open the tax firm dashboard at /dashboard/tax-firm
2. Find the client company card and click View as Client
3. You're routed to /dashboard/corporate with an amber banner showing "Operating on behalf of {Client Name}"
4. Your effective role is accounting for the duration of the session
5. Click Return to Tax Firm Dashboard in the banner to exit

While impersonating:

• All requests carry an ?as_corporate={client_uid} query parameter
• Audit log entries record both the tax firm UID (proxy_actor_uid) and the client corporate as the data scope
• Admin-only endpoints (user management, approval rule editing, etc.) are blocked because the role is fixed to accounting

Approval Rules

See Approval Workflow.

Matching Rules

Matching rules drive how Butler scores reconciliation candidates:

• Name normalisation — replace common prefixes / suffixes in bank descriptions (カ） → 株式会社)
• Amount tolerance — default fuzziness for amount matching; per-client override via clients.amount_tolerance
• Date scoring — bonus for matches close to the expected payment date

Journal Rules

Journal rules decide how reconciled documents are mapped to debits and credits. A rule has:

• Match conditions — e.g. category = consumables, payment method = corporate_card
• Debit / credit accounts — the journal entry to apply
• Tax classification — taxable / non-taxable / reduced rate

Tax firms can also set base rules at the tax-firm level that are inherited by all client companies as defaults.

Payroll (給与)

財務管理 → 帳簿・決算 → 給与 imports payroll-software results (CSV primary, inline manual rows secondary) and generates a draft payroll journal from the monthly totals. Payroll data — including totals — is stored in a dedicated database, fully separated from the books; only the aggregate journal entry reaches the ledger.

Access is controlled by the dedicated payroll feature permission, default admin only. Admins can open it to other roles (e.g. accounting) via permission settings. Butler Tax does not calculate payroll (that is the payroll-software / Butler Labor domain).

Chart of Accounts (勘定科目)

Settings → 勘定科目 (role accounting+) shows the corporate's effective account set, layered as: platform standard → advising tax firm template → corporate customs. Each row is badged with its source.

• Corporates can add custom accounts (pick the classification when creating — it is immutable afterwards, as is the code) and deactivate or, when unused, delete their own customs.
• Tax firms manage a template (科目テンプレート in the tax-firm dashboard) that is distributed to every client corporate. Template accounts can only be deactivated, not deleted.
• Standard accounts are managed in Studio Admin and read-only here.

Custom account names participate in automatic journal generation: the account resolver matches document categories against the effective set, with corporate customs taking priority over template and standard names.

Alert Configuration

Configure thresholds at Master → Alert Settings (per company) or Tax Firm Dashboard → Alert Settings (per client):

• Overdue invoices (days past due_date)
• Stale rejections (rejected documents not re-submitted in N days)
• Approval delay (pending_approval not actioned in N days)
• Tax advisor escalation (questions left unanswered in N days)

Alerts are checked by a scheduled batch (APScheduler) that runs periodically and writes notifications.