Document public API and integration contract

epic-expense-type-selection-foundation-task-014 — Produce developer documentation for all four foundation components: ExpenseTypeConfig (enum variants, FormulaParameters fields, JSON schema), MutualExclusionRuleEngine (method signatures, return types, error cases), ExpenseTypeAccessibilityService (label contract, announcement politeness levels, debounce behaviour), and ExpenseTypeAnalyticsTracker (event types, PII guarantees, flush strategy). Include a dependency diagram showing how higher-tier components (BLoC, repository) should import these modules. Documentation must be in English.

medium priority low complexity documentation pending documentor Tier 5

Acceptance Criteria

Dartdoc comments are present on every public class, constructor, method, and field in all four foundation components.

ExpenseTypeConfig documentation lists all enum variants with their display names and the HLF-specific mutual exclusion note.

FormulaParameters fields are each documented with their type, unit (e.g. km, NOK), and valid range.

A JSON schema example (inline code block in dartdoc) is included for the serialised ExpenseTypeConfig.

MutualExclusionRuleEngine dartdoc documents: method signatures, return type semantics, what constitutes an empty result, and the O(n²) complexity note for validateSelection.

ExpenseTypeAccessibilityService dartdoc documents: which WCAG 2.2 AA criterion each method addresses, the announcement politeness levels (polite vs assertive), and the 150 ms debounce contract.

ExpenseTypeAnalyticsTracker dartdoc documents: all event types with their payload fields, the PII-free guarantee (which fields are explicitly excluded), and the flush strategy (e.g. batched on app pause or immediate).

A `docs/expense-type-foundation.md` file (or equivalent in the project's docs folder) contains a dependency diagram (ASCII or Mermaid) showing the import direction: BLoC → RuleEngine, BLoC → AccessibilityService, BLoC → AnalyticsTracker, Repository → ExpenseTypeConfig.

All documentation is in English.

Running `dart doc` on the package produces zero warnings.

Technical Requirements

frameworks

Dart

dart doc

data models

ExpenseType

ExpenseTypeConfig

FormulaParameters

MutualExclusionRuleEngine

ExpenseTypeAccessibilityService

ExpenseTypeAnalyticsTracker

security requirements

Documentation must explicitly state which data is excluded from analytics events to satisfy GDPR and organisational PII policies

Execution Context

Execution Tier

Tier 5

Tier 5 - 253 tasks

Can start after Tier 4 completes

View Full Execution Plan

Implementation Notes

Enable the `public_member_api_docs` analysis option only for the `lib/features/expense/domain/` directory by adding a local `analysis_options.yaml` there, to avoid requiring dartdoc comments across the entire codebase. Use Mermaid syntax for the dependency diagram in the markdown file — it renders natively on GitHub and can be copy-pasted into Confluence. For WCAG references, cite the specific success criterion (e.g. SC 4.1.3 Status Messages) rather than just 'WCAG 2.2 AA' to give future developers an auditable reference.

Keep the JSON schema example minimal but complete — one valid example object covering all required fields is sufficient. Write the dartdoc examples in `/// Example:` blocks using triple-slash fenced code so dart doc renders them as formatted snippets.

Testing Requirements

Documentation quality is verified by: (1) running `dart doc` and asserting zero warnings in CI, (2) a documentation linting step (e.g. `dart analyze` with the `public_member_api_docs` lint rule enabled for the foundation layer files). No runtime tests are needed for this task. Reviewer checklist: every public API member has a doc comment, the dependency diagram is accurate relative to the actual import graph, and the PII guarantee statement is present and specific.

Component

Expense Type Configuration

data low

Dependencies (4)

Write exhaustive unit tests that assert every ExpenseType variant has a corresponding config entry, that all formula parameters are within valid business ranges (rate > 0, threshold >= 0), and that JSON round-trip serialisation is lossless. Tests must run in under 200 ms with no network or disk access. epic-expense-type-selection-foundation-task-003 Write unit tests asserting: semantic labels for all ExpenseType variants in selected/unselected/disabled states, conflict announcement strings include both type names, focus-order hints return types sorted by display priority, and debounce prevents duplicate announcements within 150 ms window. Validate all label strings contain no placeholder tokens. epic-expense-type-selection-foundation-task-009 Write integration tests (no UI, in-process only) asserting that when MutualExclusionRuleEngine detects a conflict and ExpenseTypeAnalyticsTracker is wired together, a conflictBlocked event is enqueued containing the correct ExpenseTypePair within 50 ms. Verify the event contains no PII. Tests should use the in-memory sink from the tracker's test mode. epic-expense-type-selection-foundation-task-013 Write property-based and example-based unit tests for MutualExclusionRuleEngine covering: all known conflicting pairs are rejected, all non-conflicting pairs are accepted, filterAllowedAdditions correctly excludes types that would trigger any conflict, resolveConflict always returns a valid post-resolution state, and an empty selection is always valid. Parameterise over all ExpenseType combinations to prevent regression when new types are added. epic-expense-type-selection-foundation-task-012

Epic Risks (2)

high impact medium prob scope

The compatibility matrix might be under-specified in source documentation. If a new organisation adds expense types or redefines rules, hardcoded pairwise logic becomes a maintenance liability and can silently allow previously excluded combinations.

Mitigation & Contingency

Mitigation: Model the matrix as a const Map<ExpenseType, Set<ExpenseType>> rather than if-else chains; add a unit test that exhaustively asserts every pair combination so any future matrix change forces explicit test updates.

Contingency: If per-organisation matrix variants are requested before the epic closes, extract matrix loading into expense-type-config with an org-override slot and defer per-org configuration to the repository epic.

medium impact medium prob technical

VoiceOver (iOS) and TalkBack (Android) handle Semantics widget announcements differently in Flutter. Live-region behaviour for disabled state changes is inconsistent across Flutter versions and may require platform-specific workarounds that are not yet documented.

Mitigation & Contingency

Mitigation: Write accessibility integration tests using Flutter's SemanticsController targeting both iOS and Android simulators from the outset; pin to a Flutter version known to handle Semantics.liveRegion correctly.

Contingency: If platform parity is unachievable before release, ship with a known gap documented in the WCAG audit log and schedule a dedicated accessibility sprint; do not block other epics.

Quick Links

All Tasks Execution Plan