更新记录

1.0.0（2026-10-27） 下载此版本

工程架构从零搭建至首个稳定形态：对标 vue-admin-template 分层思想，以 uni-app x 技术栈 + 梦曦插件系（ux-router / ux-pinia / mx-request / ux-storage / ux-utils）完整落地，Web 端全链路验证通过。

Added

• 分层骨架：api/（领域接口）、stores/（状态）、composables/（组合式函数）、components/（easycom 组件）、router/（路由与守卫）、utils/（request / auth）、config/（全局配置源）七大域。
• 网络层封装（utils/request.uts）：基于 mx-request 的全局默认配置、Authorization: Bearer 自动注入拦截器、按错误码映射文案的统一错误 toast（ERR_CANCELED 静默）。
• 鉴权体系（utils/auth.uts）：token 内存缓存（同步读）+ ux-storage 持久化（异步落盘），ensureAuthReady() 消除冷启动竞态。
• 全局路由守卫（router/permission.uts）：白名单 + token 检查 + getInfo 补拉（失败 resetToken 回登录页）；冷启动经 router.guardRoute() 补跑守卫链；async 守卫 + 显式 RawLocation/NavigationRedirect 重定向。
• 导航兜底：启用 ux-router InterceptorPlugin（interceptUniApi: true）——外部直调的 uni.navigateTo 等原生导航被拦截转交守卫链，防止绕过鉴权守卫；Web 端全链路回归通过，拦截器无误拦。
• 登录闭环：pages/login/login.uvue 登录页（redirect 回跳）、首页欢迎语与退出登录、pages.json 与路由表注册（defineUniPage 宏 + vite 插件生成）。
• 领域模块：api/user.uts（login / getInfo / logout 薄封装，DTO 强类型还原）、stores/modules/user.uts（loginAction / getInfoAction / logoutAction / resetToken）、composables/useLoading.uts（异步加载态，错误透传）。
• 组件：components/AppLogo/AppLogo.uvue（easycom 免注册，登录页与首页消费）。
• 类型组织体系：域级 types/ 目录 + types.uts 具名类型聚合出口（api / stores / composables 三域同构），DTO 与出口形状集中管理；归属标准写入各域文件头注释。
• ux-utils 接入：request 层错误 toast、App 端返回键提示（自绘通道 position 全生效）、退出登录前置 showModalAsync 确认弹窗。
• 文档：架构说明文档（仓库单文档门面）与本更新日志。
• AI 协作规则体系（.trae/）：rules/ 四件套（architecture 架构红线 / core-protocol 行为协议与 DoD / workflow 文档驱动四步工作流 / project_rules 通用规范沉淀）、skills/arch-feature 新功能开发技能、documents/ 任务文档归档（含 implementation-log 汇总索引）、uni-app-x MCP 配置；各部分职责见仓库首页架构文档第 9 节。

Changed

• servers/ 目录解散并重构为社区流行命名：servers/http.uts → utils/request.uts（initHttp → initRequest）、servers/api/ → api/、servers/index.uts 装配薄层移除（main.uts 直接调用 initRequest()）。
• permission.uts / settings.uts 从项目根目录归位至 router/、config/。
• 类型定义分批抽取：UserStore（stores）、LoadingState（composables）、DTO（api）统一收拢至各域 types/；config 的 AppSettings 维持就近（单文件模块私有契约，判据已注释存档）。
• 响应处理升级：api 层以 JSON.parse<T> 官方路径还原 DTO，store 与页面不再接触裸 UTSJSONObject 下标。
• toast 调用从 uni.showToast 迁移至 ux-utils showToast（参数同构，迁移零成本）。
• 页面路由元信息补齐：pages/index/index.uvue 补 defineUniPage({ name, title }) 编译宏（此前仅 login 页声明），路由 meta.title 由插件同步生成。

Removed

• servers/ 目录（http.uts / api/user.uts / index.uts）——职责拆入 utils/request.uts 与 api/。
• 根目录 permission.uts、settings.uts（迁移至 router/、utils/ 后又随 config 层落地至 config/index.uts）。
• store / composable 模块内的内联类型定义（迁移至各域 types/）。

Verified

• Web 端（HBuilderX 5.26 / VDOM / vapor）全链路验证：冷启动守卫重定向、登录 → 首页、带 token 冷启动、登出确认弹窗（取消 / 确定双路径）、DTO 解析、easycom 组件渲染、错误 toast；mock 服务端日志确认拦截器注入与请求协议正确。

Known Issues

• redirect query 在 Web 端存在双重编码（%252F）现象，round-trip 正常；深链场景需在 Android 端实测确认。
• 控制台 NavigationFailure（relaunch 后的确认日志）为 ux-router Web 端已知行为，跳转结果正确。
• Android（Kotlin）端代码同构，待真机回归。

平台兼容性

uni-app x(3.8.6)

其他

unix-architecture

uni-app x 工程架构模板，api / stores / router / utils / pages 全分层落地，底层由梦曦工作室自研插件系（unix- / mx-）承载。 技术栈：uni-app x（HBuilderX 5.26，VDOM 模式，vapor: true）· UTS 语言 · Vue3 组合式 API。

1. 项目定位

uni-app x 的页面是编译期静态模型（多端编译到 JS / Kotlin / Swift），无法直接套用标准 Vue3 的「单路由表、单插件协议」形态。本项目验证的目标是：在 uni-app x 的底座约束下，构建一套完整自洽的工程化分层——api / store / router / utils / pages 各司其职、类型契约清晰、装配点唯一。

分层与插件承载关系（各层职责单一、依赖单向）：

• uni-app x 无全局 layout 机制，页面结构由各页面自持。
• setup 式 store 中 computed 即 getter，无独立 getters 层。

2. 目录结构

├── main.uts                  # 唯一装配点：app.use(router) + initRequest() + setupPermission()
├── App.uvue                  # 应用生命周期（App 端返回键拦截等）
├── pages.json / manifest.json
│
├── api/                      # 接口层：薄封装（请求转发 + 路径收敛 + DTO 还原），不写业务逻辑
│   ├── user.uts
│   ├── types.uts             # 域类型聚合出口（具名类型转发）
│   └── types/
│       └── api.uts           # DTO 唯一事实源（LoginResult / UserInfo）
│
├── stores/                   # 状态层：ux-pinia 免挂载，模块级注册表即全局单例
│   ├── index.uts             # useXxxStore 出口
│   ├── types.uts             # 域类型聚合出口
│   ├── types/
│   │   └── user.uts          # UserStore 定义
│   └── modules/
│       └── user.uts          # token/name/avatar + login/getInfo/logout/resetToken
│
├── composables/              # 组合式函数：函数无出口（按需直接导入），类型走聚合出口
│   ├── useLoading.uts
│   ├── types.uts
│   └── types/
│       └── useLoading.uts    # LoadingState 定义
│
├── components/               # easycom 约定目录（components/<Name>/<Name>.uvue，免注册使用）
│   └── AppLogo/AppLogo.uvue
│
├── router/                   # 路由层
│   ├── index.uts             # createRouter（routes 由 vite 插件生成）
│   ├── permission.uts        # 全局守卫：白名单 + token 检查 + getInfo + 重定向
│   └── routes.gen.uts        # ⚠ 由 @meng-xi/unix-router/vite-plugin 自动生成，勿手改
│
├── utils/                    # 工具层
│   ├── request.uts           # mx-request 封装：configureRequest + 双拦截器（token 注入/错误 toast）
│   └── auth.uts              # token 读写：内存缓存（同步读）+ ux-storage 持久化（异步落盘）
│
├── config/
│   └── index.uts             # 全局唯一配置源（appName / baseURL / timeout）
│
├── pages/                    # 页面（uni-app x 约定，pages.json 静态注册）
│   ├── index/index.uvue
│   └── login/login.uvue
│
├── types/                    # 插件生成的 d.ts（defineUniPage / RouteNameMap），业务类型不放这里
├── .trae/                    # AI 辅助开发体系（rules / skills / documents / mcp.json，见第 9 节）
├── static/  uni_modules/  uni.scss

3. 核心调用链

页面(.uvue)
  → composables/useXxx（横切 UI 状态）
  → stores/modules/*（业务状态与动作）
  → api/<domain>（DTO 还原：JSON.parse<T>(JSON.stringify(res.data))）
  → utils/request（拦截器：token 注入 + 统一错误 toast）
  → mx-request → uni.request

• 页面不直连网络层，不接触裸 JSON；store 不引用组件。
• 鉴权数据流：登录 → setToken（内存即时生效 + ux-storage 异步落盘）→ 请求拦截器注入 Authorization: Bearer → 冷启动由 ensureAuthReady() 先行恢复内存缓存。

启动装配（main.uts，唯一装配点）

app.use(router)      // ux-router：provide + 全局 mixin(onShow syncRoute)
initRequest()        // mx-request：默认实例配置 + 双拦截器（幂等）
setupPermission()    // 注册 beforeEach + 冷启动 guardRoute() 补跑守卫链

三种装配范式并存是 uni-app x 的底座约束：ux-router 实现 Vue install 协议；ux-pinia 免挂载（原生端 app.use 不可靠，P8 实测）；mx-request 为纯函数库（全局默认实例）。

鉴权守卫（router/permission.uts）

await ensureAuthReady()           // 异步守卫（ux-router 守卫链支持 await Promise）
├─ 有 token
│   ├─ 访问登录页 → 重定向首页
│   ├─ 已有用户信息 → 放行
│   └─ 无用户信息 → await getInfoAction
│       ├─ 成功 → 放行
│       └─ 失败 → resetToken + 重定向登录页（带 redirect）
└─ 无 token
    ├─ 白名单（登录页）→ 放行
    └─ 其余 → 重定向登录页（query 带 redirect=path）

冷启动（H5 直达 / deeplink）页面已加载而守卫未执行：router.isReady().then(() => router.guardRoute()) 补跑守卫链，redirect 按 relaunch 执行。重定向指令用导出的 RawLocation / NavigationRedirect 显式类型构造（规避 UTSJSONObject 在 Kotlin 名义类型下的 cast 风险）。

4. 类型组织标准

判据：类型跟着消费关系走。

• 聚合出口一律具名类型转发（export type { X } from），不用 star re-export（Kotlin 端未实证）。
• 消费方统一从 <域>/types.uts 导入，新增类型文件时在出口追加一行转发。
• api 层负责 DTO 还原，且逐调用点内联 JSON.parse<T>(...)（具体类型）——勿提取公共泛型包装，二次泛型传递在 Kotlin 端触发泛型擦除。

5. 各域细则

• api/：薄封装；响应以 UTSJSONObject 承载、在 api 层还原为 DTO 后上抛；JSON.parse<T> 解析失败（返回 null）即 throw 快速失败。
• stores/：setup 式 defineStore<T>(id, setup)，state 用 Ref、action 用箭头函数、返回值 as T 收尾；免挂载，无需聚合实例（stores/index.uts 仅作消费入口）。
• composables/：函数从 <name>.uts 直接导入；类型经 types.uts；UTS 类型属性方法不支持泛型（uts110111161）——run 仅收 () => Promise<void> 任务，带返回值需求扩展 useTask<T> 而非给函数加泛型。
• components/：easycom 免注册；组件内只管自身样式，页面间距经外层 view 控制（规避样式隔离对组件根节点的约束）。
• router/：routes.gen.uts 与页面级 defineUniPage 宏由插件维护，人手不碰（preserveRouteChanges 会保留手工追加字段）。

6. 关键机制

7. 跨端注意事项（截至 1.0.0）

• Web 端已全量验证：冷启动守卫、登录闭环、DTO 链路、easycom、自绘 modal/toast。
• Android（Kotlin）同构代码待真机回归，已知风险点均已规避：泛型二次传递（DTO 内联还原）、export { x } from 值转发（仅用 export type）、UTSJSONObject cast（守卫重定向用导出类型构造）、app.use(pinia)（免挂载）。
• redirect query 在 Web 端存在双重编码（%252F）现象，round-trip 正常；深链场景上 Android 前建议实测。
• 控制台的 NavigationFailure（relaunch 后的确认日志）为 ux-router Web 端已知行为，跳转结果正确。

8. 运行与验证

# 运行到 Web（HBuilderX CLI）
D:\HBuilderX\cli.exe launch web --project <项目绝对路径>
# 运行日志
D:\HBuilderX\cli.exe logcat web --project <项目绝对路径> --mode lastBuild

• 后端地址：config/index.uts → settings.baseURL（接真实后端替换一处即可）。
• 本地联调可用任意 mock 服务（协议：POST /user/login → {token}，GET /user/info → {name, avatar}，POST /user/logout），注意 CORS（Authorization 头需放行）。
• 页面路由由 vite 插件从 pages/ 目录生成，新增页面 = 建文件 + pages.json 注册 + 页内 defineUniPage({ name, title })。

9. AI 辅助开发体系（.trae/）

本仓库将「AI 助手如何在此架构下工作」沉淀为可执行的规则与技能，与代码同库存放、随仓库演进。各部分职责如下：

约束关系：本文档承载「架构为什么这样设计」的原理层描述，.trae/rules/architecture.md 承载「AI 必须怎么写」的强制层约束——二者同源、同步演进，修改任一侧需检查另一侧是否需要联动。