设置 · LightAIP · frontend-intro-v5

1. 页面概览

设置页（路由 /settings，PlatformSettingsPage.vue）是平台级设置页，四张卡片从上到下：授权管理（授权状态、有效期、机器码、AUTH_KEY 保存与有效期刷新）、产品信息（静态公司/版本信息）、运行参数（各服务端口速查表）、通用偏好（主题、默认落地页，保存在本机浏览器 localStorage）。

一句话总结：平台授权管理 + 本地偏好设置页，授权数据来自 AIP /license/info，偏好仅存本机。

2. 访问入口

路由与菜单：路由 /settings（name PlatformSettings），顶部导航栏「设置」入口（App.vue）；源码 action/web/src/views/PlatformSettingsPage.vue（325 行）。
认证与权限：路由 meta.requiresAuth = true，需先登录 AIP；「保存 AUTH_KEY」按钮仅 localStorage.aip_is_admin === '1' 的管理员可见，非管理员显示提示「保存 AUTH_KEY 需管理员权限」。
端口与 API 前缀：AIP 18080；API 前缀 /aip-api/v1（aipClient，/license/info、/license/auth-key）。

3. 界面布局

┌──────────────────────────────────────────────┐
│ ① 授权管理卡                                 │
│   授权状态徽标/有效期/机器码/AUTH_KEY         │
│   AUTH_KEY 输入框 + [保存 AUTH_KEY](仅管理员) │
│   [刷新有效期]                                │
│ ② 产品信息卡（静态：产品名称/代号/单位/版本/  │
│   官网/微信）                                 │
│ ③ 运行参数卡（静态表：服务/端口/说明）        │
│ ④ 通用偏好卡：主题下拉 + 默认落地页下拉       │
└──────────────────────────────────────────────┘

各板块职责：

① 授权管理：展示授权状态与有效期/机器码；保存 AUTH_KEY（写 PUT /license/auth-key）、刷新有效期（force=1 强制在线校验）；已安排自动关闭时红字提示。
② 产品信息：只读静态公司/版本信息。
③ 运行参数：7 行静态表（AIP 18080 / Foundry 18081 / Apollo 18082 / Gotham 18083 / Swift 18084 / Web 网关 80 / 前端开发 5173）。
④ 通用偏好：主题（浅色/深色）与默认落地页（/foundry 本体工作台、/apollo 部署总览、/gotham 情报工作台、/swift 工作台总览、/chat 智能查询、/ops 运维状态），存 localStorage，登出重登后访问 / 生效。

4. 交互元素

控件	位置	含义与作用
授权状态徽标	授权管理卡	「已授权」绿 /「未授权」红，来自 license.authorized
AUTH_KEY 输入框	授权管理卡	输入平台授权密钥；占位「已设置则留空不修改」，autocomplete=off
「保存 AUTH_KEY」	授权管理卡	仅管理员；`PUT /license/auth-key {auth_key}`，成功后清空输入并刷新授权信息；保存中显示「保存中...」
「刷新有效期」	授权管理卡	`GET /license/info?force=1` 强制重新在线校验；刷新中显示「刷新中...」
主题下拉	通用偏好卡	浅色/深色，切换即写入 localStorage `zy_theme` 并设置 `document.documentElement` 的 `data-theme` 属性
默认落地页下拉	通用偏好卡	6 个目标页面，写入 localStorage `zy_landing`；登出重登后访问 `/` 生效
自动关闭红字提示	授权管理卡	当 license.shutdown_scheduled 为真时显示「系统将在 X 后自动关闭（原因：…）」，hard≈20 分钟、grace≈6 小时、其余按剩余分钟数

5. 后端关联

5.1 API 端点

方法	路径	用途
GET	`/aip-api/v1/license/info`	授权信息；`?force=1` 强制在线校验刷新（默认走 TTL 缓存）
PUT	`/aip-api/v1/license/auth-key`	更新 AUTH_KEY（body `{auth_key}`），后端写入 system_settings 并重置授权缓存

5.2 响应字段

GET /license/info 返回（后端 handlers_license.go）：authorized、exp_date、hardware_id、auth_key_set、message（后端固定返回 "-"，不透传授权服务器信息）、product_info、shutdown_scheduled、shutdown_deadline（unix 秒）、shutdown_tier（hard/grace 等）、shutdown_reason。

5.3 关键机制

授权缓存与强制刷新：fetchLicense(force) 中 force=1 时后端 licenseMgr.Refresh 在线校验，否则 Get 走 TTL 缓存；「刷新有效期」按钮即强制刷新。
保存后联动：saveAuthKey 成功后清空输入框并重新 fetchLicense()；后端 handleUpdateLicenseAuthKey 成功后 licenseMgr.Reset()，下次查询自动重新在线校验。
自动关闭提示：授权不满足时后端 shutdownScheduler 安排自动关闭，页面按 shutdown_tier 估算剩余时间并红字提示（hard≈20 分钟、grace≈6 小时、其他按分钟取整）。
本地偏好：主题与落地页 watch 即写 localStorage，刷新即生效；落地页在路由守卫中读取 zy_landing 决定 / 的跳转目标。

6. 权限与安全

进入页面需 AIP 登录（路由 requiresAuth，Bearer aip_token）。
写操作保护：PUT /license/auth-key 挂在后端 admin 路由组（仅管理员）；前端同时用 aip_is_admin === '1' 控制按钮显隐，非管理员不可见也不可点。
AUTH_KEY 输入框 autocomplete=off 防浏览器自动填充；message 字段后端固定返回 "-"，避免泄露授权服务器信息。
偏好存 localStorage，属本机数据，无服务端落库。

7. 常见问题与排错

显示「获取授权信息失败」：AIP 后端（18080）未启动或 token 失效。启动 AIP、重新登录后刷新页面。
找不到「保存 AUTH_KEY」按钮：当前账号非管理员。用 admin 账号登录（aip_is_admin=1）；如需给普通账号开放，需在用户管理授予管理员角色。
保存 AUTH_KEY 后仍是「未授权」：密钥无效或在线校验失败。核对密钥是否正确（有无空格/换行）；点「刷新有效期」强制在线校验；确认网络可达授权服务器。
主题/落地页设置「丢失」：偏好保存在本机浏览器 localStorage，换浏览器、清缓存或隐私模式不生效；重新设置即可。

8. 已知缺陷与边界

项	说明
授权仅展示	授权信息用于展示与倒计时提示，后端不强制关停
message 恒为 "-"	后端不透传授权服务器 message，避免泄露敏感信息
偏好仅本机	主题/落地页不跨设备同步，登出重登后落地页才生效
保存后非 force 刷新	保存 AUTH_KEY 后以非 force 方式重拉授权，依赖后端 Reset 后自动重新校验；若在线校验网络抖动，可再点「刷新有效期」