Tracker item lifecycle

Question and use cases

The six TrackerItemStatus values and every transition TrackerItemTransitionRules allows.

Use this state machine before adding a tracker item command, transition, or user-interface action.

Use the diagram during design review, incident diagnosis, code walkthroughs, and onboarding. It intentionally omits classes and projects unrelated to the focused question, so read it together with the source entry point and related topic pages.

This page covers only the named responsibilities and relationships; consult the relevant module documentation for capabilities not shown here.

Reading path

1. Step 1: Follow the main path from Open through Closed.
2. Step 2: Then read the three cancel exits and the manage-gated reopen paths back to Open.
3. Step 3: Read each arrow as an allowed transition that TrackerItemTransitionRules must still validate at execution time.

Do not skip arrow direction, numbering, or group titles: they express dependency or time direction, execution order, and responsibility boundaries. If the diagram differs from current source or accepted architecture decisions, correct the generated catalog immediately.

Legend and notation

This is a STATE MACHINE diagram. Use that form to understand the layout, then test your interpretation against the source facts below.

Key relationships and design meaning

Relationship 1

Source fact: TrackerItemStatus has six values; the main path is Open → InProgress → InReview → Resolved → Closed.

Architectural meaning: The main path gives user interfaces and commands a shared vocabulary for normal tracker-item progress.

Review action: Is the command legal from every source state exposed by the endpoint?

Relationship 2

Source fact: Every working state can drop to Cancelled; the rules force a written resolution for both Resolved and Cancelled (RequiresResolution).

Architectural meaning: Rework and reopening are explicit transitions rather than status overwrites, so lifecycle history and rules stay observable.

Review action: Which invariant rejects an unlisted transition?

Relationship 3

Source fact: Closed and Cancelled can flow back to Open; whether manage permission is required is adjudicated in Application, not in the rules file.

Architectural meaning: Terminal states are not dead ends: Closed and Cancelled can return to Open, keeping corrections auditable without recreating items.

Review action: Do rework and reopen preserve history and concurrency expectations?

Design review questions

Answer each question when reviewing or implementing a related change. If code, tests, or an ADR cannot support the answer, do not decide from the diagram alone.

• Is the command legal from every source state exposed by the endpoint?
• Which invariant rejects an unlisted transition?
• Do rework and reopen preserve history and concurrency expectations?

How to use the answers

1. Identify the single owner of the capability or rule.
2. Confirm that dependency, call, or event direction does not reverse ownership.
3. Capture the conclusion with an automated test or repeatable command.

Boundaries and common mistakes

Boundary 1

Every transition passes static TrackerItemTransitionRules.Validate(from, to) in Tracker.Contracts/Kernel; an illegal move fails with TrackerErrors.ItemInvalidTransition.

• Do not infer: A connector in the diagram does not mean every implementation uses synchronous calls, a shared transaction, or shared data ownership.
• Review requirement: Which invariant rejects an unlisted transition?

Boundary 2

Assigned、Reopened、Released are not statuses: dispatch reads the assignee, reopen is a counted transition, release only writes a version lock.

• Do not infer: A connector in the diagram does not mean every implementation uses synchronous calls, a shared transaction, or shared data ownership.
• Review requirement: Do rework and reopen preserve history and concurrency expectations?

Boundary 3

The slug is retained for URL compatibility; the diagram shows the Tracker item aggregate, not an order aggregate.

• Do not infer: A connector in the diagram does not mean every implementation uses synchronous calls, a shared transaction, or shared data ownership.
• Review requirement: Is the command legal from every source state exposed by the endpoint?

Source verification and regeneration

The primary verification entry point is src/Platform/Tracker/BitzOrcas.Platform.Tracker.Contracts/Kernel/TrackerItemTransitionRules.cs. Inspect it and its direct references before regenerating diagram assets and pages.

# Regenerate bilingual SVG, standalone HTML, and documentation pages
npm run diagrams

# Check locale pairs, references, safety attributes, accessibility, and canvas bounds
npm run verify:diagrams

# Confirm that generation changed only the intended diagrams and pages
git diff -- scripts/diagrams diagram-sources public/diagrams src/content/docs

# Verify internal links, MDX structure, and professional depth gates
npm run verify:docs
npm run audit:docs-depth

Change-completion checklist

• Responsibilities, order, states, and relationships match current source.
• Every new element helps answer this page’s question instead of turning the diagram into an inventory.
• Arrows have explicit direction and semantics without implying nonexistent synchronous or transactional guarantees.
• Chinese and English titles, labels, facts, and boundaries remain semantically equivalent.
• The diagram remains readable on narrow screens, in fullscreen, and while zoomed, with no overlap or overflow.
• Relevant architecture tests, integration tests, or verification commands have run.
• If a long-lived constraint changed, its ADR or architecture documentation is updated.

Continue reading

• Architecture overview
• All architecture diagrams
• Platform modules