cm-reporting-integration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

CM Reporting Integration

CM Reporting 集成指南

Use this skill to deliver production-grade

cm-reporting

integrations, not only demos.

本技能用于落地生产级

cm-reporting

集成，而非仅用于演示。

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
```
.

先路由请求，再加载必要的参考内容。

从零开始搭建新的宿主集成 → 阅读
```
references/integration-snippets.md
```
。
API/契约说明 → 阅读
```
references/contracts.md
```
。
模板/版本/文件查询 → 阅读
```
references/template-matrix.md
```
。
运行时/导出/恢复失败排查 → 阅读
```
references/troubleshooting.md
```
。
模板文件路径自动查询 → 运行
```
scripts/resolve-template-path.mjs
```
。

Non-Negotiable Constraints

不可妥协的约束规则

Apply these rules in every solution:

Keep
```
templateType
```
and
```
versionId
```
strictly matched across render, restore, and export.
Import
```
cm-reporting/styles.css
```
exactly once in host runtime.
Provide official template
```
.xlsx
```
as
```
ArrayBuffer
```
when calling Excel export APIs.

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.

所有解决方案都必须遵循以下规则：

在渲染、恢复和导出过程中，必须严格保证
```
templateType
```
与
```
versionId
```
的匹配。
在宿主运行时中仅需导入一次
```
cm-reporting/styles.css
```
。
调用Excel导出API时，需以
```
ArrayBuffer
```
格式传入官方模板
```
.xlsx
```
文件。
将Snapshot视为完整状态契约（包含
```
schemaVersion/templateType/versionId/data
```
）。
```
companyInfo.authorizationDate
```
推荐传
```
YYYY-MM-DD
```
；运行时兼容秒/毫秒时间戳（number/数字字符串），并会归一化为
```
YYYY-MM-DD
```
。
集成回调的返回结果只能是
```
{ items: [...] } | null | undefined
```
格式。
对
```
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
```
外部选择入口为“行内模式”：仅保留“新增一行”后在行内触发外部选择，不提供顶部批量“从外部选择”入口。
在使用建议中遵守包许可证（
```
PolyForm-Noncommercial-1.0.0
```
）。
对于
```
readOnly
```
行为，需将其视为仅查看契约（而非仅禁用输入框）：
- 在工作流中隐藏检查器页面和检查器入口；
- 隐藏全局必填项/错误提示横幅以及底部上一步/下一步操作按钮；
- 隐藏表格/表单的编辑功能（添加/删除/批量操作/外部选择/编辑链接），而非仅设置为
```
disabled
```
  状态；
- 当字段被禁用/设为只读时，取消必填项的黄色高亮提示。
在受控路由模式下，如果只读流程重定向了页面（例如回退到
```
checker
```
页面），需始终通过导航回调同步父组件状态，避免路由/UI不一致。
绝不能用本地的false值覆盖宿主级
```
ConfigProvider
```
的禁用状态。有效的禁用规则必须是
```
parentDisabled || readOnly
```
。
对于
```
EMRT/AMRT
```
检查器行为，需将检查器错误和进度汇总置于同一控制逻辑下：当Q1/Q2禁用冶炼厂要求时，不统计历史行中
```
smelterLookup
```
的必填进度。
对于
```
EMRT
```
，初始化为空时默认选择所有已声明的矿物；当
```
readOnly=false
```
时，用户仍可编辑声明范围的选择。

Standard Delivery Workflow

标准交付流程

Follow this order unless user asks otherwise.

Confirm host environment and peer dependency ranges.
Choose template delivery strategy (static/CDN/internal service).
Implement baseline
```
CMReporting
```
mounting with required props.
Add host orchestration via
```
CMReportingRef
```
(
```
get/set/export/validate
```
).
Add Snapshot persistence and recovery path.
Add Excel export action with tested template fetch path.
Add integrations callbacks if host needs external pickers.
Add legacy adapter flow only when interoperability is required.
Run final acceptance checklist from references before handoff.

除非用户另有要求，否则请遵循以下顺序：

确认宿主环境和对等依赖版本范围。
选择模板交付策略（静态文件/CDN/内部服务）。
实现基础的
```
CMReporting
```
组件挂载，并传入必填属性。
通过
```
CMReportingRef
```
添加宿主编排逻辑（
```
get/set/export/validate
```
）。
添加快照持久化与恢复流程。
添加Excel导出功能，并测试模板获取路径。
若宿主需要外部选择器，添加集成回调。
仅当需要兼容旧系统时，添加适配旧系统的流程。
交付前运行参考文档中的最终验收检查清单。

Output Requirements

输出要求

When producing integration code or guidance, always include:

Explicit dependency and peer dependency install commands.
Concrete
```
templateType
```
+
```
versionId
```
examples.
Snapshot save + restore behavior definition.
Excel export data flow (template source → ArrayBuffer → Blob download).
Failure fallback behavior (cancel flow, null return, retry boundaries).
Explicit readOnly behavior matrix (what is hidden vs what remains visible).

在生成集成代码或指导文档时，必须包含以下内容：

明确的依赖和对等依赖安装命令。
具体的
```
templateType
```
+
```
versionId
```
示例。
快照保存+恢复的行为定义。
Excel导出数据流（模板源 → ArrayBuffer → Blob下载）。
失败回退行为（取消流程、返回null、重试边界）。
明确的readOnly行为矩阵（隐藏内容与保留内容的对应关系）。

Anti-Patterns to Avoid

需避免的反模式

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.

不要从零开始生成工作簿用于导出。
不要在未验证映射关系的情况下假设模板文件存在。
不要混用不兼容的模板/版本组合。
不要从集成回调中返回原始数组；需包装为
```
{ items }
```
格式。
不要建议手动修改包内部代码或私有API。

References

参考文档

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.

仅加载请求所需的内容：

```
references/integration-snippets.md
```
：完整的快速入门+生产级实践方案。
```
references/contracts.md
```
：公开API和回调契约表。
```
references/template-matrix.md
```
：完整的模板/版本/文件映射关系。
```
references/troubleshooting.md
```
：症状-解决方案手册。

宿主外置保存/提交（新增集成约定）

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

默认底部仅保留翻页；如需完全由宿主控制，传
```
showPageActions={false}
```
隐藏底部翻页区。
使用
```
CMReportingRef.saveDraft()
```
执行“暂存”动作：
- 不触发必填校验；
- 直接返回
```
ReportSnapshotV1
```
  给宿主落库。
使用
```
CMReportingRef.submit()
```
执行“提交”动作：
- 先走库内
```
validate
```
  ；
- 失败返回
```
null
```
  ，并自动跳转 checker 页面；
- 成功返回
```
ReportSnapshotV1
```
  ，由宿主决定后续 API 提交。
```
useCMReporting()
```
提供同等能力（
```
saveDraft/submit
```
），适合函数式集成场景。

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

默认底部仅保留翻页；如需完全由宿主控制，传
```
showPageActions={false}
```
隐藏底部翻页区。
使用
```
CMReportingRef.saveDraft()
```
执行“暂存”动作：
- 不触发必填校验；
- 直接返回
```
ReportSnapshotV1
```
  给宿主落库。
使用
```
CMReportingRef.submit()
```
执行“提交”动作：
- 先走库内
```
validate
```
  ；
- 失败返回
```
null
```
  ，并自动跳转 checker 页面；
- 成功返回
```
ReportSnapshotV1
```
  ，由宿主决定后续 API 提交。
```
useCMReporting()
```
提供同等能力（
```
saveDraft/submit
```
），适合函数式集成场景。