用户向导

用户向导在安装、升级、应用配置和卸载时收集用户输入。文件位于 apps/<appname>/wizard/，向导字段会以同名环境变量传给生命周期脚本。

向导文件

文件	触发时机	典型用途
`wizard/install`	首次安装	端口、存储方式、管理员账号等初始配置
`wizard/upgrade`	升级期间	新增配置、兼容旧字段或重新确认风险配置
`wizard/config`	安装后的设置	修改端口、外部服务和应用运行选项
`wizard/uninstall`	卸载期间	选择保留或删除用户数据

不需要某一阶段时，按平台和应用模板保留正确的文件结构，不要用应用脚本猜测向导是否执行。

基本结构

向导通常是步骤数组，每个步骤包含 stepTitle 和 items：

json

[
  {
    "stepTitle": "基础配置",
    "items": [
      {
        "type": "text",
        "field": "wizard_port",
        "label": "服务端口",
        "helpText": "应用服务监听的端口号",
        "initValue": "5230",
        "rules": [
          {
            "required": true,
            "message": "请输入服务端口"
          },
          {
            "pattern": "^[0-9]+$",
            "message": "端口号必须为正整数"
          }
        ]
      }
    ]
  }
]

字段名建议使用 wizard_ 前缀，避免与系统保留的 TRIM_* 环境变量冲突。field 是配置契约的一部分，修改它等同于修改升级和生命周期接口。

常用字段

字段	作用
`type`	控件类型，如 `text`、`select`、`tips`
`field`	提交字段名，也是生命周期环境变量名
`label`	用户看到的字段标题
`helpText`	补充格式、用途和安全提示
`initValue`	默认值；应是安全且可运行的默认配置
`options`	`select` 的选项数组，每项包含 `label` 和 `value`
`rules`	`required`、`pattern` 等输入校验规则

复杂配置应拆成多个有明确含义的字段，不要让生命周期脚本解析一段难以校验的自由文本。密码、Token 和 DSN 必须说明存储、日志脱敏和升级保留策略。

字段与运行时联动

同一配置应在向导、Manifest、入口和生命周期脚本中保持一致：

text

wizard_port
  ├─ wizard/install、wizard/config：收集和修改
  ├─ manifest：声明服务端口或入口约束
  ├─ app/ui/config：${wizard_port} 作为入口端口
  └─ cmd/main：${wizard_port} 作为服务启动参数

安装、升级和配置向导尽量使用相同字段名，使已有配置能够平滑迁移。新增字段时应决定：旧版本缺失时的默认值、升级时是否补齐、卸载时是否清理。

向导设计原则

只询问应用无法自动判断且确实需要的配置。
每个字段提供合理默认值；非必填字段不要添加 required。
端口、地址、枚举和路径增加格式或范围校验。
select 用于少量固定选项，复杂解释放在 helpText 或 tips。
不在 helpText 中放真实密码、Token 或内部地址。
默认值必须能在干净安装中工作，不能依赖个人环境。
配置保存应可重复执行，升级不能覆盖用户主动修改的值。
卸载向导明确区分应用文件、缓存、配置和用户数据。

卸载数据选择

推荐让用户明确选择数据动作，并由 cmd/uninstall_callback 读取 wizard_data_action 环境变量执行对应逻辑：

text

用户选择“保留数据” → 停止服务 → 删除运行文件 → 保留持久化目录
用户选择“删除数据” → 停止服务 → 删除运行文件和用户数据 → 返回结果

不要根据“卸载脚本被调用”就直接删除 ${TRIM_PKGVAR} 下的全部内容；升级回滚和误操作恢复都需要保留边界。

验证

修改向导后先做结构和打包检查：

bash

# JSON 文件解析和项目统一检查
pnpm run check -- --all

# FPK 结构检查
cd apps/<appname>
fnpack build

在测试 NAS 上逐项验证：

首次安装显示字段、默认值和校验错误。
取消、重新打开和保存配置不会产生半成品配置。
升级后旧字段保留，新字段使用预期默认值。
入口端口、服务启动参数和实际监听端口一致。
管理员与普通用户看到的配置项符合权限策略。
卸载分别验证保留数据和删除数据两条路径。

用户向导 ​

向导文件 ​

基本结构 ​

常用字段 ​

字段与运行时联动 ​

向导设计原则 ​

卸载数据选择 ​

验证 ​