@robot-admin/naive-ui-components 0.14.3 → 0.16.0

package/docs/engineering.en.md

@@ -0,0 +1,132 @@
+[← English README](../README_EN.md) · [中文](./engineering.md)
+
+# Development and build
+
+## Build Architecture
+
+### Six-stage Build Pipeline
+
+```
+bun run build
+  ├── 1. tsdown          → Multi-entry bundling (55 components ESM/CJS/DTS)
+  ├── 2. sass CLI        → Compile the shared-variable entry → global-scss.css
+  ├── 3. merge-css.js    → Merge Vue-compiled SFC CSS + global variables → style.css
+  ├── 4. gen-exports.js  → Auto-generate package.json exports map
+  ├── 5. check:dist      → Validate root, subpath, SSR, and DTS public exports
+  └── 6. check:size      → Enforce full/base CSS and package-size budgets
+```
+
+### Key Technical Details
+
+- **Build engine**: [tsdown](https://github.com/rolldown/tsdown) (Rolldown-based), 55 component entries plus the root entry and resolver
+- **SCSS processing**: Custom `scssTransformPlugin` compiles SFC SCSS within the Rolldown pipeline; standalone Sass CLI only compiles the shared-variable entry
+- **CSS merging**: Post-build merges Vue scoped-compiled per-chunk CSS with shared variables into a single `style.css`, avoiding duplicate styles and leaked raw `:deep()` selectors
+- **Type exports**: Unified `export *` barrel pattern with auto-generated `.d.ts`
+- **Subpath exports**: `gen-exports.js` auto-scans `dist/` and writes the `exports` field in `package.json`
+- **Export conflict detection**: `check-export-conflicts.js` ensures no naming collisions between components
+- **Artifact entry validation**: `check-dist-entries.js` prevents internal chunks from replacing root declarations and verifies component utility subpath types
+- **Package contract validation**: blocks Naive UI internal type paths, hidden optional installs, and plugin console side effects
+- **Size budgets**: `check-size-budget.js` prevents accidental growth of global, C_Form/C_Table, and total dist output
+- **Consumer budgets**: `check-consumer-size.js` builds four minimal Vite applications, sums gzip bytes along the emitted static JS import graph, and rejects eager editor, spreadsheet, screenshot, or print dependencies.
+
+### Build Output
+
+```
+dist/
+├── index.js / index.cjs / index.d.ts     # Main entry
+├── C_Form.js / C_Form.cjs / C_Form.d.ts  # Subpath entries (55 components)
+├── C_Form.base.css / C_Form.css         # Base/full style tiers
+├── C_Table.base.css / C_Table.css       # Base/full style tiers
+├── style.css                             # Merged full styles
+└── [chunk].js                            # Shared code chunks
+```
+
+## Development
+
+The environment baseline is Node.js 20.19.0+ and Bun 1.3.14. `.node-version`, `packageManager`, `engines`, and the frozen lockfile keep local and CI installs aligned.
+
+```bash
+bun install --frozen-lockfile # Install exactly from the lockfile
+bun run dev              # Dev mode (SCSS watch + tsdown watch)
+bun run build            # Full build
+bun run build:scss       # Compile global SCSS only
+bun run build:css        # Merge fresh tsdown CSS chunks; safely skips a finalized dist
+bun run build:exports    # Generate exports map only
+bun run check:exports    # Check export naming conflicts
+bun run check:dist       # Validate built JS / DTS public entries
+bun run check:consumer-contracts # Tarball consumer types and optional peer boundaries
+bun run check:package    # Validate dependencies, exports, and public source boundaries
+bun run check:quality    # Prevent any, console, and type-suppression debt regressions
+bun run check:audit      # Audit direct and transitive dependency vulnerabilities
+bun run check:size       # Enforce publish artifact size budgets
+bun run check:consumer-size # Check initial consumer bundles after building
+bun run type-check       # TypeScript type checking
+bun run test             # Run Bun unit tests
+bun run lint:check       # Oxlint + ESLint (check only)
+bun run lint:eslint      # Audit the existing ESLint rule backlog
+bun run verify           # Type, test, export, and build verification
+```
+
+Consumer budgets include Vue and Naive UI. The four applications are independent measurements and cannot be added to estimate one application's size. `C_Form/base` renders one input; `C_Table/base` renders one row and column. The other cases render one search input and one action button. Base CSS excludes the built-in rich-text editor styles. Dynamic JS is built and checked but excluded from initial bytes; using those features still loads it. This check measures transfer size, not browser interaction performance. Both `verify` and the pre-publish lifecycle include this gate.
+
+### Project Structure
+
+```
+naive-ui-components/
+├── src/
+│   ├── index.ts                     # Library entry (global registration + export * barrel)
+│   ├── styles/
+│   │   ├── variables.scss           # CSS variables (--c-*)
+│   │   └── global.scss              # Auto-generated shared-variable entry
+│   ├── components/
+│   │   └── C_[Name]/
+│   │       ├── index.vue            # Main component file
+│   │       ├── index.ts             # Barrel export
+│   │       ├── index.scss           # Component styles
+│   │       ├── types.ts             # Type definitions
+│   │       ├── constants.ts         # Constants
+│   │       ├── data.ts              # Static data
+│   │       ├── composables/         # Composable functions
+│   │       ├── components/          # Sub-components
+│   │       └── layouts/             # Layout variants (C_Form/C_AntV)
+│   ├── plugins/                     # highlight.js and other plugins
+│   └── utils/                       # Utility functions
+├── scripts/
+│   ├── gen-global-scss.js           # Generate global.scss (shared variables only)
+│   ├── watch-global-scss.js         # Dev mode SCSS watcher
+│   ├── merge-css.js                 # Merge CSS artifacts
+│   ├── gen-exports.js               # Auto-generate package.json exports
+│   └── check-export-conflicts.js    # Export naming conflict detection
+├── types/
+│   └── env.d.ts                     # .vue / .scss module declarations
+├── tsdown.config.ts                 # Build config (multi-entry + SCSS plugin + Vue plugin)
+└── tsconfig.json
+```
+
+### Adding a New Component
+
+1. Create `src/components/C_NewComponent/` directory
+2. Write `index.vue`, `index.ts` (barrel), `types.ts`
+3. Add `export * from './components/C_NewComponent'` in `src/index.ts`
+4. Add the component import and registration to the `components` array in `src/index.ts`
+5. Add the name to `componentNames` in `src/resolver.ts`
+6. Run `bun run verify` — build scripts will auto-generate subpath entries and exports mapping
+
+### Publishing
+
+```bash
+bun run changeset       # Record changes and release level
+bun run version         # Update package version and CHANGELOG
+bun run verify          # Run all pre-publish checks
+bun run release         # Publish pending Changesets releases
+```
+
+The official local Changesets changelog generator uses commit IDs and change summaries; `bun run version` does not require a GitHub token. npm authentication is still required for publishing. On Windows, if `bun run release` stalls while npm repeats `prepublishOnly`, first confirm `bun run verify` succeeds, then publish from PowerShell with `$env:npm_config_ignore_scripts='true'; bun run release`. This skips only the repeated lifecycle check, not the prerequisite verification.
+
+## Documentation assets
+
+Brand sources and exported PNGs are in [`assets/`](./assets/). See the [asset guide](./assets/README.md) for colors, logo usage and export instructions.
+
+## Architecture boundaries
+
+See [architecture and isolation](./architecture.en.md) for dependency direction, app-level ownership and future Element Plus adaptation.

package/docs/engineering.md

@@ -0,0 +1,133 @@
+[← 项目首页](../README.md) · [English](./engineering.en.md)
+
+# 开发与构建
+
+## 构建架构
+
+### 六阶段构建流水线
+
+```
+bun run build
+  ├── 1. tsdown          → 多入口打包（55 组件 ESM/CJS/DTS）
+  ├── 2. sass CLI        → 编译共享变量入口 → global-scss.css
+  ├── 3. merge-css.js    → 合并 Vue 编译后的 SFC CSS + 全局变量 → style.css
+  ├── 4. gen-exports.js  → 自动生成 package.json exports 映射
+  ├── 5. check:dist      → 校验根入口、子路径、SSR 及 DTS 公共导出
+  └── 6. check:size      → 校验全量/基础样式与发布包体积预算
+```
+
+### 技术要点
+
+- **构建引擎**：[tsdown](https://github.com/rolldown/tsdown)（基于 Rolldown），55 个组件入口，加主入口与 Resolver
+- **SCSS 处理**：自定义 `scssTransformPlugin` 在 Rolldown 管线内编译 SFC SCSS，独立 Sass CLI 仅编译共享变量入口
+- **CSS 合并**：构建后将 Vue 已完成 scoped 转换的 per-chunk CSS 与共享变量合并为单一 `style.css`，避免重复样式和原始 `:deep()` 选择器泄漏
+- **类型导出**：统一 `export *` barrel 模式，自动生成完整 `.d.ts`
+- **子路径导出**：`gen-exports.js` 自动扫描 `dist/` 并写入 `package.json` 的 `exports` 字段
+- **导出冲突检测**：`check-export-conflicts.js` 确保组件间无命名冲突
+- **产物入口校验**：`check-dist-entries.js` 防止内部 chunk 覆盖根声明，并保证组件工具的子路径类型完整
+- **包契约校验**：禁止 Naive UI 内部类型路径、隐式可选依赖和插件控制台副作用
+- **体积预算**：`check-size-budget.js` 阻止全量样式、C_Form/C_Table 样式和 dist 总量意外膨胀
+- **消费端预算**：`check-consumer-size.js` 用 Vite 构建四个最小消费应用，沿实际静态导入图累计首屏 JS gzip；同时检查编辑器、Excel、截图和打印依赖没有进入首屏。
+
+### 输出产物
+
+```
+dist/
+├── index.js / index.cjs / index.d.ts     # 主入口
+├── C_Form.js / C_Form.cjs / C_Form.d.ts  # 子路径入口（55 组件）
+├── C_Form.base.css / C_Form.css         # 基础/完整样式层级
+├── C_Table.base.css / C_Table.css       # 基础/完整样式层级
+├── style.css                             # 合并后的全量样式
+├── images/                               # Leaflet Marker/图层控件资源
+└── [chunk].js                            # 共享代码块
+```
+
+## 开发
+
+环境基线为 Node.js 20.19.0+ 与 Bun 1.3.14；仓库通过 `.node-version`、`packageManager`、`engines` 和冻结锁文件保持本地/CI 一致。
+
+```bash
+bun install --frozen-lockfile # 严格按锁文件安装依赖
+bun run dev              # 开发模式（SCSS watch + tsdown watch）
+bun run build            # 完整构建
+bun run build:scss       # 仅编译全局 SCSS
+bun run build:css        # 合并 tsdown 刚生成的 CSS chunk；已完成的 dist 会安全跳过
+bun run build:exports    # 仅生成 exports 映射
+bun run check:exports    # 检测导出命名冲突
+bun run check:dist       # 校验构建后的 JS / DTS 公共入口
+bun run check:consumer-contracts # 真实打包消费者类型与可选 peer 边界
+bun run check:package    # 校验依赖、导出和源码公共边界
+bun run check:quality    # 防止 any、console 与类型抑制债务反弹
+bun run check:audit      # 审计直接与传递依赖漏洞
+bun run check:size       # 校验发布产物体积预算
+bun run check:consumer-size # 构建后检查常用组件的消费端首屏预算
+bun run type-check       # TypeScript 类型检查
+bun run test             # 运行 Bun 单元测试
+bun run lint:check       # Oxlint + ESLint（只检查）
+bun run lint:eslint      # ESLint 存量规则审计
+bun run verify           # 类型、测试、导出和构建全量验证
+```
+
+消费端预算包含 Vue 和 Naive UI，四个独立场景分别测量，不能相加当作同一应用的体积。`C_Form/base` 为单输入字段，`C_Table/base` 为单列单行展示表格；另外测量一个输入查询和一个操作按钮。基础样式排除内置富文本编辑器样式。动态 JS 会完成构建检查，但不计入首屏；使用对应字段或功能时仍会加载。此检查衡量传输体积，不替代真实浏览器的交互性能测量。`verify` 和发布前生命周期均包含该门禁。
+
+### 项目结构
+
+```
+naive-ui-components/
+├── src/
+│   ├── index.ts                     # 库入口（全量注册 + export * barrel）
+│   ├── styles/
+│   │   ├── variables.scss           # CSS 变量 (--c-*)
+│   │   └── global.scss              # 自动生成的共享变量入口
+│   ├── components/
+│   │   └── C_[Name]/
+│   │       ├── index.vue            # 组件主文件
+│   │       ├── index.ts             # Barrel 导出
+│   │       ├── index.scss           # 组件样式
+│   │       ├── types.ts             # 类型定义
+│   │       ├── constants.ts         # 常量
+│   │       ├── data.ts              # 静态数据
+│   │       ├── composables/         # 组合式函数
+│   │       ├── components/          # 子组件
+│   │       └── layouts/             # 布局变体（C_Form/C_AntV）
+│   ├── plugins/                     # highlight.js 等插件
+│   └── utils/                       # 工具函数
+├── scripts/
+│   ├── gen-global-scss.js           # 生成 global.scss（仅共享变量）
+│   ├── watch-global-scss.js         # 开发模式 SCSS 监听
+│   ├── merge-css.js                 # 合并 CSS 产物
+│   ├── gen-exports.js               # 自动生成 package.json exports
+│   └── check-export-conflicts.js    # 导出命名冲突检测
+├── types/
+│   └── env.d.ts                     # .vue / .scss 模块声明
+├── tsdown.config.ts                 # 构建配置（多入口 + SCSS 插件 + Vue 插件）
+└── tsconfig.json
+```
+
+### 添加新组件
+
+1. 创建 `src/components/C_NewComponent/` 目录
+2. 编写 `index.vue`、`index.ts`（barrel）、`types.ts`
+3. 在 `src/index.ts` 中添加 `export * from './components/C_NewComponent'`
+4. 在 `src/index.ts` 中导入组件并加入 `components` 注册数组
+5. 在 `src/resolver.ts` 的 `componentNames` 中登记名称
+6. 运行 `bun run verify`—构建脚本会自动生成子路径入口和 exports 映射
+
+### 发布
+
+```bash
+bun run changeset       # 记录变更及版本级别
+bun run version         # 更新版本号与 CHANGELOG
+bun run verify          # 发布前完整验证
+bun run release         # 发布 Changesets 中待发布版本
+```
+
+变更日志使用 Changesets 官方本地生成器，根据 Changeset 与 Git 提交生成，无需额外 `GITHUB_TOKEN`。npm 发布仍需要有效的发布账号认证，凭据不得写入仓库。Windows 下如果 `bun run release` 在 npm 的 `prepublishOnly` 重复验证阶段停滞，可先单独确认 `bun run verify` 成功，再在 PowerShell 中用 `$env:npm_config_ignore_scripts='true'; bun run release` 发布；该设置仅跳过已手动完成的重复生命周期验证，不应省略前一步。
+
+## 文档资源
+
+品牌源文件与 PNG 导出位于 [`assets/`](./assets/)，配色、Logo 使用及导出方式见[资源说明](./assets/README.md)。
+
+## 架构边界
+
+依赖方向、应用所有权与后续 Element Plus 适配要求见[架构与隔离](./architecture.md)。

package/docs/guides/notification-center.md

@@ -0,0 +1,95 @@
+# 通知中心：演示、远程接口与共享数据源
+
+`C_NotificationCenter` 提供顶部入口、分类列表、详情与消息操作。业务路由、用户/公司身份、待办办理和后端投递由应用负责；组件不读取业务 Store，不绑定具体后台。
+
+## 保留开箱演示
+
+```vue
+<C_NotificationCenter
+  data-mode="demo"
+  storage-key="my-app:notifications:demo"
+/>
+```
+
+未指定 `dataMode` 时，配置 `fetchNotifications` 会进入远程模式，否则保持演示兼容行为。显式 `demo` 使用内置消息，已读、删除、清空即时持久化到自己的 storage key；刷新和重挂不会恢复已经清空的消息。需要重置演示时由应用删除该 key，其他应用存储不会被修改。
+
+演示模式不调用远程适配器，不启动远程轮询。消息推送配置仍需显式提供，组件不会连接任何演示服务器。
+
+## 对接远程查询与命令
+
+```vue
+<C_NotificationCenter
+  data-mode="remote"
+  :fetch-notifications="fetchInbox"
+  :mark-as-read="markRead"
+  :mark-all-read="markAllRead"
+  :delete-notification="deleteInboxItems"
+  :clear-notifications="clearInbox"
+  :on-error="reportNotificationError"
+  @view-all="router.push('/message-center')"
+/>
+```
+
+`fetchInbox({ category, page, pageSize })` 返回：
+
+```ts
+{
+  list: NotificationMessage[],
+  total: number,        // 当前查询条件的总条数
+  unreadCount: number,  // 全局未读总数，不是当前页或当前分类的数量
+  unreadByCategory?: { system?: number, business?: number, alarm?: number }
+}
+```
+
+分类统计未返回时保持未知，UI 隐藏对应数字，不能用当前页推算完整统计。分页合并按消息 ID 去重，并更新服务端返回的同 ID 记录。分页失败保留已加载数据和当前页，重试继续失败的目标页。
+
+远程模式缺少查询或操作适配器会显示错误并拒绝该操作，绝不会回退到演示数据或伪装成功。异步命令必须在对应适配器内返回 Promise；`read`、`delete`、`allRead` 仅通知正常点击命令的成功完成。错误区的“重试”会重放最近失败的命令；重试不会补发原点击的成功事件，业务状态应以共享数据源或服务端结果为准。
+
+读、删命令使用操作日志叠加状态。旧请求失败只撤销自己的影响，不会覆盖后续成功操作，也不会用旧整表快照抹掉刷新或实时新增的消息。批量已读和清空需要后端定义作用范围、截止时间与权限；涉及跨页或复杂业务筛选时，建议使用下方应用控制器协调接口与服务端统计对账。
+
+没有服务端快照版本或事件游标时，前端无法判断一次统计响应是否已包含仍在途中的批量命令。应用适配器应发送明确截止时间/版本，成功后重新查询权威统计；查询和推送也应采用同一服务端版本规则。组件的操作日志用于避免本地请求回滚互相覆盖，不代表对服务器全量状态的交付或一致性保证。跨页已知记录索引仅额外保留最近 256 条，当前可见记录与进行中操作记录按需保留。
+
+## 顶部与完整消息中心共用应用状态
+
+`controller?: NotificationCenterController` 是可选的公开协议，所有状态为 Ref 或 computed Ref。传入后，组件不再创建内部 core，不额外请求、轮询或建连，也不会在卸载时销毁应用数据源。
+
+```ts
+import { useNotificationCore } from '@robot-admin/naive-ui-components'
+
+// 在应用拥有的 setup/effectScope 中创建；Store 的身份隔离和退出清理由应用管理。
+const controller = useNotificationCore({
+  dataMode: 'remote',
+  fetchNotifications: fetchInbox,
+  markAsRead: markRead,
+  pollingInterval: 60_000,
+})
+```
+
+```vue
+<C_NotificationCenter :controller="controller" @view-all="openMessageCenter" />
+```
+
+自定义应用 Store 也可以直接实现该接口。列表、统计和操作可投影共享 Store；`activeCategory`、`selectedMessage`、`popoverVisible` 可在顶部桥接对象中独立保存，避免完整页面的筛选改变顶部列表。请传递保留 Ref 的普通对象，避免用会自动解包 Ref 的深层 reactive 对象包裹整个控制器。
+
+控制器包含 `error`、`busy`、`pendingIds`、`clearError()`，以及可选 `retry()`。若自定义控制器未提供 retry，错误区重试会刷新列表。独立 `useNotificationCore` 另外返回 `initialize()`/`dispose()`；需要手动初始化时设 `autoStart: false`。Vue 组件挂载后自动初始化，普通 effectScope 内会立即初始化，作用域停止会清理资源。切换 dataMode/storageKey 会清理旧作用域数据并重新初始化；远程用户/公司切换仍应由应用替换控制器或销毁旧作用域，并按身份取消请求。
+
+## WebSocket 的可选增强
+
+支持：
+
+- `new_message`：完整 NotificationMessage；按 ID 去重，校验消息结构。
+- `read_sync`：完整消息数组；同步其中消息 ID 的已读状态。
+- `count_update`：`{ unreadCount, unreadByCategory? }`；校准权威未读统计，不重复扣减之前已发出的乐观命令。
+
+自动重连使用有上限的退避，旧 socket 的迟到事件会被忽略。再次连接成功后远程 core 重新查询列表和统计。可选 `heartbeatTimeout` 启用 pong 超时检测；默认 0 保持既有仅发送心跳的兼容行为。
+
+```ts
+const wsConfig = {
+  url: 'wss://your-service.example/notifications',
+  heartbeatInterval: 30_000,
+  heartbeatTimeout: 10_000,
+  getToken: () => currentAccessToken(),
+}
+```
+
+桌面通知权限仅在应用调用 `requestDesktopPermission()` 的用户手势中申请。连接、轮询和缓存都不代表服务端保证交付：事件游标、历史补偿、跨设备一致性、幂等写入、审计与投递重试需要后端协议支持。应用也应在恢复可见、重新登录或切换公司时补刷，并对消息业务目标重新校验权限。