@nebula-skills/nebula-code-standards 0.1.0

package/skill/init-new-project.md

@@ -0,0 +1,842 @@
+# 新 Nebula 项目初始化向导
+
+> 用户说「初始化新 nebula 项目」「按 nebula 规范起一个项目」「新建业务模块（前后端）」时，AI 进入本向导。目标：**一条指令把前后端跑起来 + Swagger 能调通 + 主应用菜单能点开子应用**。
+>
+> 本向导是规则文档，**不依赖任何具体业务样板项目**。生成的代码 100% 来自规则推导。
+
+---
+
+## 一、技术栈基线（强制）
+
+生成的项目**必须**对齐这套版本，避免和现有生态不兼容：
+
+| 技术 | 版本 | 备注 |
+|------|------|------|
+| JDK | `17` | 强制；用 nebula-boot 必须 JDK 17 |
+| Gradle | `8.12`（Wrapper） | 必须通过 `gradlew` 调用，不依赖本机 Gradle |
+| Spring Boot | `3.5.9` | 由 `nebula-boot-dependencies` BOM 管理 |
+| Spring Cloud | `2025.0.0` | 由 BOM 管理 |
+| MyBatis-Plus | `3.5.9` | 由 BOM 管理 |
+| nebula-support | `0.1.22-SNAPSHOT` | 实际以最新发布版为准 |
+| nebula-boot | `0.1.22-SNAPSHOT` | |
+| nebula-auth | `0.1.8-SNAPSHOT` | |
+| nebula-system | `0.2.47-SNAPSHOT` | |
+| Vue | `3.5.x` | 前端 |
+| Vite | `5.x` | |
+| TypeScript | `5.5+` | |
+| Node.js | `>= 22` | 强制 |
+| pnpm | `>= 9` | 强制 |
+| IceStark | `2.8.x` | 微前端 |
+
+### IntelliJ IDEA 必备配置
+
+向导结束时**必须**告知用户在 IDEA 中调整以下设置（否则编译会失败或行为异常）：
+
+1. **Project SDK**：`File → Project Structure → Project → SDK = 17`
+2. **Project language level**：`17`
+3. **Gradle JVM**：`File → Settings → Build, Execution, Deployment → Build Tools → Gradle → Gradle JVM = 17`
+4. **Gradle build and run using**：选 `Gradle`（而非 IDEA）以保证 Wrapper 行为一致
+5. **Java Compiler target bytecode version**：`17`
+6. **Annotation Processing**：`File → Settings → Build, Execution, Deployment → Compiler → Annotation Processors → Enable annotation processing`（Lombok / MapStruct 必需）
+7. **File Encoding**：`Settings → Editor → File Encodings → 全选 UTF-8 + Transparent native-to-ascii conversion ✅`
+8. 必装插件：`Lombok` / `MapStruct Support` / `MyBatisX` / `Save Actions`（可选）
+
+---
+
+## 二、触发关键词
+
+以下任一关键词触发本向导：
+
+- 「初始化 / 新建 / 起一个 nebula 项目 / 业务模块」
+- 「按 nebula 规范创建新工程」
+- 「一条指令把前后端跑起来」
+- 用户指定项目名（如 `mes` / `scm` / `oa`），且当前不存在对应仓库
+
+---
+
+## 三、向导总览
+
+```
+阶段 1：需求摸底（AskUserQuestion 7 道题）
+   ↓
+阶段 2：依赖连通性检测（Bash nc + mysql/redis-cli）
+   ↓
+阶段 3：后端骨架生成（Gradle 四层 + Application + application.yml + Flyway + Demo CRUD + 3 个必备 SPI 空实现）
+   ↓
+阶段 4：前端骨架生成（独立仓库 / monorepo 内置二选一，参考 [[microapp-guide]]）
+   ↓
+阶段 5：启动验证 + 配置修改指引（Gradle 命令 + MySQL/Redis 修改位置）
+   ↓
+阶段 6：收尾交付清单（git init / 启动命令 / IDEA 配置 / 后续 TODO）
+```
+
+每个阶段如遇异常（端口冲突、连接失败、文件已存在、Nexus 拉取失败），AI **必须** 用 AskUserQuestion 让用户决策，**禁止** 自行覆盖或跳过。
+
+---
+
+## 四、阶段 1：需求摸底
+
+按以下顺序发出 AskUserQuestion（一次发一题或合并发，但不能跳过）：
+
+### Q1：项目范围
+- 仅后端
+- 仅前端
+- 前后端一起（推荐）
+
+### Q2：项目 domain（小写英文）
+- 用户输入示例：`mes` / `scm` / `oa`
+- AI 自动派生（再让用户确认或自定义）：
+
+| 派生项 | 规则 | 示例（domain=mes） |
+|--------|------|-------------------|
+| 后端 group | `com.huida.{domain}` | `com.huida.mes` |
+| 后端工件 | `nebula-{domain}-{api/core/starter/server}` | `nebula-mes-api/core/starter/server` |
+| 后端端口（建议） | `80XX` 段，避开 `9010` / `8081` / `8080` | `8082` |
+| 数据库名 | `nebula_{domain}` | `nebula_mes` |
+| 表前缀 | `t_` | `t_demo` |
+| 前端工件 | `nebula-{domain}-web` | `nebula-mes-web` |
+| IceStark name | `nebula{PascalDomain}App` / `{domain}app` | `nebulaMesApp` / `mesapp` |
+| 前端端口（建议） | `30XX` 段，避开 `3000/3001/3002` | `3004` |
+| API 前缀 | `/nebula-{domain}` | `/nebula-mes` |
+
+### Q3：MySQL 配置
+- host（默认 `localhost`）
+- port（默认 `3306`）
+- 用户名 / 密码
+- 数据库不存在时：自动建 / 手动建 / 跳过
+
+### Q4：Redis 配置
+- host / port / password / db index（默认 db=0）
+
+### Q5：其他中间件（多选）
+- RocketMQ / Nacos / Elasticsearch / MongoDB
+
+> 选了什么，对应 starter 才会引入；不选可后续按需添加。
+
+### Q6：示例 CRUD 资源名
+- 默认 `demo`（生成 `t_demo` 表 + DemoController/Service/Mapper/VO）
+
+### Q7：前端形态（仅 Q1 含前端时）
+- 独立仓库（**默认**，推荐业务域）
+- monorepo 内置（仅平台公共域推荐）
+
+---
+
+## 五、阶段 2：依赖连通性检测
+
+按顺序执行（每项失败时给出 3 条排查建议 + AskUserQuestion 让用户选「修复重试 / 跳过 / 改配置」）：
+
+### 5.1 内网 Nexus（最先检测，不通后面都没意义）
+
+```bash
+curl -s -o /dev/null -w "%{http_code}" http://10.10.1.130:8081/repository/nebula-public/
+```
+
+| 返回码 | 处理 |
+|--------|------|
+| `200` / `301` / `302` | ✅ 通 |
+| `503` | ⚠️ Nexus 暂时不可用，等几分钟重试 |
+| 连接超时 / `Connection refused` | ❌ **未连接公司内网或 VPN**，先解决网络再继续 |
+
+**遇到任何拉不到 nebula 包的情况，第一句话必须是：**「请确认已连接公司内网或 VPN，可访问 `http://10.10.1.130:8081`，然后重试。」
+
+### 5.2 MySQL
+
+```bash
+nc -z {host} {port}
+mysql --protocol=tcp -h {host} -P {port} -u {user} -p{pw} -e 'SELECT 1' 2>&1
+# 选了自动建库：
+mysql --protocol=tcp -h {host} -P {port} -u {user} -p{pw} \
+  -e "CREATE DATABASE IF NOT EXISTS nebula_{domain} DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci"
+```
+
+失败排查建议：
+1. 端口不通 → 检查 mysql 是否启动、防火墙、安全组
+2. 账号失败 → 检查用户名密码、`mysql.user` 是否有当前 host 权限
+3. SSL/TLS 报错 → 在 URL 加 `useSSL=false`
+
+### 5.3 Redis
+
+```bash
+nc -z {host} {port}
+redis-cli -h {host} -p {port} [-a {pw}] -n {db} ping
+```
+
+### 5.4 RocketMQ / Nacos / ES / MongoDB（按 Q5 选择）
+
+```bash
+nc -z {host} 9876                                                      # RocketMQ NameServer
+nc -z {host} 8848 && curl -sf "http://{host}:8848/nacos/v1/console/health/liveness"  # Nacos
+curl -sf "http://{host}:9200" | head -20                              # Elasticsearch
+nc -z {host} 27017                                                     # MongoDB
+```
+
+任何一项失败 **必须** 询问用户，**不要** 默认跳过。
+
+---
+
+## 六、阶段 3：后端骨架生成
+
+仅当 Q1 含「后端」时执行。
+
+### 6.1 目录结构
+
+```
+nebula-{domain}/
+├── settings.gradle
+├── build.gradle                        # 根 build.gradle
+├── gradle.properties                   # projectGroup / version / nebula 各版本
+├── gradlew / gradlew.bat               # Gradle Wrapper
+├── gradle/wrapper/
+│   ├── gradle-wrapper.jar
+│   └── gradle-wrapper.properties
+├── .gitignore                          # 见 §六-3-.gitignore
+├── README.md                            # 启动文档
+├── nebula-{domain}-api/
+│   ├── build.gradle
+│   └── src/main/java/com/huida/{domain}/{domain}/
+│       ├── constant/{Domain}Constants.java
+│       ├── dto/                        # 跨服务 DTO
+│       └── provider/                   # RPC 接口（FeignClient）
+├── nebula-{domain}-core/
+│   ├── build.gradle
+│   └── src/main/java/com/huida/{domain}/{domain}/
+│       ├── controller/
+│       ├── service/ + service/impl/
+│       ├── mapper/ + mapper/ext/
+│       ├── entity/
+│       ├── vo/{param,resp}/
+│       ├── convert/
+│       ├── feign/local/                # LocalStub
+│       └── infra/                      # 必备 SPI 空实现（见 §六-4）
+├── nebula-{domain}-starter/
+│   ├── build.gradle
+│   └── src/main/
+│       ├── java/com/huida/{domain}/autoconfigure/{Domain}AutoConfiguration.java
+│       └── resources/META-INF/spring/
+│           └── org.springframework.boot.autoconfigure.AutoConfiguration.imports
+└── nebula-{domain}-server/
+    ├── build.gradle
+    └── src/main/
+        ├── java/com/huida/{domain}/Nebula{Domain}Application.java
+        └── resources/
+            ├── application.yml
+            ├── application-dev.yml
+            ├── application-uat.yml
+            ├── application-prod.yml
+            ├── log4j2-dev.xml
+            ├── log4j2-uat.xml
+            ├── log4j2-prod.xml
+            ├── banner.txt              # 见 §六-5
+            └── db/migration/V1.0.0__init.sql
+```
+
+### 6.2 关键文件模板
+
+**`gradle.properties`**
+```properties
+projectGroup=com.huida.{domain}
+projectVersion=0.1.0-SNAPSHOT
+nebulaSupportVersion=0.1.22-SNAPSHOT
+nebulaBootVersion=0.1.22-SNAPSHOT
+nebulaAuthVersion=0.1.8-SNAPSHOT
+nebulaSystemVersion=0.2.47-SNAPSHOT
+
+org.gradle.jvmargs=-Xmx2g -Dfile.encoding=UTF-8
+org.gradle.parallel=true
+org.gradle.caching=true
+```
+
+**根 `build.gradle`**（关键是 Nexus 仓库 + 子项目通用依赖）
+```gradle
+plugins { id 'java-library' }
+
+allprojects {
+    group = projectGroup
+    version = projectVersion
+    repositories {
+        // 公司内网 Nexus（必须连内网或 VPN 才能访问）
+        maven {
+            url 'http://10.10.1.130:8081/repository/nebula-public/'
+            allowInsecureProtocol = true
+        }
+        mavenCentral()
+    }
+}
+
+subprojects {
+    apply plugin: 'java-library'
+    java {
+        sourceCompatibility = JavaVersion.VERSION_17
+        targetCompatibility = JavaVersion.VERSION_17
+    }
+    tasks.withType(JavaCompile) {
+        options.encoding = 'UTF-8'
+        options.compilerArgs += ['-parameters']
+    }
+    dependencies {
+        api platform("com.huida.nebula:nebula-support-dependencies:${nebulaSupportVersion}")
+        api platform("com.huida.nebula.boot:nebula-boot-dependencies:${nebulaBootVersion}")
+        compileOnly 'org.projectlombok:lombok'
+        annotationProcessor 'org.projectlombok:lombok'
+    }
+}
+```
+
+**`settings.gradle`**
+```gradle
+rootProject.name = 'nebula-{domain}'
+include 'nebula-{domain}-api'
+include 'nebula-{domain}-core'
+include 'nebula-{domain}-starter'
+include 'nebula-{domain}-server'
+```
+
+**`nebula-{domain}-server/build.gradle`**
+```gradle
+plugins {
+    id 'org.springframework.boot' version '3.5.9'
+    id 'io.spring.dependency-management' version '1.1.6'
+}
+
+dependencies {
+    api project(':nebula-{domain}-starter')
+    api "com.huida.nebula.boot:nebula-boot-starter:${nebulaBootVersion}"
+    api "com.huida.nebula.boot:nebula-boot-starter-security:${nebulaBootVersion}"
+    api "com.huida.nebula:nebula-auth-starter:${nebulaAuthVersion}"
+    api "com.huida.nebula:nebula-system-starter:${nebulaSystemVersion}"
+}
+
+bootJar { archiveFileName = "${project.name}.jar" }
+```
+
+**`Nebula{Domain}Application.java`**
+```java
+package com.huida.{domain};
+
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+import org.springframework.scheduling.annotation.EnableAsync;
+import org.springframework.scheduling.annotation.EnableScheduling;
+
+@SpringBootApplication(scanBasePackages = {"com.huida.{domain}", "com.huida.nebula"})
+@EnableScheduling
+@EnableAsync
+public class Nebula{Domain}Application {
+    public static void main(String[] args) {
+        SpringApplication.run(Nebula{Domain}Application.class, args);
+    }
+}
+```
+
+**`application.yml`**
+```yaml
+spring:
+  profiles:
+    active: dev
+  application:
+    name: nebula-{domain}
+
+server:
+  port: ${PORT:{PORT}}
+
+logging:
+  config: classpath:log4j2-${spring.profiles.active}.xml
+```
+
+**`application-dev.yml`**
+```yaml
+spring:
+  datasource:
+    url: jdbc:mysql://{mysql-host}:{mysql-port}/nebula_{domain}?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true
+    username: {mysql-user}
+    password: {mysql-pw}
+    driver-class-name: com.mysql.cj.jdbc.Driver
+  data:
+    redis:
+      host: {redis-host}
+      port: {redis-port}
+      password: {redis-pw}
+      database: {redis-db}
+
+nebula:
+  flyway:
+    enabled: true
+  tenant:
+    enabled: true
+    isolation-mode: FIELD
+  swagger:
+    enabled: true
+
+springdoc:
+  swagger-ui:
+    path: /swagger-ui.html
+```
+
+> log4j2-{dev/uat/prod}.xml 模板见 [framework-standards.md](framework-standards.md) §三-E。
+
+### 6.3 .gitignore（项目根目录，必须）
+
+```gitignore
+# ---------------- Gradle ----------------
+.gradle/
+build/
+!gradle/wrapper/gradle-wrapper.jar
+gradle-app.setting
+!**/src/main/**/build/
+!**/src/test/**/build/
+
+# ---------------- IDE: IntelliJ IDEA ----------------
+.idea/
+*.iml
+*.iws
+*.ipr
+out/
+
+# ---------------- IDE: VS Code ----------------
+.vscode/
+.vscode-server/
+
+# ---------------- IDE: Eclipse ----------------
+.classpath
+.project
+.settings/
+.factorypath
+
+# ---------------- OS ----------------
+.DS_Store
+Thumbs.db
+
+# ---------------- Java ----------------
+*.class
+*.log
+hs_err_pid*
+
+# ---------------- Spring Boot ----------------
+*.original
+
+# ---------------- Local config / secrets ----------------
+application-local.yml
+application-local.yaml
+application-local.properties
+*.local.yml
+.env.local
+
+# ---------------- Logs / temp ----------------
+logs/
+*.log.gz
+tmp/
+
+# ---------------- Node (前端目录) ----------------
+node_modules/
+dist/
+*.tsbuildinfo
+.pnpm-store/
+```
+
+### 6.4 必备 SPI 空实现（`nebula-framework-task` 启动期依赖）
+
+`nebula-framework-task` 模块定义了 3 个持久化 SPI，业务项目**必须**提供实现（哪怕空实现）才能让 task starter 起来。
+
+放在 `nebula-{domain}-core/src/main/java/com/huida/{domain}/{domain}/infra/`：
+
+**`DefaultApiLogRepository.java`**
+```java
+package com.huida.{domain}.{domain}.infra;
+
+import com.huida.nebula.framework.task.apilog.ApiLogModel;
+import com.huida.nebula.framework.task.apilog.ApiLogRepository;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
+import org.springframework.stereotype.Component;
+
+/**
+ * API 日志默认占位实现。
+ * 业务方按需替换为真实存储（DB / ES / 日志文件）。
+ */
+@Slf4j
+@Component
+@ConditionalOnMissingBean(ApiLogRepository.class)
+public class DefaultApiLogRepository implements ApiLogRepository {
+    @Override
+    public void saveAsync(ApiLogModel logModel) {
+        log.debug("[ApiLog skipped] {}", logModel);
+    }
+}
+```
+
+**`DefaultTaskInstanceRepository.java`**
+```java
+package com.huida.{domain}.{domain}.infra;
+
+import com.huida.nebula.framework.task.core.executor.TaskInstanceRepository;
+import com.huida.nebula.framework.task.core.model.TaskContext;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
+import org.springframework.stereotype.Component;
+
+/**
+ * 任务实例持久化默认占位实现。
+ * 业务方启用任务调度时需实现真实持久化。
+ */
+@Slf4j
+@Component
+@ConditionalOnMissingBean(TaskInstanceRepository.class)
+public class DefaultTaskInstanceRepository implements TaskInstanceRepository {
+    @Override public void markRunning(Long instanceId)   { log.debug("[task] running   id={}", instanceId); }
+    @Override public void markSuccess(Long instanceId, TaskContext ctx) { log.debug("[task] success   id={} ctx={}", instanceId, ctx); }
+    @Override public void markFailed(Long instanceId, String errorMsg)  { log.debug("[task] failed    id={} err={}", instanceId, errorMsg); }
+    @Override public void markCancelled(Long instanceId) { log.debug("[task] cancelled id={}", instanceId); }
+    @Override public void updateProgress(Long instanceId, int progress, long successCount, long failCount) {
+        log.debug("[task] progress  id={} pct={} ok={} fail={}", instanceId, progress, successCount, failCount);
+    }
+}
+```
+
+**`DefaultTaskQueueService.java`**
+```java
+package com.huida.{domain}.{domain}.infra;
+
+import com.huida.nebula.framework.task.core.model.TaskMessage;
+import com.huida.nebula.framework.task.queue.TaskQueueService;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
+import org.springframework.stereotype.Component;
+
+/**
+ * 任务队列默认占位实现：内存直投，方便本地启动。
+ * 生产环境应替换为 RocketMQ / Disruptor 实现。
+ */
+@Slf4j
+@Component
+@ConditionalOnMissingBean(TaskQueueService.class)
+public class DefaultTaskQueueService implements TaskQueueService {
+    @Override
+    public void publish(TaskMessage message) {
+        log.debug("[task-queue] publish {}", message);
+        // 本地占位：不真投递。生产需替换为 RocketMQ / 内存直投处理器
+    }
+    @Override
+    public String queueType() {
+        return "noop";
+    }
+}
+```
+
+> 这 3 个类**禁止** 写真实业务逻辑，只是为了让 starter 在缺少业务实现时能启动。日志级别保持 `debug`，避免污染 INFO。
+
+### 6.5 banner.txt（项目身份标识）
+
+`nebula-{domain}-server/src/main/resources/banner.txt`，规则：
+
+- **禁止** 出现任何其他业务项目名（含历史样板项目名）的字眼
+- 显示当前项目名 + 版本 + Spring Boot 版本
+- 标题用 `Nebula {DomainUpper}`（中文项目名可加在副标题）
+
+通用模板（按当前项目名替换）：
+
+```
+  _   _      _           _              {Domain}
+ | \ | | ___| |__  _   _| | __ _      ________________
+ |  \| |/ _ \ '_ \| | | | |/ _` |     {业务中文名}
+ | |\  |  __/ |_) | |_| | | (_| |
+ |_| \_|\___|_.__/ \__,_|_|\__,_|     v${project.version}
+
+:: Spring Boot ::                     (v${spring-boot.version})
+:: Active Profile ::                  ${spring.profiles.active}
+```
+
+AI 生成时**必须**把 `{Domain}` / `{业务中文名}` 替换为当前项目的对应值，不能保留任何样板字眼。
+
+### 6.6 Flyway 建表脚本
+
+**`V1.0.0__init.sql`**（必须含 11 公共字段 + Demo 表）
+
+```sql
+-- 示例资源表（11 个公共字段 + 业务字段）
+CREATE TABLE IF NOT EXISTS t_{demoResource} (
+  id              BIGINT NOT NULL COMMENT '主键',
+  tenant_id       BIGINT DEFAULT NULL COMMENT '租户ID',
+  create_user_id  BIGINT DEFAULT NULL COMMENT '创建人ID',
+  creator         VARCHAR(128) DEFAULT NULL COMMENT '创建人',
+  create_time     DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6) COMMENT '创建时间',
+  modify_user_id  BIGINT DEFAULT NULL COMMENT '更新人ID',
+  updater         VARCHAR(128) DEFAULT NULL COMMENT '更新人',
+  modify_time     DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6) ON UPDATE CURRENT_TIMESTAMP(6) COMMENT '更新时间',
+  delete_flag     INT NOT NULL DEFAULT 0 COMMENT '逻辑删除（0:正常 1:已删）',
+  remark          VARCHAR(500) DEFAULT NULL COMMENT '备注',
+  custom_fields   TEXT DEFAULT NULL COMMENT '扩展字段（JSON）',
+  -- 业务字段
+  demo_name       VARCHAR(128) NOT NULL COMMENT '名称',
+  demo_code       VARCHAR(64) NOT NULL COMMENT '编码',
+  status          INT NOT NULL DEFAULT 0 COMMENT '状态（0:启用 1:禁用）',
+  PRIMARY KEY (id),
+  UNIQUE KEY uk_{demoResource}_code (tenant_id, demo_code),
+  KEY idx_{demoResource}_name (demo_name)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='示例资源';
+```
+
+### 6.7 Demo CRUD 完整生成
+
+按 [full-crud-example.md](full-crud-example.md) 模板生成完整六件套：
+
+- `entity/{Demo}DO.java`（extends BaseEntity）
+- `mapper/{Demo}Mapper.java`（extends BaseMapper<{Demo}DO>）
+- `mapper/ext/{Demo}MapperExt.java`（分页两段式 / 唯一性检查）
+- `convert/{Demo}Convert.java`（MapStruct + BaseMapperConfig）
+- `service/I{Demo}Service.java` + `service/impl/{Demo}ServiceImpl.java`
+- `controller/{Demo}Controller.java`（POST /page、GET /{id}、POST、PUT、DELETE、PATCH /{id}/v、PATCH /{id}/x）
+- `vo/param/{Demo}PageParamVO.java` + `{Demo}SaveParamVO.java`
+- `vo/resp/{Demo}RespVO.java` + `{Demo}DetailVO.java`
+
+> 不要重新发明示例代码，直接抄 [full-crud-example.md](full-crud-example.md) 并替换名字。
+
+---
+
+## 七、阶段 4：前端骨架生成
+
+仅当 Q1 含「前端」时执行。Q7 决定形态。
+
+### 7.1 独立仓库形态（默认）
+
+**严格按 [microapp-guide.md](microapp-guide.md) §二必备文件清单 + §三关键配置详解** 逐文件生成。**禁止** 拷贝任何现有业务样板项目（含其历史业务名、banner、README 等）。
+
+每个文件按 microapp-guide 中给出的模板写，替换以下占位符：
+
+| 占位符 | 取值 |
+|--------|------|
+| `{domain}` | Q2 派生 |
+| `{Domain}` | 首字母大写 |
+| `{DOMAIN}` | 全大写 |
+| `{PascalDomain}` | 同 `{Domain}` |
+| `{PORT}` | Q2 派生（30XX 段） |
+| `{业务中文名}` | 询问用户 |
+| `{your-host-domain}` | 询问用户（联调线上后端域名） |
+| `{your-gitlab-host}` | 询问用户（GitLab 域名） |
+
+### 7.2 前端 .gitignore
+
+```gitignore
+node_modules/
+dist/
+*.tsbuildinfo
+.pnpm-store/
+.DS_Store
+.idea/
+.vscode/
+*.log
+.env.local
+.env.*.local
+src/types/auto-imports.d.ts
+src/types/components.d.ts
+```
+
+### 7.3 monorepo 内置形态（备选）
+
+按 [microapp-guide.md](microapp-guide.md) 同样的配置，但放进 `nebula-web/apps/nebula-web-{domain}/`，依赖改成 `workspace:*`，scripts 沿用 monorepo 根的 dev/build。
+
+### 7.4 主应用注册
+
+按 [microapp-guide.md](microapp-guide.md) §四执行。
+
+---
+
+## 八、阶段 5：启动验证 + 配置修改指引
+
+### 8.1 启动命令（必须告诉用户）
+
+**后端**（在 `nebula-{domain}` 根目录执行）：
+
+```bash
+# 第一次构建（拉依赖 + 编译）—— 若挂内网/VPN，5~10 分钟
+./gradlew clean build -x test
+
+# 本地启动（推荐，IDE 外）
+./gradlew :nebula-{domain}-server:bootRun
+
+# 用 IDE 启动：右键 Nebula{Domain}Application.java → Run
+#（IDE 启动前确认 §一-IDEA 必备配置已完成）
+
+# 打可执行 jar
+./gradlew :nebula-{domain}-server:bootJar
+# 产物：nebula-{domain}-server/build/libs/nebula-{domain}-server.jar
+java -jar nebula-{domain}-server/build/libs/nebula-{domain}-server.jar
+```
+
+**前端**（在 `nebula-{domain}-web` 根目录执行）：
+
+```bash
+# 配置 GitLab token（首次必做）
+export GITLAB_TOKEN=glpat-xxxxx
+
+# 安装依赖
+pnpm install
+
+# 本地启动（本地 IP 后端）
+pnpm dev
+
+# 联调线上后端
+pnpm dev:remote
+
+# 类型检查
+pnpm typecheck
+
+# 构建
+pnpm build
+```
+
+### 8.2 MySQL / Redis 配置修改位置（必须告诉用户）
+
+后端项目 application 配置入口：
+
+| 想修改的内容 | 文件路径 | 关键 key |
+|------------|---------|---------|
+| MySQL 连接 | `nebula-{domain}-server/src/main/resources/application-dev.yml` | `spring.datasource.url` / `username` / `password` |
+| Redis 连接 | 同上 | `spring.data.redis.host` / `port` / `password` / `database` |
+| 服务端口 | `application.yml` | `server.port` |
+| 当前 profile | `application.yml` | `spring.profiles.active`（默认 `dev`） |
+| Flyway 开关 | `application-dev.yml` | `nebula.flyway.enabled` |
+| 多租户隔离模式 | `application-dev.yml` | `nebula.tenant.isolation-mode`（FIELD / SCHEMA / DATABASE） |
+| Swagger 开关 | `application-dev.yml` | `nebula.swagger.enabled` |
+| 日志级别 | `nebula-{domain}-server/src/main/resources/log4j2-dev.xml` | `<Logger level="..."/>` |
+
+> 生产环境改 `application-prod.yml`，**永远不要**改 `application.yml` 主文件中的具体连接串。
+
+### 8.3 启动验证（AI 自动 Bash）
+
+```bash
+# 后端 Swagger
+curl -fs "http://localhost:{PORT}/v3/api-docs" > /dev/null && echo "✅ Swagger OK"
+
+# 后端 Demo 接口（无 token 应返回 401 而非 connection refused）
+curl -s -o /dev/null -w "%{http_code}\n" "http://localhost:{PORT}/{domain}/{demo}/1"
+
+# 主应用
+curl -fs "http://127.0.0.1:3000/" > /dev/null && echo "✅ 主应用 OK"
+
+# 子应用 mount 文件
+curl -fs "http://127.0.0.1:{frontend-PORT}/" > /dev/null && echo "✅ 子应用 OK"
+```
+
+### 8.4 浏览器手工验证
+
+告知用户依次操作：
+
+1. 打开 `http://localhost:{PORT}/swagger-ui.html` → 看到 Demo CRUD 接口列表
+2. 打开 `http://127.0.0.1:3000/` → 登录
+3. 菜单点击「{业务中文名}」→ 应看到子应用页面
+
+白屏时立即查 [pitfalls-checklist.md](pitfalls-checklist.md) §G。
+
+---
+
+## 九、阶段 6：收尾交付清单
+
+AI 输出给用户的最终消息必须包含以下结构（按项目情况增删）：
+
+```markdown
+## ✅ 后端项目已创建
+
+- 位置：`{path}/nebula-{domain}`
+- Group：`com.huida.{domain}`
+- 启动命令：
+  - `cd {path}/nebula-{domain} && ./gradlew :nebula-{domain}-server:bootRun`
+  - 或在 IDE 中运行 `Nebula{Domain}Application.java`
+- Swagger：http://localhost:{PORT}/swagger-ui.html
+- 数据库：`nebula_{domain}`（已建库，已执行 V1.0.0__init.sql）
+- 示例资源：`t_{demo}`（CRUD 8 个接口可用）
+- 关键技术栈：JDK 17 / Spring Boot 3.5.9 / Gradle 8.12 / MyBatis-Plus 3.5.9
+- 依赖版本：nebula-boot=0.1.22-SNAPSHOT / nebula-auth=0.1.8-SNAPSHOT / nebula-system=0.2.47-SNAPSHOT
+
+## ✅ 前端项目已创建
+
+- 位置：`{path}/nebula-{domain}-web`
+- 启动命令：
+  - `cd {path}/nebula-{domain}-web && pnpm install && pnpm dev`
+- 端口：{frontend-PORT}
+- 主应用菜单入口：/{domain}app
+
+## 🔧 修改 MySQL / Redis 配置
+
+- 开发环境：`nebula-{domain}-server/src/main/resources/application-dev.yml`
+- 生产环境：`application-prod.yml`
+- 服务端口：`application.yml`
+
+## 🔧 IntelliJ IDEA 必须调整的设置
+
+1. Project SDK = 17
+2. Project language level = 17
+3. Gradle JVM = 17
+4. Annotation Processing 启用（Lombok / MapStruct 必需）
+5. File Encoding 全 UTF-8
+6. 必装插件：Lombok / MapStruct Support / MyBatisX
+
+## 🌐 公司内网约束
+
+- 拉依赖必须连公司内网或 VPN（Nexus：`http://10.10.1.130:8081/repository/nebula-public/`）
+- 拉不到包时第一时间检查网络
+
+## 📋 后续仍需要做
+
+1. 在 `nebula-system` 中配置菜单 + 权限
+2. 接入 `nebula-auth` 登录（如果独立部署）
+3. 把 §六-4 的 3 个占位 SPI 替换为真实持久化实现（启用任务调度时）
+4. 配置生产环境 Nginx
+5. 配置 `deploy/build-deploy.sh` 的 `SERVER_HOST`
+6. `git remote` 设置 + 首次 `git push`
+```
+
+---
+
+## 十、阶段中决策点速查
+
+向导执行中常见的二次询问：
+
+| 场景 | AskUserQuestion 选项 |
+|------|---------------------|
+| 数据库不存在 | 自动建库 / 手动建 / 仅生成脚本不执行 |
+| 端口冲突 | 自动 +1 探测可用端口 / 用户手动指定 / 终止流程 |
+| 选 MQ 但本机没装 | 跳过 MQ starter / 用 docker 起 / 改用本地内存模拟 |
+| Demo 资源名与现有冲突 | 改名 / 跳过 Demo 生成 |
+| 已有同名项目目录 | 备份原目录 / 用新目录名 / 终止 |
+| GITLAB_TOKEN 未设置（前端） | 引导设置 / 跳过 install / 终止 |
+| Nexus 503 / 连不上 | **提示连公司内网或 VPN** / 重试 / 跳过 |
+| Gradle 拉依赖超时 | 同上 / 增加超时配置 |
+
+---
+
+## 十一、依赖拉取异常处理
+
+### 11.1 现象
+
+- `Could not resolve com.huida.nebula:...`
+- `Connection refused: /10.10.1.130:8081`
+- `Read timed out`
+- `503 Service Unavailable`
+
+### 11.2 AI 处理流程
+
+1. **第一步必须做**：用 `curl -s -o /dev/null -w "%{http_code}" http://10.10.1.130:8081/repository/nebula-public/` 检测连通性
+2. 不通 → **明确告知用户「请确认已连接公司内网或 VPN」**
+3. 通了仍报错 → 检查依赖版本号是否在 Nexus 实际存在
+4. `503` → 暂时性问题，等 1~2 分钟重试；连续 503 反馈给 Nexus 管理员
+
+**严禁**：自动替换为其他公网镜像源（如阿里云 maven 镜像）—— nebula 包不在公网仓库。
+
+---
+
+## 十二、本向导与其他文档的依赖关系
+
+向导执行时大量引用：
+
+- 后端结构 → [backend-standards.md](backend-standards.md)
+- 后端 CRUD 模板 → [full-crud-example.md](full-crud-example.md)
+- 后端建表规范 → [db-standards.md](db-standards.md)
+- 框架工具与日志模板 → [framework-standards.md](framework-standards.md)
+- Boot 组件引入 → [boot-components-catalog.md](boot-components-catalog.md)
+- RPC 接入 auth/system → [rpc-api-reference.md](rpc-api-reference.md)
+- 前端独立仓库样板 → [microapp-guide.md](microapp-guide.md)
+- 前端 monorepo 子应用 → [frontend-standards.md](frontend-standards.md)
+- 异常处理 → [pitfalls-checklist.md](pitfalls-checklist.md)
+
+> AI 在执行向导时，对应阶段务必先读上述同 skill 内的文档，**禁止** 去本地项目源码目录验证，**禁止** 拷贝任何现有业务样板项目。