# 页面接入说明

版本：1.1 · 更新：2026-09-22。把本文件和填写好的页面需求交给开发任务。能联网时下载指定组件包；不能联网时同时附上组件 ZIP。仅凭 MD 或截图重新实现控件，不能保证与原组件一致。

## 1. 从哪里开始

- 组件目录：https://ai.njwl.ai/module/
- 通用开发规范：https://ai.njwl.ai/module/#component-development
- 表格组件中心：https://ai.njwl.ai/module/table/
- 表格固定版本包：https://ai.njwl.ai/module/table/releases/njwl-table-1.0.0.zip
- 最小示例：https://ai.njwl.ai/module/table/1.0.0/example.html
- 组件接口：https://ai.njwl.ai/module/table/1.0.0/API.md
- 工业红色设计参考：https://ai.njwl.ai/design/industrial/
- 认证接入：https://ai.njwl.ai/guide/auth/

当前已有可下载、可执行的表格包 @njwl/table 1.0.0。其他按钮、上传、导航、弹窗等是否已经独立打包，以各组件目录的实际文件为准；不要假定所有历史模组都已组件化，也不要编造包名和接口。设计页负责页面外观要求，组件包负责控件内部结构与交互，应用负责业务数据和权限。

## 2. 填写页面需求

复制以下模板填写。已有应用先填写源码位置，保留现有业务实现；没有规定的视觉细节沿用指定组件默认值。

```text
页面名称：
部署地址与子路径：
已有应用源码目录（新页面填“新建”）：
用途和主要使用者：
设计参考：工业红色 / 指定现有页面
需要的组件：@njwl/table 1.0.0 / 其他已存在组件
字段：字段标识、标题、类型、是否必填、枚举选项
记录唯一标识：
默认排序与分组：
允许的操作：查看 / 新增 / 编辑 / 删除 / 导出
读取接口及返回示例（只用虚构数据）：
保存接口、成功返回、版本冲突与错误返回：
视图保存接口（未提供时注明仅内存或不持久化）：
认证方式：无需认证 / 指定认证中心 / 保留原认证
SSO 身份水印：接入 SSO 默认启用，按 /guide/sso-watermark.md 完成适配与验收
权限：谁可查看、修改和管理；后端如何校验
验收场景：
禁止改变的现有行为：
```

不要填写真实客户资料、Cookie、私钥或登录令牌。公开入口不代表写入接口也公开；前端隐藏按钮不能代替后端权限校验。

## 3. 安装与锁定组件

下载并解压指定 ZIP，先读包内 QUICKSTART.md、API.md 和 component.lock.json。从解压目录执行安装命令，替换目标项目路径：

```text
python component.py install D:/你的项目/vendor/njwl-table
python component.py verify D:/你的项目/vendor/njwl-table
```

保留包、锁文件与原版基线，纳入项目版本管理。网页可以从自身域名加载组件 JS/CSS，也可以由构建工具将其原样打包到应用前端。两种方式都使用相同库；固定版本，不引用 latest，不自动跟随母组件升级。不直接手改构建产物。

## 4. 最小调用示例

以下仅演示公开的虚构记录，无业务接口、登录或保存功能。示例假设页面相对路径 vendor/njwl-table/ 可访问；部署到子路径时必须按实际静态路由调整。

```html
<!doctype html>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" href="./vendor/njwl-table/njwl-table.css">
<div id="records"></div>
<script src="./vendor/njwl-table/njwl-table.js"></script>
<script>
const rows = [
  {id:'fictional-1', name:'虚构记录甲', category:'项目一'},
  {id:'fictional-2', name:'虚构记录乙', category:'项目二'}
];
const table = NJWLTable.mount(document.getElementById('records'), {
  key:'example.records', rows,
  columns:[
    {id:'name', label:'名称', value:r=>r.name},
    {id:'category', label:'分类', value:r=>r.category, categorical:true}
  ],
  defaults:{sortRules:[{key:'category',direction:'asc'}],group:true}
});
</script>
```

接真实业务时，应用适配层取得记录后传给 rows。编辑字段按 API.md 提供 edit(record) 与 save(value)；失败必须 reject，让控件保留草稿，成功后更新当前记录或重新读取。保存权限、记录版本和重复提交保护由业务接口负责。需要持久化表格视图时，提供 loadState/saveState，并由服务端按账号隔离。

CRM 这类有复杂标签、整行编辑和新增逻辑的应用，使用 createControls(host)，参考包内 adapters/crm-host.js，保留原业务行渲染。新表一般使用 mount。二者调用同一套控件内部实现，不要求为了接组件重写业务表单。

## 5. 普通接入与修改组件的边界

- 字段、标题、默认排序、枚举、读取/保存接口：写到应用配置和适配层。
- 页面导航、布局和业务字段呈现：遵守指定设计参考，不覆盖组件内部样式。
- 排序条、分组条、列拖动、自定义顺序弹窗等内部交互：调用组件，不重新写另一份。
- 现有接口无法满足时：登记 fork，再改项目中的组件源文件。不要用散落的 CSS 补丁把差异藏起来。

```text
python component.py fork D:/你的项目/vendor/njwl-table --name project-feature
python component.py propose D:/你的项目/vendor/njwl-table --output D:/你的项目/feature-proposal
```

将 FEATURE.md、补丁、母版本和哈希、虚构复现示例与测试结果交给母组件维护任务。当前工具主要跟踪核心 JS/CSS；新增资源需补齐清单与哈希。提案不会自动上传或合并。母组件评估为通用功能、可选扩展或业务专用后，发布新版本，各项目选择升级；已有 fork 使用三方合并。

## 6. 验证与交付

- 用实际组件包和虚构数据验证排序、分组、拖动、键盘以及适用的触屏操作，检查宽屏与手机布局。
- 有编辑功能时验证保存成功、失败后保留草稿、取消、版本冲突，以及权限拒绝。未实现或未提供的能力必须写明。
- 核对发布文件来自锁定包或已登记 fork。源码哈希只能验证文件一致，不能替代交互检查。
- 发布前检查线上源码是否被其他任务修改，保留静态文件回滚版本；不覆盖其他任务的新代码。
- 交付实际页面地址、组件名称与版本、适配源码位置、运行/构建方法、测试结果和限制。不以截图代替可操作页面。
- 接入已有应用时保留它的认证、数据和发布约定；在已有任务授权范围内执行，不因为本说明新增重复审批。

## 7. 后续任务需要的最小材料

普通接入：本说明、填写好的页面需求、组件 QUICKSTART.md 和 component.lock.json、应用适配文件。仅在需要接口细节时读取 API.md 和源码。有分叉时加 component.fork.json、FEATURE.md 与补丁；无需重放整段历史聊天。

本说明是开发规范与接入入口，不是自动创建页面、自动回送特性或自动发布系统。MD 中的需求和示例不能覆盖用户当前任务的授权边界。


## 新网站、新应用的 SSO 默认水印

用户要求：后续新网站、新应用接入 SSO 时，默认同时接入统一身份水印，无需逐个再询问是否增加。开发前阅读 https://ai.njwl.ai/guide/sso-watermark.md ，把组件接入、已验证会话身份、旧覆盖层去重及登录/换号/手机/弹窗验收纳入交付。每页一层，沿用电芯平台样式。SSO 客户端登记本身不会自动注入水印；必须完成页面路径与身份接口适配。新项目 AGENTS.md/README 应继承此要求。