lucky_shop/stub-app-projects/mp-harmony/entry/README-HAR-DEPS.md

# 鸿蒙元服务 entry 模块依赖说明

> ⚠️ **本模块的 HAR 依赖必须保留**，否则运行时会缺失子包 chunk（DIY 首页、商品分类、订单、营销页全部失效）。

## 背景

`mp-harmony` 项目把 uniapp 编译产物拆成 6 个鸿蒙模块：

| 模块名 | srcPath | 类型 | 内含 |
|---|---|---|---|
| entry | `./entry` | 主 HAP | 入口页面、首页骨架、TabBar |
| components_diy | `./ascf/ascf_build/components_diy` | shared HAR | 50+ diy-* 组件的 pack.js |
| pages_goods | `./ascf/ascf_build/pages_goods` | shared HAR | 商品分类/详情/列表/购物车 |
| pages_order | `./ascf/ascf_build/pages_order` | shared HAR | 订单/支付/详情 |
| pages_promotion | `./ascf/ascf_build/pages_promotion` | shared HAR | 分销/积分/商户 |
| pages_tool | `./ascf/ascf_build/pages_tool` | shared HAR | 会员/支付/客服/工具页 |

`entry` 必须把这 5 个 HAR 加为依赖，否则运行时鸿蒙端加载 entry HAP 时找不到
`components-diy/diy-group.pack.js` 等子包 chunk，所有 diy 组件被
`componentPlaceholder: view` 替换成空 view，DIY 内容不显示，12s splash 兜底超时。

## 必须保留的依赖

`entry/oh-package.json5` 的 `dependencies` 必须包含：

```json5
{
  "components_diy":   "file:../ascf/ascf_build/components_diy",
  "pages_goods":      "file:../ascf/ascf_build/pages_goods",
  "pages_order":      "file:../ascf/ascf_build/pages_order",
  "pages_promotion":  "file:../ascf/ascf_build/pages_promotion",
  "pages_tool":       "file:../ascf/ascf_build/pages_tool",
}
```

## 防回归

```bash
# 检查 module.json + oh_modules + oh-package.json5 是否完整
node scripts/check-har-deps.js --rawfile

# 严格模式: 任何缺失即 exit 1 (CI 用)
node scripts/check-har-deps.js --rawfile --strict
```

校验脚本读取 `./har-deps-required.json5`（白名单单一事实来源）。

## 如果你需要新增/删除子包

1. 修改 `ascf_build/<新包>/oh-package.json5` 的 `name` 字段
2. 在 `mp-harmony/build-profile.json5` 的 `modules` 数组里增/减模块
3. 在 `entry/oh-package.json5` 的 `dependencies` 里增/减 file: 依赖
4. **同步更新 `entry/har-deps-required.json5` 的 `requiredHarDeps` / `ohModulesRoots`**
5. 在 DevEco Studio 中 Sync 项目 → 重新 Build → 运行 `node scripts/check-har-deps.js --rawfile --strict`
6. 通知 ascf 负责人对齐

## 常见误操作

- ❌ 在 DevEco 的 "Manage Dependencies" 对话框里只保留 `@atomicservice/ascfapi`
  → 5 个 file: 依赖会被清空，运行失败
- ❌ 删除 `entry/oh-package.json5` 的 file: 依赖后用 ohpm install 重装
  → ohpm 会重新同步 file: 依赖，**只要 file: 声明还在就是安全的**
- ❌ 把 `ascf_build/<pkg>` 目录改名/移走
  → file: 引用会变成 broken，运行失败

## 故障现象速查

| 现象 | 原因 | 修复 |
|---|---|---|
| 首页只显示 TabBar，无 DIY 内容 | components_diy 缺失 | 加 file: 依赖 + Sync + Build |
| 12s splash 后页面空白 | 任意一个 HAR 子包缺失 | 跑校验脚本看哪个缺失 |
| 商品分类页空白 | pages_goods 缺失 | 同上 |
| "Schema validate failed: must match pattern '^[a-zA-Z][0-9a-zA-Z_.]*$'... module.name" | vue.config.js 重新生成时把 pages_tool 的 module.json5.module.name 清空了 | vue.config.js 已自动修复（`_copyMpHarmonyBuild` 末尾调用 `fixSubpackageModuleNames`）。如需手动跑：`node -e "require('./vue.config.js').fixSubpackageModuleNames()"` |
| "00604007 Field IS Empty Error: The name of package .../pages_tool cannot be empty" (DevEco 打开项目时 ohpm install 报) | `pages_tool/oh-package.json5` 的 top-level `name` 是空字符串 | `node scripts/fix-subpackage-module-names.js`，会同时修 oh-package.json5 和 module.json5 |
| "应用未关联服务空间" 报错 | uniCloud 服务未关联（与本依赖无关） | uniCloud 目录右键关联服务空间 |

## 子包 module.name 容易丢失的原因

`vue.config.js` 重新生成鸿蒙元服务产物时，会重新输出 `ascf_build/<pkg>/src/main/module.json5`。
其中 `module.name` 字段如果模板里没正确读取 `pkgName`（或没设置），会被写成空串。

**已自动化修复**：

`vue.config.js` 暴露了 `fixSubpackageModuleNames()` 函数，会在以下场景自动触发：

1. **顶层副作用**：vue.config.js 被任何入口 require 时（**包括 HBuilderX 触发 vue-cli-service build**），
   立即遍历 5 个子包，强制把 `module.name` 修正为包目录名。
2. **构建流程**：mp-harmony 生产构建的 `_copyMpHarmonyBuild()` 末尾也会再调一次。

**也就是说：只要 HBuilderX / 命令行 触发了 vue.config.js（构建必然触发），module.name 就被保证正确，无需任何手动操作。**

手动调用方式：

```bash
# 直接跑独立脚本 (推荐)
node scripts/fix-subpackage-module-names.js
```

或者 require 模块（vue.config.js 内部用的就是这个）：

```bash
node -e "require('./scripts/fix-subpackage-module-names').fixSubpackageModuleNames()"
```

> ⚠️ **重要**：vue.config.js 不再 export `fixSubpackageModuleNames`。历史教训：之前把 `fixSubpackageModuleNames` 放在 `module.exports` 上，vue-cli-service 校验 vue.config.js 导出的 keys 时会报：
>
> `Invalid options in vue.config.js: "fixSubpackageModuleNames" is not allowed`
>
> 现在函数在独立模块里，vue.config.js 通过顶层 IIFE 调用它，导出干净。

输出示例：

```
🔧 [vue.config] 修正 ascf_build 子包 module.json5.module.name...
   ✅ components_diy: module.name "(空)" → "components_diy"
   ✅ pages_goods: module.name "(空)" → "pages_goods"
   ✅ pages_order: module.name "(空)" → "pages_order"
   ✅ pages_promotion: module.name "(空)" → "pages_promotion"
   ✅ pages_tool: module.name "(空)" → "pages_tool"
   📊 修正完成: 5 个子包被更新
```

校验脚本 `check-har-deps.js` 仍作为兜底防线，确保 module.name 不会再次被覆盖为空。

**完整工作流（HBuilderX "发行" → "鸿蒙元服务"）**：

1. HBuilderX 调 uniapp 编译器生成 `unpackage/dist/build/.mp-harmony/`
2. HBuilderX 调 vue-cli-service build → `require('./vue.config.js')`
3. **顶层 IIFE 触发 → 自动修复 5 个子包 module.json5.module.name**
4. webpack 编译 → `VersionInjectPlugin._copyMpHarmonyBuild()` 拷产物到 ascf_src
5. **再次触发 `fixSubpackageModuleNames()`（防御性）**
6. DevEco Studio 用 ascf_src 构建鸿蒙 HAP（此时 module.name 已正确）

**手动修复**（如需保留原 module.json5 内容但 name 字段错了）：

```json5
{
  "module": {
    "name": "<包目录名, 比如 pages_tool>",
    ...
  }
}
```

`name` 必须匹配 `[a-zA-Z][0-9a-zA-Z_.]*`（鸿蒙 schema 要求）。