@alanwang-merit/meritdata-platform-skill-package 1.0.8 → 1.0.10

package/skills/meritdata-platform-2nd-dev-check/references/checklist.md

@@ -0,0 +1,322 @@
+# 详细检查清单（60+ 项）
+
+> **通用性说明**：本清单中所有 `*` 占位符需替换为你的实际值。脚本中已通过环境变量参数化。
+
+## 变量占位符
+
+| 占位符 | 含义 | 配置方式 |
+|--------|------|----------|
+| `${APP_NAME}` | Spring Boot 应用名 | `APP_NAME` 环境变量 |
+| `${APP_PORT}` | 后端服务端口 | `APP_PORT` 环境变量 |
+| `${MERIT_HOME}` | 美林平台环境根 | `MERIT_HOME` 环境变量 |
+| `${PLATFORM_VERSION}` | 平台版本（推荐 6.13.2） | `PLATFORM_VERSION` 环境变量 |
+| `${FRONTEND_PAGES}` | 前端业务页面（逗号分隔） | `FRONTEND_PAGES` 环境变量 |
+
+---
+
+## 1. 基础设施检查（Prerequisites）
+
+### MySQL
+- [ ] 端口可达（`$MYSQL_HOST:$MYSQL_PORT`）
+  ```bash
+  telnet $MYSQL_HOST $MYSQL_PORT
+  ```
+- [ ] `$MYSQL_USER`/`$MYSQL_PASSWORD` 可登录
+  ```bash
+  mysql -h $MYSQL_HOST -P $MYSQL_PORT -u $MYSQL_USER -p$MYSQL_PASSWORD -e "SELECT VERSION();"
+  ```
+- [ ] `cloud` 库存在（≥130 张表）
+- [ ] 数据库字符集 `utf8mb4`
+- [ ] `bpm` 库如独立存在（含 Activiti `act_*` 表）
+
+### Redis
+- [ ] 端口可达（`$REDIS_HOST:$REDIS_PORT`）
+- [ ] 密码正确
+  ```bash
+  redis-cli -h $REDIS_HOST -p $REDIS_PORT -a $REDIS_PASSWORD PING
+  ```
+- [ ] DBSIZE 期望 ≥ 14（基础启动缓存）
+- [ ] key 命名空间包含 `CACHE_*` / `spring:session:*` / `nacosToken`
+
+### Nacos
+- [ ] 端口可达（`$NACOS_HOST:$NACOS_PORT`）
+- [ ] `$NACOS_USER`/`$NACOS_PASSWORD` 认证通过
+  ```bash
+  curl -u $NACOS_USER:$NACOS_PASSWORD http://$NACOS_HOST:$NACOS_PORT/nacos/v1/auth/users
+  ```
+- [ ] namespace=public 存在
+- [ ] DEFAULT_GROUP 6 份 common-* 配置存在
+
+### 平台服务（Nacos 注册）
+- [ ] `cloud-system-gateway` :8081 健康
+- [ ] `cloud-system-manage` :8085 健康
+- [ ] `cloud-system-bpm-engine` :8089 健康（**实际端口以 Nacos 注册为准**）
+- [ ] `cloud-system-job` :8086 健康（**实际端口以 Nacos 注册为准**）
+
+---
+
+## 2. 后端工程检查（Back-end）
+
+### pom.xml
+- [ ] artifactId = `${APP_NAME}`
+- [ ] packaging = `war`（或 `jar`，按需）
+- [ ] 父 POM `cloud-starter-parent:${PLATFORM_VERSION}`
+- [ ] 必备依赖：
+  - `cloud-starter-core` ${PLATFORM_VERSION}
+  - `cloud-module-base` ${PLATFORM_VERSION}
+  - `cloud-system-bpm-module-core` ${PLATFORM_VERSION}（**不是 cloud-module-bpm**）
+  - `cloud-starter-dbinit` ${PLATFORM_VERSION}
+
+### bootstrap.properties
+- [ ] `server.port=${APP_PORT}`
+- [ ] `CLOUD_HOME=${MERIT_HOME}`（真实路径）
+- [ ] `spring.cloud.nacos.config.server-addr=${NACOS_HOST}:${NACOS_PORT}`
+- [ ] `spring.cloud.nacos.config.namespace=public`
+- [ ] `spring.cloud.nacos.config.group=DEFAULT_GROUP`
+- [ ] `spring.profiles.include=common,cache,server,cloud-system-cas,cloud-system-manage,${APP_NAME}`
+- [ ] `spring.application.name=@project.artifactId@`（自动替换为 `${APP_NAME}`）
+
+### CLOUD_HOME 验证
+- [ ] `${MERIT_HOME}/key/key.tmp` 存在
+- [ ] `${MERIT_HOME}/key/public.pem` 存在
+- [ ] `${MERIT_HOME}/key/skey.dat` 存在
+
+### Java 包结构
+- [ ] `com.meritdata.cloud.${APP_NAME^}Application.java` 存在
+- [ ] `com.meritdata.cloud.common.imp.*` 平台代码齐全
+- [ ] `com.meritdata.cloud.common.entity.ProcTrackDTOApproval` 存在
+- [ ] `com.meritdata.cloud.<业务模块>/controller/*Controller.java` 存在
+- [ ] `com.meritdata.cloud.<业务模块>/entity/*Entity.java` 存在
+- [ ] 业务 Controller 含 `@Autowired SessionUtils`（实例方法）
+
+### 编译验证
+```bash
+mvn -s "$MAVEN_SETTINGS" clean compile
+```
+- [ ] BUILD SUCCESS
+- [ ] 无 ERROR 级别日志
+
+---
+
+## 3. 前端工程检查（Front-end）
+
+### package.json
+- [ ] `name = "${APP_NAME}"`
+- [ ] 依赖：
+  - `cloud-module-base: ${PLATFORM_VERSION}`
+  - `cloud-module-bpm: ${PLATFORM_VERSION}`
+- [ ] devDependencies：
+  - `cross-env: ^10.1.0`（关键，Node 24 OpenSSL 兼容）
+  - `element-ui: ^2.15.7`（或按美林平台版本）
+  - `vue: ^2.6.10`
+- [ ] scripts 含：
+  - `serve` 含 `cross-env NODE_OPTIONS=--openssl-legacy-provider`
+  - `build` 含 `cross-env NODE_OPTIONS=--openssl-legacy-provider`
+
+### .npmrc
+- [ ] `registry=https://registry.npmmirror.com`（公开镜像，默认）
+- [ ] 如有私有 registry，配置 `@meritdata:registry=<公司私有地址>`
+
+### vue.config.js
+- [ ] `publicPath: '/${APP_NAME}/'`（按业务调整）
+- [ ] `outputDir: '${APP_NAME}'`
+- [ ] `devServer.port: 8083`（避开 8080/8081/8085）
+- [ ] `devServer.proxy['/gateway/'].target: 'http://localhost:8081'`
+- [ ] `pages` 含 `$FRONTEND_PAGES` 每个页面
+- [ ] `chainWebpack` 含 `node_modules/cloud-module-base/packages` 编译规则
+
+### http.js
+- [ ] `appPath['${APP_NAME}'] = '/${APP_NAME}'`（应用路径前缀）
+- [ ] `Axios` 来自 `cloud-module-base/packages/httpConfig/http-plugin`
+
+### 业务页面结构（每个页面 11 个文件）
+- [ ] `main.js`（入口）
+- [ ] `App.vue`（根组件）
+- [ ] `Index.vue`（路由页面）
+- [ ] `router.js`（路由）
+- [ ] `store.js`（Vuex）
+- [ ] `i18n/i18n.js`（国际化）
+- [ ] `i18n/langs/{zh_CN,en_US,index}.js`
+- [ ] `view/` 至少 1 个 .vue 文件
+
+### node_modules 验证
+- [ ] `cloud-module-base/package.json` 含 `${PLATFORM_VERSION}`
+- [ ] `cloud-module-base/packages/` 含 11+ 组件
+- [ ] `cloud-module-bpm/package.json` 含 `${PLATFORM_VERSION}`
+- [ ] `cloud-module-bpm/packages/` 含 13+ 组件
+
+### 构建验证
+```bash
+npm run build
+```
+- [ ] DONE Build complete
+- [ ] 产出每个 `$FRONTEND_PAGES` HTML 入口
+- [ ] 产物总大小 < 2 MB
+
+---
+
+## 4. 平台依赖检查（Platform JARs）
+
+### 本地 Maven 仓库
+- [ ] `~/.m2/repository/com/meritdata/cloud/` `${PLATFORM_VERSION}` 系列 jar 完整
+- [ ] 检查以下 jar：
+  ```bash
+  ls ~/.m2/repository/com/meritdata/cloud/*/${PLATFORM_VERSION}/*.jar
+  ```
+
+### 9 个后端工具类（必须 100% 存在）
+- [ ] `com.meritdata.tempo.syscache.service.SysCacheServiceFacade`（23 方法）
+- [ ] `com.meritdata.tempo.syscache.service.StringCacheFacade`（3 方法）
+- [ ] `com.meritdata.cloud.utils.NacosUtils`（10 方法）
+- [ ] `com.meritdata.cloud.utils.Sm2Utils`（3 方法）
+- [ ] `com.meritdata.cloud.utils.SM3Encoder`（2 方法）
+- [ ] `com.meritdata.cloud.utils.Sm4Utils`（2 方法）
+- [ ] `com.meritdata.cloud.utils.SessionUtils`（21 方法）
+- [ ] `com.meritdata.cloud.utils.LogPattenUtils`（1 方法）
+- [ ] `com.meritdata.cloud.log.compare.CompareUtils`（1 方法）
+
+### 5 个后端组件（必须存在）
+- [ ] `com.meritdata.cloud.log.service.ILogPostService`（**注意 .service 子包**）
+- [ ] `com.meritdata.cloud.bpm.core.BpmEngine`（**注意 .core 子包**）
+- [ ] `com.meritdata.cloud.base.LogDesc`（**注意 .base 包**）
+- [ ] `com.meritdata.cloud.base.AddDesc` / `DelDesc`
+- [ ] `com.meritdata.cloud.base.tenancy.EnableDataSecretFilter`
+
+### 7 个 jar 中确实不存在的组件（需要替代方案）
+
+> **本节经过 2026-09-10 核实更新**：
+> - ❌ `IJobApi` 和 `CloudFeignMessageClient` **实测存在**，已从本节移除
+> - ✅ 剩余 5 个（Page/Undo/IBpmUndoServiceClient/IUserTaskListener/IBpmFormService）经核实 jar 中确实无独立类，需用替代方案
+- [ ] `IJobApi` 实测可用（`com.meritdata.cloud.job.api.IJobApi`，`cloud-starter-job` 模块）→ `@Autowired` 注入即可
+- [ ] `CloudFeignMessageClient` 实测可用（`com.meritdata.cloud.feignclient.CloudFeignMessageClient`，`cloud-module-mq` 模块）→ `@Autowired` 注入即可
+- [ ] `Page` / `PageQuery` 不存在（jar 中无）→ 用 `Pageable`（Spring Data）或 `GridView`（平台）
+- [ ] `Undo` 不存在（jar 中无独立类）→ 用 `UndoDTO`（`BpmEngine.getUndoPage` 返回类型）
+- [ ] `IBpmUndoServiceClient` 不存在 → 用 `BpmEngine.getUndoPage`
+- [ ] `IUserTaskListener` 不存在 → 自实现 `TaskListener`（Camunda 原生接口）
+- [ ] `IBpmFormService` 不存在 → 用 `BpmEngine.queryMainForms` / `queryMainFormsByBusinessId`
+
+---
+
+## 5. 平台服务检查（Platform Services）
+
+### Nacos 6 份 common 配置
+- [ ] `common.properties` 平台核心
+- [ ] `common-cache.properties` 缓存
+- [ ] `common-server.properties` 服务器
+- [ ] `common-cloud-system-cas.properties` CAS
+- [ ] `common-cloud-system-manage.properties` 系统管理
+- [ ] `common-datasource.properties` 数据源
+
+### 本工程专属配置
+- [ ] `common-${APP_NAME}.properties` 含：
+  - `spring.datasource.url=jdbc:mysql://...:${MYSQL_PORT}/${APP_NAME//-/_}?...`
+  - `spring.datasource.password=${MYSQL_PASSWORD}`
+  - `spring.data.redis.host=${REDIS_HOST}`
+  - `spring.data.redis.port=${REDIS_PORT}`
+  - `server.port=${APP_PORT}`
+
+### 平台服务健康
+- [ ] Nacos 显示 4 个服务 healthyInstanceCount > 0：
+  - `cloud-system-gateway`
+  - `cloud-system-manage`
+  - `cloud-system-bpm-engine`
+  - `cloud-system-job`
+
+---
+
+## 6. 数据库检查（Database）
+
+### cloud 库平台表
+- [ ] `pf_user_info`（用户主表）
+- [ ] `pf_org_user`（组织）
+- [ ] `pf_resource`（资源）
+- [ ] `act_ru_task`（BPM 任务）
+- [ ] `act_re_procdef`（BPM 流程定义）
+- [ ] `pf_job_*`（定时任务系列）
+
+### 业务表
+- [ ] 业务主表（业务开发时新建，命名 `T_${TABLE_NAME}`）
+- [ ] Hibernate `ddl-auto=none`（平台强制）
+
+---
+
+## 7. 代码规范检查（Conventions）
+
+### 命名规范
+- [ ] Controller: `XxxController`
+- [ ] Service 接口: `IXxxService`
+- [ ] Service 实现: `XxxServiceImpl`
+- [ ] Repository: `XxxRepository`
+- [ ] Entity: `XxxEntity` 或 `Xxx`
+- [ ] 工具类: `XxxUtils` / `XxxHelper`
+
+### 审计字段（每个 Entity 必须有）
+- [ ] `CREATE_BY` VARCHAR(64)
+- [ ] `CREATE_TIME` DATETIME
+- [ ] `UPDATE_BY` VARCHAR(64)
+- [ ] `UPDATE_TIME` DATETIME
+- [ ] `VERSION` INT（乐观锁）
+- [ ] `IS_DELETED` TINYINT（逻辑删除）
+
+### 密级字段（按需）
+- [ ] `SECRET_LEVEL` VARCHAR(16) — secret10/secret20/secret30/secret40
+
+### 5 个包路径偏差修正（必读）
+- [ ] `ILogPostService` 实际 `com.meritdata.cloud.log.service.ILogPostService`
+- [ ] `BpmEngine` 实际 `com.meritdata.cloud.bpm.core.BpmEngine`
+- [ ] `LogDesc` 实际 `com.meritdata.cloud.base.LogDesc`
+- [ ] `AddDesc` / `DelDesc` 实际 `com.meritdata.cloud.base.*`
+- [ ] `EnableDataSecretFilter` 实际 `com.meritdata.cloud.base.tenancy.EnableDataSecretFilter`
+
+### 6 个方法名修正
+- [ ] `NacosUtils.getConfig` → `NacosUtils.getConfigFile`
+- [ ] `NacosUtils.getAllConfig` → `NacosUtils.getAllConfigFile`
+- [ ] `NacosUtils.updateFile` → `NacosUtils.updateConfigFile`
+- [ ] `NacosUtils.resetFile` → `NacosUtils.reSetConfigFile`
+- [ ] `NacosUtils.clearFile` → `NacosUtils.clearConfigFile`
+- [ ] `Sm2Utils.getKey` → `Sm2Utils.createSM2Key`
+
+### 3 个调用方式修正
+- [ ] `NacosUtils` / `SessionUtils` 必须 `@Autowired` 注入（实例方法）
+- [ ] `SM3Encoder.encode()` 是实例方法
+
+---
+
+## 8. 工具链检查（Toolchain）
+
+### 后端
+- [ ] JDK 21（`java -version`）
+- [ ] Maven 3.9+（`mvn -v`）
+- [ ] Maven settings.xml 路径：`$MAVEN_SETTINGS`
+- [ ] Maven 本地仓库：`~/.m2/repository`
+
+### 前端
+- [ ] Node 18+（推荐 24.13+）
+- [ ] npm 10+（`npm -v`）
+- [ ] npm registry `${NPM_REGISTRY}`（默认 `https://registry.npmmirror.com`）
+
+### IDE
+- [ ] IntelliJ IDEA 2024+（后端）
+- [ ] VSCode 1.85+（前端）
+- [ ] 推荐插件：Lombok / Vue Language Features / ESLint
+
+---
+
+## 9. 业务代码状态（业务开发前必填）
+
+### 当前 Controller TODO 状态
+- [ ] 各业务 Controller 都有 TODO 标记
+- [ ] Service / Repository 层缺失
+- [ ] 前端 view 组件有 `// TODO: 调用 $http.post(...)` 标记
+
+### 业务流程
+- [ ] 业务 BPMN 流程在 cloud-system-bpm 设计器中创建
+- [ ] 流程 key 按业务命名（如 `contract_approval`）
+
+### 菜单权限
+- [ ] 在 cloud-system-manage 中录入 `${APP_NAME}` 资源
+- [ ] 配置各页面的菜单
+
+### 真实登录凭证
+- [ ] 平台 admin 账户可用
+- [ ] 启用 RBAC + 三员管理（XTGLY/AQGLY/AQSJY）

package/skills/meritdata-platform-2nd-dev-check/references/env-vars.md

@@ -0,0 +1,232 @@
+# env vars 详解（10 个变量）
+
+> **2026-08-12 新增**：本文件是 SKILL.md §Step 1-3 的详细参考。
+> **`.env` 来源**：write-env.sh 写入项目根 `.env`（chmod 600 / icacls 保护 + .gitignore 屏蔽）。
+
+---
+
+## ⚠️ 重要：Nacos 导出目录是项目自定义
+
+`<项目根>/nacos_config_export/DEFAULT_GROUP/*.properties`（可自定义路径）是**项目作者本地的环境快照**。
+
+**新接手用户**的环境可能完全不同：
+- 数据库类型不同（MySQL vs 达梦 DM vs Oracle vs PostgreSQL）
+- 主机/端口不同（localhost vs 远程服务器）
+- 凭据不同
+
+**弹窗必须让用户主动确认**："用样例默认" 还是 "我用自己的"。
+
+---
+
+## 自动加载字段（从项目内 Nacos 导出目录）
+
+| 变量 | 来源文件 | 字段 |
+|------|---------|------|
+| `MYSQL_HOST` / `PORT` | `common-datasource.properties` | `spring.datasource.url` |
+| `MYSQL_USER` / `PASSWORD` | `common-datasource.properties` | `spring.datasource.username/password` |
+| `MYSQL_DATABASE` | `common-datasource.properties` | URL 末尾的库名 |
+| `REDIS_HOST` / `PORT` | `common-cache.properties` | `meritdata.cloud.cache.serve-hosts` |
+| `REDIS_PASSWORD` | `common-cache.properties` | `meritdata.cloud.cache.serve-password` |
+| `NACOS_HOST` / `PORT` | `common.properties` | `meritdata.cloud.nacos-addr` |
+| `NACOS_USER` / `NACOS_PASSWORD` | `common-cloud-system-manage.properties` | `spring.cloud.nacos.username/password` |
+| `PLATFORM_VERSION` | `common.properties` | `meritdata.cloud.platform-version` |
+| `APP_PORT` | `common-${APP_NAME}.properties` | `server.port` |
+
+> **DATABASE_TYPE** 不在自动加载范围，必须由用户**显式指定**（MySQL/DM/Oracle/PostgreSQL）。
+
+---
+
+## 10 个变量详解
+
+### 关键变量（不填就中止）
+
+| 变量 | 含义 | 示例 |
+|------|------|------|
+| **`APP_NAME`** | Spring Boot 应用名（`spring.application.name`） | `myapp` |
+| **`MAVEN_SETTINGS`** | Maven `settings.xml` 绝对路径 | `D:/apache-maven-3.9.14/conf/settings.xml` |
+| **`MERIT_HOME`** | 美林平台环境根（含 `key/` 证书） | `D:/A_meritdata/Env_windows_V6.13.2` |
+| **`FRONTEND_PAGES`** | 前端业务页面名（逗号分隔） | `page1,page2,page3` |
+
+### 必填但有默认值
+
+| 变量 | 含义 | 默认值 |
+|------|------|--------|
+| `APP_PORT` | 后端服务端口 | `18080`（避开 8080/8081/8085）|
+| `PLATFORM_VERSION` | 美林平台版本号 | `6.13.2` |
+| `DATABASE_TYPE` | 数据库类型 | `mysql`（其他：`dm` / `oracle` / `postgresql`）|
+
+### 可选（自动加载或可省）
+
+| 变量 | 含义 | 来源 |
+|------|------|------|
+| `MYSQL_HOST` / `PORT` | 数据库地址 | Nacos 导出目录自动 |
+| `MYSQL_USER` / `PASSWORD` | 数据库凭据 | Nacos 导出目录自动 |
+| `MYSQL_DATABASE` | 数据库名 | Nacos 导出目录自动 |
+| `NACOS_HOST` / `PORT` | Nacos 地址 | Nacos 导出目录自动 |
+| `NACOS_USER` / `PASSWORD` | Nacos 凭据 | Nacos 导出目录自动 |
+| `REDIS_HOST` / `PORT` | Redis 地址 | Nacos 导出目录自动 |
+| `REDIS_PASSWORD` | Redis 密码 | Nacos 导出目录自动 |
+
+---
+
+## DATABASE_TYPE 分支逻辑
+
+| 类型 | JDBC Driver | 表前缀 | 备注 |
+|------|------------|--------|------|
+| `mysql`（默认）| `com.mysql.cj.jdbc.Driver` | 无 | 原 check-database.sh 逻辑 |
+| `dm` | `dm.jdbc.driver.DmDriver` | `DAMENG.` | 达梦数据库 |
+| `oracle` | `oracle.jdbc.OracleDriver` | `ORCL.`（取决于 SID）| |
+| `postgresql` | `org.postgresql.Driver` | `public.` | |
+
+> **表名检查**：`pf_user_info` / `act_*` / `pf_job_*` 在所有 DB 中应存在（可能带 schema 前缀）。
+
+---
+
+## .env 持久化格式
+
+```bash
+# Generated by meritdata-platform-2nd-dev-check skill at 2026-08-12 17:30:00
+APP_NAME='myapp'
+APP_PORT='18080'
+MAVEN_SETTINGS='D:/apache-maven-3.9.14/conf/settings.xml'
+MERIT_HOME='D:/A_meritdata/Env_windows_V6.13.2'
+PLATFORM_VERSION='6.13.2'
+FRONTEND_PAGES='page1,page2,page3'
+DATABASE_TYPE='mysql'
+MYSQL_HOST='localhost'
+MYSQL_PORT='3337'
+MYSQL_USER='root'
+MYSQL_PASSWORD='***敏感***'
+...
+```
+
+**保护机制**：
+- `chmod 600`（Linux/Mac）
+- `icacls /inheritance:r /grant:r ${USERNAME}:(R,W)`（Windows）
+- 自动加 `.env` 到 `.gitignore`
+
+**删除需先恢复权限**（Windows）：
+```bash
+icacls .env /reset
+```
+
+---
+
+## 弹窗分组设计
+
+> 💡 **设计要点**：AskUserQuestion **不支持文本默认值**，但 **multi-choice 可以把默认当第一项**。
+> 每个变量**单独弹窗**，按"能否有 universal 默认"分**四档**处理。
+> 用户**1-click 接受默认**（A 档）/ 部分系统（B 档）/ **必须 2-click 选 Other**（C/D 档）。
+
+### 四档分类
+
+| 档 | 含义 | 变量 | 1-click 默认？ |
+|----|------|------|---------------|
+| **A. 环境配置** | 来自**项目内 Nacos 导出目录**（默认 `nacos_config_export/`） | DATABASE_TYPE / MYSQL_*(5) / NACOS_*(4) / REDIS_*(3) / PLATFORM_VERSION | ✅ 强默认 |
+| **B. 通用约定** | 工具/系统默认位置（与机器无关）| MAVEN_SETTINGS（`~/.m2/settings.xml`）| ⚠️ 弱默认（仅 Linux/Mac）|
+| **C. 项目配置** | **新二开项目**需自己决定，**不能从样例继承** | **APP_NAME / APP_PORT / FRONTEND_PAGES** | ❌ **必须 Other** |
+| **D. 机器路径** | 每台机器不同，**无 universal 默认** | **MERIT_HOME** | ❌ **必须 Other** |
+
+> ⚠️ **关键洞察**：C 档的 `APP_NAME` / `APP_PORT` / `FRONTEND_PAGES` 是**新二开项目**的命名/端口/页面，**用户还没开始开发**，**没有"默认值"可言**。
+
+### A 档弹窗模板（环境配置）
+
+```
+Q: <变量名>?
+  ● <auto-loaded value>（来自 Nacos 导出目录）   ← 强默认，1-click
+  ○ <常见备选 1>                                       ← 2-click 改
+  ○ <常见备选 2>
+  ○ Other
+```
+
+### B 档弹窗模板（通用约定）
+
+```
+Q: MAVEN_SETTINGS?
+  ● ~/.m2/settings.xml（如果存在）                     ← 通用默认（Linux/Mac）
+  ○ ${MAVEN_HOME}/conf/settings.xml（如果 MAVEN_HOME 设置）
+  ○ Other（输入自定义路径）
+```
+
+**Windows 特殊性**：`~/.m2/settings.xml` 在 Windows 下是 `C:\Users\<user>\.m2\settings.xml`，但用户更可能用 `D:/apache-maven-*/conf/settings.xml`。所以 Windows 下 `~/.m2` 默认**可能不命中**，用户大概率要走 Other。
+
+### C 档弹窗模板（项目配置）—— **无默认**
+
+```
+Q: APP_NAME?（你的新二开项目名，pom.xml artifactId）
+  ○ my-app-name（示例）
+  ○ my-business-system（示例）
+  ○ Other（请输入你的项目名）
+
+Q: APP_PORT?（你的新二开项目端口，避开 8080/8081/8085）
+  ○ 18080（示例）
+  ○ 18081（示例）
+  ○ 18082（示例）
+  ○ Other
+
+Q: FRONTEND_PAGES?（你的新二开项目业务页，逗号分隔）
+  ○ page1,page2,page3（示例）
+  ○ platform-demo（仅当你保持样例名时）
+  ○ Other
+```
+
+### D 档弹窗模板（机器路径）—— **无默认**
+
+```
+Q: MERIT_HOME?（美林平台环境根，含 key/ 证书）
+  ○ Other（请输入你的实际路径）
+     提示：常见路径
+       Windows: D:/A_meritdata/Env_*
+       Linux:   /opt/meritdata/Env_*
+       Mac:     ~/merit-platform/env
+```
+
+**为什么 D 档不能有默认**：
+- 你本机：D:/A_meritdata/Env_windows_V6.13.2
+- 用户 A：/opt/meritdata/Env_linux
+- 用户 B：C:/Merit/Env
+- 用户 C：~/merit-platform/env
+- **每台机器不同，没有任何规律可循**
+
+**为什么 C 档不能有默认**：
+- `APP_NAME` 是**新二开项目的命名**，用户还没开始开发
+- `APP_PORT` 是新项目的端口，用户要避开 8080/8081/8085/8848（Nacos）等
+- `FRONTEND_PAGES` 是新项目的业务模块，用户自己决定
+
+### A 档实际弹窗示例（基于项目内 Nacos 导出目录真实数据）
+
+```
+Q: DATABASE_TYPE?
+  ● mysql（来自 Nacos 导出目录：com.mysql.cj.jdbc.Driver）
+  ○ dm（达梦）
+  ○ oracle
+  ○ postgresql
+
+Q: MYSQL_HOST?
+  ● localhost（来自 Nacos 导出目录）
+  ○ 127.0.0.1
+  ○ Other
+
+Q: MYSQL_PASSWORD?
+  ● ************（来自 Nacos 导出目录，已脱敏）
+  ○ Other（请输入实际密码）
+
+Q: NACOS_HOST?
+  ● localhost（来自 Nacos 导出目录）
+  ○ 127.0.0.1
+  ○ Other
+
+Q: PLATFORM_VERSION?
+  ● 6.13.2（来自 Nacos 导出目录）
+  ○ 6.12.1
+  ○ 6.11.0
+  ○ Other
+```
+
+### 关键变量未填就中止
+
+如果用户选 "Other" 但**留空**，write-env.sh 会报错：
+
+```json
+{"success": false, "error": "APP_NAME 不能为空"}
+```