# 证据和门禁

KCode Harness 的门禁用于避免跳阶段、猜 SDK、伪造验证结果或在错误产品技术栈上写代码。

## 查看门禁

```text
/kd check
/kd status
```

门禁不通过时，按原因补齐产品、文档、问题答案、计划、证据或风险说明。

## 产品确认

当需求涉及具体金蝶产品实现、构建、元数据或 SDK 查证时，必须确认产品画像：

```text
/kd product cangqiong --version V6.0
```

仅整理需求文档或处理产品无关工程事项时，完成需求梳理，并在计划中写明不涉及产品实现。后续实际修改金蝶产品代码、构建、元数据或 SDK 时，按范围确认产品。

详见 [产品画像确认](PRODUCT_PROFILE.md)。

## 计划门禁

进入 `execute` 前，`PLAN.md` 必须包含：

- 已检查的项目结构。
- 目标源码根 / 路径。
- 允许修改的文件。
- 必需的金蝶查证项。
- `## 执行步骤`，并用 `- [ ] STEP-001：...` 格式拆分步骤。
- `## TDD / 红绿检查`。
- `## 验证命令`。
- 回滚 / 影响控制。

`execute` 阶段只能写 `PLAN.md` 明确列出的源码文件。

业务事实门禁：

- 通用实现契约必须覆盖触发入口、源对象、目标对象、数据变化或字段映射、业务规则、失败处理和验收样例。
- 数据源上下文必须覆盖目标 FormId/单据或表单标识、插件类型和触发事件、字段/实体/分录标识、数据读取写入方式；SQL/KSQL 场景还必须覆盖表名和数据库字段名。
- 第三方对接必须覆盖接口文档、对接方向、触发时机、接口地址、认证配置、字段映射、并发/幂等、超时重试限流、错误补偿、日志脱敏和请求/响应样例。
- API 文档、SDK 知识库和 PLAN 自由文本不能替代结构化 facts 或 evidence。

## SDK 签名证据

涉及 Java/C# 产品代码时，进入 `execute` 前必须已有：

```text
evidence/sdk-signature.md
```

使用工具：

```text
kd_sdk_signature product=cangqiong query=QueryServiceHelper method=loadSingle
kd_sdk_signature product=flagship query=SaveServiceHelper method=save
kd_sdk_signature product=enterprise query=DynamicObject method=GetDynamicObject
```

只有以下来源允许作为签名事实：

- `kd_sdk_signature` 从当前项目真实 jar/dll 读取的结果。
- 当前项目构建输出。
- 项目源码封装。
- 官方元数据。

`kd_search`、`kd_cosmic_api` 和随包知识只能作为线索。

## TDD 红绿证据

写生产源码前必须有红灯证据：

```text
evidence/tdd-red.md
```

进入 `verify` 前必须有绿灯证据：

```text
evidence/tdd-green.md
```

绿灯证据必须包含真实成功输出和：

```text
Exit: 0
```

或：

```text
退出码：0
```

以下内容不能作为绿灯证据：

- “需在开发环境验证”
- “待验证”
- “未执行”
- “应该可以”

命令无法运行时，记录真实阻塞原因和残余风险。禁止把未运行命令当作绿灯。

## evidence/index.json

所有 evidence 文件必须登记在：

```text
evidence/index.json
```

KCode 内置工具和统一 evidence 写入路径会自动维护索引。

常见 evidence：

```text
evidence/sdk-signature.md
evidence/cosmic-config.txt
evidence/cosmic-metadata.json
evidence/cosmic-api.txt
evidence/ksql-lint.txt
evidence/tdd-red.md
evidence/tdd-green.md
evidence/step-001.md
```

## Cosmic 官方能力证据

苍穹、星瀚和星空旗舰版通常要求：

```text
kd_cosmic_config product=cangqiong
kd_cosmic_metadata product=cangqiong form=<formId或单据名>
kd_cosmic_api product=cangqiong mode=search query=<关键词>
```

这些工具成功执行后会自动写入 run 目录下的 evidence 文件。

## KSQL / SQL 证据

交付 KSQL/SQL 数据修复内容时，必须使用 normal 模式，ship 前通常要求：

```text
evidence/cosmic-metadata.json
evidence/ksql-lint.txt
```

运行：

```text
kd_ksql_lint product=cangqiong path=<sql文件路径>
```

## 风险确认

进入 `ship` 前必须确认风险等级和原因：

```text
/kd risk low 已完成本地构建和元数据检查，无残余交付风险
```

等级：

```text
low
medium
high
```

风险原因应来自 `VERIFY.md` 和 `SHIP.md` 的真实验证结果。