---
name: kd-cosmic-review
description: 金蝶AI苍穹/Cosmic 平台 Java 插件和 KSQL 代码审查技能。6 维度审查方法论（正确性/安全/健壮/性能/可维护/规范）+ Cosmic 专用 P0/P1/P2 检查清单 + AI 错误清单。适用于金蝶AI苍穹、金蝶AI星瀚、金蝶AI套件项目。
---

# 金蝶 Cosmic 审查

本技能用于审查苍穹/Cosmic 平台 Java 或 KSQL 变更。融合通用 6 维度代码审查方法论与 Cosmic 平台特化检查清单。

不要把本技能用于 Enterprise C# 代码；Enterprise 使用通用金蝶检查流程。

## 适用产品线

- 适用：基于 Cosmic/BOS Java 插件模型的金蝶AI苍穹、金蝶AI星瀚、金蝶AI套件代码审查。
- 不适用：企业版 C# / IronPython 插件审查。

## 审查输入

优先审查用户明确指定的文件。若用户要求整体审查，在可用时检查 active run 和变更的 Java/SQL 文件。

审查前：

- 用 KCode `search` 查询 Cosmic 审查清单、生命周期、平台约束、KSQL 和单测指导。
- SDK 签名或生命周期方法不确定时，优先用 `web_search` + KCode `bash`（`jar tf`/`unzip`）从当前项目实际 SDK jar 验证；查不到时再用 KCode `read` 获取知识库线索，并要求编译或人工证据兜底。
- 变更中用到字段、操作、枚举值、表名、数据库列时，用**只读连库**查 FKERNELXML/fdata 并解析（`skills/_shared/metadata-db-query.md`）或 KCode `search` 验证。

- 先运行 KCode `review`（喂 `kd-cosmic-review-rules` + `kd-coding-standards`）做基础静态检查，再按下方清单深入审查。

## 审查流程

每次代码审查按以下顺序执行，不可跳过任何环节：

1. **正确性审查** → 2. **安全性审查** → 3. **健壮性审查** → 4. **性能审查** → 5. **可维护性审查** → 6. **规范一致性审查**

## 一、正确性审查

### 逻辑正确性

- 业务逻辑是否与需求一致
- 条件判断是否覆盖所有分支
- 循环边界是否正确（off-by-one）
- 事件生命周期阶段是否正确（监听注册应在 `afterCreateControl`/`bindData`，不在 `initialize`；UI 操作应在控件创建后，不在 `beforeBindData` 前；数据修改应在 `afterBindData` 或操作事务钩子内，不在 `initialize`/`beforeBindData`）

### 数据正确性

- 字段 key 是否经元数据验证（formId/entityId/字段 key 真实存在）
- 枚举/下拉值是否查 Ext 列确认（避免凭空猜测状态值）
- DynamicObject 取值是否有空值保护（嵌套访问、分录访问）
- 操作类型是否正确（save/submit/audit/custom）

### 事务正确性

- 操作事务钩子内是否独立 `save`（应改数据包，不独立 save）
- 事务内是否跨库写
- 显式事务块 catch 异常是否 `markRollback`
- 一个事务内是否跨库写

## 二、安全性审查

### 注入攻击

- SQL/KSQL 是否参数化，避免直接拼接过滤条件以防 SQL 注入风险
- 是否存在命令注入风险
- 是否存在路径遍历风险

### 数据安全

- 硬编码组织、用户、部门、账套、URL、密钥、账号密码（P0）
- 日志中是否泄露敏感信息
- API 响应是否暴露内部信息

### 权限

- 敏感接口是否有权限校验
- 是否存在越权访问风险
- 组织上下文是否正确隔离

## 三、健壮性审查

### 异常处理

- 是否捕获了所有可能的异常
- 异常处理是否合理（避免编写空 catch 块，推荐记录日志或抛出有上下文的异常）
- 异常信息是否包含足够上下文
- `DataSet` 是否在 try-with-resources 或等价方式中关闭

### 边界条件

- 空集合/空分录是否处理
- DynamicObject 是否判空
- 集合元素即使 `isNotEmpty`，取出的数据元素也可能为 null

### 容错机制

- HTTP 或第三方调用是否有超时设置
- 是否有重试机制（含退避策略）
- 是否有降级方案

## 四、性能审查

### 数据库

- 是否存在 N+1 查询（循环内 DB 调用）
- 查询是否使用索引
- 批量操作是否使用批量语法
- 大查询是否分页
- 事务范围是否最小化

### UI 性能

- 循环内是否有 `updateView`（应循环结束后统一刷新）
- 循环内是否有 `getFieldIndex`、元数据查询、高成本序列化
- 大分录更新是否使用低效 UI model API（应用批量或属性级 API）

### 内存

- `DataSet` 是否及时关闭
- 无界集合是否累积
- 缓存 key 是否缺少账套隔离

## 五、可维护性审查

### 可读性

- 命名是否语义化，能否望文知义
- 函数长度是否超过 80 行
- 嵌套深度是否超过 3 层
- 是否有魔法值（应抽常量或枚举）

### 可扩展性

- 是否符合开闭原则
- 硬编码是否可配置化
- 是否便于添加新功能

## 六、规范一致性审查

### 命名规范

- 是否符合 Java 命名规范（PascalCase 类名、camelCase 方法名）
- 插件类名是否与插件类型一致
- Service/DAO 层方法命名是否规范（get/list/count/save/remove/update 前缀）

### 格式规范

- 缩进是否统一
- 代码风格是否与项目一致

### 注释规范

- public 方法是否有 Javadoc
- 复杂逻辑是否有注释
- 注释是否与代码一致

## 严重级别

- **P0**：阻断问题——崩溃、数据损坏、事务失效、安全暴露、严重资源泄漏、核心功能不可用。推荐优先修复。
- **P1**：高风险——影响生产性能、稳定性、扩展性、可维护性。优先修复。
- **P2**：规范和可维护性——应在计划窗口修复。

## P0 重点

- 监听注册或 UI 操作放在错误生命周期阶段（监听注册应在 `afterCreateControl`/`bindData`，不在 `initialize`；UI 操作应在控件创建后；数据修改应在 `afterBindData` 或操作事务钩子内，不在 `initialize`/`beforeBindData`）
- 在事务钩子中独立 `save` 或 `update`，而不是修改平台传入的数据实体
- `DataSet` 未使用 try-with-resources 或等价方式关闭
- 校验器或操作插件使用字段但未声明预加载属性
- 循环内数据库调用、服务保存或远程调用
- 硬编码组织、用户、部门、账套、URL、密钥、账号密码等环境相关值
- SQL 拼接、原生 `Statement`、用户输入未参数化、XML 外部实体风险
- 在事件参数类型不支持的阶段调用不存在的 API
- 嵌套 `DynamicObject` 访问缺少必要空值保护
- 原生 JDK 线程绕过平台线程管理

## P1 重点

- 循环内 `updateView`、`getFieldIndex`、元数据查询或高成本序列化
- 查询缺少过滤条件、大结果集、字段路径过深
- 大分录更新使用低效 UI model API，而不是批量或属性级 API
- 无界集合、缓存 key 缺少账套隔离
- HTTP 或第三方调用缺少超时
- 可批量处理的 SDK 调用被重复逐条调用

## P2 重点

- 应抽常量的魔法值
- 空 catch、丢失异常 cause、`printStackTrace`、日志缺少堆栈
- 类名或方法名与插件类型不一致
- 项目规范要求的 public 方法注释缺失

## 误报规避

- 固定业务元数据 ID，如 formId、appId、billTypeId、枚举编码，不按环境硬编码处理
- 不机械判定 `DynamicObject.getString`、`getLong`、`getBigDecimal` 的 null 检查，要结合字段可空性和平台行为
- 注释中的代码不作为活动代码审查
- 单元测试里的测试数据常量不按生产硬编码处理

## AI 生成代码常见问题清单

AI 生成金蝶代码时高频出现的问题，审查时重点检查。运行时排错对照 `rules/kd-debug-rules` 与产品线 skill 的硬约束。


1. **幻觉 API**：调用了不存在的 `kd.bos.*` 方法（如 `setReadOnly`、`model.getEntryCount`、`QueryServiceHelper.queryAll`、`afterCreateControl`、`model.addRow`、`model.deleteRow`、`this.getView().refresh`、`model.getEntry`、`model.getRowCount`）
2. **幻觉类名**：编造不存在的工具类（如 `BillHelper`、`FormHelper`、`ListHelper`、`PluginHelper`、`Cosmic*Helper`）
3. **生命周期错位**：在 `initialize` 注册监听或做 UI 操作、在 `beforeBindData`/`afterBindData` 改数据
4. **字段 key 臆造**：凭中文名猜英文 key，未查元数据验证
5. **枚举值臆造**：凭经验猜状态值（如 `A:已审核, B:暂存`），未查 Ext 列
6. **操作事务误用**：在事务钩子内独立 `SaveServiceHelper.save`
7. **DataSet 未关闭**：忘记 try-with-resources
8. **循环内 DB/服务调用**：N+1 查询、循环内 save/updateView
9. **Enterprise/Cosmic 混用**：把 Java `kd.bos.*` 套到 C# `Kingdee.BOS.*`
10. **硬编码环境值**：组织/用户/部门 ID 直接写死

## 审查强度等级

| 等级 | 适用场景 | 要求 |
|------|---------|------|
| 严格 | 生产代码、核心模块 | 全部 6 维度审查，P0 建议优先修复 |
| 标准 | 常规业务代码 | 全部 6 维度审查，P0 建议优先修复，P1 建议修复 |
| 宽松 | 原型验证、临时脚本 | 正确性 + 安全性审查，P0 建议优先修复 |

## 输出格式

先输出发现项，按严重级别排序。每个发现项包含：

- 级别：P0、P1 或 P2
- 文件和行号
- 具体问题
- 为什么在 Cosmic 中有风险
- 修复指令

随后说明：

- 已运行和未运行的检查
- 已验证的产品、元数据、SDK 签名和 API 线索
- 剩余风险或缺失上下文

如果没有发现问题，明确说明未发现问题，并列出剩余测试或证据缺口。

```
## 审查报告

### 通过项
- [项目]：说明

### 警告项 (P1/P2)
- [项目]：说明 → 建议修改

### 缺陷修复建议 (P0)
- [项目]：说明 → 修复方案

### 审查结论：通过 / 有条件通过 / 不通过
```