@hmos-library-adapter/fast 0.0.17-beta.1 → 0.0.17-beta.2

package/node_modules/@ohos-agent/pc-adapter/skills/pc-recipe-qt-app/scripts/fixes/qdockwidget.md

@@ -0,0 +1,230 @@
+# QDockWidget: OHOS three-layer downgrade
+
+## Problem
+
+QDockWidget does not work on OHOS — the window management system doesn't support dock areas. ADS (Advanced Docking System) is also unavailable. However, you cannot simply replace QDockWidget with QTabWidget everywhere — the fix depends on which role QDockWidget plays in your code.
+
+## Context Decision
+
+1. If a **class inherits QDockWidget** (side panels like SearchResultsDock, DebugLogDock) → Strategy A
+2. If code calls **addDockWidget()** to place a panel → Strategy B
+3. If the app uses **ADS for a central tabbed editor area** → Strategy C
+4. If code calls **setCentralWidget** (missing after ADS removal) → Strategy D
+
+## Strategy A: Compatibility Header (when: class inherits QDockWidget)
+
+Side panels still inherit QDockWidget but use a compile-time stub header. The class definition doesn't change — only the include. **You must create this header file** — it is NOT provided by the OHOS SDK. It simply includes the real `<QDockWidget>` — the limitation is runtime (dock areas don't function), not compilation.
+
+### Before
+```cpp
+#include <QDockWidget>
+
+class SearchResultsDock : public QDockWidget { ... };
+```
+
+### After
+```cpp
+#ifdef __OHOS__
+#include "QDockWidgetOhos.h"
+#else
+#include <QDockWidget>
+#endif
+
+class SearchResultsDock : public QDockWidget { ... };
+```
+
+### Create QDockWidgetOhos.h
+
+Place this file alongside the dock headers (e.g., `src/docks/QDockWidgetOhos.h`):
+
+```cpp
+/*
+ * OHOS compatibility: On OHOS with Qt5, QDockWidget exists but docking
+ * functionality doesn't work properly. We just include the real QDockWidget
+ * and accept that dock areas are non-functional (they display as regular
+ * widgets that cannot be dragged/undocked).
+ *
+ * The real QDockWidget is fine for compilation - the limitation is runtime.
+ */
+#ifndef QDOCKWIDGET_OHOS_SHIM_H
+#define QDOCKWIDGET_OHOS_SHIM_H
+
+// Simply include the real QDockWidget - it compiles fine on OHOS Qt5
+#include <QDockWidget>
+
+#endif // QDOCKWIDGET_OHOS_SHIM_H
+```
+
+## Strategy B: Hide Instead of Dock (when: addDockWidget() call)
+
+OHOS has no dock areas. Replace addDockWidget() with hide(). The dock object still exists and can be shown as dialog later, but cannot be placed in dock areas.
+
+### Before
+```cpp
+addDockWidget(Qt::BottomDockWidgetArea, srDock);
+```
+
+### After
+```cpp
+#ifdef __OHOS__
+    srDock->hide();
+#else
+    addDockWidget(Qt::BottomDockWidgetArea, srDock);
+#endif
+```
+
+## Strategy C: Replace ADS with QTabWidget (when: central editor area uses ADS)
+
+Replace the entire ADS-based DockedEditor with a QTabWidget implementation that exposes the same interface. This is a multi-step process.
+
+### Step 1: Extend DockedEditor.h with ifdef
+
+### Before
+```cpp
+#include "DockManager.h"
+class DockedEditor : public QObject {
+    ads::CDockManager* dockManager = Q_NULLPTR;
+    ads::CDockAreaWidget* currentDockArea() const;
+};
+```
+
+### After
+```cpp
+#ifdef __OHOS__
+#include "DockedEditorOhos.h"
+#else
+#include "DockManager.h"
+class DockedEditor : public QObject {
+    ads::CDockManager* dockManager = Q_NULLPTR;
+    ads::CDockAreaWidget* currentDockArea() const;
+};
+#endif
+```
+
+### Step 2: Create DockedEditorOhos.h/.cpp
+
+Create a QTabWidget-based DockedEditor that provides the same signals and methods as the ADS version. Key class:
+
+```cpp
+// DockedEditorOhos.h
+class DockAreaOhos : public QTabWidget {
+    Q_OBJECT
+public:
+    int count() const { return QTabWidget::count(); }
+    int currentIndex() const { return QTabWidget::currentIndex(); }
+    void setCurrentIndex(int index) { QTabWidget::setCurrentIndex(index); }
+    QWidget *widget(int index) const { return QTabWidget::widget(index); }
+    // ... signals for tabCloseRequested, tabChanged
+};
+
+class DockedEditor : public QObject {
+    Q_OBJECT
+    DockAreaOhos *tabWidget = Q_NULLPTR;
+public:
+    DockAreaOhos *currentDockArea() const;
+    DockAreaOhos *getTabWidget() const { return tabWidget; }
+    // ... same signals as ADS version
+};
+```
+
+### Step 3: CMake source list restructuring
+
+The source list must be **extracted to a variable** first, then OHOS-specific items are removed and added before target creation. This is a two-step restructuring — not just adding/removing after the target.
+
+### Before
+```cmake
+qt_add_executable(NotepadNext
+    WIN32
+    MACOSX_BUNDLE
+    main.cpp
+    DockedEditor.cpp
+    DockedEditor.h
+    DockedEditorTitleBar.h
+    decorators/EditorConfigAppDecorator.cpp
+    ...
+)
+```
+
+### After
+```cmake
+# Step 3a: Extract sources to a variable
+set(NotepadNext_SOURCES
+    main.cpp
+    DockedEditor.cpp
+    DockedEditor.h
+    DockedEditorTitleBar.h
+    decorators/EditorConfigAppDecorator.cpp
+    ...
+)
+
+# Step 3b: OHOS-specific source modifications BEFORE target creation
+if(OHOS)
+    list(REMOVE_ITEM NotepadNext_SOURCES
+        "DockedEditor.cpp"
+        "DockedEditor.h"
+        "DockedEditorTitleBar.h"
+        "decorators/EditorConfigAppDecorator.cpp"
+        "decorators/EditorConfigAppDecorator.h"
+    )
+    list(APPEND NotepadNext_SOURCES
+        DockedEditorOhos.h
+        DockedEditorOhos.cpp
+        docks/QDockWidgetOhos.h
+    )
+endif()
+
+# Step 3c: Create target (different type under OHOS)
+if(OHOS)
+    add_library(NotepadNext SHARED ${NotepadNext_SOURCES})
+    set_target_properties(NotepadNext PROPERTIES AUTOMOC ON AUTOUIC ON AUTORCC ON)
+else()
+    qt_add_executable(NotepadNext
+        WIN32
+        MACOSX_BUNDLE
+        ${NotepadNext_SOURCES}
+    )
+endif()
+```
+
+⚠️ **Critical ordering:** `list(REMOVE_ITEM)` and `list(APPEND)` MUST happen BEFORE `add_library()`/`qt_add_executable()`. Modifying the source list variable after target creation has no effect.
+
+Also remove the OHOS-excluded sources from any related deps:
+- Remove `DockedEditor.cpp` sources (they `#include "DockAreaWidget.h"` from ADS)
+- Remove `EditorConfigAppDecorator.cpp` sources (they depend on editorconfig-core-qt)
+- Add `DockedEditorOhos.cpp` and `QDockWidgetOhos.h` as new sources
+
+## Strategy D: setCentralWidget (when: after replacing ADS)
+
+After replacing ADS with QTabWidget, you MUST call setCentralWidget() or the window appears blank.
+
+### Before
+```cpp
+dockedEditor = new DockedEditor(this);
+```
+
+### After
+```cpp
+dockedEditor = new DockedEditor(this);
+#ifdef __OHOS__
+    setCentralWidget(dockedEditor->getTabWidget());
+#endif
+```
+
+## Common Mistakes
+
+- ❌ Do NOT replace QDockWidget with QTabWidget for side panels (Strategy A/B). Side panels are not tabs — they are sidebar/bottombar widgets. Using QTabWidget breaks the UI architecture.
+- ❌ Do NOT forget setCentralWidget() after Strategy C. Without it, the QTabWidget exists but is never placed in the main window → blank window.
+- ❌ Do NOT forget to exclude DockedEditor.cpp from CMake under OHOS. It includes ADS headers which don't exist in the OHOS build.
+- ❌ Do NOT link qtadvanceddocking in OHOS builds. ADS is excluded entirely.
+- ❌ Do NOT use `list(REMOVE_ITEM)` AFTER `add_library()`/`qt_add_executable()` — it has no effect. Source list manipulation must happen BEFORE target creation.
+- ❌ Do NOT forget to also remove `DockedEditorTitleBar.h` — it often references ADS types like `ads::CDockAreaWidget`.
+- ❌ Do NOT forget to also exclude EditorConfigAppDecorator sources when removing ADS — they are often removed together since editorconfig-core-qt is also excluded under OHOS.
+- ❌ Do NOT forget to add `DockAreaOhos::count()` as a replacement for `ads::CDockAreaWidget::dockWidgetsCount()`. The QTabWidget base class uses `count()`, not `dockWidgetsCount()`.
+- ❌ Do NOT forget to add `DockAreaOhos::widget(int)` as a replacement for `ads::CDockAreaWidget::dockWidget(i)->widget()`. On QTabWidget, `widget(int)` returns the tab content directly.
+
+## Related Symbols
+
+- `addDockWidget` — Strategy B entry point
+- `dockWidgetsCount()` — ADS API, auto-replaces to `count()`
+- `dockWidget(i)->widget()` — ADS API, auto-replaces to `widget(i)`
+- `setCentralWidget` — Critical step in Strategy D

package/node_modules/@ohos-agent/pc-adapter/skills/pc-recipe-qt-app/scripts/fixes/qlist-int-constructor.md

@@ -0,0 +1,81 @@
+# QList<T>(int) Constructor: Qt5 Missing Overload
+
+## Problem
+
+In Qt6, `QList<T>(int count)` constructs a list with `count` default-constructed elements. This constructor does not exist in Qt5 — it was added when QVector and QList merged in Qt6. Using it on Qt5 produces:
+
+```
+error: no matching constructor for initialization of 'QList<ResultItem *>'
+    QList<ResultItem*> columns(numberOfColumns);
+                      ^        ~~~~~~~~~~~~~~
+```
+
+## Context Decision
+
+- If the intent is to create a list pre-filled with `count` default (null/zero) elements → **Strategy A**.
+- If the intent is to create a list and then assign values at specific indices → **Strategy B**.
+
+## Strategy A: Pre-fill with Default Values
+
+### Before
+```cpp
+QList<ResultItem*> columns(numberOfColumns);
+// All elements are nullptr — then individual ones are assigned
+columns[0] = createItem0();
+columns[1] = createItem1();
+```
+
+### After
+```cpp
+#ifdef __OHOS__
+QList<ResultItem*> columns;
+for (int i = 0; i < numberOfColumns; ++i)
+    columns.append(nullptr);
+#else
+QList<ResultItem*> columns(numberOfColumns);
+#endif
+columns[0] = createItem0();
+columns[1] = createItem1();
+```
+
+Or more concisely without the guard (works on both Qt5 and Qt6):
+```cpp
+QList<ResultItem*> columns;
+columns.reserve(numberOfColumns);
+for (int i = 0; i < numberOfColumns; ++i)
+    columns.append(nullptr);
+```
+
+## Strategy B: Build List Incrementally
+
+If the code immediately fills all elements after construction, skip the pre-fill entirely:
+
+### Before
+```cpp
+QList<QString> names(count);
+for (int i = 0; i < count; ++i)
+    names[i] = getName(i);
+```
+
+### After
+```cpp
+QList<QString> names;
+names.reserve(count);
+for (int i = 0; i < count; ++i)
+    names.append(getName(i));
+```
+
+This works on both Qt5 and Qt6 without any `#ifdef`.
+
+## Common Mistakes
+
+- ❌ Don't use `QList<T>(count)` with `reserve()` — `reserve()` only pre-allocates memory, it doesn't change the list's `size()`. You still need `append()` or the constructor.
+- ❌ Don't try `QList<T>::fill(value, count)` as a replacement — `fill()` only works on an already-sized list (it replaces existing elements, doesn't create new ones from scratch).
+- ❌ Don't forget that Qt5's `QList<T>` and Qt6's `QList<T>` are fundamentally different containers (Qt5 QList = linked list of arrays, Qt6 QList = QVector alias). Performance characteristics differ.
+- ❌ Don't use `QVector<T>(count)` as a Qt5 replacement if the surrounding code uses `QList` API — the types are not interchangeable in Qt5.
+
+## Related Symbols
+
+- `QVector` — Qt5 equivalent that does have the `QVector<T>(int)` constructor, but is not API-compatible with QList
+- `QList::reserve()` — pre-allocates capacity without changing size
+- `QList::append()` — adds elements to the end

package/node_modules/@ohos-agent/pc-adapter/skills/pc-recipe-qt-app/scripts/fixes/qmap-forward-decl.md

@@ -0,0 +1,165 @@
+# QMap/QSet with Forward Declaration Only
+
+## Problem
+
+Qt6 allows `QMap<T,U>` or `QSet<T>` in a header file where `T` or `U` is only forward-declared (not fully defined). This works because Qt6 defers template instantiation more aggressively. In Qt5, using these containers with incomplete types causes compilation errors:
+
+```
+error: implicit instantiation of undefined template 'QMap<int, CheckThread::Details>'
+```
+
+This is especially common when:
+- A class member is `QMap<K, V>` where `V` is defined in a separate header
+- A signal parameter is `QMap<K, V>` requiring `Q_DECLARE_METATYPE`
+- The header only has `class V;` forward declaration instead of `#include "v.h"`
+
+The error cascades: once QMap instantiation fails, Qt5's `connect()` template deduction also breaks, producing seemingly unrelated errors like:
+```
+error: cannot initialize a parameter of type 'const QObject *' with an lvalue of type 'const typename QtPrivate::FunctionPointer<...>::Object *'
+```
+
+## Context Decision
+
+- If the header already includes the full definition of the value type elsewhere (e.g., it's used by other members), the missing `#include <QMap>` or `#include <QSet>` is the root cause → **Strategy A**.
+- If the value type is genuinely only forward-declared and no full definition is available in this header → **Strategy B**.
+
+## Strategy A: Add Missing #include + Replace Forward Declaration (most common)
+
+The most frequent case is actually **two problems at once**:
+1. Missing `#include <QMap>` or `#include <QSet>` (Qt6 gets it transitively, Qt5 doesn't)
+2. The value type `V` in `QMap<K, V>` is only forward-declared — but Qt5 needs `V` fully defined for template instantiation
+
+When the value type is a **nested type** like `OtherClass::Details`, this is especially likely: the header forward-declares `OtherClass` but `OtherClass::Details` is inaccessible without the full definition.
+
+### Before (real-world pattern — two problems at once)
+```cpp
+#ifndef MYHANDLER_H
+#define MYHANDLER_H
+
+class OtherClass;  // forward declaration only — OtherClass::Details NOT accessible
+
+#include <QList>
+#include <QObject>     // no #include <QMap> — Qt6 gets it transitively
+
+class MyHandler : public QObject {
+    Q_OBJECT
+    // ...
+    QMap<int, OtherClass::Details> mDetails;  // ERROR on Qt5: two problems:
+    //   1. QMap is not included → implicit instantiation of undefined template QMap
+    //   2. OtherClass is only forward-declared → OtherClass::Details is inaccessible
+};
+```
+
+### After
+```cpp
+#ifndef MYHANDLER_H
+#define MYHANDLER_H
+
+#include "otherclass.h"  // ← REPLACE forward declaration with full include (provides OtherClass::Details)
+                        //   Note: add this with the other #include statements at the top,
+                        //   and remove the "class OtherClass;" forward declaration from below
+
+#include <QList>
+#include <QMap>          // ← ADD THIS
+#include <QObject>
+
+class MyHandler : public QObject {
+    Q_OBJECT
+    // ...
+    QMap<int, OtherClass::Details> mDetails;  // OK: QMap included + OtherClass::Details accessible
+};
+```
+
+**Placement note**: When replacing `class OtherClass;` with `#include "otherclass.h"`, the `#include` goes with the other includes at the top of the file, and the `class OtherClass;` line is removed from the forward-declaration group (often near line 40-50 in typical Qt headers). Don't leave the forward declaration in place after adding the full include — it's redundant and may cause confusion.
+
+**Key point**: Both fixes are required simultaneously. Adding only `#include <QMap>` without providing the full definition of the value type will produce a different error (`OtherClass::Details has not been declared`). Adding only the full include without `<QMap>` will produce the original QMap instantiation error. **You need both.**
+
+### Simpler variant (value type already fully included)
+
+If the value type's header is already included (just `<QMap>` is missing), the fix is simpler:
+
+### Before
+```cpp
+#include "mytype.h"  // MyType already fully defined
+#include <QList>
+#include <QObject>   // no <QMap>
+
+class MyHandler : public QObject {
+    QMap<int, MyType> mDetails;  // ERROR: only QMap is missing
+};
+```
+
+### After
+```cpp
+#include "mytype.h"
+#include <QList>
+#include <QMap>      // ← just add this
+#include <QObject>
+
+class MyHandler : public QObject {
+    QMap<int, MyType> mDetails;  // OK
+};
+```
+
+## Strategy B: Move QMap/QSet Usage to .cpp (rare)
+
+If you intentionally want to keep the header lightweight and avoid including the value type's full definition:
+
+### Before (header)
+```cpp
+class MyType;
+class MyHandler : public QObject {
+    QMap<int, MyType> mDetails;  // ERROR
+};
+```
+
+### After (header)
+```cpp
+class MyType;
+class MyHandler : public QObject {
+    // Use pointer to avoid needing full type definition
+    QMap<int, MyType*>* mDetails;  // OK: pointer doesn't require full type
+    // OR: move to .cpp and use Pimpl pattern
+};
+```
+
+### After (header with Pimpl)
+```cpp
+class MyType;
+class MyHandlerPrivate;
+class MyHandler : public QObject {
+    Q_OBJECT
+    Q_DECLARE_PRIVATE(MyHandler)
+public:
+    explicit MyHandler(QObject *parent = nullptr);
+    ~MyHandler() override;
+private:
+    QScopedPointer<MyHandlerPrivate> d_ptr;
+};
+```
+
+### After (cpp with full includes)
+```cpp
+#include "myhandler.h"
+#include "mytype.h"
+#include <QMap>
+
+class MyHandlerPrivate {
+public:
+    QMap<int, MyType> details;  // OK: both QMap and MyType are fully defined
+};
+```
+
+## Common Mistakes
+
+- ❌ Don't assume that because the code compiles on Qt6, the includes are correct — Qt6 transitively includes many headers that Qt5 does not.
+- ❌ Don't just add `#include <QMap>` without also ensuring the value type is fully defined — both must be present. The two problems almost always co-occur when `QMap<K, NestedType>` is used.
+- ❌ Don't confuse the QMap/QSet forward-declaration issue with the `Q_DECLARE_METATYPE` issue (see `qdeclare-metatype-incomplete.md`) — they are related but distinct. The QMap fix usually resolves the `connect()` cascade errors; if it doesn't, check Q_DECLARE_METATYPE next.
+- ❌ Don't replace `class OtherClass;` with `#include "otherclass.h"` inside `#ifdef __OHOS__` — the `QMap<int, OtherClass::Details>` member declaration is unconditional and triggers template instantiation regardless of `#ifdef`. The include and the member must agree: if the member is unconditional, the include must be unconditional too. Either guard both, or neither.
+- ❌ Don't forget that replacing a forward declaration with a full `#include` may introduce new transitive dependencies or slow compilation — this is the price of Qt5 compatibility. If this is unacceptable, use Strategy B (Pimpl/move to .cpp).
+
+## Related Symbols
+
+- `QSet<T>` — same issue, same fix
+- `QHash<T,U>` — less commonly affected but same pattern applies
+- `Q_DECLARE_METATYPE` — see `qdeclare-metatype-incomplete.md` for the related metatype registration issue

package/node_modules/@ohos-agent/pc-adapter/skills/pc-recipe-qt-app/scripts/fixes/qshortcut.md

@@ -0,0 +1,47 @@
+# QShortcut (multi-arg constructor): Overload Missing in Qt5
+
+## Problem
+
+The QShortcut 5-arg constructor `QShortcut(key, parent, member, member, context)` does not exist in Qt5. Additionally, the 4-arg form ending with `Qt::WidgetWithChildrenShortcut` as a positional argument also doesn't exist. Code using these overloads fails to compile.
+
+## Context Decision
+
+Any QShortcut construction using more than 2 positional arguments (key, parent) must be split. This is unconditional — the multi-arg overloads simply don't exist in Qt5.
+
+## Strategy A: Split into Constructor + setContext + connect (when: using multi-arg QShortcut constructor)
+
+Break the single constructor call into: create QShortcut with (key, parent), call setContext(), and connect the activated signal to the slot.
+
+### Before
+```cpp
+// 5-arg form: QShortcut(key, parent, member, member, context)
+new QShortcut(QKeySequence(Qt::Key_Escape), this, SLOT(onEscape()), SLOT(onEscapePressed()), Qt::WidgetWithChildrenShortcut);
+
+// 4-arg form with context
+new QShortcut(QKeySequence::Copy, this, SLOT(copy()), Qt::WidgetWithChildrenShortcut);
+```
+
+### After
+```cpp
+// 5-arg form split
+QShortcut *escShortcut = new QShortcut(QKeySequence(Qt::Key_Escape), this);
+escShortcut->setContext(Qt::WidgetWithChildrenShortcut);
+connect(escShortcut, &QShortcut::activated, this, &MyClass::onEscape);
+
+// 4-arg form split
+QShortcut *copyShortcut = new QShortcut(QKeySequence::Copy, this);
+copyShortcut->setContext(Qt::WidgetWithChildrenShortcut);
+connect(copyShortcut, &QShortcut::activated, this, &MyClass::copy);
+```
+
+## Common Mistakes
+
+- ❌ Don't try to pass the context as a constructor argument — QShortcut(key, parent, member, member, context) simply doesn't exist in Qt5 and won't compile.
+- ❌ Don't forget to call setContext() — without it the shortcut defaults to `Qt::WindowShortcut` which may cause unexpected activation from other widgets.
+- ❌ Don't use SLOT() macro with the new connect syntax — prefer the functor-based `connect(shortcut, &QShortcut::activated, this, &Class::slot)` for compile-time checking.
+- ❌ Don't pass the same slot twice (member, member) — the original 5-arg form had `member` and `ambiguousMember` as separate slots; most code passes the same slot for both, but only one connect is needed.
+
+## Related Symbols
+
+- `QShortcut::setContext` — must be called separately after construction
+- `QShortcut::activated` — the signal to connect to the slot

package/node_modules/@ohos-agent/pc-adapter/skills/pc-recipe-qt-app/scripts/fixes/qstyleoptiontab.md

@@ -0,0 +1,54 @@
+# QStyleOptionTabV4: Missing Style Option Version in OHOS Qt5
+
+## Problem
+
+QStyleOptionTabV4 does not exist in the Qt 5.15.17 OHOS SDK. The style option hierarchy stops at QStyleOptionTabV3 (or QStyleOptionTab). Any code using QStyleOptionTabV4 will fail to compile.
+
+## Context Decision
+
+If the code only needs fields available in QStyleOptionTabV3 or QStyleOptionTab, downgrade the version. If V4-specific fields (e.g. `tabIndex`, `tabCount` added in later Qt versions) are truly required, the feature must be stubbed on OHOS.
+
+## Strategy A: Replace with QStyleOptionTabV3 (when: V4-specific fields are not used or can be omitted)
+
+### Before
+```cpp
+QStyleOptionTabV4 opt;
+opt.initFrom(tabBar);
+opt.text = tabBar->tabText(index);
+```
+
+### After
+```cpp
+#ifdef __OHOS__
+QStyleOptionTabV3 opt;
+#else
+QStyleOptionTabV4 opt;
+#endif
+opt.initFrom(tabBar);
+opt.text = tabBar->tabText(index);
+```
+
+## Strategy B: Replace with QStyleOptionTab (when: even V3 is unavailable or only base fields needed)
+
+### Before
+```cpp
+QStyleOptionTabV4 opt;
+opt.initFrom(tabBar);
+```
+
+### After
+```cpp
+QStyleOptionTab opt;
+opt.initFrom(tabBar);
+```
+
+## Common Mistakes
+
+- ❌ Don't cast a lower-version option to QStyleOptionTabV4 — the memory layout differs and you'll get garbage or crashes.
+- ❌ Don't forget to check which V4 fields are actually used before downgrading — `tabIndex` and `tabCount` don't exist in V3.
+- ❌ Don't use `QStyleOptionTabV4` inside `#ifndef __OHOS__` guards without also guarding the corresponding `#include` — the symbol is absent at link time too.
+
+## Related Symbols
+
+- `QStyleOptionTabV3` — nearest available version on OHOS
+- `QStyleOptionTab` — base class always available

package/node_modules/@ohos-agent/pc-adapter/skills/pc-recipe-qt-app/scripts/fixes/qsystemtrayicon.md

@@ -0,0 +1,45 @@
+# QSystemTrayIcon: Not Supported on OHOS
+
+## Problem
+
+QSystemTrayIcon is not supported on OHOS because the platform has no system tray concept. Creating a QSystemTrayIcon on OHOS either crashes at runtime or the icon simply never appears.
+
+## Context Decision
+
+If the system tray icon is essential to the application's core functionality (e.g. a daemon that only lives in the tray), the feature must be redesigned for OHOS. If it's a convenience (minimize-to-tray, notifications), guard it out with `#ifndef __OHOS__`.
+
+## Strategy A: Guard with #ifndef __OHOS__ (when: tray icon is non-essential convenience)
+
+### Before
+```cpp
+#include <QSystemTrayIcon>
+
+QSystemTrayIcon *trayIcon = new QSystemTrayIcon(icon, this);
+trayIcon->show();
+connect(trayIcon, &QSystemTrayIcon::activated, this, &MainWindow::trayActivated);
+```
+
+### After
+```cpp
+#ifndef __OHOS__
+#include <QSystemTrayIcon>
+#endif
+
+#ifndef __OHOS__
+QSystemTrayIcon *trayIcon = new QSystemTrayIcon(icon, this);
+trayIcon->show();
+connect(trayIcon, &QSystemTrayIcon::activated, this, &MainWindow::trayActivated);
+#else
+// OHOS: no system tray — keep window visible or use notification API
+#endif
+```
+
+## Common Mistakes
+
+- ❌ Don't create QSystemTrayIcon and just call `show()` hoping it works on OHOS — it won't display and may log warnings or crash.
+- ❌ Don't guard only the `show()` call — the constructor itself may fail or link incorrectly on some OHOS Qt builds.
+- ❌ Don't forget to also guard the `#include <QSystemTrayIcon>` — the header may be missing entirely in some OHOS SDK configurations.
+
+## Related Symbols
+
+- None