一、实验目标

完成实验后，能够：

1. 说明 DevEco Studio、HarmonyOS SDK、Node.js、OHPM 和模拟器的职责；
2. 按照 Empty Ability 流程创建并运行最小工程；
3. 使用 TypeScript 建立元服务配置和设备快照模型；
4. 将设备快照映射为卡片显示状态；
5. 模拟刷新事件并保持不可变更新；
6. 对配置和外部数据进行校验；
7. 用自动化测试验证卡片逻辑；
8. 形成权限最小化、数据可信、原创开发和问题可追踪的工程习惯。
   说明：实验代码使用标准 TypeScript/Node.js，因此即使实验机暂时没有 DevEco Studio、模拟器或 HarmonyOS 设备，也可以先完成可执行的业务层训练。具备条件时，再把相同模型和函数迁移到 ArkTS/ArkUI 工程。

二、实验情境

智慧农业平台需要提供一个“大棚环境卡片”，在桌面或服务入口展示：
• 大棚名称和设备编号；
• 在线、离线或维护中状态；
• 温度、湿度；
• 最近更新时间；
• 刷新数据、打开应用等动作。
本实验不连接真实设备，而是使用一条模拟设备快照完成“配置检查 → 状态生成 → 卡片渲染 → 刷新更新 → 测试验收”的最小闭环。

三、环境与代码结构

1. 环境

• Node.js 18 或更高版本
• npm
• 任意编辑器
• 可选：DevEco Studio、HarmonyOS SDK 和模拟器

2. 目录结构

meta-service-basic-development-1-code/
├── package.json
├── tsconfig.json
├── README.md
├── src/
│   ├── meta-service.ts       # 配置、模型、卡片状态和事件逻辑
│   └── index.ts              # 演示入口
└── test/
    └── meta-service.test.cjs # 自动化测试

四、实验流程（建议 120 分钟）

五、操作步骤

步骤 1：运行实验代码

解压代码包，进入项目目录：

npm install
npm run build
npm start

预期输出包含：

=== 元服务工程配置检查 ===
应用：智慧农业设备
卡片：大棚环境卡片
配置校验：通过

=== 首个元服务卡片预览 ===
...

然后执行：

npm test

预期：5 个测试全部通过。

步骤 2：检查 Empty Ability 工程

在 DevEco Studio 中：

1. Create Project；
2. 选择课程适用的应用/元服务模板；
3. 选择 Empty Ability；
4. 设置小写点分包名；
5. 等待依赖同步；
6. 运行默认页面；
7. 记录 API 版本、SDK 路径和构建结果。
   如果当前环境无法安装 DevEco，报告中应说明原因，并用标准 TypeScript 代码完成相同的配置和数据逻辑，不要伪造真机运行结果。

步骤 3：配置校验

阅读 src/meta-service.ts 中的：

export interface MetaServiceConfig {
  readonly bundleName: string;
  readonly displayName: string;
  readonly cardName: string;
  readonly permissions: readonly string[];
}

将 demoConfig.bundleName 临时改成 BadName，运行：

npm run build
npm start

观察程序如何阻止错误配置继续运行。再把权限改为 “camera”，说明为什么权限命名空间必须明确。
思考：
• 为什么包名不应包含空格或大写？
• 为什么权限应该最小化？
• 配置错误放在构建前发现有什么好处？

步骤 4：生成卡片状态

阅读：

const card = createCardState(demoDevice);
console.log(renderCard(card));

填写字段映射表：

步骤 5：实现刷新动作

运行：

const next = reduceCardAction(
  demoDevice,
  "refresh",
  "2026-09-13T09:35:00+08:00"
);

验证：

console.log(next !== demoDevice); // true
console.log(next.updatedAt);       // 新时间
console.log(demoDevice.updatedAt); // 原时间

不要直接改写 demoDevice.updatedAt。不可变更新便于 UI 状态刷新、回滚和测试。

步骤 6：处理 unknown

模拟外部接口返回：

const value: unknown = JSON.parse(
  '{"id":"greenhouse-01","name":"一号大棚","status":"online","temperature":25,"humidity":70,"updatedAt":"2026-09-13T09:30:00+08:00"}'
);
const device = parseDeviceSnapshot(value);

再传入以下非法数据：

{ "id": 1, "name": "错误设备" }

比较 parseDeviceSnapshot 和直接 value as DeviceSnapshot 的差异，并在报告中解释：类型断言不会检查运行时数据，类型保护才会。

步骤 7：扩展实验

至少完成一项：

1. 增加 battery 电量字段，要求范围 0–100；
2. 增加“离线超过 10 分钟”的提醒文本；
3. 增加 CardAction = “refresh” | “open” | “retry”；
4. 增加 CardView 的 loading/ready/error 可辨识联合；
5. 为时间格式化函数增加无效日期测试。

六、必做与选做任务

必做
• [ ] npm run build 编译通过；
• [ ] npm start 输出卡片预览；
• [ ] npm test 的 5 个测试全部通过；
• [ ] 完成一次配置错误实验；
• [ ] 完成一次非法 unknown 数据实验；
• [ ] 提交卡片字段映射表。
选做
• [ ] 在 DevEco Studio 中运行 Empty Ability；
• [ ] 将 DeviceSnapshot 迁移到 ArkTS；
• [ ] 添加 loading/error 状态；
• [ ] 添加一条自动化测试；
• [ ] 绘制元服务数据流图。

七、实验报告要求（建议 2–3 页）

报告文件名建议：学号-姓名-元服务基础功能一实验报告.md。
至少包含：

1. 环境信息：Node.js、npm、DevEco Studio/SDK（如有）；
2. 工程创建过程：模板、包名、API 版本、运行结果；
3. 卡片数据模型和字段映射；
4. 配置校验、unknown 类型保护和不可变更新说明；
5. 测试结果及新增测试；
6. 一个环境/编译/逻辑错误的定位与修复记录；
7. 工程伦理小结：权限最小化、旧数据提示、原创代码和责任担当。