# 模板迁移评估：`.htm` (Lua) → `.ut` (ucode)

> **状态**：评估完成，未执行迁移。原因：本机无 OpenWrt 构建/运行环境，`.ut` 模板无法编译验证，冒然上线未经验证的 `.ut` 比保留 `.htm` 更危险（若 25.12 模板加载器优先 `.ut`，带 bug 的 `.ut` 会直接覆盖原本可用的 `.htm`）。

## 1. 背景

本项目的 LuCI 前端采用 **Lua 兼容模式**（`luci-lua-runtime` + `luci-compat`），模板为 `.htm`（Lua 代码 + `<% %>` / `<%= %>` / `<%: %>` 标签）。

| LuCI 版本 | 模板体系 | 本项目的 `.htm` |
|-----------|----------|------------------|
| 23.05 | Lua（`.htm`） | ✅ 原生支持 |
| 24.10 | ucode（`.ut`）为主，Lua 兼容层保留 `.htm` | ✅ 经 `luci-lua-runtime` |
| 25.12+ | 趋向 ucode（`.ut`），Lua 兼容层可能移除 | ⚠️ 风险点 |

调研结论（来自 LuCI 上游变更）：24.10 起 `luci-base` 重写为 ucode，模板加载器优先查找 `.ut`；`.htm` 通过 Lua 兼容层继续工作。25.12 若彻底移除 `luci-lua-runtime`，则 `.htm` 失效，需 `.ut` 模板。

## 2. 涉及文件（5 个模板）

`root/usr/lib/lua/luci/view/substore/` 下：
- `subscriptions.htm` — 订阅列表（表格、token 链接、复制按钮、多表单）
- `form.htm` — 添加/编辑订阅
- `nodes.htm` — 节点查看（GET 表单筛选/排序）
- `output.htm` — 输出页（格式下拉、textarea）
- `settings.htm` — 设置页（cron 选择器、规则）

## 3. `.htm` → `.ut` 语法对照

| 事项 | Lua `.htm` | ucode `.ut` |
|------|-----------|-------------|
| 输出标签 | `<%=expr%>` | `<%= expr %>`（ucode 表达式）或 `{{= expr }}` |
| 翻译标签 | `<%:Text%>` | `<%:Text%>`（保留，语义一致） |
| 引入其它模板 | `<%+header%>` / `<%+footer%>` | `<% include("header") %>` / `<% include("footer") %>` |
| 取 HTTP 参数 | `require("luci.http")` + `http.formvalue(...)` | 预绑定全局 `http`，`http.formvalue(...)` |
| 取查询参数 | `luci.dispatcher.context.query` | 预绑定全局 `REQUEST`，`REQUEST.query` |
| 迭代数组 | `for _, v in ipairs(t) do ... end` | `for (let v in t) { ... }` |
| 条件 | `if cond then ... end` | `if (cond) { ... }` |
| 字符串拼接 | `..` | `+` |
| 三元 | `a and b or c`（有陷阱） | `cond ? a : b` |
| 取长度 | `#t` | `length(t)` |
| 索引 | `t[k]` / `t.k` | `t[k]` / `t.k` |
| 核心库调用 | `require("substore.core")` 后 `core.xxx()` | `core = include("substore/core.lua")` 后 `core.xxx()` |

## 4. 关键决策点

1. **核心库无需改写**：`/usr/share/substore/*.lua` 是纯 Lua，ucode 通过 `include()` 加载 Lua 文件并调用其函数（ucode 内置 Lua 互操作）。这是本方案最有利的一点——迁移成本集中在 5 个模板文件的“胶水代码”，核心逻辑（解析/转换/输出）不受影响。

2. **控制器**：`controller/admin/substore.lua` 目前用 `module()` + `entry()`。24.10 仍支持；若 25.12 要求 ucode 控制器（`.uc`），则需另写 `controller/admin/substore.uc`。与模板一样，属胶水层。

3. **数据存储与下载端点**：`core.lua`、`action_download` 逻辑与模板语言无关，无需迁移。

## 5. 建议的落地策略

按“能验证再迁移”原则，分步：

- **第 1 步（当前）**：保持 `.htm` + `luci-lua-runtime` 依赖，确保 23.05 / 24.10 可用。
- **第 2 步**：在真实 24.10 设备上安装，验证 `.htm` 经兼容层正常渲染。
- **第 3 步**：拿到 25.12 构建环境后，逐模板迁移为 `.ut`（可 `.htm` 与 `.ut` 并存，LuCI 优先 `.ut`），每个模板迁完即在设备上验证页面。
- **第 4 步**：25.12 若移除 Lua 运行时，同步评估控制器 `.uc` 迁移。

## 6. 示例迁移（subscriptions.htm 片段）

Lua 现状：

```html
<%
local core = require("substore.core")
local items = core.list()
for _, it in ipairs(items) do
%>
  <tr><td><%=it.name%></td></tr>
<%
end
%>
```

ucode 等价：

```html
<%
let core = include("substore/core.lua");
let items = core.list();
for (let it in items) {
%>
  <tr><td><%= it.name %></td></tr>
<%
}
%>
```

> 注：`include("substore/core.lua")` 的路径与 ucode 的 `LUCI_PATH` / `package.path` 解析规则有关，具体以 25.12 目标机的 `include` 路径解析为准，迁移时需在设备上确认。