Angular/Cumulocity 代码质量分析

技能文档

---
name: cumulocity-iot-code-quality-analysis
title: Angular/Cumulocity 代码质量分析
category: 开发工具
description: 分析 Angular / Cumulocity Web SDK 代码中的反模式、缺陷与质量问题：覆盖 TypeScript 最佳实践、Angular 惯用法、C8Y SDK 使用模式与项目约定，按 22 条反模式清单逐文件检查并输出结构化报告（含问题片段与修复建议）。当用户需要代码评审、检查反模式、质量检查、重构建议、缺陷分析，或提到代码坏味道、风格规范时触发。触发词：代码评审、反模式、质量分析、代码坏味道。
---

# Angular/Cumulocity 代码质量分析

## 概述

对 Angular + Cumulocity Web SDK 代码库执行全面的代码质量分析。分析依据三方面规范：

1. **TypeScript 最佳实践** — 类型守卫、类型窄化、泛型约束、Zod 运行时校验等主题（可参考 TypeScript 官方手册或团队内的 TypeScript 规范资料）
2. **Angular 官方文档** — 控制流、生命周期、变更检测与对应版本的风格指南（angular.dev）
3. **Cumulocity 文档知识库** — 组件与 API 参考、设计系统的工具类与色彩令牌；若当前环境提供 Cumulocity 文档检索工具，按关键词查询相关主题

---

## 技能工作流

### 步骤1：收集参考资料

分析任何文件之前，先准备以下参考材料：

1. TypeScript 规范资料中与目标文件相关的主题（类型守卫与窄化、Zod 校验等）
2. Angular 官方文档中与目标文件特性相关的章节
3. Cumulocity 文档知识库的结构总览，以及与被审文件所用特性相关的查询主题（如「间距工具类」「色彩令牌」「组件懒加载」）
4. `@c8y/client` SDK 的服务清单，用于校验 C8Y SDK 用法

### 步骤2：确定要分析的文件

如果用户未指定文件，搜索以下类型：

- 全部 `*.component.ts`
- 全部 `*.service.ts`
- 全部 `*.module.ts`
- 全部 `*.component.html`

### 步骤3：逐文件分析

对目标文件逐条运行 [references/anti-patterns.md](references/anti-patterns.md) 中的检查项。每发现一个问题：

- 注明**文件路径与行号**
- 指出命中的**反模式编号与名称**
- 展示**问题代码片段**
- 给出**修正/推荐版本**

### 步骤4：输出结构化报告

按下方「输出格式」汇总每个文件的分析结果。

---

## 反模式速查表

完整定义、违规信号与修复示例见 [references/anti-patterns.md](references/anti-patterns.md)。

| 编号 | 反模式 | 严重度 |
|------|--------|--------|
| AP-01 | 用 `*ngIf` 而非 `@if`（Angular 控制流） | Low |
| AP-02 | 组件内承载过多业务逻辑 | Medium |
| AP-03 | 到处使用 `any` | Medium |
| AP-04 | 忽略 OnPush 变更检测 | Medium |
| AP-05 | 循环缺少 `trackBy` / `track` | Medium |
| AP-06 | 非独立组件（NgModule / `standalone: false`） | High |
| AP-07 | 简单值却滥用 RxJS | Low |
| AP-08 | 模板中的重逻辑 / 方法调用 | Medium |
| AP-09 | 订阅后未取消订阅 | High |
| AP-10 | 用 `FetchClient`/`HttpClient` 调 `@c8y/client` 已覆盖的接口 | Medium |
| AP-11 | Widget/插件模块未懒加载 | Medium |
| AP-12 | 重自定义样式 / 硬编码颜色 | Low |
| AP-13 | 重复代码 — 缺少工具服务或共享组件 | Medium |
| AP-14 | 模型接口定义在组件文件内 | Low |
| AP-15 | 所有服务都标 `providedIn: 'root'` | Low |
| AP-16 | 组件内执行长时异步任务 | High |
| AP-17 | 对 `IManagedObject` 附加属性的无类型/无守卫访问 | High |
| AP-18 | 缺少本地化（`| translate`） | Medium |
| AP-19 | 密钥、凭据与租户 URL 提交进版本库 | High（安全） |
| AP-20 | 使用已弃用的 `HOOK_*` 注入令牌而非钩子函数 | Medium |
| AP-21 | 模板未使用的公开方法与属性 | Low |
| AP-22 | 覆写 `@c8y/ngx-components` 私有 API | High（技术债） |

---

## 输出格式

对每个被分析文件，产出结构化报告：

```
## 分析：<文件路径>

### 摘要
<一段式总结>

### 发现

| # | 反模式 | 严重度 | 行号 |
|---|--------|--------|------|
| 1 | AP-06 非独立组件 | High | 12 |
| 2 | AP-09 缺少取消订阅 | Medium | 45–52 |

### 详情

#### 发现 1 — AP-06 非独立组件（第 12 行）
**代码：**
```ts
// problematic snippet
```
**建议：**
```ts
// fixed snippet
```
```

### 严重度分级

- **High** — 疑似缺陷、内存泄漏或安全问题
- **Medium** — 可维护性或性能问题
- **Low** — 风格 / 约定违规

---

## 情境化参考

分析涉及以下主题时：

- **TypeScript 类型 / 泛型** → 查阅 TypeScript 官方手册的 Narrowing 等章节（https://www.typescriptlang.org/docs/handbook/2/narrowing.html）
- **Angular 生命周期 / 控制流 / 变更检测** → 查阅 angular.dev 官方文档
- **Angular 风格指南与约定** → 按项目版本查阅对应风格指南：`https://vMAJOR.angular.dev/style-guide`（如 Angular 20 用 `https://v20.angular.dev/style-guide`，Angular 19 用 `https://v19.angular.dev/style-guide`，最新版用 `https://angular.dev/style-guide`）
- **CSS 工具类、设计令牌、组件 API** → 用相关关键词查询 Cumulocity 文档知识库
- **C8Y REST API 封装** → 查阅 `@c8y/client` 官方文档与服务清单

使用说明

# Angular/Cumulocity 代码质量分析

按 22 条反模式清单分析 Angular / Cumulocity Web SDK 代码中的反模式、缺陷与质量问题，覆盖 TypeScript 最佳实践、Angular 惯用法与 C8Y SDK 使用模式，输出含问题片段与修复建议的结构化报告。

## 使用

```text
评审 src/modules/sensor 下的组件和服务，
重点看变更检测、订阅泄漏和 C8Y SDK 用法。
```

技能按「收集参考资料 → 确定分析文件 → 逐文件跑反模式检查 → 输出结构化报告」四步执行，每条发现包含文件路径、行号、反模式编号、问题片段与修正版本。

## 工作原理

- **反模式清单**：22 条 AP 检查项（控制流、OnPush、订阅泄漏、懒加载、本地化、密钥入库、私有 API 覆写等），定义见 `references/anti-patterns.md`
- **严重度分级**：High（缺陷/泄漏/安全）、Medium（可维护性/性能）、Low（风格约定）
- **参考依据**：TypeScript 官方手册、angular.dev 文档与版本风格指南、Cumulocity 设计系统文档

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。