#63 Spec: doctype-backed Cash Flow Category mapping (generate cash_flow_categories.csv from konsol)

[Anonymous]

Originally created by: pyy3

Context

Phase 6.1 (Cash Flow Statement, indirect method) shipped seeds/cash_flow_categories.csv as a static, hand-edited seed — the same class as allocation_rules.csv / ic_elimination_rules.csv. It maps each balance-sheet GL account → cash-flow category + sign:

Column	Type	Meaning
main_account	String	GL account (matches gold_bs_movement.main_account)
cf_category	String	Operating / Investing / Financing
cf_line_item	String	Sub-line label (e.g. Change in Trade Receivables)
is_cash	UInt8	1 = the cash/cash-equivalent account (excluded from activity, defines reconciliation target)
sign	Int8	+1 credit-natured (liabilities/equity/contra-assets), -1 debit-natured (assets/contra-equity)

Consumed by gold_cash_flow_indirect and gold_consolidated_cash_flow.

Confirmed current state: there is no Main Account / Cash Flow Mapping doctype in konsol, and dbt_config.py does not generate this seed — it only regenerates dimension_mappings.csv (from published Dimension Mapping docs), the dbt_project.yml vars, and gold-model domains. So the seed is editable only by committing a CSV, not from the Frappe desk.

Problem

Onboarding a new GL account to the cash flow statement currently means a code change + PR. Every other account-level governance object (dimensions, account categories, scenarios, allocation rules) is — or is moving toward — desk-editable. Cash-flow mapping is the odd one out. The build will hard-fail (the relationships test on gold_bs_movement.main_account → cash_flow_categories) if any BS account is left uncategorized, so a finance user needs a non-developer path to add the mapping.

Proposed solution

Mirror the existing dimension_mapping → regenerate_dimension_mappings_seed() pattern:

1. New doctype Cash Flow Category (module epm) with fields main_account, cf_category (Select: Operating/Investing/Financing), cf_line_item, is_cash (Check), sign (Select/Int -1/+1). Optionally a status (Draft/Published) like Dimension Mapping.
2. regenerate_cash_flow_categories_seed() in konsol/dbt_config.py writing seeds/cash_flow_categories.csv from published docs.
3. Publish/unpublish hooks on the doctype (on_update) calling the regenerator + requesting a governed rebuild — copy epm/doctype/dimension_mapping/dimension_mapping.py.
4. install.py hook to repopulate the seed after migrate (mirror _regenerate_dimension_mappings_seed()), seeded with the current 12-row demo default so behaviour is unchanged on a fresh deploy.
5. Reconcile the data-dictionary note in docs/data-dictionary/seeds-reference.md (move cash_flow_categories.csv from "static" to "generated").

Out of scope

• The dbt models/tests themselves (already shipped in Phase 6.1).
• Cube.js / =EPM() exposure of the cash flow lines.
• Direct-method cash flow.

Acceptance criteria

• [ ] Cash Flow Category doctype exists; CRUD from desk regenerates seeds/cash_flow_categories.csv identically to the hand-authored file.
• [ ] Publishing a mapping triggers a governed rebuild (no full ClickHouse rebuild — respects the build-governance guard).
• [ ] Fresh bench migrate repopulates the seed with the 12-row demo default; existing Phase 6.1 dbt tests still pass unchanged.
• [ ] relationships test still catches an uncategorized BS account.

Related: Phase 6.1 PRD docs/prd/PRD-CASH-FLOW-STATEMENT.md; pattern reference epm/doctype/dimension_mapping/.

[Anonymous]

Originally posted by: grynn-in

Resolved. The doctype-backed mapping is in place on main:

• Cash Flow Category doctype exists (konsol/epm/doctype/cash_flow_category/) with a fixture + test.
• regenerate_cash_flow_categories_seed() (konsol/dbt_config.py:99) rewrites seeds/cash_flow_categories.csv from Published Cash Flow Category docs, and is called from the doctype's publish() / unpublish() / validate (cash_flow_category.py:47/56/70) → governed rebuild.
• The real-chart remap (12→256 accounts) landed via [#122], generated from these docs.

Cash-flow mapping is now desk-editable like the other governance objects — no code change/PR needed to onboard an account. Closing.

[Anonymous]

Ticket changed by: grynn-in

• status: open --> closed