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

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

@@ -0,0 +1,205 @@
+# QByteArrayView: Qt5 Missing Type
+
+## Problem
+
+QByteArrayView doesn't exist in Qt5. Code that uses it unconditionally fails to compile on Qt 5.15.17 OHOS SDK with a "no type named 'QByteArrayView'" error.
+
+## Context Decision
+
+If QByteArrayView is used widely across the codebase (e.g. in public headers or many call sites), use Strategy A to preserve the API surface with a minimal shim. If it appears in only one or two isolated spots, Strategy B is simpler and avoids introducing a custom class.
+
+## Strategy A: Define a Minimal QByteArrayView Shim (when: used in 3+ files or public headers)
+
+Provide a lightweight QByteArrayView that wraps const char* / QByteArray and exposes the subset of methods your code actually calls (data(), size(), isEmpty(), toByteArray(), etc.). Place it in a dedicated header so all consumers include it unconditionally.
+
+### Before
+```cpp
+#include <QByteArrayView>
+
+void process(QByteArrayView data) {
+    qDebug() << data.size();
+}
+```
+
+### After
+```cpp
+#ifdef __OHOS__
+#include "qbytearrayview_shim.h"
+#else
+#include <QByteArrayView>
+#endif
+
+void process(QByteArrayView data) {
+    qDebug() << data.size();
+}
+```
+
+Where `qbytearrayview_shim.h` contains:
+
+```cpp
+#ifndef QBYTEARRAYVIEW_SHIM_H
+#define QBYTEARRAYVIEW_SHIM_H
+
+#include <QByteArray>
+
+class QByteArrayView {
+public:
+    QByteArrayView() = default;
+    QByteArrayView(const char *s) : m_data(s), m_size(s ? qstrlen(s) : 0) {}
+    QByteArrayView(const QByteArray &ba) : m_data(ba.constData()), m_size(ba.size()) {}
+
+    const char *data() const { return m_data; }
+    int size() const { return m_size; }
+    bool isEmpty() const { return m_size == 0; }
+    QByteArray toByteArray() const { return QByteArray(m_data, m_size); }
+
+private:
+    const char *m_data = nullptr;
+    int m_size = 0;
+};
+
+#endif
+```
+
+## Strategy B: Replace with QByteArray / typedef (when: isolated usage in 1-2 files)
+
+### Before
+```cpp
+QByteArrayView view = someFunc();
+consume(view);
+```
+
+### After
+```cpp
+#ifdef __OHOS__
+typedef QByteArray QByteArrayView;
+#endif
+
+QByteArrayView view = someFunc();
+consume(view);
+```
+
+⚠️ **Warning:** This typedef is fragile — `QByteArray` makes deep copies on construction from `const char*` while `QByteArrayView` is a non-owning view. Only use this if the call sites don't rely on view semantics (zero-copy, non-owning). Prefer Strategy C when QByteArrayView is used in container types or algorithm interfaces.
+
+## Strategy C: Typedef the Container Name + Adapt Algorithm (when: QByteArrayView used inside QVector/QList as a type parameter)
+
+This is the most common real-world pattern. When `QVector<QByteArrayView>` is used as an algorithm's input/output type, don't typedef `QByteArrayView` itself — instead typedef the **container type** to a semantic name (e.g., `SorterLines`), then branch the typedef between OHOS and non-OHOS. This avoids the fragile QByteArray→QByteArrayView equivalence while keeping the algorithm interface clean.
+
+### Before
+```cpp
+// Sorter.h
+#include <QVector>
+#include <QByteArrayView>
+
+typedef QVector<QByteArrayView> SorterLines;
+
+class Sorter {
+public:
+    virtual void sort(SorterLines &lines) const = 0;
+};
+```
+
+### After
+```cpp
+// Sorter.h
+#include <QVector>
+#include <QByteArray>
+#ifdef __OHOS__
+// OHOS: QByteArrayView does not exist in Qt5, use QByteArray
+typedef QVector<QByteArray> SorterLines;
+#else
+#include <QByteArrayView>
+typedef QVector<QByteArrayView> SorterLines;
+#endif
+
+class Sorter {
+public:
+    virtual void sort(SorterLines &lines) const = 0;
+};
+```
+
+Then adapt algorithm code that constructs or consumes `SorterLines`. On OHOS, convert elements individually:
+
+**Important prerequisite:** The code below calls `ByteArrayUtils::split()` which returns `QList<QByteArrayView>`. For this to compile on OHOS, `ByteArrayUtils.h` must provide its own QByteArrayView shim under `#ifdef __OHOS__` (see Strategy A). If you haven't patched `ByteArrayUtils.h` yet, the split result type on OHOS would be `QList<QByteArray>` instead, and the element-by-element conversion loop is unnecessary.
+
+### Before (algorithm consuming split result)
+```cpp
+QVector<QByteArrayView> lines = ByteArrayUtils::split(text, eol);
+sorter.sort(lines);
+QByteArray result = ByteArrayUtils::join(lines, eol);
+```
+
+### After (full branch)
+```cpp
+#ifdef __OHOS__
+    // ByteArrayUtils::split returns QList<QByteArrayView> using a shim in ByteArrayUtils.h.
+    // Convert to QVector<QByteArray> (SorterLines) for the sorter.
+    QList<QByteArrayView> viewLines = ByteArrayUtils::split(text, eol);
+    SorterLines lines;
+    lines.reserve(viewLines.size());
+    for (const auto &v : viewLines) {
+        lines.append(QByteArray(v.data(), v.size()));
+    }
+    sorter.sort(lines);
+    // ByteArrayUtils::join expects QByteArrayView — re-join manually from QByteArray
+    QByteArray result;
+    for (int i = 0; i < lines.size(); ++i) {
+        if (i > 0) result.append(eol);
+        result.append(lines[i]);
+    }
+#else
+    QVector<QByteArrayView> lines = ByteArrayUtils::split(text, eol).toVector();
+    sorter.sort(lines);
+    QByteArray result = ByteArrayUtils::join(lines, eol);
+#endif
+```
+
+**Note:** Introducing the `SorterLines` typedef also changes the **non-OHOS** code — the function signatures in `Sorter.cpp` use `SorterLines &lines` instead of `QVector<QByteArrayView> &lines`. This is intentional: the typedef makes both code paths share a single type name, differing only in the element type.
+
+And in the sorter implementations, branch the comparison:
+
+### Before
+```cpp
+void CaseInsensitiveSorter::sort(SorterLines &lines) const {
+    std::stable_sort(lines.begin(), lines.end(),
+        [dir = direction](const QByteArrayView &a, const QByteArrayView &b) {
+            int result = a.compare(b, Qt::CaseInsensitive);
+            return dir == Direction::Ascending ? (result < 0) : (result > 0);
+        });
+}
+```
+
+### After
+```cpp
+#ifdef __OHOS__
+void CaseInsensitiveSorter::sort(SorterLines &lines) const {
+    std::stable_sort(lines.begin(), lines.end(),
+        [dir = direction](const QByteArray &a, const QByteArray &b) {
+            int result = a.compare(b, Qt::CaseInsensitive);
+            return dir == Direction::Ascending ? (result < 0) : (result > 0);
+        });
+}
+#else
+void CaseInsensitiveSorter::sort(SorterLines &lines) const {
+    std::stable_sort(lines.begin(), lines.end(),
+        [dir = direction](const QByteArrayView &a, const QByteArrayView &b) {
+            int result = a.compare(b, Qt::CaseInsensitive);
+            return dir == Direction::Ascending ? (result < 0) : (result > 0);
+        });
+}
+#endif
+```
+
+## Common Mistakes
+
+- ❌ Don't `#include <QByteArrayView>` unconditionally on OHOS — the header simply doesn't exist and the compiler will error before reaching any workaround.
+- ❌ Don't implement the full Qt 6 QByteArrayView API in the shim — only add methods that are actually called, otherwise you'll waste time and risk mismatches.
+- ❌ Don't forget to handle `nullptr` in the shim constructor — `const char *` can be null and `qstrlen(nullptr)` is UB.
+- ❌ Don't use `typedef QByteArray QByteArrayView` when QByteArrayView is used inside a container (e.g., `QVector<QByteArrayView>`) — the deep-copy semantics of QByteArray will silently change behavior. Use Strategy C (typedef the container) instead.
+- ❌ Don't forget to adapt both the split (construction) and join (consumption) code paths when using Strategy C — the OHOS path cannot use ByteArrayUtils::join with QByteArray elements if it expects QByteArrayView.
+
+## Related Symbols
+
+- `QByteArray` — underlying storage type used by the shim and Strategy C
+- `QStringView` — analogous Qt6-only type that may need a similar shim
+- `QVector` / `QList` — container types that may need the SorterLines typedef pattern

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

@@ -0,0 +1,46 @@
+# QCalendar: Qt 5.15 OHOS SDK Missing Class
+
+## Problem
+
+QCalendar is not available in the Qt 5.15.17 OHOS SDK. Code referencing QCalendar fails to compile because the class header and symbols are absent.
+
+## Context Decision
+
+If the QCalendar usage is for locale-aware calendar calculations that can be approximated with QDate, guard and replace. If QCalendar is central to the feature and the Gregorian-only fallback is unacceptable, the feature must be disabled on OHOS.
+
+## Strategy A: Guard with #ifndef __OHOS__ and Use QDate Fallback (when: calendar logic is Gregorian-only or can tolerate Gregorian approximation)
+
+Replace QCalendar calls with equivalent QDate operations. QDate's built-in methods (dayOfWeek(), daysInMonth(), daysInYear()) cover the common Gregorian use cases.
+
+### Before
+```cpp
+#include <QCalendar>
+
+QCalendar cal;
+int days = cal.daysInMonth(month, year);
+```
+
+### After
+```cpp
+#ifndef __OHOS__
+#include <QCalendar>
+#endif
+
+#ifndef __OHOS__
+QCalendar cal;
+int days = cal.daysInMonth(month, year);
+#else
+QDate date(year, month, 1);
+int days = date.daysInMonth();
+#endif
+```
+
+## Common Mistakes
+
+- ❌ Don't include `<QCalendar>` unconditionally on OHOS — the header does not exist and will cause a fatal build error.
+- ❌ Don't assume `QCalendar::Gregorian` enum exists — the entire QCalendar class is missing, not just some methods.
+- ❌ Don't silently skip the calendar feature without documenting it — add a comment explaining the OHOS limitation.
+
+## Related Symbols
+
+- `QDate` — fallback for Gregorian calendar operations on OHOS

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

@@ -0,0 +1,56 @@
+# QDataStream << enum: Qt5 Cannot Serialize Enum Values Directly
+
+## Problem
+
+Qt5 cannot serialize enum values directly via QDataStream. The `<<` and `>>` operators for QDataStream only work with Qt-registered types and fundamental types. Writing `stream << myEnum` produces a compile error because no matching operator is found.
+
+## Context Decision
+
+This applies to all enum serialization via QDataStream on Qt5. Use the cast strategy unconditionally — it works on both Qt5 and Qt6 and is zero-cost at runtime.
+
+## Strategy A: Cast to qint32 for Serialization (when: always — this is the universal fix)
+
+Cast enum values to `qint32` on write and cast back to the enum type on read. This preserves the binary layout and works across all Qt5 versions.
+
+### Before
+```cpp
+enum class Color { Red, Green, Blue };
+
+QDataStream &operator<<(QDataStream &out, Color c) {
+    out << c;
+    return out;
+}
+
+QDataStream &operator>>(QDataStream &in, Color &c) {
+    in >> c;
+    return in;
+}
+```
+
+### After
+```cpp
+enum class Color { Red, Green, Blue };
+
+QDataStream &operator<<(QDataStream &out, Color c) {
+    out << static_cast<qint32>(c);
+    return out;
+}
+
+QDataStream &operator>>(QDataStream &in, Color &c) {
+    qint32 v;
+    in >> v;
+    c = static_cast<Color>(v);
+    return in;
+}
+```
+
+## Common Mistakes
+
+- ❌ Don't register the enum with `Q_DECLARE_METATYPE` and expect QDataStream to work — `Q_DECLARE_METATYPE` helps QVariant, not QDataStream.
+- ❌ Don't cast to `int` instead of `qint32` — `int` size varies by platform and breaks binary compatibility when streaming across architectures.
+- ❌ Don't forget to cast back on deserialization — reading into a `qint32` and assigning without `static_cast` won't compile for scoped enums.
+
+## Related Symbols
+
+- `QDataStream` — the serialization class that lacks enum operators in Qt5
+- `Q_DECLARE_METATYPE` — helps QVariant but does NOT add QDataStream operators

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

@@ -0,0 +1,162 @@
+# Fix: Missing Transitive Includes (QDebug, QUrl, QCloseEvent, etc.)
+
+## Context
+
+In Qt6, many headers are included transitively via other Qt headers (e.g., `<QDebug>` via `<QApplication>`, `<QUrl>` via `<QGuiApplication>`, `<QCloseEvent>` via `<QWidget>`). Code that works on Qt6 may fail on Qt5 with "incomplete type" or "forward declaration" errors because Qt5 does NOT include these headers transitively.
+
+This is a **systemic problem** — not limited to `<QDebug>`. The same pattern affects any Qt type that is forward-declared in a widely-included header but only fully defined in its own header file.
+
+**Error patterns:**
+```
+// Missing <QDebug>
+error: calling 'warning' with incomplete return type 'QDebug'
+    qWarning() << "message";
+note: forward declaration of 'QDebug'
+
+// Missing <QUrl>
+error: variable has incomplete type 'QUrl'
+    QUrl fileUrl(file);
+note: forward declaration of 'QUrl'
+
+// Missing <QCloseEvent>
+error: member access into incomplete type 'QCloseEvent'
+    event->accept();
+note: forward declaration of 'QCloseEvent'
+```
+
+## Decision
+
+| Condition | Strategy |
+|-----------|----------|
+| File uses `qWarning()`, `qInfo()`, or `qDebug()` with `<<` operator | Strategy A (add `<QDebug>`) |
+| File constructs `QUrl` objects or calls QUrl methods | Strategy B (add `<QUrl>`) |
+| File accesses `QCloseEvent` members (e.g., `event->accept()`, `event->ignore()`) | Strategy C (add `<QCloseEvent>`) |
+| File uses any other forward-declared Qt type as a complete type | Strategy D (add the specific header) |
+| File uses `qWarning()`/`qInfo()`/`qDebug()` without `<<` (just `qWarning("format", args...)`) | No fix needed (printf-style works without QDebug) |
+
+## Strategy A: Add `#include <QDebug>`
+
+Add `#include <QDebug>` to the file's includes if it uses streaming-style logging.
+
+### Before
+```cpp
+#include <QStatusBar>
+#include <QLineEdit>
+
+// ... later in code ...
+qWarning() << "Cannot locate action named" << fullObjectName;
+qInfo() << "Loading stylesheet:" << f.fileName();
+```
+
+### After
+```cpp
+#include <QStatusBar>
+#include <QLineEdit>
+#include <QDebug>
+
+// ... later in code (unchanged) ...
+qWarning() << "Cannot locate action named" << fullObjectName;
+qInfo() << "Loading stylesheet:" << f.fileName();
+```
+
+### Guarding
+
+For OHOS-only builds, you can guard the include:
+```cpp
+#ifdef __OHOS__
+#include <QDebug>
+#endif
+```
+However, `#include <QDebug>` is harmless on Qt6 too, so a plain unconditional include is preferred for simplicity.
+
+## Strategy B: Add `#include <QUrl>`
+
+Qt6 includes `<QUrl>` transitively via `<QApplication>`, `<QGuiApplication>`, `<QDesktopServices>`, etc. Qt5 does not. Any file that constructs `QUrl` objects, calls `QUrl` methods, or passes `QUrl` to functions that require a complete type will fail.
+
+### Before
+```cpp
+#include <QApplication>
+// No #include <QUrl> — works on Qt6 because QApplication transitively includes it
+
+QUrl fileUrl(file);
+if (fileUrl.isValid()) { ... }
+```
+
+### After
+```cpp
+#include <QApplication>
+#ifdef __OHOS__
+#include <QUrl>
+#endif
+
+QUrl fileUrl(file);
+if (fileUrl.isValid()) { ... }
+```
+
+**Common trigger points:** `QDesktopServices::openUrl()`, `QUrl()`, `url.toString()`, `url.isValid()`, any function taking/returning `QUrl`.
+
+## Strategy C: Add `#include <QCloseEvent>`
+
+Qt6 includes `<QCloseEvent>` transitively via `<QWidget>`. Qt5 only forward-declares it in `<QWidget>`. Any code that accesses `QCloseEvent` members (even just `event->accept()`) needs the full definition.
+
+This is especially common after applying the `closeevent.md` fix — the OHOS guard calls `event->accept()` which requires the complete type.
+
+### Before
+```cpp
+#include <QWidget>
+
+void MyDialog::closeEvent(QCloseEvent *event) {
+#ifdef __OHOS__
+    event->accept();  // ERROR: incomplete type QCloseEvent
+#else
+    QDialog::closeEvent(event);
+#endif
+}
+```
+
+### After
+```cpp
+#include <QWidget>
+#ifdef __OHOS__
+#include <QCloseEvent>
+#endif
+
+void MyDialog::closeEvent(QCloseEvent *event) {
+#ifdef __OHOS__
+    event->accept();
+#else
+    QDialog::closeEvent(event);
+#endif
+}
+```
+
+**Common trigger points:** `closeEvent()` overrides that call `event->accept()`, `event->ignore()`, or access any `QCloseEvent` member.
+
+## Strategy D: Add the Specific Header (when: any other forward-declared Qt type used as complete type)
+
+The same pattern applies to many other Qt types. Below is a reference table of commonly forward-declared types that may need explicit includes on Qt5/OHOS:
+
+| Type | Header to Include | Forward-declared in |
+|------|-------------------|-------------------|
+| `QDebug` | `<QDebug>` | `<qlogging.h>` (via many headers) |
+| `QUrl` | `<QUrl>` | `<QApplication>`, `<QGuiApplication>`, `<QDesktopServices>` |
+| `QCloseEvent` | `<QCloseEvent>` | `<QWidget>` |
+| `QKeyEvent` | `<QKeyEvent>` | `<QWidget>` |
+| `QMouseEvent` | `<QMouseEvent>` | `<QWidget>` |
+| `QAction` | `<QAction>` | `<QWidget>` (Qt5), `<QShortcut>` |
+| `QPainter` | `<QPainter>` | `<QPaintEvent>` sometimes |
+| `QMetaMethod` | `<QMetaMethod>` | `<QObject>` |
+| `QStyleOptionViewItem` | `<QStyleOptionViewItem>` | `<QAbstractItemView>` |
+| `QTextBlock` | `<QTextBlock>` | `<QTextDocument>` |
+| `QTextCursor` | `<QTextCursor>` | `<QTextEdit>` |
+
+**General rule:** If you see `error: incomplete type 'QFoo'` or `error: forward declaration of 'QFoo'`, add `#include <QFoo>` under `#ifdef __OHOS__`. The include is harmless on Qt6.
+
+## Common Mistakes
+
+1. **Don't replace `qWarning()` with `qWarning("format")`** — the streaming API is more flexible and works fine once `<QDebug>` is included.
+2. **Don't add `#include <QtDebug>`** — that's a Qt6-only convenience header. Use `<QDebug>`.
+3. **Don't forget header files** — if a `.h` file uses `qWarning() <<`, it also needs `#include <QDebug>`.
+4. **Check transitive includes** — if the `.cpp` includes a `.h` that already has `#include <QDebug>`, you don't need to add it again. But be safe and add it if in doubt.
+5. **Don't assume the error is only about QDebug** — the same "incomplete type" pattern applies to `QUrl`, `QCloseEvent`, `QKeyEvent`, and many other Qt types. Check the error message to identify which type is incomplete and add its header.
+6. **Don't add the include only in the .cpp** — if a `.h` file uses the type (e.g., `QCloseEvent *event` in a virtual function override), the header may also need the include. However, for parameter types that are only used as pointers/references, a forward declaration suffices in the header — you only need the full include in the `.cpp` where members are accessed.

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

@@ -0,0 +1,122 @@
+# Q_DECLARE_METATYPE / QMap with Incomplete Type — connect() Cascade
+
+## Problem
+
+When a header uses `QMap<int, T>` or `QSet<T>` where `T` is a nested type (like `OtherClass::Details`) and `OtherClass` is only forward-declared (not fully included), Qt5 fails to instantiate the template. This failure cascades into `connect()` template deduction errors that look like a `QObject` inheritance problem but are actually caused by the incomplete type.
+
+The typical error cascade:
+
+1. `QMap<int, OtherClass::Details>` can't instantiate because `OtherClass` is only forward-declared → `OtherClass::Details` is inaccessible
+2. `QtPrivate::FunctionPointer` can't deduce the slot's object type (the broken QMap poisoned the template context)
+3. `QObject::connect()` template can't convert `MyHandler*` → `const QObject*`
+4. You see 8+ errors like:
+```
+error: cannot initialize a parameter of type 'const QObject *' 
+  with an lvalue of type 'const typename QtPrivate::FunctionPointer<void (MyHandler::*)()>::Object *'
+  (aka 'const MyHandler *')
+```
+
+**Root cause is always the incomplete type (forward declaration where full include is needed), not the QObject inheritance or the connect() syntax.**
+
+Note: `Q_DECLARE_METATYPE(T)` itself may be correctly placed (after the full definition of `T`). The problem is that a *different* header tries to use `T` (e.g., inside a `QMap<K,T>`) with only a forward declaration of the enclosing class. Fixing the include resolves both the QMap and the connect() errors simultaneously.
+
+## Typical Trigger Pattern
+
+```cpp
+// checkthread.h
+struct Details { int threadIndex; QString file; QTime startTime; };
+Q_DECLARE_METATYPE(CheckThread::Details);  // OK: Details is fully defined above
+
+// threadhandler.h
+class CheckThread;  // forward declaration only!
+
+class ThreadHandler : public QObject {
+    Q_OBJECT
+signals:
+    void threadDetailsUpdated(QMap<int, CheckThread::Details> details);
+    //                                   ^^^^^^^^^^^^^^^^^^^^^^
+    // QMap needs CheckThread::Details fully defined
+    // Q_DECLARE_METATYPE(CheckThread::Details) was in checkthread.h
+    // but QMap<int, CheckThread::Details> can't instantiate with
+    // only a forward declaration of CheckThread
+};
+```
+
+## Context Decision
+
+- If the type IS fully defined in another header that should be included → **Strategy A**.
+- If the `Q_DECLARE_METATYPE` is in the wrong location → **Strategy B**.
+- If the type is used as a signal parameter via `QMap<K,V>` and `V` is incomplete → **Strategy A + see qmap-forward-decl.md**.
+
+## Strategy A: Replace Forward Declaration with Full Include
+
+The most common fix: the header has a forward declaration where it should have a full include.
+
+### Before
+```cpp
+// threadhandler.h
+class CheckThread;  // forward declaration — NOT ENOUGH for Qt5
+
+class ThreadHandler : public QObject {
+    Q_OBJECT
+    QMap<int, CheckThread::Details> mThreadDetails;  // ERROR: CheckThread::Details not accessible
+};
+```
+
+### After
+```cpp
+// threadhandler.h
+#include "checkthread.h"  // full include — provides CheckThread::Details definition
+
+class ThreadHandler : public QObject {
+    Q_OBJECT
+    QMap<int, CheckThread::Details> mThreadDetails;  // OK: full type available
+};
+```
+
+**Note**: This also resolves the `QMap` forward-declaration issue (see `qmap-forward-decl.md`). The two problems often co-occur.
+
+## Strategy B: Move Q_DECLARE_METATYPE After Full Definition (rare)
+
+If `Q_DECLARE_METATYPE` is genuinely placed before the full class definition in the same header:
+
+### Before
+```cpp
+class MyType;  // forward declaration
+Q_DECLARE_METATYPE(MyType);  // PROBLEM: MyType is incomplete at this point
+
+class MyType { ... };  // too late!
+```
+
+### After
+```cpp
+class MyType { ... };  // full definition first
+Q_DECLARE_METATYPE(MyType);  // OK: MyType is complete
+```
+
+**However**, in practice, `Q_DECLARE_METATYPE` is almost always correctly placed after the class definition (at the bottom of the header). The real problem is usually Strategy A — a *different* header using the type with only a forward declaration. If you're seeing the cascade error, check Strategy A first before assuming Q_DECLARE_METATYPE is misplaced.
+
+## The Cascade Error Explained
+
+When a header uses a type inside a container (`QMap`, `QSet`, etc.) but the enclosing class is only forward-declared, the cascade looks like:
+
+1. `QMap<int, OtherClass::Details>` can't instantiate → `implicit instantiation of undefined template 'QMap<int, OtherClass::Details>'` (if `<QMap>` is missing) or `OtherClass::Details has not been declared` (if `OtherClass` is only forward-declared)
+2. `QtPrivate::FunctionPointer` can't deduce the slot's object type (the broken template context propagates)
+3. `QObject::connect()` template can't convert `MyHandler*` → `const QObject*`
+4. You see 8+ "cannot initialize a parameter of type 'const QObject*'" errors
+
+**Root cause is always the incomplete type / missing include, not the QObject inheritance or the connect() syntax.** Fix the include (add `#include "otherclass.h"` + `#include <QMap>`), and the connect() errors disappear automatically — no need to touch any `connect()` call.
+
+## Common Mistakes
+
+- ❌ Don't try to fix the `connect()` error by adding casts or changing the connect syntax — the root cause is the incomplete type / missing include, not the signal/slot connection.
+- ❌ Don't assume `Q_DECLARE_METATYPE` is misplaced — it's usually correct (after the full class definition). The problem is that a *different* header tries to use the type with only a forward declaration.
+- ❌ Don't confuse this with the QMap forward-declaration issue — they're the same root cause viewed from different angles. Fixing the include (Strategy A) resolves both simultaneously.
+- ❌ Don't use `qRegisterMetaType<T>("T")` at runtime as a workaround for missing `Q_DECLARE_METATYPE` — while it can work for some cases, it doesn't fix the compile-time template deduction errors that cause the connect() cascade.
+- ❌ Don't waste time debugging the `QObject*` conversion error — it's always a symptom, never the cause. Trace back to the first error (usually `implicit instantiation of undefined template QMap<...>` or `has not been declared`) to find the real missing include.
+
+## Related Symbols
+
+- `QMap<T,U>` / `QSet<T>` — see `qmap-forward-decl.md` for the container-specific instantiation issue
+- `Q_DECLARE_METATYPE` — macro that registers a type for use in signal/slot connections
+- `qRegisterMetaType<T>()` — runtime registration (complement to Q_DECLARE_METATYPE)

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

@@ -0,0 +1,70 @@
+# QDesktopServices::openUrl: Doesn't Work on OHOS
+
+## Problem
+
+QDesktopServices::openUrl() doesn't work on OHOS because there is no desktop shell to handle URL dispatch. The call silently fails or does nothing. On OHOS, opening a URL requires using the Ability framework via QOpenHarmonyAbility.
+
+## Context Decision
+
+This fix applies only on OHOS. On desktop platforms, QDesktopServices works correctly and should be kept. Use `#ifdef __OHOS__` to dispatch to the OHOS-specific implementation.
+
+## Strategy A: Replace with QOpenHarmonyAbility::start(want) (when: running on OHOS and need to open URLs/files)
+
+Use QOpenHarmonyAbility to create an OHOS Want and start the appropriate Ability. Set `want.uri` directly as a public member — do NOT call `want.setUri()` which may not exist in all SDK versions. You also need `#include <QUrl>` for `url.toString()`.
+
+### Important: Include Path
+
+The OhExtras module uses **module-prefixed lowercase paths** — NOT the capitalized forwarding headers that standard Qt modules provide. The correct include is:
+
+```cpp
+#include <QtOhExtras/qopenharmonyability.h>
+```
+
+This works because CMake adds `-isystem .../include/QtOhExtras` to the include path, so the compiler finds `qopenharmonyability.h` within that directory.
+
+The capitalized form `<QOpenHarmonyAbility>` does NOT exist as a forwarding header in the OhExtras SDK (unlike standard Qt modules which provide both `QtCore/QString` and `QString`).
+
+### Before
+```cpp
+#include <QDesktopServices>
+
+void openLink(const QUrl &url) {
+    QDesktopServices::openUrl(url);
+}
+```
+
+### After
+```cpp
+#include <QDesktopServices>
+#include <QUrl>
+#ifdef __OHOS__
+#include <QtOhExtras/qopenharmonyability.h>
+#endif
+
+void openLink(const QUrl &url) {
+#ifdef __OHOS__
+    QOpenHarmonyWant want;
+    want.uri = url.toString();
+    QOpenHarmonyAbility::start(want);
+#else
+    QDesktopServices::openUrl(url);
+#endif
+}
+```
+
+## Common Mistakes
+
+- ❌ Don't use `#include <QOpenHarmonyAbility>` (capitalized forwarding header) — the OhExtras module does NOT provide capitalized forwarding headers like standard Qt modules do. Use `#include <QtOhExtras/qopenharmonyability.h>` (module-prefixed lowercase path) instead.
+- ❌ Don't use `#include <qopenharmonyability.h>` (bare lowercase without module prefix) — this won't work with the standard CMake include path setup (`-isystem .../include/QtOhExtras`), because the compiler looks for `qopenharmonyability.h` within the `QtOhExtras/` directory, not at the top-level include path. Always use the module-prefixed form: `#include <QtOhExtras/qopenharmonyability.h>`.
+- ❌ Don't call `want.setUri(url.toString())` — use direct member assignment `want.uri = url.toString()` as `setUri()` may not exist in some SDK versions.
+- ❌ Don't use `OHOS::AppExecFwk::Want` (the raw NDK type) — always use `QOpenHarmonyWant` (the Qt wrapper class provided by OhExtras).
+- ❌ Don't forget `#include <QUrl>` — it's needed for `url.toString()` and may not be transitively included on Qt5/OHOS. See `qdebug-include.md` Strategy B.
+- ❌ Don't forget to handle the case where no Ability can handle the URL — QOpenHarmonyAbility::start can fail silently; consider logging or showing a user-facing error.
+- ❌ Don't remove the QDesktopServices path for non-OHOS builds — it still works correctly on Linux/Windows/macOS.
+- ❌ Don't forget to add `Qt5::OhExtras` to `find_package()` and `target_link_libraries()` in CMake — without it, the linker will report undefined references to `QOpenHarmonyAbility::start()`.
+
+## Related Symbols
+
+- `QOpenHarmonyAbility` — OHOS-specific ability launcher (from Qt5::OhExtras)
+- `QOpenHarmonyWant` — Qt wrapper for OHOS Want/Intent (from Qt5::OhExtras)
+- `QDesktopServices` — standard Qt URL opener (works on desktop, not OHOS)