CM Reporting Integration

Use this skill to deliver production-grade

cm-reporting

integrations, not only demos.

Fast Routing

Route requests first, then load the minimum references.

New host integration from zero → read
```
references/integration-snippets.md
```
.
API/contract clarification → read
```
references/contracts.md
```
.
Template/version/file lookup → read
```
references/template-matrix.md
```
.
Runtime/export/restore failures → read
```
references/troubleshooting.md
```
.
Template file path lookup automation → run
```
scripts/resolve-template-path.mjs
```
.

Apply these rules in every solution:

Treat Snapshot as full-state contract (

schemaVersion/templateType/versionId/data

```
companyInfo.authorizationDate
```
推荐传
```
YYYY-MM-DD
```
；运行时兼容秒/毫秒时间戳（number/数字字符串），并会归一化为
```
YYYY-MM-DD
```
。
Return integrations callback result in
```
{ items: [...] } | null | undefined
```
shape only.
对
```
SmelterList
```
外部回写结果，
```
id
```
与冶炼厂识别号码语义严格分离：
```
id
```
仅用于行主键与去重判定；识别号码应由
```
smelterNumber
```
回写并仅用于展示（
```
smelterId
```
仅内部兼容）。
```
SmelterList
```
新增行应先生成临时 ID（
```
smelter-new-<timestamp>
```
）；宿主外部选择回写
```
id
```
后覆盖该临时 ID，未回写
```
id
```
时本次回写无效并提示错误。
```
SmelterList
```
行内外部选择需保证同一个
```
metal
```
下冶炼厂唯一，按回写
```
id
```
判重。

SmelterList

行内外部选择成功后（非

Smelter not listed / not yet identified

），应锁定基础主数据字段不可编辑：

smelterNumber

、

country

、

smelterIdentification

、

sourceId

、

street

、

city

、

state

。

```
SmelterList
```
外部选择入口为“行内模式”：仅保留“新增一行”后在行内触发外部选择，不提供顶部批量“从外部选择”入口。
Respect package license (
```
PolyForm-Noncommercial-1.0.0
```
) in usage recommendations.
For
```
readOnly
```
behavior, treat it as view-only contract (not just disabled inputs):
- hide checker page and checker entry in workflow;
- hide global required/error hint banner and bottom prev/next actions;
- hide table/form editing affordances (add/delete/batch/external pick/edit links), not merely
```
disabled
```
  ;
- suppress required yellow highlight when fields are disabled/read-only.
In controlled routing mode, if readOnly flow remaps page (e.g.
```
checker
```
fallback), always sync parent state via navigation callback to avoid route/UI drift.
Never override host-level
```
ConfigProvider
```
disabled state with local false. Effective disabled rule must be
```
parentDisabled || readOnly
```
.
For
```
EMRT/AMRT
```
checker behavior, keep checker errors and progress summary under the same gating: when smelter requirement is disabled by Q1/Q2, do not count
```
smelterLookup
```
required progress from historical rows.
For
```
EMRT
```
, default selection should include all declared minerals on empty initialization; when
```
readOnly=false
```
, users can still edit the declaration scope selections.

Follow this order unless user asks otherwise.

When producing integration code or guidance, always include:

Do not generate workbook from scratch for export.
Do not assume template files exist without mapping verification.
Do not mix incompatible template/version pairs.
Do not return raw arrays from integrations callbacks; wrap in
```
{ items }
```
.
Do not advise manual mutation of package internals or private APIs.

Load only what the request needs:

```
references/integration-snippets.md
```
: full quickstart + production recipes.
```
references/contracts.md
```
: public API and callback contract tables.
```
references/template-matrix.md
```
: complete template/version/file mapping.
```
references/troubleshooting.md
```
: symptom-to-action playbook.

当业务希望在弹窗或页面外层接管流程时，推荐使用以下模式：