# Ulthon Admin 前端静态构建说明

本目录使用纯 PHP 的 ThinkPHP 命令进行静态合并构建，不依赖前端构建工具。拆分后的模块文件都会“完善 ua 对象”，最终合并为单文件供页面直接引用。

## 设计结构

**目录结构**
- `src/`：拆分后的源码模块
- `ua.build.json`：构建清单（sources + output）
- `ulthon-admin.js`：合并输出文件（运行时引用）

**模块划分**
- `ulthon-admin.01-core.js`：基础上下文与核心能力（ctx、init、config、url、headers、checkAuth、parame）
- `ulthon-admin.02-common.js`：请求/消息/公共方法（request、common、msg）
- `ulthon-admin.03-table.js`：表格能力（admin.table）
- `ulthon-admin.04-listen.js`：统一监听入口（admin.listen、open、checkMobile）
- `ulthon-admin.05-api.js`：组件 API 能力（admin.api）
- `ulthon-admin.06-utils.js`：工具能力（查询、缓存、页面设置、扩展名识别等）

**设计要点**
- 每个模块都只做“补全 ua 对象”的工作，避免模块间互相覆盖。
- 使用 `window.__uaCtx` 做跨模块上下文共享，保证拆分后仍能共享变量。
- 构建顺序严格依赖 `ua.build.json`，以顺序决定覆盖与依赖关系。

## 如何使用

**前端引用**
- 页面只需要引用合并后的 `ulthon-admin.js`，无需加载 `src/` 内的拆分文件。
- 全局入口保持不变：`window.ua` / `window.ulAdmin`。

**常见调用**
- `ua.listen()`：初始化页面常规行为
- `ua.table.render(...)`：渲染表格
- `ua.request.post(...)`：通用请求
- `ua.msg.success(...)`：统一消息

## 如何开发

**新增功能的推荐方式**
1. 判断属于哪类能力：核心/公共/表格/监听/API/工具
2. 在对应模块内追加 `admin.xxx = ...` 或 `admin.xxx = { ... }`
3. 若新增模块，请更新 `ua.build.json` 中的 `sources` 顺序
4. 执行构建命令生成最新 `ulthon-admin.js`

**新增模块的边界**
- 只负责“补全 ua 对象”，不引入不必要的全局变量
- 只引用 `__uaCtx` 中已注册的上下文
- 避免模块内重复初始化全局配置

**构建命令**
```bash
php think tools:ua:build
```

可通过命令参数指定配置文件路径（默认读取本目录的 `ua.build.json`）：
```bash
php think tools:ua:build --config public/static/plugs/ulthon-admin/ua.build.json
```

## 构建清单说明

`ua.build.json` 使用相对路径时，基于配置文件所在目录解析：

```json
{
  "output": "ulthon-admin.js",
  "sources": [
    "src/ulthon-admin.01-core.js",
    "src/ulthon-admin.02-common.js",
    "src/ulthon-admin.03-table.js",
    "src/ulthon-admin.04-listen.js",
    "src/ulthon-admin.05-api.js",
    "src/ulthon-admin.06-utils.js"
  ]
}
```

## 兼容性与约定

- 兼容原有 `ua` 对外 API，保持使用方式不变
- 不依赖前端打包工具
- 模块拆分后只影响维护方式，不改变运行结果

## 常见问题

**1. 构建后功能异常**
- 检查 `ua.build.json` 的顺序是否符合依赖
- 检查新增模块是否遗漏 `window.ulAdmin = window.ua = admin;`

**2. 新方法不可用**
- 确认方法定义在 `admin` 上
- 确认构建文件已更新（重新执行构建）

**3. 引用未更新**
- 页面只引用 `ulthon-admin.js`，不要引用 `src/` 文件

## 进一步建议

- 若模块继续增大，建议细分 `admin.api` 为 upload/editor/form 等更小模块
- 对外 API 建议保持稳定，避免破坏老页面
- 合并构建可纳入发布流程，避免线上文件与源码不一致