@ohos-cpf/3rdloop 0.0.1

package/vendor/Server/Skills/rn-library-documentation-quality-check/assets/REPORT_TEMPLATE.md

@@ -0,0 +1,311 @@
+# 文档质量检视报告模板
+
+本文件定义 `rn-library-documentation-quality-check` 技能生成的检视报告的标准格式。
+
+> ⚠️ 报告必须包含 `**综合评分：XX/100**` 格式，且评分值位于"二、综合评分"章节，确保可被 `_parseRNLibraryScore` 函数正确解析。
+
+---
+
+## 一、报告结构
+
+报告文件名：`文档质量检视报告.md`，保存到 `{outputDir}` 目录。
+
+报告包含六个章节：
+
+1. 检视概览
+2. 综合评分
+3. 各维度评分明细
+4. 检视维度详情
+5. 问题清单
+6. 改进建议
+
+---
+
+## 二、报告 Markdown 模板
+
+```markdown
+# {repoName} 文档质量检视报告
+
+## 一、检视概览
+
+| 字段 | 内容 |
+|------|------|
+| **仓库名称** | {repoName} |
+| **仓库地址** | {repoUrl} |
+| **检视类型** | RN 鸿蒙化文档质量检视 |
+| **检视时间** | {timestamp} |
+| **文档模式** | 内嵌文档 / 跳转文档 |
+| **外部文档链接** | {externalDocUrls，跳转模式填写；内嵌模式填"无"} |
+| **文档文件数** | {docFileCount} |
+| **源码文件数** | {sourceFileCount} |
+| **export API 数** | {apiCount} |
+| **有注释 API 数** | {documentedApiCount} |
+| **API 文档覆盖率** | {documentedApiCount}/{apiCount} ({coveragePct}%) |
+| **交叉验证不一致数** | {crossMismatchCount}（接口规格说明与文档描述不一致的 API 数量） |
+
+## 二、综合评分
+
+**综合评分：{score}/100**
+
+评分等级：{grade}
+
+## 三、各维度评分明细
+
+| 检视维度 | 权重 | 扣分 | 维度得分 | Critical数 | Major数 | Minor数 |
+|----------|------|------|----------|-----------|---------|---------|
+| API 文档完整性 | 20% | {api扣分} | {api得分} | {c1} | {m1} | {n1} |
+| 鸿蒙化适配说明 | 20% | {adapt扣分} | {adapt得分} | {c2} | {m2} | {n2} |
+| 代码仓基础信息 | 15% | {readme扣分} | {readme得分} | {c3} | {m3} | {n3} |
+| 代码示例质量 | 10% | {example扣分} | {example得分} | {c4} | {m4} | {n4} |
+| 变更记录与版本规范 | 10% | {changelog扣分} | {changelog得分} | {c5} | {m5} | {n5} |
+| 文档与代码交叉验证 | 15% | {cross扣分} | {cross得分} | {c6} | {m6} | {n6} |
+| 文档准确性与国际化 | 10% | {accuracy扣分} | {accuracy得分} | {c7} | {m7} | {n7} |
+
+## 四、检视维度详情
+
+### 文档模式说明
+
+> {若为跳转模式，说明：本文档为跳转文档模式，主要检视对象为外部 usage-docs 文档（{列出链接}），本地 README 极简为设计选择，不作为文档缺失扣分依据。}
+> {若为内嵌模式，说明：本文档为内嵌文档模式，README.md/README_zh.md 为主要检视对象。}
+
+### 4.1 API 文档完整性
+
+**检查项数**：{count}
+
+**发现问题**：
+
+#### Critical
+| # | 文件 | 行号 | 检查项编号 | 描述 | 修复建议 |
+|---|------|------|-----------|------|----------|
+| 1 | `{filePath}` | L{lineNum} | AD-001 | {description} | {fixSuggestion} |
+
+#### Major
+| # | 文件 | 行号 | 检查项编号 | 描述 | 修复建议 |
+|---|------|------|-----------|------|----------|
+| 1 | `{filePath}` | L{lineNum} | TG-001 | {description} | {fixSuggestion} |
+
+#### Minor
+| # | 文件 | 行号 | 检查项编号 | 描述 | 修复建议 |
+|---|------|------|-----------|------|----------|
+| 1 | `{filePath}` | L{lineNum} | TG-005 | {description} | {fixSuggestion} |
+
+### 4.2 鸿蒙化适配说明
+（同上格式，使用 HA-xxx 编号）
+
+### 4.3 代码仓基础信息
+（同上格式，使用 RM-xxx / CF-xxx 编号）
+
+### 4.4 代码示例质量
+（同上格式，使用 EX-xxx 编号）
+
+### 4.5 变更记录与版本规范
+（同上格式，使用 CL-xxx 编号）
+
+### 4.6 文档与接口规格交叉验证
+
+> 本章节为 Phase 2.5 强制交叉验证环节的检视结果。以 `接口规格说明.md`（由 `RNLibraryInterfaceAnalyzer` 生成）为权威基准，与用户文档进行双向比对。
+
+**接口规格比对**：{已比对 / 未比对（接口规格说明文档不存在，跳过交叉验证）}
+
+**接口规格中 API 数量**：{specApiCount}
+
+**文档中描述的 API 数量**：{docApiCount}
+
+**双向比对结果**：
+
+| 比对方向 | 一致 | 轻微偏差 | 不一致 |
+|----------|------|----------|--------|
+| 接口规格→文档 | {specToDocMatch} | {specToDocMinor} | {specToDocMismatch} |
+| 文档→接口规格 | {docToSpecMatch} | {docToSpecMinor} | {docToSpecMismatch} |
+| 签名比对 | {sigMatch} | {sigMinor} | {sigMismatch} |
+| 鸿蒙化差异比对 | {harmonyMatch} | — | {harmonyMismatch} |
+| 权限比对 | {permMatch} | — | {permMismatch} |
+| 版本与支持矩阵 | {verMatrixMatch} | — | {verMatrixMismatch} |
+
+**发现问题**：
+
+#### Critical
+| # | 文件 | 行号 | 检查项编号 | 描述 | 修复建议 |
+|---|------|------|-----------|------|----------|
+| 1 | `{filePath}` | L{lineNum} | XC-003 | {description} | {fixSuggestion} |
+
+#### Major
+| # | 文件 | 行号 | 检查项编号 | 描述 | 修复建议 |
+|---|------|------|-----------|------|----------|
+| 1 | `{filePath}` | L{lineNum} | XC-002 | {description} | {fixSuggestion} |
+
+#### Minor
+| # | 文件 | 行号 | 检查项编号 | 描述 | 修复建议 |
+|---|------|------|-----------|------|----------|
+| 1 | `{filePath}` | L{lineNum} | XC-007 | {description} | {fixSuggestion} |
+
+**接口规格与文档差异详情**：
+
+| # | API 名称 | 比对方向 | 差异类型 | 接口规格 | 文档描述 | 检查项编号 | 严重度 |
+|---|----------|----------|----------|----------|----------|-----------|--------|
+| 1 | `{apiName}` | 规格→文档 | API 未描述 | {specDef} | 无 | XC-002 | Major |
+| 2 | `{apiName}` | 文档→规格 | API 不存在 | 无 | {docDesc} | XC-003 | Critical |
+| 3 | `{apiName}` | 签名比对 | 返回类型不一致 | Promise\<T\> | T | XC-006 | Critical |
+| 4 | `{apiName}` | 鸿蒙化差异 | 缺失接口仍标记支持 | 第5.1节标记缺失 | Yes | XC-008 | Critical |
+
+### 4.7 文档准确性与国际化
+（同上格式，使用 AC-xxx 编号）
+
+## 五、问题清单
+
+| # | 文件 | 行号 | 严重度 | 检视维度 | 检查项编号 | 描述 | 修复建议 |
+|---|------|------|--------|----------|-----------|------|----------|
+| 1 | `{filePath}` | L{lineNum} | 🔴 Critical | API 文档完整性 | AD-001 | {description} | {fixSuggestion} |
+| 2 | `{filePath}` | L{lineNum} | 🟡 Major | 鸿蒙化适配说明 | HA-006 | {description} | {fixSuggestion} |
+| 3 | `package.json` | — | 🔵 Minor | 代码仓基础信息 | RM-007 | keywords 缺少鸿蒙相关关键词 | 补充 harmony / ohos 关键词 |
+
+> **文件路径说明**：跳转文档模式下，外部 usage-docs 文件路径标注为 `external-docs/{库名}_zh.md` 或 `external-docs/{库名}_en.md`。
+
+## 六、改进建议
+
+### 优先修复项（Critical）
+1. {suggestion1}
+2. {suggestion2}
+
+### 建议改进项（Major）
+1. {suggestion1}
+2. {suggestion2}
+
+### 优化建议项（Minor）
+1. {suggestion1}
+2. {suggestion2}
+
+### 文档改进路线图
+
+| 阶段 | 目标 | 预计影响 |
+|------|------|----------|
+| 第一阶段 | 修复交叉验证不一致项（接口规格与文档对齐） | 消除所有 Critical 交叉验证问题 |
+| 第二阶段 | 补充核心 API 文档注释 | 消除 API 文档完整性 Critical 问题 |
+| 第三阶段 | 补充鸿蒙化适配说明和安装指南 | 消除适配说明 Major 问题 |
+| 第四阶段 | 完善 README 结构和代码示例 | 提升至 80+ 分 |
+| 第五阶段 | 补充 CHANGELOG 和国际化文档 | 达到 90+ 分 |
+
+---
+
+**报告生成时间**：{timestamp}
+```
+
+---
+
+## 三、评分解析兼容性
+
+报告中的评分格式必须兼容 `_parseRNLibraryScore` 函数的正则匹配：
+
+```
+评分正则匹配优先级：
+1. **综合评分：XX/100**（最高优先级，本 SKILL 使用）
+2. 总体评分/评分：XX
+3. 得分：XX
+```
+
+**关键格式要求**：
+- 评分必须使用 `**综合评分：XX/100**` 格式（加粗 + 冒号 + 分数/100）
+- 评分必须位于"二、综合评分"章节
+- 分数为 0-100 的整数
+
+---
+
+## 四、各维度扣分计算示例
+
+### 示例 1：API 文档完整性
+
+```
+检查发现：
+- AD-001 (Critical): 2 个 export 接口无注释 → -8 × 2 = -16
+- TG-001 (Major): 3 个方法缺少 @param → -4 × 3 = -12
+- TG-005 (Minor): 5 个方法缺少 @since → -1 × 5 = -5
+
+维度扣分 = min(-20, -16 + (-12) + (-5)) = min(-20, -33) = -20
+维度得分 = 20 + (-20) = 0
+```
+
+### 示例 2：文档与接口规格交叉验证
+
+```
+检查发现：
+- XC-003 (Critical): 1 个文档描述的 API 在接口规格中不存在 → -8
+- XC-002 (Major): 3 个接口规格中定义的 API 在用户文档中无描述 → -4 × 3 = -12
+- XC-005 (Major): 2 个方法返回类型不一致 → -4 × 2 = -8
+- XC-008 (Critical): 1 个缺失接口仍标记为支持 → -8
+- XC-007 (Minor): 1 个参数可选性不一致 → -1
+
+维度扣分 = min(-15, -8 + (-12) + (-8) + (-8) + (-1)) = min(-15, -37) = -15
+维度得分 = 15 + (-15) = 0
+```
+
+### 示例 3：代码仓基础信息
+
+```
+检查发现：
+- RM-004 (Major): 基础章节不完整（缺少约束与限制章节） → -4
+- RM-007 (Minor): keywords 缺少鸿蒙相关关键词 → -1
+
+维度扣分 = min(-15, -4 + (-1)) = -5
+维度得分 = 15 + (-5) = 10
+```
+
+### 示例 4：综合评分计算
+
+```
+各维度扣分：
+- API 文档完整性: -20
+- 鸿蒙化适配说明: -20
+- 代码仓基础信息: -5
+- 代码示例质量: -8
+- 变更记录与版本规范: -4
+- 文档与代码交叉验证: -15
+- 文档准确性与国际化: -1
+
+归零检查：文档非完全空白，核心 API 有部分注释 → 不触发归零
+
+最终分 = max(0, 100 - 20 - 20 - 5 - 8 - 4 - 15 - 1) = max(0, 27) = 27
+评分等级：极差
+```
+
+### 示例 4：跳转文档模式评分
+
+```
+仓库：rntpc_react-native-network-info
+文档模式：跳转文档
+
+检视发现：
+- API 文档完整性:
+  - DT-001 (Major): TurboModule Spec 接口缺少注释 → -4
+  - Minor: 2 个方法缺少 @since → -1 × 2 = -2
+  - 维度扣分 = min(-25, -4 + (-2)) = -6
+
+- 鸿蒙化适配说明:
+  - HA-019 (Major): 外部文档约束与限制不完整 → -4
+  - HA-023 (Minor): 遗留问题章节为空 → -1
+  - 维度扣分 = min(-25, -4 + (-1)) = -5
+
+- 代码仓基础信息:
+  - RM-003 (Minor): 缺少 README_zh.md（中文文档） → -1
+  - 注意：README 极简是跳转模式设计，不记录 RM-002/RM-004
+  - 维度扣分 = min(-15, -1) = -1
+
+- 代码示例质量:
+  - 外部文档有完整示例，但示例未展示错误处理 → EX-007 Minor → -1
+  - 维度扣分 = min(-15, -1) = -1
+
+- 变更记录与版本规范:
+  - CL-001 (Major): 缺少 CHANGELOG.md → -4
+  - 维度扣分 = min(-10, -4) = -4
+
+- 文档准确性与国际化:
+  - XC-012 (Major): 外部文档版本号与 package.json 不一致 → -4
+  - 维度扣分 = min(-5, -4) = -4
+
+最终分 = max(0, 100 - 6 - 5 - 1 - 1 - 4 - 4) = max(0, 79) = 79
+评分等级：一般
+
+注意与内嵌模式的差异：
+- 跳转模式下 README 维度扣分较少（极简是设计选择不是缺陷）
+- 但外部文档的完整性、与本地代码的一致性成为重点检视对象
+- CHANGELOG 缺失等本地文件问题仍需独立计算
+```