@broke_wire/crud

采用单包 + 子路径导出：

1. @broke_wire/crud（根入口，仅 core）
2. @broke_wire/crud/core（显式 core 子路径）
3. @broke_wire/crud/element-plus（Element Plus 适配子路径）

安装策略（重要）

1. 只用 core：pnpm add @broke_wire/crud，不需要额外安装 vue/element-plus。
2. 用 Element Plus 适配层：请在业务项目自行安装 vue 与 element-plus。
3. 设计原则：根入口不再导出适配器，避免“安装 core 自动带 UI 依赖”。

相关设计文档：

1. ../../docs/02-architecture-overview.md
2. ../../docs/03-core-contract-v1.md
3. ../../docs/05-element-plus-adapter-v1.md
4. ../../docs/13-version-handshake-v1.md
5. ../../docs/19-error-code-reference-v1.md

当前进度

1. S1：握手契约、原因码、能力协商已落地。
2. S2：生命周期协议、事件总线、插件上下文标准化已落地。
3. S3：Element Plus 可用组件首版已落地（独立组件 + 编排组件）。
4. S4：三类迁移示例资源与对照清单已落地。

已实现的核心能力

1. 核心契约版本常量：CORE_CONTRACT_VERSION
2. 运行时握手：runVersionHandshake / assertVersionHandshake
3. 原因码：CRUD_REASON_CODES
4. 核心创建时自动握手：createCrudKernel(...).handshake
5. Element Plus 适配能力声明：contractVersion + capabilities
6. 列表并发保护：旧请求晚返回不会覆盖最新请求状态
7. 列表请求取消：新请求发起时可通过 AbortController 中断旧请求
8. 表单内置校验：enableFormValidate 开启后自动执行 formRef.validate
9. 强校验入口：SCHEMA_INVALID / PLUGIN_INVALID 会在初始化阶段直接抛错
10. 批量动作链路：runBatchAction + batch-action 事件
11. 选择状态链路：selectedRows / selectedRowKeys + selection-change
12. URL 同步：queryUrlSync 可把查询条件与分页状态映射到地址栏
13. 服务端排序筛选协议：sortProtocol / filterProtocol
14. 权限驱动 schema：permissionCode(s) + permissionBehavior
15. 列配置持久化工具：createColumnStateManager
16. 运行时可视化调试：createCrudDevtools（事件/错误筛选、耗时统计、日志导出）
17. 权限决策审计：permissionAuditTrail / onPermissionAudit

已实现的 Element Plus 组件

1. EpCrudPage
2. EpCrudTable
3. EpCrudPagination
4. EpCrudDialog
5. EpCrudDrawer
6. EpCrudFormFields

其他项目最小接入示例（JS）

import { createCrudKernel } from '@broke_wire/crud'
import {
  createElementPlusCrudAdapter,
  useElementPlusBridge,
  createEpCrudPageBindings,
  EpCrudPage,
} from '@broke_wire/crud/element-plus'

const kernel = createCrudKernel({
  list: { fetchList: (payload) => api.queryList(payload) },
  form: {
    createApi: (payload) => api.create(payload),
    updateApi: (payload) => api.update(payload),
  },
  action: {
    deleteApi: (payload) => api.remove(payload),
  },
})
// Devtools 默认不自动启用（避免生产环境误开）。
// 如需开启：createCrudKernel({ ..., devtools: true })
// 也可传对象：createCrudKernel({ ..., devtools: { enabled: true, enableOverlay: true } })
// 或手动插件：plugins: [createCrudDevtools({ enabled: true }).plugin]

const adapter = createElementPlusCrudAdapter()
const bridge = useElementPlusBridge(kernel, adapter)
const bindings = bridge.createPageBindings({
  querySchema,
  tableColumns,
  formSchema,
  actionSchema,
})
// 也支持显式调用：
// const bindings = createEpCrudPageBindings(bridge, { querySchema, tableColumns, formSchema, actionSchema })

// 在 Vue 页面中：
// <EpCrudPage
//   v-bind="bindings.props"
//   v-on="bindings.events"
//   :enable-selection="true"
//   :enable-column-settings="true"
//   :batch-action-retry="1"
// />

批量动作弹框/样式自定义：

const bindings = bridge.createPageBindings({
  querySchema,
  tableColumns,
  formSchema,
  actionSchema,
  pageProps: {
    batchActionConfirm: async ({ action, selectedRows }) => {
      // 可接入 ElMessageBox / ElDialog / 自研弹框。
      return window.confirm(`确认执行 ${action.label || action.key}？共 ${selectedRows.length} 条`)
    },
  },
})

样式和布局扩展方式

1. 可只用 EpCrudTable/EpCrudPagination，不用 EpCrudPage。
2. 可通过 props/events/slots 覆盖默认布局和动作区。
3. 可通过 actionSchema + resolveActionType 自定义按钮组件和样式。

错误提示（开发友好）

运行时错误对象包含以下字段：

1. error.code：稳定错误码
2. error.messageZh：中文主消息
3. error.tip：排查建议
4. error.detail：错误上下文

示例：

try {
  createCrudKernel({ list: {} })
} catch (error) {
  console.log(error.code) // RUNTIME_OPTIONS_INVALID
  console.log(error.messageZh) // 列表控制器初始化失败：`fetchList` 必须是函数。
  console.log(error.tip) // 请检查 create*Controller 的必填函数参数是否正确传入。
}

完整错误码与 reason 说明请参考：../../docs/19-error-code-reference-v1.md。

权限决策审计（可追踪“为什么隐藏/禁用”）

import { createCrudSchemaPack } from '@broke_wire/crud'

const permissionAuditTrail = []
const schemaPack = createCrudSchemaPack({
  querySchema,
  tableSchema,
  formSchema,
  actionSchema,
  permissionContext: ['query:view'],
  permissionAuditTrail,
})

console.log(permissionAuditTrail[0])
// {
//   schemaName: 'tableSchema',
//   itemKey: 'owner',
//   decision: 'hidden' | 'disabled' | 'visible',
//   reasonCode: 'PERMISSION_DENIED_HIDE' | 'PERMISSION_DENIED_DISABLE' | ...
// }

并发请求保护（列表）

loadList 内置“最新请求优先”策略：

1. 新请求发出后，旧请求如果晚返回会被标记为 stale，不会改写 tableData/pageData/loading。
2. 旧请求失败也不会污染当前 requestError。
3. 默认开启 enableAbortOnRequery，新请求会给 fetchList 透传 signal，可直接接入 fetch/axios 取消能力。

表单内置校验（可选）

在 createFormController 配置 enableFormValidate: true 后：

1. 提交前会自动执行 formRef.validate。
2. 校验失败时返回 null，并触发 submit-fail 事件（reason=FORM_VALIDATE_FAILED）。

S4 示例资源

1. examples/s4-scenarios/scenario-a-standard-crud.js
2. examples/s4-scenarios/scenario-b-extended-actions.js
3. examples/s4-scenarios/scenario-c-complex-custom.js
4. examples/s4-scenarios/README.md