File size: 8,754 Bytes
cfa8541
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
a831e2a
 
c920df3
cfa8541
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
c920df3
cfa8541
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
c920df3
cfa8541
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
c920df3
cfa8541
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
c920df3
cfa8541
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
c920df3
cfa8541
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
81a8217
cfa8541
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
c920df3
 
 
81a8217
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
"""Static Finance application catalogue.

The six entries below are navigation/application contracts, not data stores.  Every fact key
resolves through :mod:`modules.finance_spine`, which keeps one governed definition of scope,
freshness, lineage, drill-through, and reconciliation for every consumer.
"""
from copy import deepcopy

from modules import financial, health, inventory, management, o2c, procurement


FINANCE_GROUP = {
    "key": "finance",
    "label": "Finance",
    "description": "Receivables, spend, cash, margin, inventory, and planning.",
    "routePrefix": "/finance",
}


# Workflow ownership lives here, at the application layer.  Source modules describe only the
# governed-data requirement and its read-only validation seam; they do not create queue state.
_OWNED_WORK = {
    "open_purchase_orders": ("Buyer", "Chase the late purchase order"),
    "lead_time_coverage": ("Buyer", "Confirm the replenishment lead time"),
    "replenishment": ("Buyer", "Create the replenishment plan"),
    "inventory_value": ("Inventory manager", "Reconcile the inventory valuation"),
    "excess_stock": ("Inventory manager", "Disposition the excess stock"),
    "dead_stock": ("Inventory manager", "Choose the dead-stock disposition"),
}


def _owned_work_signals():
    """Compose non-executable owned-work requirements without manufacturing queue records."""
    signals = procurement.finance_workflow_contract() + inventory.finance_workflow_contract()
    for signal in signals:
        signal["state"] = signal.pop("availability")
        signal["ownerRole"], signal["nextAction"] = _OWNED_WORK[signal["key"]]
        signal["status"] = "unavailable"
    return signals


FINANCE_APPLICATIONS = (
    {
        "key": "ar-collections",
        "label": "Collection",
        "navLabel": "Collection",
        "description": "Prioritize customer balances that need collection action.",
        "mode": "workflow",
        "permissionKey": "ar",
        "composes": ["ar", "collections"],
        "factKeys": ["ar_outstanding"],
        "kpiKeys": ["ar_outstanding"],
        "worklist": {
            "title": "Priority queue",
            "cadence": "Daily, 15 min",
            "sourceFact": "ar_outstanding",
            "pageSize": 500,
            "maxRows": 10000,
            "displayLimit": 50,
            "entityField": "partner",
            "documentField": "move",
            "amountField": "ar_outstanding",
            "overdueAmountField": "ar_overdue",
            "dueDateField": "due_date",
            "ownerField": "collection_owner",
            "statusField": "payment_state",
            "promiseDateField": "promise_date",
            "promiseAmountField": "promise_amount",
            "nextAction": "Preview outreach",
            "previewOnly": True,
        },
        "question": "Which customer balances need an owner and a next action?",
        "deepLink": "/finance/ar-collections",
    },
    {
        "key": "ap-spend",
        "label": "AP & Spend",
        "navLabel": "AP & Spend",
        "description": "Review supplier obligations before payment.",
        "mode": "workflow",
        "permissionKey": "spend",
        "composes": ["spend", "vendor_bills"],
        "factKeys": ["ap_outstanding"],
        "kpiKeys": ["ap_outstanding"],
        "worklist": {
            "title": "Payment queue",
            "cadence": "Daily, 15 min",
            "sourceFact": "ap_outstanding",
            "pageSize": 500,
            "maxRows": 10000,
            "displayLimit": 50,
            "entityField": "vendor",
            "documentField": "move",
            "amountField": "ap_outstanding",
            "dueDateField": "due_date",
            "ownerField": "ap_owner",
            "statusField": "payment_state",
            "nextAction": "Review payable",
            "previewOnly": False,
            "concentration": True,
        },
        "question": "Which supplier obligations need review or payment action?",
        "deepLink": "/finance/ap-spend",
    },
    {
        "key": "cash-o2c",
        "label": "Cash & O2C",
        "navLabel": "Cash & O2C",
        "description": "Track how invoiced demand converts into cash.",
        "mode": "dashboard",
        "permissionKey": "o2c",
        "composes": ["o2c", "ar"],
        "factKeys": ["invoiced_sales", "ar_outstanding"],
        "kpiKeys": ["invoiced_sales", "ar_outstanding"],
        "dashboard": {
            "basisNotice": "Mirror facts use the selected window. Cycle measures name their own LTM or point-in-time basis.",
            "sections": [
                o2c.dashboard_contract(),
                financial.cash_cycle_dashboard_contract(),
            ],
        },
        "question": "How is invoiced demand converting into collectible cash?",
        "deepLink": "/finance/cash-o2c",
    },
    {
        "key": "pnl-gross-margin",
        "label": "Management P&L & Gross Margin",
        "navLabel": "P&L & Margin",
        "description": "Understand what drives operating performance.",
        "mode": "dashboard",
        "permissionKey": "financial",
        "composes": ["financial", "sales"],
        "factKeys": ["revenue", "opex", "commission_accrued"],
        "kpiKeys": ["revenue", "opex", "commission_accrued"],
        "dashboard": {
            "basisNotice": "Order, posted-GL, and commission actuals retain separate source bases and are never silently summed.",
            "sections": [
                management.comparison_dashboard_contract(),
                financial.margin_dashboard_contract(),
            ],
        },
        "question": "Where are revenue, operating expense, and selling cost moving?",
        "deepLink": "/finance/pnl-gross-margin",
    },
    {
        "key": "procurement-inventory",
        "label": "Procurement & Inventory",
        "navLabel": "Procurement & Inventory",
        "description": "Prioritize buying and warehouse work from stock movements.",
        "mode": "workflow",
        "permissionKey": "procurement",
        "composes": ["procurement", "inventory"],
        "factKeys": ["stock_in", "stock_out", "stock_net"],
        "kpiKeys": [],
        "worklist": {
            "kind": "unavailable_requirements",
            "title": "Owned work requirements",
            "cadence": "Daily, 15 min",
            "basisNotice": ("Inventory and demand use one physical all-channel warehouse basis. "
                            "Open purchase orders stay company-wide."),
            "signals": _owned_work_signals(),
        },
        "question": "Which physical stock movements require a buying or warehouse action?",
        "deepLink": "/finance/procurement-inventory",
    },
    {
        "key": "planning-data-health",
        "label": "Planning & Data Health",
        "navLabel": "Planning & Data Health",
        "description": "Assess whether planning inputs are ready to use.",
        "mode": "dashboard",
        "permissionKey": "health",
        "composes": ["planning", "health"],
        "factKeys": ["revenue", "invoiced_sales", "commission_accrued"],
        "kpiKeys": ["revenue", "invoiced_sales", "commission_accrued"],
        "dashboard": {
            "basisNotice": ("Actuals come only from governed Finance facts. Planning and close "
                            "exceptions remain named gaps until their canonical mirror facts exist."),
            "sections": [
                health.planning_dashboard_contract(),
                *health.data_health_dashboard_contracts(),
            ],
        },
        "question": "Are planning inputs fresh, traceable, and reconciled?",
        "deepLink": "/finance/planning-data-health",
    },
)


def finance_group():
    """Return a caller-owned copy of the one Finance navigation group."""
    return deepcopy(FINANCE_GROUP)


# Finance descriptors retain permission keys and fact composition after App retirement.
def finance_applications(may_open=None):
    """Return immutable descriptors, optionally filtered through the request permission wall."""
    rows = FINANCE_APPLICATIONS
    if may_open is not None:
        rows = tuple(app for app in rows if may_open(app["permissionKey"]))
    return deepcopy(list(rows))


def finance_application(key, may_open=None):
    """Resolve a direct-link descriptor without introducing a Finance-home aggregate."""
    for app in FINANCE_APPLICATIONS:
        if app["key"] == key:
            if may_open is not None and not may_open(app["permissionKey"]):
                raise PermissionError(f"access to {key} is not granted")
            return deepcopy(app)
    raise KeyError(key)


def finance_templates(may_open=None):
    """Keep the retired Finance template provider empty for legacy callers."""
    return []