GovOPlaN/govoplan-quick-access
2
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

feat(quick-access): expose effective preference provenance

Browse Source
This commit is contained in:
zemion
2026-08-20 02:39:41 +02:00
parent b5b629b357
commit 127b6ee5d0
8 changed files with 211 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/QUICK_ACCESS.md
+6
View File
@@ -25,6 +25,12 @@ override that decision, but may configure any still-available item. Stale
preferences are retained and diagnosed so uninstalling and reinstalling a
contributing module does not silently discard a user's arrangement.
The effective API reports each item's `availability_state`,
`availability_source`, and `order_source`. It also returns every unavailable
stored id as a `stale_preferences` entry with its system, tenant, or user
source. Administration and support tooling can therefore explain a result
without reading or copying any contributing module's state.
## Categories
The initial stable categories are Work, Calendar, Messages, and Files. Messages
src/govoplan_quick_access/backend/manifest.py
+4
View File
@@ -174,6 +174,8 @@ DOCUMENTATION = (
body=(
"The catalogue follows installed module registrations. System settings constrain tenants; "
"tenant settings constrain users. An item may remain available, be blocked, or be forced. "
"Effective entries identify the system, tenant, user, or module source of availability and ordering; "
"preferences for retired entries retain their scope provenance. "
"Views and permissions form additional ceilings and Quick Access never grants access to domain data. "
"A View may recommend tools or focus the rail to a subset, but only currently enabled, context-compatible, authorized "
"tools participate. The All available tools escape only restores that permission-derived set for the current session; "
@@ -191,6 +193,8 @@ DOCUMENTATION = (
"body": (
"Der Katalog folgt den Registrierungen installierter Module. Systemeinstellungen begrenzen Mandanten, "
"Mandanteneinstellungen begrenzen Benutzer. Ein Eintrag kann verfuegbar, gesperrt oder erzwungen sein. "
"Effektive Eintraege nennen System, Mandant, Benutzer oder Modul als Quelle fuer Verfuegbarkeit und Reihenfolge; "
"Einstellungen fuer entfernte Eintraege behalten ihren Ebenennachweis. "
"Ansichten und Berechtigungen bilden weitere Grenzen; Schnellzugriff erteilt selbst keinen Datenzugriff. "
"Eine Ansicht darf Werkzeuge empfehlen oder die Leiste auf eine Teilmenge fokussieren, jedoch nur innerhalb "
"der aktivierten, kontextgeeigneten und berechtigten Werkzeuge. Alle verfuegbaren Werkzeuge stellt nur diese "
src/govoplan_quick_access/backend/schemas.py
+13
View File
@@ -71,17 +71,30 @@ class EffectiveToolResponse(CatalogueToolResponse):
enabled: bool
forced: bool
locked_by: str | None = None
availability_state: Literal["available", "forced", "blocked"]
availability_source: Literal["module", "system", "tenant", "user"]
order_source: Literal["module", "system", "tenant", "user"]
class EffectiveCategoryResponse(CatalogueCategoryResponse):
enabled: bool
forced: bool
locked_by: str | None = None
availability_state: Literal["available", "forced", "blocked"]
availability_source: Literal["module", "system", "tenant", "user"]
order_source: Literal["module", "system", "tenant", "user"]
tools: list[EffectiveToolResponse]
class EffectiveStalePreferenceResponse(BaseModel):
id: str
kind: Literal["category", "tool"]
source: Literal["system", "tenant", "user"]
class EffectiveQuickAccessResponse(BaseModel):
categories: list[EffectiveCategoryResponse]
stale_preferences: list[EffectiveStalePreferenceResponse] = Field(default_factory=list)
diagnostics: list[str] = Field(default_factory=list)
src/govoplan_quick_access/backend/service.py
+50
View File
@@ -18,6 +18,7 @@ from govoplan_quick_access.backend.schemas import (
CatalogueToolResponse,
EffectiveCategoryResponse,
EffectiveQuickAccessResponse,
EffectiveStalePreferenceResponse,
EffectiveToolResponse,
PreferenceEntry,
ProfileResponse,
@@ -241,6 +242,7 @@ def resolve_effective(
("user", get_profile(session, scope_type="user", tenant_id=tenant_id, scope_id=account_id)),
)
diagnostics: list[str] = []
stale_preferences = _stale_preferences(profiles, catalogue)
category_states: dict[str, _EffectiveState] = {}
for category in catalogue.categories:
state = _EffectiveState(enabled=True, order=category.order)
@@ -259,6 +261,11 @@ def resolve_effective(
state.apply(entry, source=source)
category_state = category_states.get(tool.category_id)
enabled = state.enabled and bool(category_state and category_state.enabled)
availability_source = (
category_state.availability_source
if state.enabled and category_state and not category_state.enabled
else state.availability_source
)
tool_payload = tool.model_dump()
tool_payload["order"] = state.order
tools_by_category.setdefault(tool.category_id, []).append(
@@ -267,6 +274,9 @@ def resolve_effective(
enabled=enabled,
forced=state.forced,
locked_by=state.locked_by,
availability_state=_availability_state(enabled, state.forced),
availability_source=availability_source,
order_source=state.order_source,
)
)
@@ -286,12 +296,16 @@ def resolve_effective(
enabled=enabled,
forced=state.forced,
locked_by=state.locked_by,
availability_state=_availability_state(enabled, state.forced),
availability_source=state.availability_source,
order_source=state.order_source,
tools=tools,
)
)
categories.sort(key=lambda item: (item.order, item.id))
return EffectiveQuickAccessResponse(
categories=categories,
stale_preferences=stale_preferences,
diagnostics=list(dict.fromkeys(diagnostics)),
)
@@ -302,16 +316,20 @@ class _EffectiveState:
order: int
forced: bool = False
locked_by: str | None = None
availability_source: str = "module"
order_source: str = "module"
def apply(self, entry: PreferenceEntry | None, *, source: str) -> None:
if entry is None:
return
if entry.order is not None:
self.order = entry.order
self.order_source = source
if self.locked_by is not None:
return
if entry.enabled is not None:
self.enabled = entry.enabled
self.availability_source = source
if source != "user" and entry.enabled is False:
self.forced = False
self.locked_by = source
@@ -319,6 +337,38 @@ class _EffectiveState:
self.enabled = True
self.forced = True
self.locked_by = source
self.availability_source = source
def _availability_state(enabled: bool, forced: bool) -> str:
if not enabled:
return "blocked"
return "forced" if forced else "available"
def _stale_preferences(
profiles: tuple[tuple[str, QuickAccessProfile | None], ...],
catalogue: CatalogueResponse,
) -> list[EffectiveStalePreferenceResponse]:
category_ids = {item.id for item in catalogue.categories}
tool_ids = {item.id for item in catalogue.tools}
stale: list[EffectiveStalePreferenceResponse] = []
for source, profile in profiles:
if profile is None:
continue
for kind, field, known_ids in (
("category", "category_preferences", category_ids),
("tool", "tool_preferences", tool_ids),
):
values = getattr(profile, field, {})
if not isinstance(values, Mapping):
continue
stale.extend(
EffectiveStalePreferenceResponse(id=str(item_id), kind=kind, source=source)
for item_id in values
if str(item_id) not in known_ids
)
return sorted(stale, key=lambda item: (item.source, item.kind, item.id))
def _profile_entry(
tests/test_quick_access.py
+85
View File
@@ -136,6 +136,91 @@ class QuickAccessTests(unittest.TestCase):
self.assertTrue(work.enabled)
self.assertTrue(work.forced)
self.assertEqual("tenant", work.locked_by)
self.assertEqual("forced", work.availability_state)
self.assertEqual("tenant", work.availability_source)
def test_effective_resolution_reports_availability_and_order_provenance(self) -> None:
with Session(self.engine) as session:
session.add_all(
(
QuickAccessProfile(
scope_type="system",
tenant_id=None,
scope_id=None,
scope_key="system:*",
category_preferences={},
tool_preferences={"example.work": {"enabled": True, "order": 40}},
revision=2,
),
QuickAccessProfile(
scope_type="user",
tenant_id="tenant-1",
scope_id="account-1",
scope_key="user:tenant-1:account-1",
category_preferences={},
tool_preferences={"example.work": {"order": 5}},
revision=2,
),
)
)
session.commit()
effective = resolve_effective(
session,
registry=registry_with_tools(),
tenant_id="tenant-1",
account_id="account-1",
permission_checker=lambda _scope: True,
)
tool = next(item for item in effective.categories if item.id == "work").tools[0]
self.assertEqual("available", tool.availability_state)
self.assertEqual("system", tool.availability_source)
self.assertEqual("user", tool.order_source)
self.assertEqual(5, tool.order)
def test_effective_resolution_retains_stale_preferences_with_scope_provenance(self) -> None:
with Session(self.engine) as session:
session.add_all(
(
QuickAccessProfile(
scope_type="tenant",
tenant_id="tenant-1",
scope_id="tenant-1",
scope_key="tenant:tenant-1",
category_preferences={"retired.category": {"enabled": False}},
tool_preferences={"retired.tool": {"order": 5}},
revision=2,
),
QuickAccessProfile(
scope_type="user",
tenant_id="tenant-1",
scope_id="account-1",
scope_key="user:tenant-1:account-1",
category_preferences={},
tool_preferences={"missing.user-tool": {"enabled": True}},
revision=2,
),
)
)
session.commit()
effective = resolve_effective(
session,
registry=registry_with_tools(),
tenant_id="tenant-1",
account_id="account-1",
permission_checker=lambda _scope: True,
)
self.assertEqual(
[
("retired.category", "category", "tenant"),
("retired.tool", "tool", "tenant"),
("missing.user-tool", "tool", "user"),
],
[(item.id, item.kind, item.source) for item in effective.stale_preferences],
)
if __name__ == "__main__":
webui/src/api/quickAccess.ts
+11
View File
@@ -56,17 +56,28 @@ export type EffectiveQuickAccessTool = QuickAccessTool & {
enabled: boolean;
forced: boolean;
locked_by?: string | null;
availability_state: "available" | "forced" | "blocked";
availability_source: "module" | "system" | "tenant" | "user";
order_source: "module" | "system" | "tenant" | "user";
};
export type EffectiveQuickAccessCategory = QuickAccessCategory & {
enabled: boolean;
forced: boolean;
locked_by?: string | null;
availability_state: "available" | "forced" | "blocked";
availability_source: "module" | "system" | "tenant" | "user";
order_source: "module" | "system" | "tenant" | "user";
tools: EffectiveQuickAccessTool[];
};
export type EffectiveQuickAccess = {
categories: EffectiveQuickAccessCategory[];
stale_preferences: Array<{
id: string;
kind: "category" | "tool";
source: "system" | "tenant" | "user";
}>;
diagnostics: string[];
};
webui/src/features/settings/QuickAccessSettingsPanel.tsx
+38
View File
@@ -32,6 +32,11 @@ type Draft = {
tools: Record<string, QuickAccessPreference>;
};
type AvailabilityMode = "inherit" | "available" | "blocked" | "forced";
type EffectiveProvenance = {
state: "available" | "forced" | "blocked";
availabilitySource: "module" | "system" | "tenant" | "user";
orderSource: "module" | "system" | "tenant" | "user";
};
const EMPTY_DRAFT: Draft = { categories: {}, tools: {} };
@@ -186,6 +191,14 @@ export default function QuickAccessSettingsPanel({
const lockedTools = new Map(
(effective?.categories ?? []).flatMap((category) => category.tools).filter((item) => item.locked_by).map((item) => [item.id, item.locked_by])
);
const categoryProvenance = new Map(
(effective?.categories ?? []).map((item) => [item.id, effectiveProvenance(item)])
);
const toolProvenance = new Map(
(effective?.categories ?? []).flatMap((category) =>
category.tools.map((item) => [item.id, effectiveProvenance(item)] as const)
)
);
const categoryIds = categories.map((item) => item.id);
return (
@@ -219,6 +232,7 @@ export default function QuickAccessSettingsPanel({
preference={draft.categories[category.id]}
isPersonal={isPersonal}
lockedBy={editableConstraintSource(scope, lockedCategories.get(category.id))}
provenance={categoryProvenance.get(category.id)}
disabled={!canWrite || saving}
onChange={(value) => setPreference("categories", category.id, value)}
onMoveUp={() => move("categories", categoryIds, category.id, -1)}
@@ -243,6 +257,7 @@ export default function QuickAccessSettingsPanel({
defaultEnabled={tool.default_enabled}
isPersonal={isPersonal}
lockedBy={editableConstraintSource(scope, lockedTools.get(tool.id))}
provenance={toolProvenance.get(tool.id)}
disabled={!canWrite || saving}
onChange={(value) => setPreference("tools", tool.id, value)}
onMoveUp={() => move("tools", toolIds, tool.id, -1)}
@@ -268,6 +283,7 @@ function PreferenceRow({
defaultEnabled = true,
isPersonal,
lockedBy,
provenance,
disabled,
onChange,
onMoveUp,
@@ -282,6 +298,7 @@ function PreferenceRow({
defaultEnabled?: boolean;
isPersonal: boolean;
lockedBy?: string | null;
provenance?: EffectiveProvenance;
disabled: boolean;
onChange: (value: QuickAccessPreference | null) => void;
onMoveUp: () => void;
@@ -303,6 +320,15 @@ function PreferenceRow({
})}
</small>
) : null}
{provenance ? (
<small>
{i18nMessage("i18n:govoplan-quick-access.effective_provenance", {
value0: provenance.state,
value1: provenance.availabilitySource,
value2: provenance.orderSource
})}
</small>
) : null}
</div>
<div className="quick-access-preference-controls">
{isPersonal ? (
@@ -338,6 +364,18 @@ function PreferenceRow({
);
}
function effectiveProvenance(item: {
availability_state: "available" | "forced" | "blocked";
availability_source: "module" | "system" | "tenant" | "user";
order_source: "module" | "system" | "tenant" | "user";
}): EffectiveProvenance {
return {
state: item.availability_state,
availabilitySource: item.availability_source,
orderSource: item.order_source
};
}
function preferenceMode(preference?: QuickAccessPreference): AvailabilityMode {
if (!preference || preference.enabled === null || preference.enabled === undefined) return "inherit";
webui/src/i18n/generatedTranslations.ts
+4 -2
View File
@@ -44,7 +44,8 @@ export const generatedTranslations: PlatformTranslations = {
"i18n:govoplan-quick-access.category.messages_description": "Mail, Postfach und künftige Gesprächskanäle in einer Einblendung.",
"i18n:govoplan-quick-access.category.files": "Dateien",
"i18n:govoplan-quick-access.category.files_description": "Aktuelle und kontextbezogene Dateien, ohne die laufende Aufgabe zu verlassen.",
"i18n:govoplan-quick-access.locked_by_value": "Durch {value0} festgelegt"
"i18n:govoplan-quick-access.locked_by_value": "Durch {value0} festgelegt",
"i18n:govoplan-quick-access.effective_provenance": "Effektiv {value0}; Verfügbarkeit von {value1}, Reihenfolge von {value2}"
},
en: {
"i18n:govoplan-quick-access.quick_access": "Quick Access",
@@ -89,6 +90,7 @@ export const generatedTranslations: PlatformTranslations = {
"i18n:govoplan-quick-access.category.messages_description": "Mail, Postbox, and future conversational channels in one overlay.",
"i18n:govoplan-quick-access.category.files": "Files",
"i18n:govoplan-quick-access.category.files_description": "Recent and contextual files without leaving the current task.",
"i18n:govoplan-quick-access.locked_by_value": "Set by {value0}"
"i18n:govoplan-quick-access.locked_by_value": "Set by {value0}",
"i18n:govoplan-quick-access.effective_provenance": "Effective {value0}; availability from {value1}, order from {value2}"
}
};