# 硬约束与交付红线

> 本文件为**流程与原则守卫**（guidance-only），不直接对应 lint 脚本。
> 可自动检测的规则见：[anti-patterns.md](anti-patterns.md)（SCENE）、[coding-preferences.md](coding-preferences.md)（STYLE/RESOURCE/VERIFY）。

本文件只承载 `ok-cosmic` 的 **A 层规则**：会直接影响事实准确性、插件上下文、事件阶段和交付正确性的硬约束。

- 命中本文件中的问题，默认按 **阻断交付** 处理。
- 不属于本文件的"推荐写法"与"目标态治理"，请分别查看：
  - [coding-preferences.md](coding-preferences.md)
  - [post-check.md](post-check.md)

## A1. 事实校验与模板约束

- **[A1.1] 拒绝幻觉**：严禁凭记忆或猜测生成任何 API 签名、事件方法名或单据字段标识。
- **[A1.2] 模板先行约束**：为确保代码符合项目对生命周期方法和事件签名的约定，AI 在生成任何苍穹插件代码前，建议先读取对应的 `assets/*.java` 模板文件，并严格遵守模板中的方法签名。
- **[A1.3] 签名校验指引**：在编写任何 `@Override` 方法或调用 BOS SDK 关键方法前，建议通过 `bash`(`jar tf`) + `web_search`、项目 SDK 或编译结果验证该方法确实存在且签名准确（已在 `rules/cheat-sheet.md` 中列出的 API 可直接使用，无需额外验证）。
- **[A1.4] 入口对齐规范**：为避免调用错误的页面上下文 API 导致执行异常，界面控制与数据操作建议区分入口：
   - **UI 控制 (只读/隐藏/弹窗)**：推荐使用 `IFormView`（由 `this.getView()` 获取）。
   - **数据操作 (取值/赋值/结构)**：推荐使用 `IDataModel`（由 `this.getModel()` 获取）。
- **[A1.5] 验证路径**：在使用原生 SDK 前，建议优先查找本地 `.md` 文档确认，其次通过脚本或编译结果进行验证。
- **[A1.6] 继承溯源**：利用脚本返回的继承树确认方法是否在基类中。
- **[A1.7] 代码风格基线**：为保持项目的统一风格 and 结构，推荐新生成的代码结构以对应模板为主，避免脱离生命周期方法的基础骨架。
- **[A1.8] 枚举/下拉选项值校验**：使用 ComboField、下拉列表等字段的具体选项值前（无论用于条件判断、状态赋值还是 QFilter 构造等场景），为防范字面值映射错误，建议先**只读连库**查 FKERNELXML/fdata（读取 Ext 列的真实枚举映射，形如 `A:已审核, B:暂存`）核对后写入代码。步骤见 `skills/_shared/metadata-db-query.md`。
- **[A1.9] 字段真实性验证**：只要要生成或修改涉及字段的代码，且已知目标单据/表单，为防范拼写或版本差异导致找不到字段，推荐先**只读连库**查元数据（FKERNELXML/fdata）验证字段是否存在、字段类型、所属实体和特殊取值规则，确认后再写入代码。见 `skills/_shared/metadata-db-query.md`。


## A2. 平台开发红线

> 以下条目的平台背景详见 [platform-baseline.md](platform-baseline.md)，对应的自动化 lint 规则主要见 [anti-patterns.md](anti-patterns.md)。

- **[A2.1] 绑定阶段数据变更**：由于数据绑定期间改数极易引发重绘冲突，建议避免在 `beforeBindData`、`afterBindData` 中进行数据赋值（如 `setValue` 或改数据包）。推荐将数据变更移至 `createNewData`、`propertyChanged` 或保存前等事件中。
- **[A2.2] initialize 边界**：由于此时控件尚未实例化完毕，易产生空指针异常。建议避免在 `initialize()` 中进行控件事件注册或编写界面 UI 逻辑（控件注册建议放 `registerListener`，界面控制放 `afterBindData`）。
- **[A2.3] 元数据访问边界**：为防范平台底层表结构变更导致业务中断，业务代码中建议避免直接访问平台元数据底表 `t_meta_xxx`，推荐调用平台元数据服务。
- **[A2.4] 标准产品保护**：为避免破坏原厂升级兼容性及核心逻辑，建议避免继承标准产品的表单/单据插件，且不推荐禁用原厂已注册的插件。
- **[A2.5] 引用对象类型一致**：为防范由于关联属性的类型不匹配报错，推荐在创建引用对象或给引用属性赋值时，保持对象类型与属性复杂类型一致。
- **[A2.6] 元数据单例保护**：由于缓存中的实体元数据对象是全局共用的，直接修改会导致状态污染。在需要修改元数据前，推荐先进行 `clone`，在副本上修改后再使用。
- **[A2.7] 设计器/PDM 一致性**：业务对象、字段、默认值、可空性等定义以 PDM 和设计器为准。

## A3. 运行时与运维红线

- **[A3.1] 数据访问安全**：防范内存溢出与 SQL 注入风险，推荐查询使用参数化方式，且 `DataSet` 在使用完毕后推荐及时关闭（建议使用 try-with-resources），避免使用字符串拼接 SQL 过滤条件。
- **[A3.2] 性能与大循环**：为防范高延迟操作导致阻塞，应避免在循环体内部调用外部数据库查询、Redis 访问、`view.updateView()`、`ORM.create()` 或远程服务。推荐将数据批量加载后在内存中过滤，刷新操作在循环体外统一执行。
- **[A3.3] 日志记录规范**：为避免异常堆栈输出到控制台导致日志丢失或硬盘占满，推荐统一使用 `kd.bos.logging.Log` 记录，避免调用 `printStackTrace()`。
- **[A3.4] 异常分类规范**：为了便于框架正确向终端反馈业务提示，推荐在业务流程中抛出具体的业务异常（如 `KDBizException`），避免直接使用通配型的 `RuntimeException`。

## A4. 与 B/C 层的边界

- **不属于 A 层**：
  - "优先使用 `Ext` 基类而不是原生基类"
  - "优先使用 `OpUtils` / `BotpUtils`"
  - "优先使用 `QueryServiceHelper.exists(...)` 替代 `queryOne(...)`"
  - "给每个 `@Override` 都补验证来源注释"
- 上述内容仍然是有价值的，但默认分别归入：
  - **B 层推荐项**：新代码默认遵守
  - **C 层治理项**：适合逐步清理历史项目，不作为当前一次性交付的硬阻断

## A5. 当前默认交付判断

- 针对 `SCENE-*` 中的硬错误，建议优先进行修复与调整。
- 针对本文件列出的平台红线或运行时红线，建议优先进行优化以符合交付基线。
- 若用户明确要求保留历史风格，可局部保留 **B/C 层** 写法，但仍不推荐突破 **A 层** 关键红线。