83 lines
8.1 KiB
Markdown
83 lines
8.1 KiB
Markdown
# `biz_zax_app_cloud` 开发规则
|
||
|
||
> 适用于 uni-app 移动端项目。执行任务前必须先完整阅读 [HQ Platform 通用规则](../agents/common.md)，并继续检查目标目录内更具体的说明和现有同类实现。
|
||
|
||
## 技术栈基线与平台范围
|
||
|
||
以下版本是当前项目扫描结果，后续以 `package.json`、`src/uni_modules/tm-ui/package.json` 和锁文件为准。
|
||
|
||
- 应用框架：uni-app Vue 3，DCloud 依赖版本为 `3.0.0-5000720260410001`，应用由 `createSSRApp` 创建。
|
||
- 基础运行时：Vue `3.4.x`、TypeScript `4.9.x`、Vite `5.2.8`。
|
||
- UI 框架：项目内置 uni_modules 版 tm-ui `3.2.0`，Vue 3 + TypeScript，支持 App Vue 与 H5；本地组件描述明确不支持 App NVUE，因此使用 NVUE 前必须单独核对组件兼容性。
|
||
- 样式体系：UnoCSS `0.58.9`、`unocss-preset-weapp`、Sass。UnoCSS 已启用 `whRpx`、Attributify 和 class transformer。
|
||
- 状态管理：Pinia `3.0.x` 与 `pinia-plugin-persistedstate`，持久化适配器使用 `uni.getStorageSync` / `uni.setStorageSync`，不得直接替换为浏览器 `localStorage`。
|
||
- 网络层：`luch-request`，统一封装位于 `src/sheep/utils/request.ts`，负责 H5/App Base URL、Token、Token 刷新、租户头、TOC 头、请求/响应加解密、登录过期跳转和统一提示。
|
||
- 路由：以 `src/pages.json` 为页面与分包真源，通过 Vite 路由插件读取 `meta`，业务跳转统一使用 `src/sheep/router` 对 `uni.navigateTo`、`switchTab`、`redirectTo`、`reLaunch` 的封装。
|
||
- 列表与数据展示：`z-paging` 用于分页列表；`@qiun/uni-ucharts` 和本地 qiun/uCharts 组件用于跨端图表。
|
||
- 图形能力：用户关系树使用 `@antv/hierarchy` 的 `compactBox` 布局；不要把 PC 端 `@vue-flow` 直接搬到移动端。
|
||
- 动效与工具：Lottie Web、Day.js、Radash、CryptoJS、Base64 等已经存在，使用前先检查跨端封装。
|
||
- 目标平台：**iOS App、Android App、H5**。项目虽保留多个小程序构建依赖和脚本，但当前需求默认不以小程序为验收目标，除非用户另行指定。
|
||
|
||
## 关键目录与入口
|
||
|
||
- `src/main.ts`：创建应用，加载 `uno.css`，注册 Pinia 和 tm-ui。
|
||
- `src/App.vue`：应用生命周期、启动逻辑、App 平台推送/权限初始化、全局状态联动等。
|
||
- `src/pages`：实际页面，包含登录、用户、食堂、商城、订单、钱包、配送、门禁/人脸、商户和管理等业务。
|
||
- `src/pages.json`：页面、分包、导航栏、TabBar 和 Easycom 配置。新增页面必须同步登记，优先放入对应业务分包。
|
||
- `src/sheep/api`：移动端接口层；页面不得直接散落 `uni.request` 或新建请求实例。
|
||
- `src/sheep/components`：基础组件、CRUD 组件和业务公共组件；Easycom 已将 `base-*`、`crud-*` 自动映射到此处。
|
||
- `src/sheep/hooks`：页面与列表公共逻辑；新页面应先搜索分页、状态和业务 Hook。
|
||
- `src/sheep/stores`：用户、TabBar、购物车、支付、推送等 Pinia Store。
|
||
- `src/sheep/router`：统一路由跳转、TabBar 判断、防重复跳转和返回处理。
|
||
- `src/sheep/utils`：请求、环境、加解密、文件、支付、推送、平台跳转等工具。
|
||
- `src/uni_modules/tm-ui`：项目实际使用的 TMUI 源码与组件，不得直接修改第三方组件来解决单页问题，除非明确要求进行全局修复。
|
||
- `src/static/app-plus` 与 `src/static/h5`：平台专属资源；共用资源放在通用 `src/static` 下。
|
||
- `vite.config.ts`：`@` 指向 `src`，`@@` 指向 `src/sheep`；接入 uni、UnoCSS、路由插件和 IIFE 构建兼容处理，开发服务端口为 `8889`。
|
||
|
||
## UI 与 UnoCSS 约定
|
||
|
||
- `src/pages.json` 已通过 Easycom 自动映射 `tm-*`、`base-*`、`crud-*` 和 `z-paging*`，优先直接使用这些既有组件命名。
|
||
- 修改前必须检查 `unocss.config.ts`。当前已有 `flex-col-center`、`flex-row-center`、`flex-col`、`flex-row`、`border-base` shortcuts，以及 `theme-text-*`、`main-text-*`、`sub-text-*`、`second-text-*`、`show-line-*`、`card`、`shadow-main` 等规则。
|
||
- `whRpx: true` 会把宽高相关原子值按 rpx 体系处理。新增尺寸前先理解现有类的实际输出，避免把 px、rpx 和设计稿数值混用。
|
||
- 普通布局、间距、字号、圆角、颜色、截断优先用 UnoCSS；只有平台差异、动态计算、第三方组件深层覆盖或复杂动画才使用局部 SCSS/CSS。
|
||
- UI 组件优先使用项目内 tm-ui 与 `sheep/components` 封装。需要核对 API 时参考 <https://tmui.design/> 与本地组件源码，不能凭其他 UI 框架经验猜测属性和事件。
|
||
- 页面视觉应延续同业务现有风格，尤其是顶栏、安全区、卡片密度、列表行高、按钮尺寸、表单校验、弹层和加载/空状态。
|
||
|
||
## 请求、状态与路由约定
|
||
|
||
- 所有业务请求通过 `src/sheep/utils/request.ts` 和 `src/sheep/api` 发起；不得绕过现有 Token 刷新、请求加密、租户和错误处理。
|
||
- H5 的 Base URL 从 `VITE_API_URL` 读取，非 H5 由 `getBaseApiUrl()` 根据开发/生产环境读取服务地址；修改环境逻辑前必须同时核对两条路径。
|
||
- Token 与用户信息使用项目 storage 常量和 Pinia 持久化，不得另建同义 Key。
|
||
- 页面跳转优先使用 `@@/router`，保持 TabBar、节流、防重复跳转和无历史返回逻辑一致。
|
||
- 新增页面时先判断属于主包还是现有分包，避免扩大主包；页面路径、TabBar 路径和路由辅助逻辑必须保持一致。
|
||
|
||
## 原生与跨平台能力
|
||
|
||
- `src/manifest.json` 已配置 Push、Payment、OAuth、Share、VideoPlayer、Maps、Barcode、Camera 等 App 模块，以及 Android/iOS 权限、Universal Links、支付、地图和推送配置。
|
||
- 不得随意修改 AppID、包名、Bundle ID、证书、Universal Links、推送 AppKey、支付参数、地图 Key、权限或隐私描述。需求涉及这些配置时先说明影响并取得确认。
|
||
- App 生命周期与推送初始化已有 `APP-PLUS` 条件编译；新增平台代码必须沿用 `#ifdef` / `#ifndef`，并提供 H5 或另一移动平台的合理降级。
|
||
- H5 专属 DOM、Lottie 或浏览器 API 必须隔离；App 原生插件、`plus` API 和权限请求也必须隔离。共享模块不能在导入阶段直接访问单平台全局对象。
|
||
- 必须检查安全区域、状态栏、底部手势区、软键盘、页面滚动、返回行为、触摸目标和不同屏宽。
|
||
|
||
## 常用命令与验证
|
||
|
||
- H5 开发：`pnpm dev:h5`。
|
||
- H5 构建：`pnpm build:h5`。
|
||
- 类型检查：`pnpm type-check`。
|
||
- App 真机与发行包按项目现有 HBuilderX / uni-app 工作流执行；不得把 H5 构建成功等同于 iOS、Android 已验证。
|
||
- 涉及条件编译、原生权限、支付、推送、地图、相机或扫码时，必须分别核对 Android、iOS 与 H5 路径，并如实说明哪些平台只做了静态检查。
|
||
|
||
## 开发规则
|
||
|
||
- 修改前必须查看 `unocss.config.ts`、`vite.config.ts`、`src/pages.json`、`src/manifest.json`、全局样式和同类页面，确认已有快捷类、主题、页面配置与平台配置。
|
||
- UI 组件优先使用项目内现有 tm-ui 组件和封装，并遵循当前项目的组件调用方式；需要确认组件能力时参考 TMUI 文档，不凭印象编造属性或事件。
|
||
- 常规样式优先使用 UnoCSS 原子类和项目已有 shortcuts/rules，不重复写可被原子类表达的 scoped CSS。
|
||
- 所有页面和功能必须同时考虑 iOS、Android、H5，不得只按单一平台实现。涉及平台能力差异时，使用 uni-app 官方能力或规范的条件编译，并为不支持的平台提供合理降级。
|
||
- 注意安全区域、状态栏、导航栏、底部操作区、键盘顶起、滚动容器、触摸区域、单位选择和横竖屏/不同屏宽下的表现。
|
||
- 禁止直接使用仅浏览器可用的 DOM/BOM API 或仅 App 可用的原生能力而不做平台隔离。
|
||
- 日常修改不自动执行 H5 或 App 构建；收到用户明确的集中验证指令后，再检查 H5 构建，并按改动范围核对 iOS、Android 分支及相关配置，明确说明实际验证范围。
|
||
|
||
## 完成前项目检查
|
||
|
||
- [ ] 移动端改动已考虑 iOS、Android、H5 适配。
|