Repository navigation
Knowledge Base contract
Knowledge Base is a native Qt Quick documentation surface. It intentionally
uses TextEdit and QTextDocument rather than Qt WebEngine, so opening an
article does not start a browser process or load a web application runtime.
The dock header and Workspace panels menu use the same open-book icon as the
Knowledge Base surface, so the feature is recognizable before it is opened.
Each project owns one PROJECT/th_knowledge_article Search Type. The first
initialization is an explicit administrator action shared with Messages. Its
confirmation lists every schema change: it creates the article Search Type and
its seven content columns when missing, including linked_skeys, and adds the
metadata text column to
sthpw/message and sthpw/message_log. Existing columns and data are never
removed. The table stores sections
and articles in one hierarchy and adds searchable plain text beside canonical
Markdown. TACTIC remains the source of truth; the desktop controller owns only
the current catalog, article draft, revision, and presentation lifecycle.
If one of the shared collaboration Search Types resolves to TACTIC's
Undefined sentinel, Knowledge Base remains readable and reports Messages as
uninitialized instead of failing the complete catalog request.
The navigation hierarchy follows a compact page-tree presentation. Sections and articles are ordinary borderless rows; disclosures stay before the item icon, and section descriptions remain small secondary text. Only the current entry receives a quiet neutral background, without an outline or accent rail. The disclosure hit area is excluded from row activation: its click only expands or collapses the branch, while the rest of the row opens the section. Navigation owns a separate presentation identity, so selection follows a pointer activation immediately while the selected page continues loading asynchronously. If a request is already running, the controller retains and loads the latest click.
Supervisors can drag an existing article or section onto a section to change
its parent, or above and below another row to order siblings. These changes are
an explicit local organization draft: the header exposes Save order and Undo
only after the first move, and the server receives the changed parents and
sort positions as one validated batch. Search, reload, creation, and deletion
stay blocked until that draft is saved or discarded. A section cannot be moved
into its own descendant. When a new article enters its editor, a compact
two-step flow first collects its title and summary, then gives the available
height to the rich-text body. The metadata step also names the parent section
(or the Knowledge Base root) so the destination is visible before content is
written. Existing articles open directly on their content with title and
summary collapsed. A labeled Show title and summary disclosure with a
downward chevron restores those fields without losing body edits; while they
are open, the same control becomes Hide title and summary with an upward
chevron. It never uses the Edit icon or implies that a second editor will open.
Unsaved article and section edits never block navigation. Before another page
is selected, the controller snapshots the current form, Markdown body, linked
objects, and attachment staging context into a project-local draft persisted
through the shared configuration write queue. While the editor is dirty, it
checkpoints the current document without blocking the UI, so a process crash or
forced restart can restore recent work.
Checkpoints with no content changes also leave the editor open; only explicit
save, cancel, or navigation actions exit editing. The controller regression
and real-QML mouse test cover this no-op checkpoint path.
That draft remains in the navigation tree with a Local draft badge and opens
back into the editor without a server request. A new page follows the same
path and does not create a TACTIC row until Save as draft, Publish, or the
first attachment upload.
The article viewer and editor expose an explicit Back to articles action only
when their page has replaced the navigation list. The action stays hidden when
navigation and article content are visible side by side. In the wide layout, a
dedicated header button hides or restores the navigation panel and immediately
returns its width to the viewer or editor. The editor synchronizes
the live QTextDocument before returning to the navigation list. Discard removes the
local draft, while Save replaces it with the server-backed entry. The feature
uses the shared DockWorkspaceFooter as its dock surface, including the common
lower-corner treatment, without adding a separate empty action row.
An article projects its h1–h6 headings into the right-side outline. The
list action in the article header hides or restores that outline; hiding it
immediately returns the reserved width to the article body. In a narrow reader,
the inline outline uses the complete reading width whenever no vertical
scrollbar is needed and reserves the shared scrollbar gutter only while the
article actually overflows. The reader header uses neutral surfaces for the
page-kind tile, active outline toggle, and Edit action; accent color is limited
to glyphs and state cues so those three controls do not compete as primary
actions. A selected section presents its complete descendant outline in the
main reading area. Entries use one compact borderless column at every width.
Subsections use an open-folder icon, an explicit Section label, and indentation;
their descendants remain visible and receive a deeper indent instead of being
hidden behind another navigation step. Activating any row still selects that
page through KnowledgeController.
The article header estimates reading time from searchable plain text at 200 words per minute. A quiet metadata row after the article body shows the immutable creator login, creation time, and latest update time. Creation and update timestamps come from TACTIC's standard system fields and use the same server-clock-corrected local presentation as the Activity Feed; raw server timestamps are never shown as a fallback.
The Knowledge Base server procedure enforces the same edit permissions as the UI. Administrators and members of supervisor groups can save entries. Saved page removal goes through TACTIC's ordinary sObject delete permissions and dependency review. Other users can list, search, and read entries. Optimistic revisions prevent one editor from silently overwriting another editor's newer article.
The editor stores one canonical Markdown body and exposes it through Visual and
Markdown source modes. Switching modes synchronizes the same draft; there is no
parallel HTML field or migration layer. The visual mode supports headings,
emphasis, lists, alignment, links, remote image URLs, and article attachments.
The compact formatting row exposes text styles through one Aa menu, list
types through one list menu, and keeps the Visual/Markdown switch visible.
Character-format buttons reflect the current selection or caret position. With
no selection they stay active as typing modes until toggled off. Quote, pull
quote, and code actions open one insertion panel prefilled from the current
selection. Code insertion stores the selected language on one contiguous
Markdown fence; Python blocks reuse the script editor's syntax palette. The
visual editor and reader render quotes with explicit quotation treatment and
code with one framed surface and language header. Divider inserts one
horizontal rule at the caret. Visual mode uses the reader's workspace
background, typography, semantic surfaces, spacing, and article width; only
the caret, selection, and editing controls distinguish it from the saved
article.
CommonMark deliberately ignores repeated blank lines between block elements.
Before Qt parses an article, the document bridge temporarily replaces only
those extra lines with private markers, removes the markers into empty
QTextBlocks after parsing, and serializes them as standalone <br /> rows.
Fenced-code contents are excluded from this preprocessing. This preserves
author-entered vertical spacing through Markdown, Visual, reader, and save
round trips without storing private marker characters.
Narrow editors move secondary actions into an accessible overflow menu instead
of wrapping the toolbar. With article
metadata and attachments closed, the body expands to the remaining editor
height. Image dimensions and content-width sizing use the readable Markdown
suffix {width=320 height=180 fit=content}. Object links remain ordinary
skey:// Markdown links.
The editor header also responds to the width of its own action set. Save, Cancel, and Delete stay directly available; their labels collapse into compact icon buttons when they no longer fit. The header row never increases the article viewport's horizontal content width.
Hovering an existing text link reveals a compact Edit link action beside its rendered range. It opens the shared link panel with the current address and label. Saving replaces that exact anchor range, so moving focus to the action does not make the edit depend on the current text selection.
Pointer hover and ordinary text selection stay inside the native TextEdit.
The editor resolves a link only when Qt reports that the hovered anchor changed.
Its passive tap handler does not take the pointer grab from native text selection;
an image click is resolved through the painted QTextDocument layout, with the
caret boundary used only as a compatibility fallback. Dragging across ordinary
text therefore performs no per-pointer-move Python calls or controller state
updates.
The editor also keeps image fitting out of the live dock-resize path. Dock
geometry continues to update normally while the pointer moves, but the live
QTextDocument image formats are fitted once when the resize gesture ends.
Ordinary non-dock width changes cross a coarse width bucket before fitting, so
one pixel of geometry never causes a full document rewrite. No debounce timer
or rasterized dock preview participates in this path.
The attachment library is closed by default. The paperclip in the formatting row shows or hides it, and its close action returns the space to the body. One Attach files action inside that library accepts images, video, and ordinary files into a shared pre-upload library. The staging toolbar keeps only the distinct clipboard-image and clear actions instead of duplicating the file chooser. A new article stays local until that action needs a server identity; its first upload reserves that identity as an owner-only TACTIC draft and attaches the uploaded snapshots before they are inserted into the text. Save as draft explicitly creates or updates that owner-only server row and keeps the editor open. Publish clears the draft status and makes the article visible to readers. Drafts are excluded from other users' catalogs and from the Search Object link index.
Uploaded images, video, and other files are TACTIC snapshots attached to the
article. The attachment library derives file and preview URLs through the
native Snapshot and File APIs. Compact attachment cards use previews when
available. The reader and visual editor prefer the bounded preview and retain
the original as a fallback. The same library inserts the permanent URL or a
normal file link, and saving, drafting, and reopening preserve that original
URL in Markdown. The live QTextDocument owns only a transparent placeholder
with the image dimensions; a bounded asynchronous QML image paints over those
document coordinates. This prevents a malformed or decoder-hostile file from
blocking TextEdit layout while preserving caret placement, selection,
movement, and resizing. A QML regression verifies preview rendering, original
URL round trips, and resize geometry without recreating the image delegate. A
labeled Copy link action copies the permanent URL and changes to Copied as
immediate feedback without a timeout. The reader
hides linked-object previews and attachment cards by default; its paperclip
button reveals or hides both groups below the article. Attachments retain their
original name, preview, extension, and size. Activating a file card opens its permanent web URL;
the same mouse, touch, Enter, and Space paths work for image and non-image files.
Stored file names combine the article's server code with an opaque per-attachment
identity;
the original uploaded name remains metadata shown by the library and never
becomes the technical repository name. A physical-path collision is retried
with a new technical suffix without overwriting an existing repository file.
The editor library keeps every uploaded file in the same compact row regardless
of attachment count. The preview, original name, size, insert action, copy-link
action, and confirmed delete action remain visible without switching to a
separate image-card layout.
Attachment deletion accepts only a snapshot that the server has verified
belongs to the current article. Delete article is visible in both the reader
and editor. A saved page enters the shared sObject deletion window, which asks
TACTIC for the complete dependency graph before removal. The operator reviews
every related Search Type and chooses which dependencies to remove; the normal
defaults include snapshots and files. Linked sObject search keys stored in the
article body are values rather than ownership relations, so deleting the page
does not delete those objects. An unsaved local draft has no server object or
dependencies and is removed locally without opening the window.
An inserted image is placed at the current text caret, starts at no more than
560 pixels wide, and never exceeds the current text area. Clicking an image
selects its inline image character and draws a resize frame over the rendered
image. The frame uses the bounds from the live document layout rather than a
text caret rectangle. Clock, preview, and other unrelated controller updates
do not reload the editor document or clear its image selection. Dragging the
selected image itself moves that existing fragment to the drop caret without
creating a copy; the move is one undoable document edit. A
compact selection readout shows
the displayed size, saved article size when it differs, intrinsic source pixel
size when Qt has loaded it, and whether proportional resizing is available.
The selection panel offers two explicit sizing modes. Stretch to content width keeps the image at the current article width. When it is disabled, the
slider and bottom-right handle set a strict proportional size from a 24-pixel
minimum up to the current content width. The editor retains that strict size
while stretch mode is enabled, so switching back restores it. The reader keeps
both modes inside the current text width. Selecting ordinary
text clears the image frame without taking mouse selection or keyboard focus
away from the editor. In the reader, each inline image is an accessible action:
clicking or pressing Enter or Space opens the original safe HTTP/HTTPS source,
while rendering may still use a local or generated preview fallback.
The reader and visual editor attach the same Markdown conversion controller to
native TextEdit documents and use the same typography, block decorations,
spacing, background, and image overlays. This is the WYSIWYG contract: at the
same content width, viewing and editing have identical document geometry and
paint. A real QML regression test compares both surfaces, their document HTML,
block rectangles, and image rectangles. Images remain asynchronous cached QML
items with a bounded decode size over transparent document placeholders, so a
remote or malformed image never enters QTextDocument resource loading.
An article can own a list of normalized Search Object keys in linked_skeys.
Creation remains independent from the current Search query and selection. Once
the new article editor is visible, a contextual action links the currently
selected Search Objects; it disappears when there is nothing new to link. The
editor keeps its live linked-object header visible above the body throughout
creation and later edits, so every linked object can be reviewed or unlinked.
The saved article shows the same live object header with the current preview,
title, description, and native object action. The preview itself uses that same object
action rather than acting as decoration. Left and right controls page through the
header when the article describes several objects without expanding every
preview into the reading surface. While editing, the unlink action removes
only the object currently shown in that header; the relation change remains in
the article draft until Save as draft or Publish. It never retires the linked
sObject itself. Compact article and section creation actions live in the
Knowledge Base header rather than consuming navigation height.
Search result cards and rows expose a persistent Knowledge Base action only when the current project reports an article linked to that exact Search Object. The action stays at the trailing edge of the item-action group, so hover-only actions can appear without moving it. Activating it opens the linked article in the Knowledge Base dock. The server returns a lightweight project link index separately from article bodies, and the application applies that index to every retained Search tab model. This avoids loading article content or issuing one request per visible result item. If Knowledge Base has not been initialized for a project, the same index request returns an empty result and ordinary Search results remain unchanged.
Article search keys use the ordinary TACTIC form for
PROJECT/th_knowledge_article. They can be copied into Notes, Messages, and
other link-aware text. Notes and Messages render a Knowledge Base search key as
a compact article card with the page title, article or section type, and the
available summary instead of exposing the technical Search Type and code.
Activating the card opens that page in the native Knowledge Base dock. The
shared link router recognizes:
-
skey://for Search Objects, tasks, notes, snapshots, files, users, projects, and Knowledge Base articles; -
tactic-search://for saved searches; -
http://,https://, andftp://for external resources.
Plain descriptions are HTML-escaped before linkification. Article Markdown is stored verbatim after boundary and size validation; its rendered rich text is sanitized before presentation, so executable markup and unsafe URL schemes are not exposed to the native viewer.
The dock is hidden by default. Its controller does not load the catalog or any article body until the dock is presented. A project change may still request the lightweight link index used by visible Search results; that request never loads article content. Hiding the dock keeps its current request, catalog, article, and editor state; project changes and shutdown still cancel owned work, and stale completions are ignored. Search runs asynchronously with a short debounce. Lists and article bodies use the shared persistent scrollbar. The reader and editor reflow the same retained native document; resizing only refits its image fragments and does not parse a second presentation model. The shared controller finds images through QText block fragments rather than scanning every document character during width fitting.
Shared ItemPreview suspends image loading and its OpacityMask whenever it
is invisible, including visibility inherited from a collapsed attachment panel
or a compact card's hidden full-size layout. Qt Layouts can probe such layouts
with near-DBL_MAX widths. Rendering a hidden mask with that width overflows
Qt's texture size and traps its render thread in a zero-doubling loop, blocking
the main window even after the inline article image has loaded successfully.
ItemPreviewLifecycleTests.test_hidden_preview_does_not_render_unbounded_layout_size_hints
replays the dump dimensions and hide/show transitions; run it with
QT_QPA_PLATFORM=windows, QT_QUICK_BACKEND=rhi, QSG_RHI_BACKEND=opengl,
and QSG_RENDER_LOOP=threaded to cover the native rendering boundary as well
as the default software tests. The editor image-resize test also checks that
the inline image renders while the hidden attachment preview is unloaded.
A load or save that reaches the server after another client deleted the entry returns a structured missing-entry result instead of an XML-RPC fault. Stale loads refresh the catalog and preserve a still-valid selection; stale saves retain the local draft and leave navigation available.
tests/test_knowledge_base.py covers Markdown/visual round trips, source-mode
switching, linkification and sanitization, the native QTextDocument formatting
bridge, the shared schema-initialization warning,
missing-entry races, contextual selection linking, drag-and-drop organization,
creation-parent presentation, draft reservation before attachment upload, and
the real linked-object carousel at narrow and wide sizes. It also verifies that
navigation stashes and restores unsaved local drafts without a server read and
that the narrow editor exposes its Back to articles action.
tests/test_sobject_delete.py verifies that a Knowledge Base search key enters
the same dependency discovery and delete batch as a loaded Search result,
including checked snapshots and files and visible unchecked relation types.
The runtime QML coverage also verifies the shared Knowledge Base dock surface
and full-width inline outline without a scrollbar.
tests/test_knowledge_server_links.py verifies link persistence, revisions,
owner-only drafts, publishing, deterministic indexes, safe uninitialized
projects, batched hierarchy updates, and cycle rejection.
tests/test_knowledge_workspace_links.py
plus the workspace delegate test cover conditional row/card controls and native
action routing. Dock and search-key resolver suites cover layout restoration
and link navigation.
TACTIC-Handler · Releases · Issues · English · Русский
English
- Home
- Installation
- Feature tour
- User guide
- Assistant
- Dashboards
- Knowledge Base
- Maya / Shelf
- Plugins / Плагины
Русский
- Главная
- Установка
- Обзор возможностей
- Руководство пользователя
- Помощник
- Дашборды
- База знаний
- Maya / Shelf
- Plugins / Плагины
Development / Разработка