@hlw-uni-mp/vue 开发规范与工程架构文档

1. 项目定位与开发阶段原则

• 核心定位：@hlw-uni-mp/vue 为 hlw 生态的公共核心前端生态包（Vue 3 + uni-app + Vite + TypeScript），向各业务小程序（如短视频矩阵 qz3、亲友对局记分 dapai 等）提供通用原子 UI 组件库、交互反馈门面、有状态组合式 Hooks、Pinia 持久化插件、无状态工具函数以及高可用网络请求与文件上传层。
• 初期开发阶段铁律：本项目处于初期全新开发阶段，尚未上线。完全没有历史兼容包袱，坚决严禁编写任何兼容旧写法、兼容废弃 API 或冗余 polyfill 的防御性代码。若需修改或重构，直接采用最新、最干净的标准写法。
• 全局唯一准则：所有 AI 助手、代码生成器及开发者在本项目的所有开发、重构、修复任务中，必须且只能无条件严格遵守本规范文档。

2. 目录架构与模块边界

hlw-uni-mp/vue (生态包根目录)
├── src/
│   ├── components/       # 原子 UI 组件库 (配合 uni-app easycom 机制全自动按需加载)
│   ├── composables/      # 有状态生命周期 Hooks (msg, theme, refs, share)
│   ├── directives/       # Vue 自定义指令 (如 vCopy 自动点击复制指令)
│   ├── request/          # 网络请求与上传层 (UniHttpClient 拦截器、OSS 直传、Local/七牛直传及纯类型)
│   ├── store/            # 全局状态管理 (如 themeStore 主题状态)
│   ├── utils/            # 纯无状态静态工具集 (ad, common, crypto, device, navigator)
│   ├── app.ts            # 小程序应用根上下文入口 (useApp, install)
│   ├── hlw.ts            # 全局单例门面对象 ($msg, $ad)
│   ├── index.ts          # 包唯一公开出口 (按需/统一导出)
│   ├── style.css         # 全局基础盒模型重置与设计令牌系统 (Design Tokens)
│   └── types.d.ts        # 全局门面纯类型声明
├── dist/                 # Vite 构建产物 (ESM: index.mjs, CJS: index.js, Types: index.d.ts)
├── package.json          # NPM 依赖与 exports 映射配置
└── vite.config.ts        # Vite + vite-plugin-dts 构建配置

模块边界划分

• 有状态与生命周期依赖严格收敛在 composables/ 目录下，严禁在无状态工具中混入生命周期。
• 纯无状态静态函数严格收敛在 utils/ 目录下，无任何 Vue 响应式或生命周期依赖，支持直接内联调用。
• 外部业务项目零污染：基础包内坚决严禁混入任何特定业务项目（如短视频查权重、账号诊断、亲友算分等）的私有业务逻辑或字典配置。

3. 组件开发与 easycom 集成规范

3.1 easycom 全自动按需扫描

业务项目 pages.json 中统一配置 easycom，在页面模板中直接使用 hlw- 开头的 UI 组件，无需手动 import 注册：

{
  "easycom": {
    "autoscan": true,
    "custom": {
      "^hlw-(.*)": "@hlw-uni-mp/vue/src/components/hlw-$1/index.vue"
    }
  }
}

3.2 组件专有类型规范

• 组件若有专有的配置项或返回值接口，必须且只能定义在组件同级 types.d.ts 文件中。
• 所有组件类型统一在包根目录 src/index.ts 中显式重导出，方便业务项目按需引用。

3.3 公共包组件样式收敛规范

• 样式外置规则：当通用组件样式超过 50 行或层级复杂时，允许且推荐剥离为同级独立的 .scss 文件（如 hlw-modal/modal.scss、hlw-page/page.scss），保持 .vue 组件模板结构轻量清晰。
• 优先复用设计令牌：所有组件样式必须优先使用 src/style.css 中定义的 CSS 变量（如 --primary-color、--radius-md、--radius-lg、--bg-page 等），严禁随意书写未经令牌化的死值。

4. KISS 极致简约与代码质量铁律

4.1 坚决杜绝兜底的三元运算符与链式防御性判断

• 严禁编写多层嵌套三元与空值合并链：坚决禁止编写类似 (opts?.modalOptions?.content) ?? (opts?.msg) ?? ... 等繁杂兜底代码。
• 不存在即不存在：数据不存在即自然判定为假值（!msg），直接返回或拦截，坚决严禁层层套用假兜底。
• 严禁使用三元做函数存在性兜底：严禁编写 uni.getDeviceInfo ? uni.getDeviceInfo() : {} 或 opts.getToken ? opts.getToken() : ''，必须统一使用原生可选链调用 uni.getDeviceInfo?.() || {} 与 opts.getToken?.() || ''。
• 模板 Class 绑定严禁使用空字符串三元：模板中严禁出现 :class="[border ? '' : 'no-border']" 或 item.tagPulse ? 'pulse' : ''，必须统一采用标准 Vue 对象语法 :class="{ 'no-border': !border }" 与 :class="{ pulse: item.tagPulse }"。

4.2 接口字段唯一性铁律：只认 msg，坚决消灭 message

• 全栈统一提示字段：全栈接口与交互提示文案统一且唯一为 msg。
• 坚决严禁兼容 message：网络请求层、交互反馈层与各工具函数中，坚决严禁编写 body?.msg ?? body?.message 等任何形式的 message 兼容或兜底逻辑。
• 空即不显：若 msg 为 null、undefined 或空字符串 ""，坚决不弹出任何 Toast 或模态弹窗，直接静默结束。

4.3 全栈坚决杜绝静态假数据兜底 (Empty is Empty SSOT)

• 真实接口单一事实源：全栈所有数据必须且只能以真实网络接口与参数为唯一事实源。
• 严禁内置静态假数据：通用组件和工具函数中坚决严禁内置假列表、备用数组或默认假文案。
• 空即为空：数据为空直接保持为空（[] 或 ''），由页面自然呈现空状态，严禁弄虚作假注入兜底假数据。
• 时间戳格式化零假数据：时间戳为空或 <= 0 时，格式化方法必须且只能直接返回空字符串（''），严禁私自硬编码输出“刚刚”、“最近”等静态假数据。

4.4 原生布尔逻辑型铁律 (Native Booleans - Zero 0/1)

• 严禁整数代布尔：全栈所有状态标识、控制开关（如 modal、closable、showFooter、showCancel、showConfirm、closeOnMask、fixed、refresherEnabled 等），后端与接口必须且只能返回原生布尔值（true / false），前端 TypeScript 纯类型声明强制为 boolean，坚决严禁使用整数 0 | 1。

4.5 TypeScript 纯类型声明文件命名规范 (*.d.ts Standard)

• 纯类型声明文件后缀必须加 .d.ts：所有仅包含 TypeScript 类型声明、接口定义（interface、type）而无实际运行时 JS 执行逻辑的独立类型文件，文件名必须且只能以 .d.ts 结尾（例如 types.d.ts），坚决严禁命名为 types.ts 等普通代码后缀。
• 严谨隔离：保持类型系统与业务运行时逻辑的严谨分离，提升 IDE 类型索引效率与编译轻量化。

4.6 坚决严禁别名导出与冗余二传手文件 (Zero Aliases & Passthroughs)

• 严禁别名重导出：重构或调整 Composable、函数、方法、类型或接口命名后，坚决严禁编写别名重导出兼容旧写法，必须一步到位全局更新为最新标准名称。
• 严禁过渡二传手文件：模块迁移新目录后，坚决严禁在原路径留下仅有一行重导出的过渡文件，旧文件彻底删除，杜绝路径碎片化。
• 严禁单行微型包装函数：在 Vue 模板中直接进行基础值比较与状态判断，严禁在 script setup 中额外编写单行包装辅助函数。

4.7 表单占位符与文案排版规范

• 统一使用“例如：”，严禁写“如：”：全栈所有举例提示一律统一使用“例如：”，坚决禁止使用“如：”或“如 ”。
• 帮助说明与示例末尾严禁加句号：表单下方的辅助提示说明以及“例如：xxx”示例末尾坚决严禁添加句号（。），保持视觉极致干净利落。

5. 消息交互与弹窗调度规范 (hlw.$msg)

5.1 hlw.$msg.toast 核心交互标准

• 内容唯一来源：Toast 与 Modal 的提示内容严格取 msg。若 !msg，直接返回 Promise.resolve(true)，不触发任何界面提示。
• 模态弹窗模式：当 modal === true 时，使用 hlw.$msg.modal 弹出，透传 modalOptions 定制参数，内容强制对齐 content: msg。用户点击确定时回调返回 true，点击取消时回调返回 false。
• 轻提示模式：当 modal 为 false 或缺省时，使用 uni.showToast 显示轻提示。
• 消除默认值硬编码重复：modal() 内部已有默认选项解构，toast 在调度 modal 时直接透传 { ...opts.modalOptions, content: msg }，严禁在外部重复硬编码默认按钮与标题。
• 双重调用支持：同时支持回调风格 toast(res, (confirm) => { ... }) 与异步 Promise 风格 const confirm = await toast(res)。

6. 网络请求与存储上传规范 (request/)

6.1 接口响应契约 (ApiRes)

• 响应顶层规范：响应数据必须严格满足强类型结构，包含 code: number、msg: string、data: T & ApiResData。
• 弹窗多态扩展：支持后端通过顶层 modal: boolean 与 modalOptions: UniApp.ShowModalOptions 动态控制客户端弹窗行为。
• 鉴权拦截机制：HTTP 状态码或业务 Code 为 401 / 403 时，自动限流调用 handleUnauthorized，调起统一失效反馈并触发 onUnauthorized 业务回调。

6.2 客户端加密验签请求头契约 (Crypto & Sign)

网络请求拦截器必须自动生成并挂载标准化防篡改头：

• X-Client-Timestamp：客户端 13 位毫秒级时间戳。
• X-Client-Nonce：10 位随机防重放字符串。
• X-Client-Context：设备环境与 Token 经 RSA 公钥非对称加密后的密文字符串。
• X-Client-Sign：基于密钥、时间戳、Nonce、Context 及参数递归排序串计算得出的 SHA-256 签名，严格与后端验签助手 1:1 对齐。

6.3 存储上传统一抽象 (upload/)

• 存储驱动多态：底层抽象统一兼容 local（本地服务端分片直传）、alioss（阿里云 OSS 表单直传）与 qiniu（七牛云直传）。
• 统一门面方法：业务统一调用 uploadFile({ biz, filePath })，自动串联凭证申请、表单拼装与直传，返回最终公网访问 URL。

7. 终端命令与工程构建守则

• 严禁擅自执行终端 CMD / 脚本命令：严禁在未获用户明确指示的情况下擅自执行 pnpm dev、pnpm build、npm publish 等长耗时、常驻守护或编译类终端命令。开发服务器的启动、监听与打包全部交由用户在本地终端自行把控。
• 产物双向对齐守则：修改 src/ 核心逻辑后，必须同步校验并维护 dist/ 关键产物（dist/index.mjs 与 dist/index.js），确保业务项目通过本地软链接引用时即刻生效，行为 100% 一致。