# 通用组件开发规范

规范版本：1.0 · 更新：2026-09-12。适用于表格、弹窗、上传、文件浏览、导航等可复用组件。默认采用“固定版本下发 → 项目按需 fork → 特性回送 → 母组件评估 → 发布新版本 → 项目选择升级”。

这是新建及后续改造组件的开发规范，不代表 module 中所有历史代码片段已经完成组件化。表格组件是首个实施示例；各组件应明确标注自己的封装、工具与验证状态。

## 1. 复用可执行组件，而非重新解释规范

- 有成熟实现时，从经过验证的应用源码抽取，以它的实际结构、样式和交互为基准。文档和截图用于说明，不作为重新实现一套相似控件的指令。
- 母组件只有一份可维护的开发源码。不同应用使用相同版本的代码；业务适配文件负责字段、数据、权限与扩展接口。
- 应用不得独立复制并修改组件内部实现、覆盖内部样式后仍声称使用原版。内部行为变更应进入可追踪的 fork。
- 组件不携带业务数据库、用户会话、密钥或固定业务地址。需要实时数据或配置时，由明确接口提供；不能通过配置悄悄替换可执行代码。

## 2. 下发完整、固定版本的包

包应包含可读源码、样式与必要资源、最小运行示例、接口说明、组件测试，以及以下维护材料：

- `QUICKSTART.md`：最短接入流程、运行方法、已知限制。
- `component.lock.json`：组件标识、母版本、来源、文件哈希和依赖版本。
- `API.md`：公开参数、事件、业务适配与样式扩展边界。
- `FEATURE.md`：新增特性和回送说明模板。
- 原版基线及分叉记录机制：可以使用 Git 基线或经哈希校验的 `.upstream`，必须能重建差异。

项目将包和适配代码纳入自己的版本管理，同源部署或原样打包进应用。默认不依赖“latest”地址，不自动升级。构建输出不是另一份手工源码；应能证明实际发布文件来自锁定版本或已登记的 fork。

## 3. 区分配置、业务扩展与 fork

| 变更 | 放在哪里 | 是否登记 fork |
|---|---|---|
| 字段标题、默认排序、现有参数、数据映射 | 应用配置 | 否 |
| 保存接口、权限验证、业务字段渲染、已有扩展插槽 | 业务适配层 | 否 |
| 新增组件能力、改变内部交互或内部样式、修改公共接口 | 组件开发源 | 是 |

在具体任务中需要改组件时，先记录母版本、原版哈希、项目和分叉名称，再修改该项目的组件源码。保留原版，不覆盖母版本号，也不以散落的 CSS 补丁规避分叉记录。

## 4. 项目特性回送母组件

回送材料至少包括：

1. 母版本、分叉标识和原版哈希。
2. 具体使用场景、原行为、新行为，以及不能仅用现有配置实现的原因。
3. 可应用的代码补丁或提交；新增文件和二进制资源也应有完整清单及哈希。
4. 公共接口、默认行为、兼容性和依赖变化。
5. 明确标记的虚构复现示例、测试结果及必要截图。
6. 影响范围、迁移和回滚方式。

回送是提出特性，不是直接覆盖母组件。发送提案、合并或发布按当前任务授权执行，不因为生成补丁就自动执行后续动作。不要附带真实业务数据、会话或凭证。

## 5. 母组件评估与收敛

母组件维护任务核对基线、检查补丁、复现测试，并记录决定：

- **通用修复**：修复现有能力，保持兼容。
- **通用新能力**：抽象为公开参数或接口，不绑定某个应用。
- **可选扩展**：能力只适合部分场景，保持明确的启用方式。
- **业务专用**：留在应用适配层或该项目分叉，不强行进入母组件。
- **暂不合并**：记录原因或待补充材料。

合并后同步维护源码、接口说明、示例和测试。不要只接受截图或文字结论，也不要让母组件不断积累项目名称判断和业务特例。

## 6. 验证、发布与升级

- 组件维护适用于自身的共用交互测试；应用维护数据接口、权限及业务回归测试。使用同一份候选构建包验证代表性应用。
- UI 组件验证实际点击、键盘、适用的触屏操作、宽窄屏、空值及错误状态；有编辑功能时验证草稿、取消、重复提交和保存失败。只验证 HTTP 状态或文件哈希不能替代交互验证。
- 部署前校验锁定版本、源码差异与最终构建产物。未登记的修改必须显式处理，不能冒充原版通过发布。
- 发布新的不可变版本目录、哈希、变更说明和迁移信息，不覆盖旧版本。兼容修复用补丁版本，兼容能力用次版本，不兼容变化用主版本。
- 各项目主动选择升级。没有本地修改时验证后换版；有 fork 时对原母版、本地改版、新母版做三方合并，再测试部署。
- 回滚使用项目先前的组件版本与适配配置，不回滚业务数据来掩盖组件问题。

## 7. 给后续任务的最小上下文

通常只需读取：本规范、组件 `QUICKSTART.md`、`component.lock.json` 和应用适配文件。有 fork 时再读取分叉记录、`FEATURE.md` 与差异补丁。需要实现细节时直接查源码与测试，不要求重新复述整套历史对话。

## 已实施示例与自动化边界

[CRM 基础表格组件](https://ai.njwl.ai/module/table/)已提供固定版本源码包、示例，以及本地安装、校验、登记 fork 和生成提案工具。其当前工具主要跟踪 JS/CSS 两个核心文件；新增资源应补充提案清单与哈希。

这份规范本身不是自动发布系统。其他组件在接入这些工具前，不能宣称已经自动检测修改、自动回送或自动合并。母组件评估、跨版本合并和项目升级仍需明确执行。


## 记录删除交互补充（2026-09-15）

删除入口、确认、提交中、失败保留、版本冲突和成功后列表更新应作为接入验收项；编辑与删除权限独立。通用交互与关联删除业务规则分开维护。此为规范补充，不表示所有组件已有删除接口。完整要求见 [表格删除交互规范](/module/delete-interaction.md)。