📏 uni-app 编码规范

uni-app 主工程使用 Vue3 + TypeScript + Pinia。它需要同时兼顾 H5、微信小程序和 App，因此不能照搬 Web Admin 的运行时代码。

🧮 硬性规则

• Vue 文件统一使用 <script lang="ts" setup> 与组合式 API。
• 业务能力通过按需导入 API、组合式函数和 Pinia store 引入。
• 请求、缓存、反馈使用 uni-app 端专属封装（utils/request.ts、utils/cache.ts、utils/feedback.ts），不复用 Admin 的 axios、localStorage、Element Plus 反馈工具。
• 小程序/App 的接口域名必须是完整 URL。

🏗️ 页面组织

System 页面：

src/pages/system

新增模块：

src/pages/{module}

模块私有接口：

src/modules/{module}/apis

跨模块公共接口：

src/apis/{module}

🆕 页面新增步骤

1. 新增 .vue 页面，使用 <script lang="ts" setup>。
2. 在 src/pages.json 登记页面，并为页面项声明稳定的 name。
3. 如果页面允许游客访问，在页面项中声明 guest: true；未声明时默认需要登录。
4. 如果是 tab 页面，同步 pages.json 的 tabBar。
5. 所有跳转统一使用 toRouter()；页面后退统一使用 backRouter()。

🛰️ 请求规范

• API 文件只写 system/user/info 这类业务路径。
• 不写 /api 前缀。
• 不拼完整域名，除非调用第三方绝对 URL。
• 登录态由请求封装自动带 token。
• 业务错误交给请求封装提示，页面只处理具体业务状态。

🧰 工具方法用途

src/utils 只放跨页面、跨模块复用的运行时工具。页面私有逻辑优先放在页面目录或对应 composable 中。

文件	用途	使用场景
auth.ts	登录凭据和用户信息缓存读写	请求封装、用户 Store、登录失效处理
cache.ts	带项目前缀和过期时间的本地缓存	token、用户信息、配置类缓存
request.ts	统一 API 请求、token 注入、响应 code 处理	src/apis 下所有业务接口
feedback.ts	Toast、Modal、Loading、复制文本的统一入口	页面提交、接口错误、确认操作、复制提示
page.ts	从 pages.json 解析页面 name、路径、游客页和 tabBar	路由跳转前的页面识别
router.ts	页面跳转、后退、登录拦截、装修链接协议解析	页面跳转、重定向、重启统一使用 toRouter()；页面后退统一使用 backRouter()
file.ts	文件 URL 补全	图片、头像、附件字段渲染前处理
decoration.ts	装修数据和组件结构归一化	DecorationRender.vue 渲染前处理后端数据
navigation.ts	自定义导航栏安全区计算	自定义 Navbar、顶部沉浸式页面
platform.ts	编译平台判断	H5、小程序、App 差异逻辑
text.ts	页面 query 文本解码	标题、搜索词、文章详情标题
theme.ts	移动端主题色读取入口	自定义 tabBar、局部主题样式
update.ts	微信小程序强制更新检查	小程序启动时发现新版本后更新再继续使用
value.ts	常见空值判断	表单、参数、配置值校验

页面跳转优先传页面 name：

toRouter('userCenter')
toRouter('articleDetail?id=1')
toRouter('profile', { mode: 'redirectTo' })
toRouter('home', { mode: 'reLaunch' })
backRouter({ fallback: 'userCenter' })

后台装修数据和模块资源清单仍保存当前有效页面路径，例如 /pages/system/article/detail。前端业务代码不要再维护页面路径常量。

🔐 登录与受保护页面

页面登录规则由 pages.json 管理。跳转前会：

• 检查 token。
• 微信小程序尝试静默登录。
• 失败则跳转登录页并带 redirect。

页面默认需要登录，允许游客访问的页面声明 "guest": true ：

{
  "path": "pages/system/index/index",
  "name": "home",
  "guest": true
}

页面内部如必须登录，也可使用：

src/composables/useRequireLoginPage.ts

📖 组件规范

基础组件放：

src/components/base

业务组件放：

src/components/{domain}

页面私有组件优先放页面目录附近，避免全局组件目录膨胀。

🎨 装修渲染

装修渲染统一收口：

src/components/decoration/DecorationRender.vue

新增装修组件时：

• 先确认 Admin 装修设计器输出的数据结构。
• 在 src/types/decoration.ts 补类型。
• 在 src/utils/decoration.ts 做归一化。
• 主工程基础组件在 DecorationRender.vue 增加渲染分支。
• 可安装模块的装修组件在模块 Resources/publish-manifest.json 中声明，由模块安装器生成 src/modules/decoration-widgets.ts 和 src/modules/DecorationWidgetsRender.vue，不要直接手写这两个生成文件。
• 链接跳转统一使用 toRouter()。

💫 样式规范

• 通用布局、间距、颜色、圆角、阴影优先使用 Tailwind 工具类，保持和 Admin 端接近的原子化写法。
• Tailwind 配置集中在 tailwind.config.ts，多端转换由 weapp-tailwindcss 处理。
• 使用 rpx 适配多端，Tailwind 主题中的 spacing、fontSize、radius、shadow 已按移动端单位配置。
• 项目仅使用 Tailwind 工具类。
• 公共变量放 src/styles/variables.scss。
• 页面复杂结构、平台差异和装修组件动态样式使用 scoped SCSS。
• 图片使用 BaseImage 处理兜底。
• 注意小程序不支持的 CSS 能力，复杂效果先验证平台。

🔌 第三方插件

src/uni_modules/z-paging 是第三方插件目录。业务规范检查、批量格式化、重构搜索时应排除该目录，避免误改插件源码。

✅ 构建检查

# 进入 uni-app 项目目录
cd frontend/uniapp

# 执行 TypeScript 类型检查
npm run typecheck

# 构建 H5 生产产物
npm run build:h5

# 构建微信小程序生产产物
npm run build:mp-weixin

# 构建 App 生产产物
npm run build:app

微信小程序构建前，需要在 frontend/uniapp/src/manifest.json 的 mp-weixin.appid 填写微信小程序 AppID：

{
  "mp-weixin": {
    "appid": "你的微信小程序 AppID"
  }
}

至少确认：

• H5 构建后已自动发布到 public/h5，并能通过 /h5 打开。
• 小程序已填写 mp-weixin.appid，构建产物能被微信开发者工具导入。
• 受保护页面未登录时能正确跳登录。
• 装修链接使用当前有效页面路径。