SWIP-12 design + UITemplateInitializer auto-discovery & dev hot-reload (#13834)

**1. SWIP-12 design doc** (`docs/en/swip/SWIP-12.md`)
Proposes WeChat & Alipay Mini-Program monitoring as a new pair of `Layer` values. Covers SDK alignment (histogram bucket unit), native-trace SegmentListener SPI, entity model, layer partitioning, dashboards layout, and MAL/OAL scope split. Still a design-only proposal — implementation lands in follow-up PRs.

**2. UITemplateInitializer extensibility + dev hot-reload**
- `UI_TEMPLATE_FOLDER` is now computed from `Layer.values() + "custom"` at class-init time. Adding a new `Layer` enum value is enough — drop a `ui-initialized-templates/<layer-name-lowercased>/` folder on disk and it's scanned on the next boot. Removes the prior hardcoded allowlist that was easy to miss.
- `SW_UI_TEMPLATE_FORCE_RELOAD` env var switches the initializer from `addIfNotExist` to a new `addOrReplace` helper on `UITemplateManagementService`. When true, shipped templates overwrite any seeded copy every boot — so dev/extension edits show up after a simple OAP restart without wiping storage. Unset / false preserves the production behavior where operator UI edits persist.
- `UITemplateCheckerTest` updated to tolerate missing folders (several `Layer` values have no template folders today).

**3. `new-monitoring-feature` skill** (`.claude/skills/new-monitoring-feature/SKILL.md`)
A wiring map for contributors adding a new layer: which extension point handles which signal (OAL / MAL / LAL / SpanListener / SegmentListener), where contracts live, UI template + submodule touchpoints, and cross-cutting traps.

Author: wu-sheng

.claude/skills/new-monitoring-feature/SKILL.md

@@ -68,12 +68,13 @@ All accepted and proposed SWIPs can be found in [here](https://github.com/apache
 
 ## Known SWIPs
 
-Next SWIP Number: 12
+Next SWIP Number: 13
 
 ### Proposed SWIPs
 
 ### Accepted SWIPs
 
+- [SWIP-12 Support WeChat & Alipay Mini Program Monitoring](SWIP-12.md)
 - [SWIP-11 Support iOS App Monitoring via OpenTelemetry](SWIP-11.md)
 - [SWIP-10 Support Envoy AI Gateway Observability](SWIP-10/SWIP.md)
 - [SWIP-9 Support Flink Monitoring](SWIP-9.md)

docs/en/swip/SWIP-12.md

@@ -25,8 +25,10 @@
 import java.io.File;
 import java.io.FileNotFoundException;
 import java.io.IOException;
+import java.util.Arrays;
 import java.util.List;
 import java.util.Objects;
+import java.util.stream.Stream;
 import org.apache.skywalking.oap.server.core.CoreModule;
 import org.apache.skywalking.oap.server.core.analysis.Layer;
 import org.apache.skywalking.oap.server.core.query.input.DashboardSetting;
@@ -39,53 +41,37 @@
  * UITemplateInitializer load the template from the config file in json format. It depends on the UI implementation only.
  * Each config file should be only one dashboard setting json object.
  * The dashboard names should be different in the same Layer and entity.
+ * <p>
+ * Folder discovery is automatic: every {@link Layer} enum value is probed as a folder
+ * (via {@code Layer.name().toLowerCase()}) plus the {@code "custom"} slot. Folders that
+ * don't exist are silently skipped. Extensions adding a new {@code Layer} do not need to
+ * touch this class.
+ * <p>
+ * Dev/extension reload: when environment variable {@code SW_UI_TEMPLATE_FORCE_RELOAD}
+ * is {@code true}, each template on disk is written via {@code addOrReplace} rather
+ * than {@code addIfNotExist}, so edits to shipped JSON take effect on the next OAP
+ * restart without needing to wipe the storage container.
  */
 @Slf4j
 public class UITemplateInitializer {
-    public static String[] UI_TEMPLATE_FOLDER = new String[] {
-        Layer.MESH.name(),
-        Layer.GENERAL.name(),
-        Layer.OS_LINUX.name(),
-        Layer.MESH_CP.name(),
-        Layer.MESH_DP.name(),
-        Layer.MYSQL.name(),
-        Layer.POSTGRESQL.name(),
-        Layer.K8S.name(),
-        Layer.BROWSER.name(),
-        Layer.SO11Y_OAP.name(),
-        Layer.VIRTUAL_DATABASE.name(),
-        Layer.VIRTUAL_CACHE.name(),
-        Layer.K8S_SERVICE.name(),
-        Layer.SO11Y_SATELLITE.name(),
-        Layer.APISIX.name(),
-        Layer.VIRTUAL_MQ.name(),
-        Layer.AWS_EKS.name(),
-        Layer.OS_WINDOWS.name(),
-        Layer.AWS_S3.name(),
-        Layer.AWS_DYNAMODB.name(),
-        Layer.AWS_GATEWAY.name(),
-        Layer.REDIS.name(),
-        Layer.ELASTICSEARCH.name(),
-        Layer.RABBITMQ.name(),
-        Layer.MONGODB.name(),
-        Layer.KAFKA.name(),
-        Layer.PULSAR.name(),
-        Layer.BOOKKEEPER.name(),
-        Layer.NGINX.name(),
-        Layer.ROCKETMQ.name(),
-        Layer.CLICKHOUSE.name(),
-        Layer.ACTIVEMQ.name(),
-        Layer.CILIUM_SERVICE.name(),
-        Layer.SO11Y_JAVA_AGENT.name(),
-        Layer.KONG.name(),
-        Layer.SO11Y_GO_AGENT.name(),
-        Layer.FLINK.name(),
-        Layer.BANYANDB.name(),
-        Layer.VIRTUAL_GENAI.name(),
-        Layer.ENVOY_AI_GATEWAY.name(),
-        Layer.IOS.name(),
-        "custom"
-    };
+    /**
+     * Every {@link Layer} enum value, lower-cased, plus the {@code "custom"} folder.
+     * Computed once from {@link Layer#values()} so adding a new {@code Layer} automatically
+     * causes its {@code ui-initialized-templates/<layer>/} folder to be scanned.
+     */
+    public static final String[] UI_TEMPLATE_FOLDER = Stream.concat(
+        Arrays.stream(Layer.values()).map(Layer::name),
+        Stream.of("custom")
+    ).toArray(String[]::new);
+
+    /**
+     * Environment variable: when {@code true}, templates on disk overwrite any previously
+     * seeded copy in storage on every boot. Read from the OS environment directly so
+     * operators / extenders can flip it without touching {@code application.yml}.
+     */
+    private static final boolean FORCE_RELOAD =
+        Boolean.parseBoolean(System.getenv("SW_UI_TEMPLATE_FORCE_RELOAD"));
+
     private final UITemplateManagementService uiTemplateManagementService;
     private final ObjectMapper mapper;
 
@@ -98,6 +84,9 @@ public UITemplateInitializer(ModuleManager manager) {
     }
 
     public void initAll() throws IOException {
+        if (FORCE_RELOAD) {
+            log.info("SW_UI_TEMPLATE_FORCE_RELOAD=true — shipped UI templates will overwrite any previously seeded copy on this boot.");
+        }
         for (String folder : UITemplateInitializer.UI_TEMPLATE_FOLDER) {
             try {
                 File[] templateFiles = ResourceUtils.getPathFiles("ui-initialized-templates/" + folder.toLowerCase());
@@ -128,7 +117,11 @@ public void initTemplate(File template) throws IOException {
         setting.setId(inId);
         setting.setConfiguration(configNode.toString());
 
-        uiTemplateManagementService.addIfNotExist(setting);
+        if (FORCE_RELOAD) {
+            uiTemplateManagementService.addOrReplace(setting);
+        } else {
+            uiTemplateManagementService.addIfNotExist(setting);
+        }
     }
 
     private void verifyNameConflict(File template, String inId, String inNameKey) throws IOException {

docs/en/swip/readme.md

@@ -75,4 +75,19 @@ public void addIfNotExist(DashboardSetting setting) throws IOException {
             getUITemplateManagementDAO().addTemplate(setting);
         }
     }
+
+    /**
+     * Add or replace: if a template with the same id already exists, overwrite it;
+     * otherwise create a new one. Used by the initializer when
+     * {@code SW_UI_TEMPLATE_FORCE_RELOAD=true} so that edits to shipped templates
+     * take effect without wiping the storage container.
+     */
+    public void addOrReplace(DashboardSetting setting) throws IOException {
+        DashboardConfiguration configuration = getUITemplateManagementDAO().getTemplate(setting.getId());
+        if (configuration == null) {
+            getUITemplateManagementDAO().addTemplate(setting);
+        } else {
+            getUITemplateManagementDAO().changeTemplate(setting);
+        }
+    }
 }

oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/management/ui/template/UITemplateInitializer.java

@@ -28,6 +28,7 @@
 import org.junit.jupiter.api.Test;
 
 import java.io.File;
+import java.io.FileNotFoundException;
 import java.io.IOException;
 import java.util.HashSet;
 import java.util.Locale;
@@ -45,8 +46,15 @@ public void validateUITemplate() throws IOException {
         Set<String> dashboardIds = new HashSet<>();
         Set<String> dashboardNames = new HashSet<>();
         for (String folder : UITemplateInitializer.UI_TEMPLATE_FOLDER) {
-            File[] templateFiles = ResourceUtils.getPathFiles("ui-initialized-templates/" + folder.toLowerCase(
-                Locale.ROOT));
+            File[] templateFiles;
+            try {
+                templateFiles = ResourceUtils.getPathFiles("ui-initialized-templates/" + folder.toLowerCase(
+                    Locale.ROOT));
+            } catch (FileNotFoundException e) {
+                // Layer enum values without an on-disk template folder are skipped —
+                // mirrors UITemplateInitializer.initAll() behavior post-auto-discovery.
+                continue;
+            }
             for (File template : templateFiles) {
                 JsonNode jsonNode;
                 try {