QM-ServerV2 知识库

Appearance

规范项目结构树（uniapp CLI 编译要求对照） ​

基准：qm-frontend api 分支（v18 真机验证通过的形态）。✅ = 符合规范；⚠️ = 可用但有改进项。

qm-frontend/                      # 仓库根 = 工程根（CLI 形态，HBuilderX 不参与编译）
├── package.json                  # ✅ @dcloudio/* 3.0.0-5020420260813001 精确锁版本（禁 caret）
├── vite.config.ts                # ✅ @dcloudio/vite-plugin-uni
├── tsconfig.json                 # ✅ @ 别名 → src
├── index.html                    # ✅ CLI 入口
├── src/                          # ✅ 源码根（UNI_INPUT_DIR）
│   ├── main.ts                   # ✅ createSSRApp 入口
│   ├── App.vue                   # ✅ 全局生命周期
│   ├── manifest.json             # ✅ appid __UNI__F1DDAB4 / 包名 cn.qingmulife.muhehealth
│   ├── pages.json                # ✅ 34 页注册 + tabBar(custom)
│   ├── pages/                    # ✅ 页面目录（分组建：login/index/ai/run/mine/detail/form/agreement/my-plan/webview）
│   │   ├── run/*.nvue            # ⚠️ 仅 2 页 .nvue（GPS 跑步 — 原生渲染 map 必需）；新页面默认 .vue
│   │   ├── */components/         # ✅ 页面私有子组件就地放（index/mine/info 均如此）
│   │   └── ...
│   ├── components/               # ✅ 全局 qm-* 组件 ×20（easycom 可考虑，见改进项 3）
│   ├── api/                      # ✅ 6 文件（agreement/device/login/splash/training/user）
│   │                             #    ⚠️ 仍未收敛：api/stats.ts 未建（首页直调）+ api/sport.ts 未建（改进项 1）
│   ├── utils/                    # ✅ request.ts（请求封装核心）/ storage / device / toastUtil 等 9 文件
│   ├── config/                   # ✅ BASE_URL 等环境配置
│   ├── static/                   # ✅ 静态资源（编译直拷）
│   └── uni_modules/              # ✅ uniapp 插件
└── BUILD-CLI.md                  # ✅ 编译说明（npm i → npm run build:app → dist/build/app）

编译要求对照（硬性） ​

要求做法违反后果
编译器精确锁版本@dcloudio/* 全系 3.0.0-5020420260813001caret 拉 alpha → createUniXKotlinCompilerOnce 崩
隐藏依赖显式声明sass、uni-uts-v1 必须在 devDependencies首次 npm i 缺失即编译失败
根平铺不可用源码必须在 src/UNI_INPUT_DIR=. 根平铺模式 vite resolve 失败（已验证放弃）
产物npm run build:app → dist/build/app/= 基座 assets/apps/__UNI__F1DDAB4/www/ 替换资源

改进项（按优先级） ​

  1. API 层收敛：device.ts 已于 2026-09-18 建立（device-list.vue 已 import）—— 现在 src/api/ 是 6 文件，实际内联点只剩首页 index.vue 的 2 处（getTodayOverview + myTodayHealth， 按手册口径归「页面直调」）。后续按需补 stats.ts / sport.ts — 统一超时/鉴权/解包路径，便于契约文档对账
  2. pages.json 分包：detail（13 页）+ mine（10 页）可拆 subPackages 减小主包体积（当前全在主包）
  3. easycom：qm-* 组件配置 easycom 自动注册，免逐页 import
  4. 环境分型：config/index.ts 目前单 BASE_URL；建议 dev/prod 双环境注入（编译期 process.env.NODE_ENV）

注：以上均为「建议」，任何结构改动需走完整编译 + 真机回归（v18 基线）。