diff --git a/code/fms/FMS元数据驱动架构重构方案.md b/code/fms/FMS元数据驱动架构重构方案.md
index e5fbb627..a4d1f46e 100644
--- a/code/fms/FMS元数据驱动架构重构方案.md
+++ b/code/fms/FMS元数据驱动架构重构方案.md
@@ -7,17 +7,17 @@
 
 ## 1. 结论摘要
 
-本次重构保留并强化**元数据驱动**这一核心概念。模块定义、字段语义、关系、页面视图和通用行为仍由元数据描述，通用运行时读取已发布的元数据运行。
+本次重构保留并强化**元数据驱动**这一核心概念。模块定义、字段语义、关系、页面视图和通用行为由元数据描述，通用运行时读取已发布的元数据运行；列表、查询、保存、权限、关系、工作流和公式等能力统一通过通用接口执行，复杂逻辑由 SQL、函数库和业务处理器补充。
 
 项目属于草稿 / Demo 阶段，不要求兼容现有元数据表结构和配置 JSON。可以重做元数据数据库，并整体替换配置和运行时主链路；不需要新旧格式长期双写或并行维护。
 
 ```text
 物理数据源与表结构 → 模块元数据 → 模板 / 默认值 → 校验 / 编译 / 发布
                                                     ↓
-                                     统一模块运行时 → SQL 业务表 / 视图
+                       统一模块运行时 + 通用代码协议 → SQL 业务表 / 视图
 ```
 
-SQL Server 中的真实业务表和视图继续作为业务数据事实来源。元数据描述如何理解、呈现和操作这些数据；不采用 EAV 存储所有业务记录，也不让元数据引擎任意生成业务表。
+SQL Server 中的真实业务表和视图继续作为业务数据事实来源。元数据描述如何理解、呈现和操作这些数据，通用 SQL、函数库和业务处理器协议可以补充复杂逻辑；不采用 EAV 存储所有业务记录，也不让元数据引擎任意生成业务表。
 
 ## 2. 重构目标与边界
 
@@ -27,9 +27,10 @@ SQL Server 中的真实业务表和视图继续作为业务数据事实来源。
 - 默认配置可推导、可重复生成；用户明确调整过的配置不被覆盖。
 - 元数据发布前经过统一校验，运行时消费同一份有效定义。
 - 元数据数据库可以整体重做，不受 `s_module`、`s_field`、`s_module_schema` 现有结构约束。
-- 复杂查询和业务动作保留 SQL / 后端扩展出口，不强迫所有逻辑都配置化。
+- 列表、查询、保存、权限、关系、工作流和公式均提供元数据默认实现，并保留统一 SQL / 函数库 / 业务处理器协议。
+- 后端通过通用接口绑定 SQL、函数和处理器，不为具体模块增加特殊 API，也不在元数据中保存可执行代码。
 - 不将所有字段值改为 EAV 或通用 JSON；业务表仍通过 SQL migration / 数据库变更管理。
-- 不建设可执行任意脚本的规则引擎，不把库存、财务、结算等复杂事务塞进配置。
+- 不建设可执行任意脚本的规则引擎，不把库存、财务、结算等复杂事务强行塞进配置；复杂逻辑通过受控的代码扩展实现。
 - 不为本次目标无差别重写认证、文件、导出等稳定模块，只调整必要集成点。
 - 不要求兼容旧元数据格式；需要保留的 Demo 数据可一次性导入，否则重建 / 播种。
 
@@ -48,7 +49,7 @@ SQL Server 中的真实业务表和视图继续作为业务数据事实来源。
                          ↓
              SQL Server 表、视图与只读查询 SQL
                          ↓
-            注册的后端业务动作及工作流扩展
+            统一模块接口、SQL、函数库及业务处理器
 ```
 
 ### 配置面
@@ -57,11 +58,31 @@ SQL Server 中的真实业务表和视图继续作为业务数据事实来源。
 
 ### 元数据编译与校验
 
-后端维护权威校验与解析逻辑。发布时将模块定义、模板默认值和用户覆盖项合成为有效定义，并检查字段引用、数据源、视图、关系、查询条件和动作引用。前端预览使用后端返回的有效定义，避免前后端分别推导默认规则。
+后端维护权威校验与解析逻辑。发布时将模块定义、模板默认值和用户覆盖项合成为有效定义，并检查字段引用、数据源、视图、关系和查询条件。前端预览使用后端返回的有效定义，避免前后端分别推导默认规则。
 
 ### 运行面
 
-通用运行时负责适合通用化的列表、过滤、排序、分页、字段呈现、标准保存和权限约束。查询值参数化；自定义查询入口仅用于只读查询。多表事务、库存过账、财务结算等动作由后端注册的业务处理器执行。元数据声明动作入口和参数契约，不保存可执行代码。
+后端只提供统一的模块接口。统一接口读取已发布的 `ModuleDefinition`，负责列表、查询、保存、权限、关系、工作流和公式等通用能力；查询值参数化，保存和动作在统一事务上下文中执行。SQL、公式函数和业务代码作为通用接口内部的实现来源，不为每个模块新增专用 API。
+
+### 通用接口与代码控制
+
+每项能力都遵循同一套调用方式：
+
+1. 元数据提供模块、字段、视图、关系和默认规则。
+2. 通用接口根据模块定义执行默认列表、查询、保存、权限、关系、工作流和公式逻辑。
+3. 需要代码控制时，在通用接口内部调用统一的 SQL、函数或业务处理器协议；调用方式不随模块变化。
+
+| 能力 | 元数据默认职责 | 代码扩展或接管职责 |
+|---|---|---|
+| 列表 | 数据源、字段、过滤、排序、分页和列展示 | 自定义查询、聚合、行转换和复杂数据范围 |
+| 查询 | 条件字段、操作符、条件组和参数定义 | 特殊条件解析、跨表查询和只读 SQL |
+| 保存 | 标准增删改、字段校验、主键和关系处理 | 事务编排、状态流转、库存扣减和保存前后钩子 |
+| 权限 | 模块、字段、角色和数据范围声明 | 上下文权限判断、动态授权和特殊拒绝规则 |
+| 关系 | 主从、引用、多对多和加载规则 | 复杂关联加载、级联校验和同步逻辑 |
+| 工作流 | 节点、连线、参与者和状态定义 | 审批条件、业务动作、会签规则和外部调用 |
+| 公式 | 表达式、字段依赖和受限通用函数 | 通用函数库、复杂计算、跨单据取数和异步计算 |
+
+代码实现通过后端统一注册表或 SQL 目录管理，不在数据库中保存 Java 类名、脚本或任意可执行内容。通用权限约束不能被业务代码绕过；业务代码可以补充通用接口的规则。模块只声明需要的标准能力和参数，不声明专用接口。
 
 ## 4. 元数据逻辑模型
 
@@ -69,7 +90,7 @@ SQL Server 中的真实业务表和视图继续作为业务数据事实来源。
 
 ### 模块
 
-包含稳定编码、名称、多语言键、类型、状态、组织层级、查询数据源、标准保存目标 / 主键、字段、关系、视图、动作引用、模板和发布版本。模块类型收敛为少数明确类别，如标准数据、只读查询、业务动作模块。
+包含稳定编码、名称、多语言键、类型、状态、组织层级、查询数据源、标准保存目标 / 主键、数据范围字段、字段、关系、视图、模板和发布版本。模块类型收敛为少数明确类别，如标准数据、只读查询、业务动作模块。
 
 ### 字段
 
@@ -87,7 +108,7 @@ SQL Server 中的真实业务表和视图继续作为业务数据事实来源。
 - 表单、列表、查询、详情是不同视图类型，只保存顺序、分组、布局、列宽、排序、操作符等视图特有信息；布局采用可读、可校验的结构化定义，不保存画布坐标。
 - 字段参与视图的默认状态由字段能力、模板和默认策略推导；个性化差异作为显式覆盖。
 - 简单校验和通用 CRUD 可由元数据表达；复杂业务动作映射到稳定的后端处理器编码。
-- 工作流、权限、公式等能力通过稳定引用接入，不重复定义模块字段。
+- 列表、查询、保存、权限、关系、工作流和公式通过统一模块接口接入；这些能力引用模块定义和已发布快照，不为每个模块建立特殊接口。
 
 ## 5. 元数据数据库重构
 
@@ -95,31 +116,226 @@ SQL Server 中的真实业务表和视图继续作为业务数据事实来源。
 
 | 逻辑实体 | 职责 | 建议存储 |
 |---|---|---|
-| 模块 | 身份、类型、数据源、状态、组织关系 | 规范化关系表 |
+| 模块 | 身份、类型、状态、树结构、数据源和通用运行参数 | 规范化关系表 |
 | 模块字段 | 字段编码、物理映射、业务语义、能力标记 | 规范化关系表；模块内编码唯一 |
 | 模块关系 | 关系类型及源 / 目标字段 | 规范化关系表；发布时校验引用 |
-| 模块视图 | 表单、列表、查询、详情定义 | 按模块和视图类型区分；灵活布局可用 JSON |
+| 模块视图 | 表单、列表、查询、详情及布局 | `s_module_schema`，按视图类型保存受校验 JSON |
 | 模板 | 默认字段能力、视图结构、推荐规则 | 可版本化定义 |
 | 发布版本 | 不可变快照、版本号、校验结果、发布时间 | 版本记录；运行时按已发布版本读取 |
-| 动作注册 | 动作编码与后端处理器参数契约 | 只存稳定编码和契约，不存可执行代码 |
+
+### 推荐目标表结构
+
+建议继续使用现有的 `s_` 前缀和核心表。后端是通用接口，因此不再为数据源、视图和代码扩展分别增加运行时表：模块数据源保留在 `s_module`，视图 JSON 保留在 `s_module_schema`，复杂代码由后端统一实现和注册。只新增发布版本和快照表解决草稿与运行态隔离。
+
+| 目标实体 | 关键字段 / 组成 | 说明 |
+|---|---|---|
+| 模块 `s_module` | 模块编码、父级、名称、多语言键、模块类型、查询/保存来源、主键、数据范围和默认排序 | 保留当前模块主表，清理无约束的大 JSON；数据源由通用接口读取 |
+| 模块字段 `s_field` | 模块、字段编码、来源类型、来源名称/别名、名称、多语言键、语义类型、字段能力、启用状态 | 支持物理列、查询别名、计算字段和虚拟字段；物理 SQL 类型仍优先从数据库读取 |
+| 模块视图 `s_module_schema` | 模块、视图类型、结构版本、`b_schema_json` | JSON 保存分组、字段引用、列属性、查询条件、控件和公式；发布时统一校验 |
+| 模块关系 `s_relation` | 关系编码、源/目标模块字段、关系类型、用途、基数、加载规则、删除策略 | 发布时校验模块和字段引用，保留现有删除语义 |
+| 模块版本 `s_module_version` | 模块、版本号、草稿/已发布/废弃状态、校验摘要、发布人、发布时间 | 管理草稿与当前有效版本边界 |
+| 发布快照 `s_module_snapshot` | 版本、编译后的 `ModuleDefinition`、快照摘要、生成时间 | 运行时只读取不可变快照，不直接读取编辑态表 |
+| 模板及模板版本 `s_template` / `s_template_version` | 模板编码、版本、默认字段能力、视图 JSON、推荐规则 | 模板是可编辑初始值，不是硬编码页面 |
+| 用户偏好 `s_user_module_pref` | 用户、模块、视图、相对默认值的覆盖 | 可选保留，只能改变布局偏好，不能改变语义、权限或数据源 |
+
+`s_module_schema.b_schema_json` 不是无约束 JSON：必须包含 `schemaVersion`，只能引用本模块已登记的字段和关系，并由后端 JSON Schema 和发布校验共同约束。编辑态以 `s_module_schema` 为事实来源，发布后编译成 `s_module_snapshot`。
+
+### 推荐 DDL（示例）
+
+```sql
+create table dbo.s_module (
+    b_id varchar(80) not null primary key,
+    b_parent_id varchar(80) null,
+    b_depth int not null default 0,
+    b_path varchar(1500) not null,
+    b_name nvarchar(200) not null,
+    b_i18n varchar(150) null,
+    b_module_type varchar(20) not null, -- module / data / virtual
+    b_view_table varchar(256) null,
+    b_save_table varchar(256) null,
+    b_key_field varchar(80) null,
+    b_scope_field varchar(80) null,
+    b_order_sql varchar(500) null,
+    b_query_sql nvarchar(max) null,
+    b_config_json nvarchar(max) null,
+    b_canuse tinyint not null default 1,
+    b_xh int not null default 0,
+    b_bz nvarchar(2000) null,
+    b_updated_by varchar(50) null,
+    b_updated_at datetime2 null
+);
+
+create table dbo.s_field (
+    b_module_id varchar(80) not null,
+    b_field varchar(80) not null,
+    b_source_type varchar(20) not null, -- physical / alias / computed / virtual
+    b_source_name varchar(256) null,
+    b_name nvarchar(200) not null,
+    b_i18n varchar(150) null,
+    b_semantic_type varchar(40) not null,
+    b_can_read tinyint not null default 1,
+    b_can_edit tinyint not null default 0,
+    b_can_filter tinyint not null default 0,
+    b_can_sort tinyint not null default 0,
+    b_can_export tinyint not null default 0,
+    b_canuse tinyint not null default 1,
+    b_xh int not null default 0,
+    primary key (b_module_id, b_field)
+);
+
+create table dbo.s_module_schema (
+    b_module_id varchar(80) not null,
+    b_schema_type varchar(20) not null,  -- view / edit / query / detail
+    b_schema_version int not null default 1,
+    b_schema_json nvarchar(max) not null,
+    b_canuse tinyint not null default 1,
+    b_updated_by varchar(50) null,
+    b_updated_at datetime2 null,
+    primary key (b_module_id, b_schema_type)
+);
+
+create table dbo.s_relation (
+    b_relation_code varchar(100) not null primary key,
+    b_source_module_id varchar(80) not null,
+    b_source_field varchar(80) not null,
+    b_target_module_id varchar(80) not null,
+    b_target_field varchar(80) not null,
+    b_relation_type varchar(30) not null, -- one_to_one / one_to_many / many_to_one
+    b_usage varchar(30) not null,         -- reference / detail / selector / load
+    b_load_mode varchar(20) not null default 'lazy',
+    b_on_delete varchar(20) not null default 'restrict',
+    b_canuse tinyint not null default 1,
+    b_xh int not null default 0
+);
+
+create table dbo.s_module_version (
+    b_id varchar(100) not null primary key,
+    b_module_id varchar(80) not null,
+    b_version_no int not null,
+    b_status varchar(20) not null, -- draft / published / retired
+    b_checksum varchar(128) null,
+    b_published_by varchar(50) null,
+    b_published_at datetime2 null,
+    b_created_by varchar(50) null,
+    b_created_at datetime2 not null default sysdatetime(),
+    unique (b_module_id, b_version_no)
+);
+
+create table dbo.s_module_snapshot (
+    b_version_id varchar(100) not null primary key,
+    b_module_id varchar(80) not null,
+    b_snapshot_json nvarchar(max) not null,
+    b_checksum varchar(128) not null,
+    b_created_at datetime2 not null default sysdatetime()
+);
+
+create table dbo.s_user_module_pref (
+    b_user_id varchar(50) not null,
+    b_module_id varchar(80) not null,
+    b_schema_type varchar(50) not null,
+    b_preference_json nvarchar(max) not null,
+    b_updated_at datetime2 null,
+    primary key (b_user_id, b_module_id, b_schema_type)
+);
+```
+
+模板表沿用相同原则：`s_template` 保存模板身份，`s_template_version` 保存版本、默认字段能力和视图 JSON；模板应用只是生成模块草稿，不直接成为运行时配置。
+
+```sql
+create table dbo.s_template (
+    b_id varchar(80) not null primary key,
+    b_name nvarchar(200) not null,
+    b_template_type varchar(30) not null, -- master_data / document / detail / readonly
+    b_canuse tinyint not null default 1
+);
+
+create table dbo.s_template_version (
+    b_id varchar(100) not null primary key,
+    b_template_id varchar(80) not null,
+    b_version_no int not null,
+    b_default_fields_json nvarchar(max) not null,
+    b_views_json nvarchar(max) not null,
+    b_extensions_json nvarchar(max) null,
+    b_status varchar(20) not null, -- draft / published / retired
+    b_created_at datetime2 not null default sysdatetime(),
+    unique (b_template_id, b_version_no)
+);
+```
+
+推荐补充以下约束和发布检查：
+
+- `s_field.b_module_id`、`s_module_schema.b_module_id`、`s_module_version.b_module_id` 必须引用存在的模块；模块树字段由业务层校验不能成环。
+- `s_module` 的数据源字段由模块类型和通用接口校验组合有效性；查询 SQL 只允许用于受控的只读查询，排序字段必须来自字段定义。
+- `s_module_schema.b_schema_json`、`s_module.b_config_json` 和模板 JSON 使用 `ISJSON` 做基础检查，并由后端 JSON Schema 检查 `schemaVersion`、字段引用和关系引用。
+- `s_module_snapshot`、已发布的 `s_module_version` 和已发布模板版本不可原地修改；回滚通过切换当前有效版本完成。
+- 动态业务表不因为元数据引用而强制建立数据库外键；元数据内部引用使用外键或等效约束，跨 JSON 引用由发布校验保证。
+
+### Demo 数据示例
+
+以下示例定义一个客户资料模块，业务事实表为 `b_othercompany`，只读查询视图为 `v_b_othercompany`：
+
+```text
+s_module
+  base.customer       → 基础资料 / 客户资料 / data / v_b_othercompany / b_othercompany / b_id
+
+s_field
+  base.customer.b_ywid       → physical / b_ywid / 客户编码 / code / read+edit+filter+sort
+  base.customer.b_name       → physical / b_name / 客户名称 / text / read+edit+filter+sort
+  base.customer.b_owner_id   → physical / b_owner_id / 业务员 / user_reference / read+edit+filter
+
+s_module_schema
+  base.customer / list       → schema JSON：列、宽度、排序
+  base.customer / form       → schema JSON：分组、控件、必填、公式
+  base.customer / query      → schema JSON：条件字段、组件、操作符
+```
+
+列表 JSON 示例：
+
+```json
+{
+  "schemaVersion": 1,
+  "columns": [
+    { "field": "b_ywid", "visible": true, "width": 140, "sortable": true },
+    { "field": "b_name", "visible": true, "width": 220, "sortable": true },
+    { "field": "b_owner_id", "visible": true, "width": 120 }
+  ],
+  "defaultSort": [{ "field": "b_name", "direction": "asc" }]
+}
+```
+
+### 现有表到目标表的改造映射
+
+- `s_module.b_view_table`、`b_query_sql`、`b_save_table`、`b_key_field`、`b_scope_field`、`b_order_sql` 继续由 `s_module` 保存；删除或收紧无约束的 `b_config_json` 内容。
+- `s_field` 保留模块字段身份，并补充来源映射、语义类型和能力标记；列表、表单、查询的顺序和显示属性保留在对应 `s_module_schema.b_schema_json` 中。
+- `s_module_schema.view/edit/query` 保留为视图配置的主要存储格式，增加 `b_schema_version` 和后端 JSON Schema 校验。
+- `s_relation` 保留已有源/目标字段和删除策略，增加稳定关系编码、用途、加载规则等字段；历史关系先一次性导入，再由发布校验补足引用检查。
+- 现有模块配置可通过一次性导入工具转换；不在新旧表之间长期双写，也不让旧表继续作为第二事实来源。
+
+### 不需要整体重做的表
+
+- 真实业务表和业务视图继续由 SQL migration 管理，不因为元数据重构而改成 EAV 或通用 JSON。
+- `wf_definition`、`wf_version`、`wf_binding` 及工作流运行表可继续使用；`wf_binding` 需要改为引用模块的已发布版本或在发布时校验模块版本。
+- 现有权限主体和授权表可以保留；权限运行时通过通用接口读取已发布字段和模块定义。
+- 公式不要求新增业务数据表；简单公式随模块快照发布，复杂函数由通用公式接口调用后端函数库。
 
 ### 对现有核心表的评估
 
 **结论：需要重构元数据配置表，但不需要仅因配置器难用而整体重做所有业务数据表。** 当前表结构能表达基本模块、字段和关系；主要问题是职责混放、字段能力分散到视图 JSON，以及缺少可发布的版本边界。
 
-- **`s_module`**：当前模块身份 / 树结构与查询表、保存表、主键、数据范围字段、默认排序 SQL、查询 SQL 和扩展 JSON 放在同一表。建议将模块身份与数据源 / 查询定义分开建模；移除缺少强约束的通用 `b_config_json`，把常用配置变为有类型的字段或关联实体。模块树优先只保留权威父级和同级顺序；`depth/path` 仅在查询性能有证据需要时保留为派生索引。模块草稿 / 发布时间应由版本模型管理，不靠一个模块级更新时间代表所有子配置状态。
+- **`s_module`**：继续保存模块身份、树结构和默认数据源，因为后端统一通过模块接口读取这些定义；`b_config_json` 只保留少量经过 schema 校验的低频配置，模块草稿 / 发布时间由版本模型管理。
 - **`s_field`**：当前主要保存名称、业务类型、启用和顺序，尚未明确区分物理列、查询别名、计算 / 虚拟字段。建议增加明确的字段来源种类与来源映射、语义类型和模块级能力；数据库物理类型由 SQL Server 结构检查获得。表单 / 列表 / 查询中的显示顺序和控件差异放到对应视图字段配置，不塞回字段主定义。
-- **`s_module_schema`**：当前每模块按 `view/edit/query` 保存整份 `nvarchar(max)` JSON，便于早期迭代，但字段参与、字段语义和复杂布局容易混在一起。既然不采用拖拽画布，建议将它替换为视图定义 + 结构化的视图字段 / 分组配置；常用属性使用有类型的列，只有少量确实灵活的扩展留在受校验 JSON。表单不保存行列像素坐标，列表不把所有列属性藏在任意 JSON 节点中。
+- **`s_module_schema`**：继续按 `view/edit/query` 保存视图 JSON，增加结构版本和发布校验；不新增 `s_module_view`、`s_module_view_group` 或 `s_module_view_field`。
 - **`s_relation`**：保留关系作为独立元数据，但建议引入稳定关系编码 / 标识，显式描述关系用途、基数、展示 / 加载规则，并对模块和字段引用建立数据库约束。现有删除策略等已表达的业务含义应迁移保留，不因改表而丢失。
 - **`s_user_module_pref`**：如保留个性化配置，只允许保存列表列、查询布局等用户偏好覆盖，不得改变模块字段语义、数据源、权限或保存行为。若 Demo 暂无真实个性化需求，可先不纳入新核心模型。
-- **新增发布版本实体**：保存草稿与已发布版本的边界、版本号、校验摘要和不可变运行快照；发布失败不替换当前有效版本。
+- **新增发布版本实体**：使用 `s_module_version` 保存草稿与已发布版本的边界，使用 `s_module_snapshot` 保存不可变运行快照；发布失败不替换当前有效版本。
+- **代码扩展**：不新增模块扩展绑定表；后端统一接口通过 SQL 目录、公式函数库和通用业务处理器协议调用代码实现，模块只使用通用参数和元数据配置。
 
 元数据表之间应使用主键、唯一约束和可表达的外键保障内部引用完整性，并用发布校验补足跨 JSON / 动态数据源的检查。不要为了引用元数据而给所有动态业务表强行建立数据库外键。
 
 ### 规范化与 JSON 边界
 
 - 模块、字段、关系、版本等有稳定身份、查询和引用的对象采用关系表。
-- 表单布局、列表列布局、查询 UI 等灵活结构可存 JSON，但其中只能引用已定义字段和动作。
+- 表单布局、列表列布局、查询 UI、公式和少量扩展属性继续存 JSON，但其中只能引用已定义字段和关系；JSON 必须带 `schemaVersion` 并通过结构校验。
 - 发布快照可采用 JSON 作为编译产物，不作为编辑态唯一事实来源。
 - 对模块编码、模块内字段编码、模块 / 视图类型、版本号等建立唯一约束；可表达的元数据引用建立外键或等效约束，并由发布校验再次检查。
 - 明确删除、改名和关系变更策略，不依赖前端操作顺序保证一致性。
@@ -150,7 +366,7 @@ SQL Server 中的真实业务表和视图继续作为业务数据事实来源。
 - **列表**：采用列配置表 / 字段矩阵，集中设置是否显示、顺序、宽度、格式、对齐、排序和汇总等属性；支持批量添加、移除和套用模板。
 - **预览**：配置面板旁提供实时预览，但预览仅用于检查结果，不作为拖放编辑画布。
 - **元数据**：保存语义结构和字段引用，不保存像素坐标、拖拽路径或依赖编辑器内部实现的状态。
-- **高级场景**：通过分组、布局模板、字段显示规则及明确的扩展配置解决；不以重新引入自由拖拽作为兜底。
+- **高级场景**：通过分组、布局模板、字段显示规则及通用接口配置解决；不以重新引入自由拖拽作为兜底。
 
 默认规则：
 
@@ -175,13 +391,13 @@ SQL Server 中的真实业务表和视图继续作为业务数据事实来源。
 
 不做新旧格式长期并行或渐进兼容；按依赖顺序拆分实施任务，便于验证：
 
-1. **确定元数据契约**：模块类型、字段语义、关系、视图、默认覆盖、发布和动作扩展模型。
-2. **重建元数据数据库**：新表、约束、种子 / migration；决定 Demo 配置重建还是一次性导入。
-3. **实现后端目录与编译器**：读取、校验、默认合成、发布、版本切换、缓存失效和回滚。
+1. **确定元数据契约**：模块类型、字段语义、关系、视图、默认覆盖、发布和通用接口契约。
+2. **重建元数据数据库**：调整模块、字段、视图 JSON 和关系表，新增版本与快照表，补充主键 / 唯一约束 / 引用约束；决定 Demo 配置重建还是一次性导入。
+3. **实现后端目录与编译器**：读取物理结构、校验字段和视图 JSON、默认合成、生成快照、发布、版本切换、缓存失效和回滚。
 4. **替换配置工作台**：数据源检查、字段导入、模板初始化、能力矩阵、预览、发布。
 5. **替换运行时消费链路**：列表、查询、表单、保存统一读取发布定义。
-6. **接入扩展能力**：权限、关系、公式、工作流、导出和业务动作。
-7. **删除旧路径**：完成导入或确认弃用后，删除旧 Schema 适配和重复逻辑。
+6. **接入通用能力**：在统一模块接口中接入列表、查询、保存、权限、关系、工作流和公式的标准实现，并接入统一 SQL、函数库和业务处理器协议。
+7. **删除旧路径**：完成一次性导入或确认弃用后，删除旧 `s_module_schema` JSON 结构适配和重复逻辑；保留新格式下的同一张表作为唯一视图配置来源。
 
 虽然不需要渐进兼容，仍建议用一个基础资料、一个主从单据、一个只读查询模块验证新契约，再批量建立 Demo 配置。这是新架构验收，不是要求新旧架构并行运行。
 
@@ -194,22 +410,25 @@ SQL Server 中的真实业务表和视图继续作为业务数据事实来源。
 - 默认配置可重复生成，且不覆盖显式配置。
 - 无效字段引用、数据源列缺失、关系目标错误、非法查询规则在发布时给出明确错误。
 - 运行时只消费已发布版本；发布失败不影响当前可用版本。
+- 编辑态使用模块、字段、视图 JSON 和关系表；运行态使用对应的不可变发布快照。
+- 列表、查询、保存、权限、关系、工作流和公式均可使用元数据默认实现，并可通过统一 SQL、函数库和业务处理器协议补充复杂逻辑。
+- 统一接口的参数、字段引用和依赖关系在发布时校验；接口执行失败有明确错误和审计信息。
 - 简单 CRUD 使用通用运行时；复杂业务动作由明确的后端处理器完成。
 - 真实 SQL Server 业务表仍是业务数据事实来源，不引入 EAV 业务数据主存储。
 - 旧元数据路径已删除或仅作为一次性导入工具，不存在双重事实来源。
 
 ## 10. 需要同步修订的文档
 
-目前架构文档存在方向冲突：部分草案提出以业务域代码包取代元数据运行时，开发规范与现有系统仍要求模块 / 字段 / 界面元数据驱动通用模块。本方案评审通过后应统一修订：
+目前架构文档存在方向冲突：部分草案提出以业务域代码包取代元数据运行时，而本方案采用元数据主导、通用接口承载复杂逻辑的模式。本方案评审通过后应统一修订：
 
-- `FMS新系统核心架构设计.md`：明确元数据驱动是通用模块核心，SQL / 后端动作是扩展机制。
-- `FMS新系统核心架构实施计划.md`：改为元数据数据库、编译器、工作台和运行时重构任务。
+- `FMS新系统核心架构设计.md`：明确元数据运行时是通用能力核心，业务域代码通过统一模块接口、SQL 和业务处理器协议接入复杂逻辑。
+- `FMS新系统核心架构实施计划.md`：增加元数据数据库、编译器、工作台、运行时和通用接口实现任务。
 - `FMS新系统核心表结构设计.md`：重新定义元数据表，不再将现有 `s_module`、`s_field`、`s_module_schema` 作为不可变前提。
-- `开发规范.md`：明确元数据契约、发布定义、查询 / 保存边界和动作扩展约定。
+- `开发规范.md`：明确元数据契约、发布定义、查询 / 保存边界和通用接口约定。
 
 ## 11. 假设与待定项
 
 - 暂保留 SQL Server 作为数据库目标；允许重做元数据表，不主动改变租户数据库路由模式。
 - 元数据和 Demo 配置可重建；是否保留样例数据，实施前决定重建或一次性导入。
 - 本文确定架构方向，不冻结最终 DDL、API、类名或 Vue 目录；这些在元数据契约评审后设计。
-- 权限、工作流、公式、多语言是否随模块发布版本整体冻结，需结合实际使用方式决定，避免第一版过度设计。
+- 需要确定权限、工作流、公式、多语言及通用接口实现是否随模块发布版本整体冻结，并定义接口版本兼容、事务边界、错误模型和规则优先级。
diff --git a/code/g3soft-erp/web/.bc-bg.png b/code/g3soft-erp/web/.bc-bg.png
new file mode 100644
index 00000000..30329dd2
Binary files /dev/null and b/code/g3soft-erp/web/.bc-bg.png differ
diff --git a/code/g3soft-erp/web/.bc-normal.png b/code/g3soft-erp/web/.bc-normal.png
new file mode 100644
index 00000000..4109fc46
Binary files /dev/null and b/code/g3soft-erp/web/.bc-normal.png differ
diff --git a/code/g3soft-erp/web/.bc.png b/code/g3soft-erp/web/.bc.png
new file mode 100644
index 00000000..e5d8a681
Binary files /dev/null and b/code/g3soft-erp/web/.bc.png differ
diff --git a/code/g3soft-erp/web/.bc2.png b/code/g3soft-erp/web/.bc2.png
new file mode 100644
index 00000000..c462225d
Binary files /dev/null and b/code/g3soft-erp/web/.bc2.png differ
diff --git a/code/g3soft-erp/web/.h-bg.png b/code/g3soft-erp/web/.h-bg.png
new file mode 100644
index 00000000..e7e3d234
Binary files /dev/null and b/code/g3soft-erp/web/.h-bg.png differ
diff --git a/code/g3soft-erp/web/.h-normal.png b/code/g3soft-erp/web/.h-normal.png
new file mode 100644
index 00000000..38aeec93
Binary files /dev/null and b/code/g3soft-erp/web/.h-normal.png differ
diff --git a/code/g3soft-erp/web/index.html b/code/g3soft-erp/web/index.html
index 2d944557..9aeeb0bd 100644
--- a/code/g3soft-erp/web/index.html
+++ b/code/g3soft-erp/web/index.html
@@ -4,9 +4,321 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>G3Soft ERP</title>
+    <script>
+      // 首帧前同步应用的暗色偏好，避免暗色用户先看到浅色闪屏。
+      // 偏好持久化 key = 'g3erp:preferences'（见 src/preferences/store.ts），
+      // 结构 { theme: { mode: 'light' | 'dark' | 'auto' } }。
+      // 注意：此刻全局样式还没加载，加载屏只能用字面量颜色、不能依赖 --g3-* 变量。
+      try {
+        var raw = localStorage.getItem('g3erp:preferences')
+        var mode = raw ? (JSON.parse(raw) || {}).theme.mode : null
+        var dark = mode === 'dark'
+        if (mode === 'auto' || mode === null) {
+          dark = window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches
+        }
+        if (dark) document.documentElement.classList.add('boot-dark')
+      } catch (e) {
+        /* 无持久化数据 / 解析失败时按浅色默认渲染 */
+      }
+    </script>
+    <style>
+      *,
+      *::before,
+      *::after {
+        box-sizing: border-box;
+      }
+
+      html,
+      body {
+        margin: 0;
+        padding: 0;
+        height: 100%;
+      }
+
+      /* ===== 开屏加载屏 =====
+         配色对齐本应用 token（浅色）：背景 #f5f6f8 / 文字 #1f2329 /
+         次级 #4e5969 / 三级 #86909c / 主色 #165dff / 边框 #e5e6eb；
+         深色（html.boot-dark，由上方脚本按持久化偏好写入）对齐 .dark 覆盖值。
+         品牌区版式对齐登录页 .login__logo-mark（主色圆角方块 + 白字）。 */
+      .app-boot {
+        display: flex;
+        background-color: #f5f6f8;
+        position: fixed;
+        left: 0;
+        top: 0;
+        height: 100%;
+        width: 100%;
+        z-index: 9999;
+        transition: opacity 0.3s ease-in;
+        opacity: 1;
+        pointer-events: none;
+        /* 锁定字体，避免 Vue 注入的 web 字体就绪后替换导致文字重定位抖动 */
+        font-family: system-ui, -apple-system, 'Segoe UI', Roboto, 'PingFang SC', 'Microsoft YaHei',
+          sans-serif;
+      }
+
+      .boot-dark .app-boot {
+        background-color: #17171a;
+      }
+
+      .app-boot--hide {
+        opacity: 0;
+      }
+
+      /* 加载失败态：浅红渐变背景 + 错误提示；错误时需要可交互（重试按钮可点击） */
+      .app-boot--error {
+        background: radial-gradient(circle at 50% 50%, #fef2f2 0%, #fee2e2 100%);
+        color: #b91c1c;
+        pointer-events: auto;
+      }
+
+      .boot-dark .app-boot--error {
+        background: radial-gradient(circle at 50% 50%, #2a1215 0%, #1c0e10 100%);
+        color: #f87171;
+      }
+
+      .app-boot__container {
+        display: flex;
+        flex-direction: column;
+        align-items: center;
+        justify-content: center;
+        width: 100%;
+        flex-grow: 1;
+        user-select: none;
+        -webkit-user-select: none;
+      }
+
+      /* 加载效果：字母逐个从下方弹起的文字 loader（字形 SVG + translateY 动画）。
+         原实现用 .loader / .letter / .i 这类通用类名，直接放进 index.html 会污染
+         整个应用（例如所有 class="i" 的元素），因此统一收敛到 .app-boot__loading 下。
+         字形 fill 改走 currentColor，跟随主题色。 */
+      .app-boot__loading {
+        display: flex;
+        flex-direction: row;
+        align-items: center;
+        justify-content: center;
+        /* 容器刻意比字母高：字母静止时居中，上下各留出 10px 渐隐带供出入场过渡 */
+        height: 60px;
+        overflow: hidden; /* 关键：裁掉位于容器外的字母，动画升上来才可见 */
+        color: #1f2329;
+        opacity: 0;
+        animation: app-boot-fade 0.45s ease-out 0.08s forwards;
+        /* 上下各 10px 渐隐：字母升入/降出时淡进淡出，避免被容器硬边切成
+           「从切面冒出来」的生硬边缘。字母静止区间正好落在中间的清晰区。 */
+        -webkit-mask-image: linear-gradient(
+          to bottom,
+          transparent 0,
+          #000 10px,
+          #000 calc(100% - 10px),
+          transparent 100%
+        );
+        mask-image: linear-gradient(
+          to bottom,
+          transparent 0,
+          #000 10px,
+          #000 calc(100% - 10px),
+          transparent 100%
+        );
+      }
+
+      .boot-dark .app-boot__loading {
+        color: #f7f8fa;
+      }
+
+      .app-boot__loading span {
+        display: flex;
+        transform: translateY(50px);
+        animation: app-boot-letters 1s alternate infinite cubic-bezier(0.86, 0, 0.07, 1);
+      }
+
+      .app-boot__loading svg {
+        width: auto;
+        height: 40px;
+        fill: currentColor;
+      }
+
+      /* 字母间留一点呼吸，同时窄字形 i 额外加边距，避免和 d / n 贴太近 */
+      .app-boot__loading span + span {
+        margin-left: 2px;
+      }
+
+      .app-boot__loading span:nth-child(5) {
+        margin-inline: 6px;
+      }
+
+      /* 逐个错开 70ms，形成波浪式弹起 */
+      .app-boot__loading span:nth-child(1) {
+        animation-delay: 0ms;
+      }
+
+      .app-boot__loading span:nth-child(2) {
+        animation-delay: 70ms;
+      }
+
+      .app-boot__loading span:nth-child(3) {
+        animation-delay: 140ms;
+      }
+
+      .app-boot__loading span:nth-child(4) {
+        animation-delay: 210ms;
+      }
+
+      .app-boot__loading span:nth-child(5) {
+        animation-delay: 280ms;
+      }
+
+      .app-boot__loading span:nth-child(6) {
+        animation-delay: 350ms;
+      }
+
+      .app-boot__loading span:nth-child(7) {
+        animation-delay: 420ms;
+      }
+
+      @keyframes app-boot-letters {
+        from {
+          transform: translateY(50px);
+        }
+        to {
+          transform: translateY(0);
+        }
+      }
+
+      @keyframes app-boot-fade {
+        from {
+          opacity: 0;
+        }
+        to {
+          opacity: 1;
+        }
+      }
+
+      /* 错误态：隐藏正常加载内容，展示提示与重试按钮 */
+      .app-boot--error .app-boot__loading {
+        display: none;
+      }
+
+      .app-boot__message {
+        font-size: 14px;
+        font-weight: 600;
+      }
+
+      .app-boot__retry {
+        margin-top: 16px;
+        padding: 6px 18px;
+        border: 1px solid currentColor;
+        border-radius: 8px;
+        background: transparent;
+        color: inherit;
+        font-size: 14px;
+        font-family: inherit;
+        cursor: pointer;
+        transition: background 150ms ease;
+      }
+
+      .app-boot__retry:hover {
+        background: rgba(185, 28, 28, 0.08);
+      }
+
+      .boot-dark .app-boot__retry:hover {
+        background: rgba(248, 113, 113, 0.1);
+      }
+
+      @media (prefers-reduced-motion: reduce) {
+        /* 关掉弹跳动画后，字母静止排成一行，仍可读地表示「加载中」 */
+        .app-boot__loading {
+          opacity: 1;
+          animation: none;
+        }
+
+        .app-boot__loading span {
+          transform: none;
+          animation: none;
+        }
+      }
+    </style>
   </head>
+
   <body>
-    <div id="app"></div>
+    <div id="app">
+      <script>
+        // 模块加载失败时（如直接 file:// 打开）展示错误，避免永远卡在加载屏。
+        // 忽略良性噪音错误（ResizeObserver 循环等浏览器警告也会走 error 事件），
+        // 否则 DevTools 展开/收起等触发 resize 时会把整个页面误替换成错误页。
+        window.addEventListener('error', (e) => {
+          const msg = e && e.message ? String(e.message) : ''
+          if (/ResizeObserver loop/i.test(msg)) return
+          const app = document.getElementById('app')
+          if (app) {
+            app.innerHTML =
+              '<div class="app-boot app-boot--error" style="position:fixed;inset:0;z-index:10000;display:flex;align-items:center;justify-content:center;flex-direction:column;gap:12px;pointer-events:auto;font-family:sans-serif">' +
+              '<div style="font-size:20px;font-weight:bold">加载失败</div>' +
+              '<div style="font-size:14px">请通过本地开发服务器访问（如 pnpm dev），不要直接以 file:// 方式打开本文件。</div>' +
+              (msg ? '<div style="font-size:12px;opacity:.7">' + msg + '</div>' : '') +
+              '</div>'
+          }
+        })
+      </script>
+    </div>
+
+    <div id="app-boot" class="app-boot" role="status" aria-busy="true">
+      <div class="app-boot__container">
+        <div class="app-boot__loading" aria-hidden="true">
+          <span>
+            <svg xmlns="http://www.w3.org/2000/svg" fill="currentColor" viewBox="0 0 11 18" height="18" width="11">
+              <path
+                d="M0.28 16.14V0.94L3.7 0.64L5.7 1.64V12.3L8.5 12.06L10.5 13.06V16.44L2.28 17.14L0.28 16.14ZM3.5 12.7V0.859999L0.48 1.12V15.94L8.3 15.26V12.28L3.5 12.7Z"
+              ></path>
+            </svg>
+          </span>
+          <span>
+            <svg xmlns="http://www.w3.org/2000/svg" fill="currentColor" viewBox="0 0 16 18" height="18" width="16">
+              <path
+                d="M8.94 17.24C8.84667 17.2533 8.74667 17.26 8.64 17.26C8.54667 17.26 8.45333 17.26 8.36 17.26C7.66667 17.26 7.02667 17.16 6.44 16.96C5.86667 16.7733 5.30667 16.5533 4.76 16.3C3.33333 15.5933 2.28667 14.6 1.62 13.32C0.966667 12.0267 0.64 10.4933 0.64 8.72C0.64 7.68 0.766667 6.67333 1.02 5.7C1.28667 4.71333 1.68 3.82667 2.2 3.04C2.72 2.24 3.36667 1.58667 4.14 1.08C4.92667 0.573332 5.84667 0.273333 6.9 0.18C7.00667 0.166666 7.10667 0.159999 7.2 0.159999C7.29333 0.159999 7.38667 0.159999 7.48 0.159999C8.14667 0.159999 8.74 0.246666 9.26 0.419999C9.78 0.579999 10.3067 0.766666 10.84 0.979999C11.8 1.36667 12.6 1.94 13.24 2.7C13.88 3.46 14.36 4.35333 14.68 5.38C15 6.39333 15.16 7.48 15.16 8.64C15.16 9.72 15.0333 10.7533 14.78 11.74C14.5267 12.7267 14.14 13.62 13.62 14.42C13.1133 15.2067 12.4667 15.8467 11.68 16.34C10.9067 16.8467 9.99333 17.1467 8.94 17.24ZM6.92 16.04C7.94667 15.96 8.84 15.68 9.6 15.2C10.36 14.7067 10.9867 14.0733 11.48 13.3C11.9733 12.5133 12.34 11.64 12.58 10.68C12.8333 9.70667 12.96 8.69333 12.96 7.64C12.96 6.68 12.8467 5.76667 12.62 4.9C12.4067 4.02 12.0733 3.24 11.62 2.56C11.1667 1.88 10.5933 1.34667 9.9 0.959999C9.22 0.559999 8.41333 0.359999 7.48 0.359999C7.38667 0.359999 7.29333 0.359999 7.2 0.359999C7.12 0.359999 7.02667 0.366666 6.92 0.38C5.89333 0.473333 5 0.766666 4.24 1.26C3.48 1.74 2.84667 2.37333 2.34 3.16C1.83333 3.93333 1.45333 4.8 1.2 5.76C0.96 6.70667 0.84 7.69333 0.84 8.72C0.84 9.72 0.953333 10.6667 1.18 11.56C1.40667 12.44 1.74667 13.22 2.2 13.9C2.65333 14.5667 3.22667 15.0933 3.92 15.48C4.61333 15.8667 5.42 16.06 6.34 16.06C6.44667 16.06 6.54667 16.06 6.64 16.06C6.73333 16.06 6.82667 16.0533 6.92 16.04ZM6.92 12.94C6.86667 12.94 6.81333 12.9467 6.76 12.96C6.72 12.96 6.67333 12.96 6.62 12.96C5.82 12.96 5.18667 12.6133 4.72 11.92C4.26667 11.2267 4.04 10.0667 4.04 8.44C4.04 7.28 4.16667 6.34667 4.42 5.64C4.67333 4.93333 5.02 4.41333 5.46 4.08C5.9 3.73333 6.38667 3.54 6.92 3.5C6.97333 3.5 7.02667 3.5 7.08 3.5C7.13333 3.48667 7.18667 3.48 7.24 3.48C8.02667 3.48 8.64 3.82 9.08 4.5C9.52 5.16667 9.74 6.31333 9.74 7.94C9.74 9.67333 9.47333 10.9267 8.94 11.7C8.42 12.46 7.74667 12.8733 6.92 12.94ZM6.86 12.74C7.64667 12.6733 8.28667 12.2733 8.78 11.54C9.28667 10.8067 9.54 9.60667 9.54 7.94C9.54 7.18 9.49333 6.53333 9.4 6C9.30667 5.46667 9.16667 5.03333 8.98 4.7C8.91333 4.68667 8.84667 4.68 8.78 4.68C8.71333 4.66667 8.64667 4.66 8.58 4.66C7.79333 4.66 7.20667 5.07333 6.82 5.9C6.43333 6.71333 6.24 7.89333 6.24 9.44C6.24 10.2133 6.29333 10.8733 6.4 11.42C6.50667 11.9533 6.66 12.3933 6.86 12.74Z"
+              ></path>
+            </svg>
+          </span>
+          <span>
+            <svg xmlns="http://www.w3.org/2000/svg" fill="currentColor" viewBox="0 0 15 18" height="18" width="15">
+              <path
+                d="M9.28 15.76L8.54 13.38L6.96 13.52L5.98 17.02L2.58 17.32L0.58 16.32L4.96 0.699999L8.26 0.419999L10.26 1.42L14.72 16.48L11.28 16.76L9.28 15.76ZM5.12 0.899999L0.88 16.08L3.8 15.84L4.8 12.34L8.36 12.02L9.42 15.56L12.44 15.3L8.1 0.64L5.12 0.899999ZM5.5 9.42C5.75333 8.59333 5.96 7.80667 6.12 7.06C6.29333 6.31333 6.44 5.56667 6.56 4.82H6.64C6.74667 5.55333 6.88 6.27333 7.04 6.98C7.21333 7.67333 7.42 8.42 7.66 9.22L5.5 9.42Z"
+              ></path>
+            </svg>
+          </span>
+          <span>
+            <svg xmlns="http://www.w3.org/2000/svg" fill="currentColor" viewBox="0 0 14 18" height="18" width="14">
+              <path
+                d="M0.28 16.24V1.04L4.44 0.679999C4.61333 0.666666 4.78 0.66 4.94 0.66C5.1 0.646666 5.24667 0.64 5.38 0.64C6.11333 0.64 6.76667 0.726666 7.34 0.899999C7.92667 1.07333 8.56667 1.32667 9.26 1.66C10.1933 2.08667 10.9533 2.61333 11.54 3.24C12.1267 3.85333 12.56 4.61333 12.84 5.52C13.12 6.41333 13.26 7.50667 13.26 8.8C13.26 10.4933 12.9733 11.92 12.4 13.08C11.84 14.24 11.0667 15.1333 10.08 15.76C9.09333 16.3733 7.95333 16.74 6.66 16.86L2.28 17.24L0.28 16.24ZM4.64 15.68C5.89333 15.5733 7 15.2133 7.96 14.6C8.93333 13.9867 9.69333 13.1133 10.24 11.98C10.7867 10.8467 11.06 9.45333 11.06 7.8C11.06 5.53333 10.5733 3.80667 9.6 2.62C8.64 1.43333 7.21333 0.84 5.32 0.84C5.18667 0.84 5.04667 0.846666 4.9 0.859999C4.75333 0.859999 4.60667 0.866666 4.46 0.879999L0.48 1.22V16.02L4.64 15.68ZM3.5 3.9L4.08 3.86C4.22667 3.84667 4.36 3.84 4.48 3.84C4.61333 3.82667 4.74667 3.82 4.88 3.82C5.57333 3.82 6.14 3.94667 6.58 4.2C7.03333 4.45333 7.36667 4.88667 7.58 5.5C7.80667 6.11333 7.92 6.97333 7.92 8.08C7.92 9.65333 7.59333 10.8067 6.94 11.54C6.28667 12.26 5.4 12.6667 4.28 12.76L3.5 12.82V3.9ZM5.7 12.2C6.38 11.9067 6.88667 11.4333 7.22 10.78C7.55333 10.1133 7.72 9.21333 7.72 8.08C7.72 6.66667 7.52 5.65333 7.12 5.04C7.06667 5.02667 7.01333 5.02 6.96 5.02C6.90667 5.02 6.85333 5.02 6.8 5.02C6.68 5.02 6.56 5.02667 6.44 5.04C6.33333 5.04 6.22 5.04667 6.1 5.06L5.7 5.08V12.2Z"
+              ></path>
+            </svg>
+          </span>
+          <span>
+            <svg xmlns="http://www.w3.org/2000/svg" fill="currentColor" viewBox="0 0 6 17" height="18" width="6">
+              <path
+                d="M0.38 15.96V0.76L3.86 0.439999L5.86 1.44V16.64L2.38 16.94L0.38 15.96ZM0.58 0.94V15.74L3.66 15.46V0.66L0.58 0.94Z"
+              ></path>
+            </svg>
+          </span>
+          <span>
+            <svg xmlns="http://www.w3.org/2000/svg" fill="currentColor" viewBox="0 0 13 18" height="18" width="13">
+              <path
+                d="M7.22 15.82L5.72 12.44V16.92L2.28 17.22L0.28 16.22V1.02L3.52 0.74L5.52 1.74L7 4.94V0.64L10.48 0.319999L12.48 1.32V16.54L9.22 16.82L7.22 15.82ZM7.2 0.819999V6.42C7.2 6.56667 7.20667 6.80667 7.22 7.14C7.23333 7.46 7.24667 7.8 7.26 8.16C7.28667 8.50667 7.30667 8.80667 7.32 9.06C7.33333 9.3 7.34 9.42 7.34 9.42L7.28 9.46C7.28 9.46 7.26 9.38667 7.22 9.24C7.19333 9.09333 7.14667 8.92 7.08 8.72C7.01333 8.50667 6.94 8.31333 6.86 8.14L3.4 0.959999L0.48 1.2V16L3.52 15.76V10.52C3.52 10.36 3.51333 10.0867 3.5 9.7C3.48667 9.31333 3.47333 8.90667 3.46 8.48C3.46 8.05333 3.45333 7.69333 3.44 7.4C3.42667 7.09333 3.42 6.94 3.42 6.94L3.48 6.92C3.48 6.92 3.51333 7.05333 3.58 7.32C3.66 7.57333 3.76667 7.84 3.9 8.12L7.4 15.62L10.28 15.36V0.539999L7.2 0.819999Z"
+              ></path>
+            </svg>
+          </span>
+          <span>
+            <svg xmlns="http://www.w3.org/2000/svg" fill="currentColor" viewBox="0 0 15 18" height="18" width="15">
+              <path
+                d="M14.04 13.72C13.64 14.6533 12.9933 15.44 12.1 16.08C11.22 16.72 10.1333 17.0933 8.84 17.2C8.72 17.2133 8.6 17.22 8.48 17.22C8.36 17.22 8.24 17.22 8.12 17.22C7.12 17.22 6.16667 17.0467 5.26 16.7C4.36667 16.3533 3.57333 15.8333 2.88 15.14C2.18667 14.4333 1.64 13.54 1.24 12.46C0.84 11.38 0.64 10.1 0.64 8.62C0.64 7.48667 0.78 6.42667 1.06 5.44C1.34 4.44 1.74667 3.55333 2.28 2.78C2.82667 2.00667 3.48667 1.38667 4.26 0.92C5.03333 0.453333 5.90667 0.179999 6.88 0.0999997C6.96 0.0866657 7.04 0.0799987 7.12 0.0799987C7.2 0.0799987 7.28 0.0799987 7.36 0.0799987C8.33333 0.0799987 9.28 0.299999 10.2 0.74C11.1333 1.18 11.9467 1.78 12.64 2.54C13.3467 3.3 13.8467 4.16 14.14 5.12L11.76 6.46L12.04 6.44L14.04 7.44V13.72ZM5.9 7.16V10L8.98 9.74V11.46C8.80667 11.8067 8.52667 12.1067 8.14 12.36C7.76667 12.6 7.37333 12.7333 6.96 12.76C6.90667 12.7733 6.84667 12.78 6.78 12.78C6.72667 12.78 6.66667 12.78 6.6 12.78C5.73333 12.78 5.08 12.4333 4.64 11.74C4.2 11.0467 3.98 9.92 3.98 8.36C3.98 6.94667 4.20667 5.82 4.66 4.98C5.11333 4.14 5.84 3.68 6.84 3.6H7.06C7.60667 3.6 8.07333 3.76 8.46 4.08C8.86 4.4 9.14667 4.86667 9.32 5.48L11.9 4.02C11.6733 3.38 11.36 2.78 10.96 2.22C10.5733 1.64667 10.0867 1.18 9.5 0.819999C8.91333 0.459999 8.2 0.28 7.36 0.28C7.29333 0.28 7.22 0.28 7.14 0.28C7.06 0.28 6.98 0.286666 6.9 0.299999C5.63333 0.406666 4.54667 0.846666 3.64 1.62C2.73333 2.38 2.04 3.37333 1.56 4.6C1.08 5.81333 0.84 7.15333 0.84 8.62C0.84 10.14 1.06 11.4533 1.5 12.56C1.94 13.6667 2.56667 14.52 3.38 15.12C4.19333 15.72 5.16 16.02 6.28 16.02C6.37333 16.02 6.46 16.02 6.54 16.02C6.63333 16.02 6.72667 16.0133 6.82 16C8.07333 15.8933 9.12667 15.54 9.98 14.94C10.8467 14.3267 11.4733 13.5733 11.86 12.68V6.66L5.9 7.16ZM9.2 5.78C9.14667 5.59333 9.08667 5.42 9.02 5.26C8.95333 5.08667 8.88 4.93333 8.8 4.8C8.2 4.85333 7.70667 5.06667 7.32 5.44C6.94667 5.8 6.66667 6.29333 6.48 6.92L10.8 6.56L9.2 5.78ZM7.8 11.26L6.24 10.46C6.26667 10.9933 6.32 11.4133 6.4 11.72C6.49333 12.0133 6.62667 12.3 6.8 12.58C6.84 12.5667 6.88667 12.56 6.94 12.56C7.28667 12.5333 7.63333 12.4267 7.98 12.24C8.32667 12.04 8.59333 11.8067 8.78 11.54V11.14L7.8 11.26Z"
+              ></path>
+            </svg>
+          </span>
+        </div>
+        <div class="app-boot__message" id="app-boot-message" hidden></div>
+        <button class="app-boot__retry" id="app-boot-retry" type="button" hidden>重新加载</button>
+      </div>
+    </div>
+
     <script type="module" src="/src/main.ts"></script>
   </body>
 </html>
diff --git a/code/g3soft-erp/web/src/App.vue b/code/g3soft-erp/web/src/App.vue
index a78fb6fd..07cbbb5a 100644
--- a/code/g3soft-erp/web/src/App.vue
+++ b/code/g3soft-erp/web/src/App.vue
@@ -1,7 +1,48 @@
 <script setup lang="ts">
 import { RouterView } from 'vue-router'
+import ErrorBoundary from '@/views/fallback/ErrorBoundary.vue'
+import FallbackPage from '@/views/fallback/FallbackPage.vue'
+import { useOnline } from '@/composables/useOnline'
+
+/**
+ * 应用根：渲染当前路由页面 + 离线兜底层。
+ *
+ * ErrorBoundary 包住整个 RouterView（含 DefaultLayout 外壳）：
+ * 页面或布局的渲染错误就地兜成 500 缺省页，而不是整屏白。
+ * 对照 fms-vue 的 App.vue（`<ErrorBoundary><router-view /></ErrorBoundary>`）。
+ *
+ * 注意 onErrorCaptured 只捕获【后代组件】的错误；根组件自身与
+ * 事件回调 / 异步链里的错误不走这里 —— 那些由 main.ts 的
+ * app.config.errorHandler 与接口层的统一提示兜底。
+ */
+
+const { isOffline } = useOnline()
+
+/**
+ * 离线兜底：断网时在最上层【盖一页】离线缺省页，恢复后自动移除。
+ *
+ * ⚠️ 用覆盖层，而不是 v-if 把 RouterView 换掉：
+ *   原页面组件始终挂载，断网前后的表单输入、滚动位置、页签缓存全部保留；
+ *   若用 v-else 替换，断网瞬间页面被卸载，恢复后回到初始状态，用户填了一半的表单就没了。
+ *   这正是 fms-vue 的做法（它注释里明确写了这个取舍）。
+ *
+ * z-index 取 5000：高于弹窗（G3UI 的弹层走 z-index 管理器，基数 200 左右），
+ * 断网时全域可见、不被任何浮层遮挡。
+ */
 </script>
 
 <template>
-  <RouterView />
+  <ErrorBoundary>
+    <RouterView />
+  </ErrorBoundary>
+
+  <FallbackPage v-if="isOffline" status="offline" class="app-offline" />
 </template>
+
+<style lang="scss" scoped>
+.app-offline {
+  position: fixed;
+  inset: 0;
+  z-index: 5000;
+}
+</style>
diff --git a/code/g3soft-erp/web/src/composables/useOnline.ts b/code/g3soft-erp/web/src/composables/useOnline.ts
new file mode 100644
index 00000000..5fa60ff3
--- /dev/null
+++ b/code/g3soft-erp/web/src/composables/useOnline.ts
@@ -0,0 +1,63 @@
+import { computed, onBeforeUnmount, readonly, ref, type ComputedRef, type Ref } from 'vue'
+
+/**
+ * 网络在线状态。
+ *
+ * 对照 fms-vue 的 App.vue —— 它在应用根监听 window 的 online/offline，
+ * 断网时盖一层离线缺省页（FallbackPage status="offline"），恢复后自动移除。
+ *
+ * 为什么用 navigator.onLine + 事件监听，而不是轮询：
+ *   轮询会持续发请求，白耗流量与电量；这两个 API 是浏览器原生事件驱动，
+ *   零轮询、零定时器，断网/恢复的响应是即时的。性能开销可忽略。
+ *
+ * ⚠️ 已知局限（fms-vue 也记了同一条）：navigator.onLine 只反映【本机是否连上网】，
+ * 连在局域网但服务端不可达时它仍报在线。那种场景由接口层兜底 ——
+ * request.ts 对「无 status（服务端不可达）」统一弹「网络异常」提示。
+ * 所以本 composable 不需要、也不应该去做健康检查。
+ */
+
+/** 模块级单例：多处读取共用一份状态与一套监听 */
+const online = ref(true)
+let listenerCount = 0
+
+function sync(): void {
+  online.value = navigator.onLine
+}
+
+/** 首个使用者挂监听，最后一个使用者解绑 —— 避免重复注册 */
+function bind(): void {
+  if (listenerCount === 0) {
+    sync()
+    window.addEventListener('online', sync)
+    window.addEventListener('offline', sync)
+  }
+  listenerCount += 1
+}
+
+function unbind(): void {
+  listenerCount -= 1
+  if (listenerCount > 0) return
+
+  window.removeEventListener('online', sync)
+  window.removeEventListener('offline', sync)
+}
+
+/** 只读的在线态（对外只读，写入只能由浏览器的 online/offline 事件驱动） */
+const isOnline = readonly(online)
+
+/** 离线态：取反，供模板直接 v-if */
+const isOffline: ComputedRef<boolean> = computed(() => !online.value)
+
+export interface UseOnlineReturn {
+  /** 当前是否在线 */
+  isOnline: Readonly<Ref<boolean>>
+  /** 当前是否离线 */
+  isOffline: ComputedRef<boolean>
+}
+
+export function useOnline(): UseOnlineReturn {
+  bind()
+  onBeforeUnmount(unbind)
+
+  return { isOnline, isOffline }
+}
diff --git a/code/g3soft-erp/web/src/layouts/LayoutBreadcrumb.vue b/code/g3soft-erp/web/src/layouts/LayoutBreadcrumb.vue
index d29259b6..5ee981f2 100644
--- a/code/g3soft-erp/web/src/layouts/LayoutBreadcrumb.vue
+++ b/code/g3soft-erp/web/src/layouts/LayoutBreadcrumb.vue
@@ -3,31 +3,59 @@ import { computed } from 'vue'
 import { useRoute } from 'vue-router'
 import { House } from '@lucide/vue'
 import { usePreferencesStore } from '@/preferences'
-import { findMenuItemByPath, findParentKeyByPath } from '@/router'
-import { menuItems } from '@/constants/menu'
+import { findMenuItemByKey, findMenuItemByPath, findParentKeysByPath } from '@/router'
+
+/** 面包屑单项：有 path 的是可点的父级，没有的是当前页。 */
+interface Crumb {
+  title: string
+  path?: string
+}
 
 /**
  * 面包屑。
- * 数据来自菜单常量：父级分组 + 当前页，与侧栏同源，不额外维护。
+ * 数据来自菜单常量：祖先分组链 + 当前页，与侧栏同源，不额外维护。
  */
 const route = useRoute()
 const prefStore = usePreferencesStore()
 const pref = computed(() => prefStore.preferences)
 
-/** 当前路径对应的祖先链：[分组, 当前页] */
-const crumbs = computed(() => {
-  const list: Array<{ title: string; path?: string }> = []
+/**
+ * 当前路径对应的祖先链：[...分组, 当前页]。
+ *
+ * 父级用 findParentKeysByPath（返回【完整】祖先 key 链）而不是
+ * findParentKeyByPath（只取 [0] = 顶级）—— 后者在多级菜单下会漏掉中间层：
+ * 「海运 → 订舱业务 → 订舱单」只会显示成「海运 / 订舱单」。
+ */
+const crumbs = computed<Crumb[]>(() => {
+  const list: Crumb[] = []
 
   if (pref.value.breadcrumb.showHome) {
     list.push({ title: '首页', path: '/' })
   }
 
-  const current = findMenuItemByPath(route.path)
-  const parentKey = findParentKeyByPath(route.path)
-  const parent = parentKey ? menuItems.find((item) => item.key === parentKey) : undefined
+  // 1) 菜单里的完整祖先链（顶级 → 最近一级分组）
+  for (const key of findParentKeysByPath(route.path)) {
+    const node = findMenuItemByKey(key)
+    if (node) list.push({ title: node.title, path: node.path })
+  }
 
-  if (parent) list.push({ title: parent.title, path: parent.path })
-  if (current && current.key !== parent?.key) list.push({ title: current.title })
+  const current = findMenuItemByPath(route.path)
+
+  // 2) 菜单里查不到祖先（页面不在菜单树 / 菜单与路由不同步）时，
+  //    用路由层级兜底：route.matched 上带 title 的祖先记录即父级。
+  //    当前页不在这里补（由下面统一追加），避免自链接。
+  if (!current && list.length === 0) {
+    for (const record of route.matched) {
+      if (record.path === route.path) break
+      const title = record.meta.title as string | undefined
+      if (title) list.push({ title, path: record.path })
+    }
+  }
+
+  // 3) 当前页：菜单里查得到就用菜单名（业务页）；
+  //    查不到（403/404/500 等缺省页、详情页）回退到 route.meta.title。
+  const currentTitle = current?.title ?? (route.meta.title as string | undefined)
+  if (currentTitle) list.push({ title: currentTitle })
 
   return list
 })
@@ -50,11 +78,16 @@ const visible = computed(() => {
       <span v-if="index > 0" class="layout-breadcrumb__sep">/</span>
 
       <RouterLink v-if="crumb.path" class="layout-breadcrumb__item" :to="crumb.path">
-        <House v-if="index === 0 && pref.breadcrumb.showHome" :size="14" />
-        <span>{{ crumb.title }}</span>
+        <!-- __content 是 background 风格里做「内容整体左移」的包裹层（照 vben 的 li a > span） -->
+        <span class="layout-breadcrumb__content">
+          <House v-if="index === 0 && pref.breadcrumb.showHome" :size="14" />
+          {{ crumb.title }}
+        </span>
       </RouterLink>
 
-      <span v-else class="layout-breadcrumb__item is-current">{{ crumb.title }}</span>
+      <span v-else class="layout-breadcrumb__item is-current">
+        <span class="layout-breadcrumb__content">{{ crumb.title }}</span>
+      </span>
     </template>
   </nav>
 </template>
@@ -65,13 +98,8 @@ const visible = computed(() => {
   align-items: center;
   gap: 6px;
   min-width: 0;
-  font-size: 13px;
-
-  &.is-background {
-    padding: 4px 10px;
-    background: var(--g3-color-fill-hover, #f2f3f5);
-    border-radius: 6px;
-  }
+  /* 字号：15px —— 比顶栏 18px 的图标按钮小一档，层次清楚又不至于太弱 */
+  font-size: 15px;
 
   &__sep {
     color: var(--g3-color-text-tertiary, #86909c);
@@ -80,7 +108,6 @@ const visible = computed(() => {
   &__item {
     display: inline-flex;
     align-items: center;
-    gap: 4px;
     color: var(--g3-color-text-secondary, #4e5969);
     text-decoration: none;
 
@@ -92,5 +119,113 @@ const visible = computed(() => {
       color: var(--g3-color-text, #1f2329);
     }
   }
+
+  &__content {
+    display: inline-flex;
+    align-items: center;
+    gap: 4px;
+  }
+
+  /* ---- background 风格 ----
+   * 照搬 vben 的 breadcrumb-background.vue：整条不是「灰底圆角块」，而是
+   * 一段段 accent 底色的「>」形（面包屑步骤条）。段与段之间不再用 / 分隔符，
+   * 靠两块 14px 边框三角拼接：
+   *   ::before 放在段左侧 28px 处，左三角透明 → 形成向左的凹口；
+   *   ::after  放在段右侧，只留左三角着色 → 形成指向右的尖角。
+   * 14px 边框 × 上下两半 = 28px，正好等于段高 h-7(28px)。 */
+  &.is-background {
+    gap: 0;
+    font-size: 13px;
+
+    /* 有箭头就没有分隔符了 */
+    .layout-breadcrumb__sep {
+      display: none;
+    }
+
+    .layout-breadcrumb__item {
+      position: relative;
+      display: flex;
+      align-items: center;
+      height: 28px;
+      /* mr-9(36px)：给右箭头占的 28px 留位，另留 8px 视觉间隙 */
+      margin-right: 36px;
+      padding: 0 8px 0 5px;
+      color: var(--g3-color-text-secondary, #4e5969);
+      background: var(--g3-color-accent, #f2f3f5);
+      transition: background-color 0.2s ease;
+
+      &::before,
+      &::after {
+        content: '';
+        position: absolute;
+        top: 0;
+        width: 0;
+        height: 0;
+        border: 14px solid var(--g3-color-accent, #f2f3f5);
+      }
+
+      &::before {
+        left: -28px;
+        z-index: 10;
+        border-left-color: transparent;
+      }
+
+      &::after {
+        left: 100%;
+        border-color: transparent;
+        border-left-color: var(--g3-color-accent, #f2f3f5);
+      }
+
+      /* 首段：左端不开口，左侧留白加大并做左圆角 */
+      &:first-child {
+        padding-left: 15px;
+        border-radius: 2px 0 0 2px;
+
+        &::before {
+          border: none;
+        }
+      }
+
+      /* 末段（当前页）：不做右箭头，右侧留白加大并做右圆角 */
+      &:last-child {
+        padding-right: 15px;
+        border-radius: 0 2px 2px 0;
+
+        &::after {
+          border: none;
+        }
+      }
+
+      &.is-current {
+        color: var(--g3-color-foreground, #373c43);
+      }
+
+      /* 悬停只换底色，不改文字色（对齐 vben：当前页不可点，不参与 hover） */
+      &:not(:last-child):hover {
+        color: var(--g3-color-text-secondary, #4e5969);
+        background: var(--g3-color-accent-hover, #e3e5e8);
+
+        &::before {
+          border-color: var(--g3-color-accent-hover, #e3e5e8);
+          border-left-color: transparent;
+        }
+
+        &::after {
+          border-left-color: var(--g3-color-accent-hover, #e3e5e8);
+        }
+      }
+    }
+
+    /* 内容整体左移，视觉上落进「>」的口子里（照 vben 的 -ml-3 / 首段 -ml-1） */
+    .layout-breadcrumb__content {
+      position: relative;
+      z-index: 10;
+      margin-left: -12px;
+    }
+
+    .layout-breadcrumb__item:first-child .layout-breadcrumb__content {
+      margin-left: -4px;
+    }
+  }
 }
 </style>
diff --git a/code/g3soft-erp/web/src/layouts/LayoutHeader.vue b/code/g3soft-erp/web/src/layouts/LayoutHeader.vue
index 935ade23..b9e1c5a1 100644
--- a/code/g3soft-erp/web/src/layouts/LayoutHeader.vue
+++ b/code/g3soft-erp/web/src/layouts/LayoutHeader.vue
@@ -1,22 +1,27 @@
 <script setup lang="ts">
 import { computed, ref } from 'vue'
-import { useRoute } from 'vue-router'
+import { useRoute, useRouter } from 'vue-router'
 import {
+  Bell,
+  Languages,
+  LogOut,
   Maximize,
   Minimize,
   Moon,
-  PanelLeftClose,
-  PanelLeftOpen,
+  PanelLeft,
+  PanelRight,
   Settings,
   Sun,
   User,
 } from '@lucide/vue'
+import { G3Message } from '@g3soft/ui'
 import { useUserStore } from '@/stores'
 import { usePreferencesStore } from '@/preferences'
 import { useFullscreen } from '@/composables/useFullscreen'
 import PreferencesDrawer from '@/preferences/components/PreferencesDrawer.vue'
 
 const route = useRoute()
+const router = useRouter()
 const userStore = useUserStore()
 const prefStore = usePreferencesStore()
 const pref = computed(() => prefStore.preferences)
@@ -51,6 +56,20 @@ function toggleSidebar(): void {
   prefStore.update({ sidebar: { collapsed: !pref.value.sidebar.collapsed } })
 }
 
+/**
+ * 退出登录。
+ *
+ * 对照 vben：登出走 authStore.logout() → resetAllStores()，
+ * 把用户/权限等 store 全部 $reset()。本仓库用户模块尚未落地，
+ * 所以这里做当前能做的事：清会话（userStore.clear：清 userInfo + localStorage 的 token）。
+ *
+ * TODO 用户模块落地后补：调登出接口、清权限码、销毁动态路由。
+ */
+function logout(): void {
+  userStore.clear()
+  router.replace('/login')
+}
+
 /** 当前是否深色（auto 跟随系统时也能正确反映） */
 const isDark = computed(() => prefStore.isDark)
 
@@ -69,6 +88,21 @@ function toggleTheme(): void {
  * 与页签栏的「局部全屏」是两件事 —— 那个只隐藏应用外壳，浏览器窗口本身不变。
  */
 const { isFullscreen, isSupported: fullscreenSupported, toggle: toggleFullscreen } = useFullscreen()
+
+/* ---------------- 语言 / 提醒（功能未实现，先给占位反馈） ---------------- */
+
+/**
+ * 语言切换：项目尚未接入 i18n（无 vue-i18n 依赖），
+ * 与登录页 Login.vue 的 toggleLang 保持同一占位口径，接入后替换为真实切换。
+ */
+function handleLanguage(): void {
+  G3Message.info('语言切换待接入 i18n 后生效')
+}
+
+/** 消息提醒：功能未实现，先给占位反馈 */
+function handleNotification(): void {
+  G3Message.info('消息提醒功能尚未实现')
+}
 </script>
 
 <template>
@@ -95,9 +129,11 @@ const { isFullscreen, isSupported: fullscreenSupported, toggle: toggleFullscreen
         :title="pref.sidebar.collapsed ? '展开侧栏' : '折叠侧栏'"
         @click="toggleSidebar"
       >
-        <!-- 折叠/展开语义图标（对照 vben 的 ep:fold / ep:expand）：折叠态显示「展开」、展开态显示「折叠」 -->
-        <PanelLeftOpen v-if="pref.sidebar.collapsed" :size="18" />
-        <PanelLeftClose v-else :size="18" />
+        <!-- 折叠/展开语义图标（对照 vben 的 ep:fold / ep:expand）：
+             折叠态显示 PanelRight（点击展开）、展开态显示 PanelLeft（点击折叠）。
+             两者同为 18×18 圆角矩形轮廓，仅分隔线在左/右，视觉重量与切换动效一致，不会因换图标跳动。 -->
+        <PanelRight v-if="pref.sidebar.collapsed" :size="18" />
+        <PanelLeft v-else :size="18" />
       </button>
 
       <!-- 顶部菜单布局：菜单直接放进顶栏 -->
@@ -110,18 +146,15 @@ const { isFullscreen, isSupported: fullscreenSupported, toggle: toggleFullscreen
       <slot v-else name="breadcrumb" />
     </div>
 
+    <!-- 右侧工具区。顺序照 vben 的 preferences.widget.order
+         （packages/@core/preferences/src/config.ts:157-168）：
+           ['globalSearch','preferences','themeToggle','languageToggle','timezone',
+            'fullscreen','refresh','notification','lockScreenBtn','logoutBtn']
+         本仓库没有 globalSearch / timezone，refresh 在页签栏而非顶栏，
+         lockScreen 已移除，故实际为：
+           preferences → themeToggle → languageToggle → fullscreen → notification
+           → logoutBtn（用户区整体在最后） -->
     <div class="layout-header__right">
-      <button
-        type="button"
-        class="layout-header__icon-btn"
-        :title="isDark ? '切换为浅色' : '切换为深色'"
-        @click="toggleTheme"
-      >
-        <!-- 深色时显示太阳（点击切回浅色），浅色时显示月亮（点击切深色） -->
-        <Sun v-if="isDark" :size="17" />
-        <Moon v-else :size="17" />
-      </button>
-
       <button
         v-if="pref.app.enablePreferences"
         type="button"
@@ -129,7 +162,29 @@ const { isFullscreen, isSupported: fullscreenSupported, toggle: toggleFullscreen
         title="偏好设置"
         @click="preferencesOpen = true"
       >
-        <Settings :size="17" />
+        <Settings :size="18" />
+      </button>
+
+      <button
+        type="button"
+        class="layout-header__icon-btn"
+        :title="isDark ? '切换为浅色' : '切换为深色'"
+        @click="toggleTheme"
+      >
+        <!-- 深色时显示太阳（点击切回浅色），浅色时显示月亮（点击切深色） -->
+        <Sun v-if="isDark" :size="18" />
+        <Moon v-else :size="18" />
+      </button>
+
+      <!-- 语言切换：i18n 未接入，点击给占位提示（与登录页同一口径） -->
+      <button
+        v-if="pref.header.showLanguage"
+        type="button"
+        class="layout-header__icon-btn"
+        title="语言切换"
+        @click="handleLanguage"
+      >
+        <Languages :size="18" />
       </button>
 
       <!-- 页面全屏：原生 Fullscreen API，整页铺满屏幕；浏览器不支持时不渲染 -->
@@ -140,13 +195,34 @@ const { isFullscreen, isSupported: fullscreenSupported, toggle: toggleFullscreen
         :title="isFullscreen ? '退出全屏' : '页面全屏'"
         @click="toggleFullscreen()"
       >
-        <Minimize v-if="isFullscreen" :size="17" />
-        <Maximize v-else :size="17" />
+        <Minimize v-if="isFullscreen" :size="18" />
+        <Maximize v-else :size="18" />
+      </button>
+
+      <!-- 消息提醒：功能未实现，点击给占位提示 -->
+      <button
+        v-if="pref.header.showNotification"
+        type="button"
+        class="layout-header__icon-btn"
+        title="消息提醒"
+        @click="handleNotification"
+      >
+        <Bell :size="18" />
       </button>
 
       <div class="layout-header__user">
         <User :size="16" />
         <span>{{ displayName }}</span>
+        <!-- 退出登录：用户模块落地前只有「回登录页」这一个动作 -->
+        <button
+          class="layout-header__logout"
+          type="button"
+          title="退出登录"
+          aria-label="退出登录"
+          @click="logout"
+        >
+          <LogOut :size="15" />
+        </button>
       </div>
     </div>
 
@@ -170,7 +246,7 @@ const { isFullscreen, isSupported: fullscreenSupported, toggle: toggleFullscreen
   &__right {
     display: flex;
     align-items: center;
-    gap: 12px;
+    gap: 10px;
     min-width: 0;
   }
 
@@ -261,5 +337,27 @@ const { isFullscreen, isSupported: fullscreenSupported, toggle: toggleFullscreen
     font-size: 13px;
     color: var(--g3-color-foreground, #1f2329);
   }
+
+  /* 退出登录：比工具条按钮小一号，不抢视觉；色值走 inherit，半深色顶栏也不脱色 */
+  &__logout {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    flex-shrink: 0;
+    width: 24px;
+    height: 24px;
+    padding: 0;
+    color: inherit;
+    cursor: pointer;
+    background: none;
+    border: 0;
+    border-radius: 6px;
+    opacity: 0.7;
+
+    &:hover {
+      background: var(--g3-color-accent, #f2f3f5);
+      opacity: 1;
+    }
+  }
 }
 </style>
diff --git a/code/g3soft-erp/web/src/layouts/LayoutTabbar.vue b/code/g3soft-erp/web/src/layouts/LayoutTabbar.vue
index 7df96870..1bd1b312 100644
--- a/code/g3soft-erp/web/src/layouts/LayoutTabbar.vue
+++ b/code/g3soft-erp/web/src/layouts/LayoutTabbar.vue
@@ -79,7 +79,7 @@ const overflowed = ref(false)
 const canScrollLeft = ref(false)
 const canScrollRight = ref(false)
 
-/** 滚动区末尾的样式留白（与 .layout-tabbar__spacer 的 24px 一致）。
+/** 滚动区末尾的样式留白（与 .layout-tabbar__track 的 padding-right: 24px 一致）。
  * 它是纯占位、不计真实内容，但会计入 scrollWidth；判断"是否需要滚动"时必须把它排除，
  * 否则页签刚好接近铺满时会被误判为溢出 —— 左侧冒出一个变灰、不可点的滚动按钮 */
 const TRACK_END_SPACER = 24
@@ -150,9 +150,27 @@ function revealActiveTab(): void {
 
   if (selfFullyVisible && !hasHiddenLeft && !hasHiddenRight) return
 
+  /** 让激活项居中所需要的滚动增量 */
   const offset = activeRect.left - trackRect.left - (trackRect.width - activeRect.width) / 2
+
+  /**
+   * 计算「让激活项居中」的滚动量，并钳制到合法区间。
+   *
+   * 为什么要显式钳上限（不只是 Math.max(0, ...) 的钳下限）：
+   *   当激活项靠近【末尾】时，「居中」所需的目标 scrollLeft 会超过
+   *   track.scrollWidth - track.clientWidth（右侧没有足够内容撑出滚动量），
+   *   浏览器会把 scrollTo 静默截断 —— 结果停在「居中所需但被截断」的中间值，
+   *   激活项仍有一截露在可视区外（实测最后一项右边界超出 54px）。
+   *
+   * 正确行为：目标超过上限时，滚到【上限】（贴右），让激活项至少完整可见；
+   * 而不是停在那个被截断的中间位置。
+   */
+  const targetScrollLeft = track.scrollLeft + offset
+  const maxScrollLeft = track.scrollWidth - track.clientWidth
+  const clamped = Math.min(Math.max(0, targetScrollLeft), Math.max(0, maxScrollLeft))
+
   try {
-    track.scrollTo({ left: Math.max(0, track.scrollLeft + offset), behavior: 'smooth' })
+    track.scrollTo({ left: clamped, behavior: 'smooth' })
   } catch {
     /* 环境不支持平滑滚动时忽略 */
   }
@@ -171,12 +189,48 @@ function handleWheel(event: WheelEvent): void {
 
 let resizeObserver: ResizeObserver | null = null
 
-onMounted(() => {
-  resizeObserver = new ResizeObserver(updateScrollState)
+onMounted(async () => {
+  /* ResizeObserver 回调里既刷箭头状态、又重定位激活页签。
+   *
+   * 为什么 resize 也要 reveal（这是第二个坑）：
+   *   挂载那一刻 revealActiveTab 已经跑过、滚到了正确位置（贴右或居中）。
+   *   但之后侧栏展开动画 / 滚动条出现 / 局部全屏切换会让轨道【变窄】，
+   *   maxScrollLeft 变大而 scrollLeft 停在旧值 —— 激活项右缘又被裁出去。
+   *   实测：挂载时 clientWidth=661、滚到 maxScroll=722；稳定后 clientWidth 缩到 595，
+   *   maxScroll 涨到 788，但 scrollLeft 仍停在 722 → 右缘露出去 66px。
+   *
+   *   revealActiveTab 有完整守卫（完整可见且左右无隐藏就 return），
+   *   所以 resize 里再调一次是安全的：没被裁就不滚，被裁了才补滚。
+   */
+  resizeObserver = new ResizeObserver(() => {
+    updateScrollState()
+    revealActiveTab()
+  })
   if (trackRef.value) {
     resizeObserver.observe(trackRef.value)
     trackRef.value.addEventListener('wheel', handleWheel, { passive: false })
   }
+
+  /* 首次挂载也要定位激活页签 —— 修复「刷新后页签不居中」。
+   *
+   * 为什么不能只靠下面的 watch：
+   *   页签是持久化的（g3erp:app:v2），刷新时 pinia 在组件挂载【之前】就把 tabs 还原好了，
+   *   而 route.fullPath 在路由解析完成时也已确定。
+   *   于是 watch 的两个依赖在挂载这一刻【already 是初始值】，
+   *   没有 immediate 的 watch 根本不会触发 → revealActiveTab 一次都没跑
+   *   → 被恢复的页签栏停在 scrollLeft = 0，激活页签若在后面就看不见。
+   *
+   * 为什么不用 watch 的 immediate: true：
+   *   immediate 的回调在 onMounted【之前】执行，那时 trackRef 还是 null，
+   *   revealActiveTab 第 126 行的守卫会直接 return —— 等于没修。
+   *
+   * 为什么加 await nextTick()：
+   *   挂载时页签虽是同步渲染的，但激活项的高亮/宽度可能受样式影响；
+   *   等一帧确保布局稳定后再量 getBoundingClientRect，避免量到中间态。
+   */
+  await nextTick()
+  revealActiveTab()
+  updateScrollState()
 })
 
 onBeforeUnmount(() => {
@@ -366,9 +420,6 @@ const activeTabContextItems = computed<DropdownItemData[]>(() => {
           </div>
         </div>
       </G3Dropdown>
-
-      <!-- 末尾留白（照 vben 的 pr-6） -->
-      <span class="layout-tabbar__spacer" />
     </div>
 
     <!-- 右侧滚动箭头（页签溢出时显示） -->
@@ -471,8 +522,10 @@ const activeTabContextItems = computed<DropdownItemData[]>(() => {
   flex: 1;
   align-items: stretch;
   min-width: 0;
-  /* 照 vben：标签区顶部留 3px（pt-0.75），chrome 标签从留白下沿延伸到底边线 */
-  padding-top: 3px;
+  /* 注意：这里【不能】写死 padding-top: 3px。
+   * 那 3px 是 chrome 专属的 —— 见下方 .is-chrome .layout-tabbar__track。
+   * 写死会让 plain / card 的页签整体下移 3px，文字与满高竖线都不居中。 */
+  padding-right: 24px;
   overflow-x: auto;
   overflow-y: hidden;
   scrollbar-width: none;
@@ -482,11 +535,13 @@ const activeTabContextItems = computed<DropdownItemData[]>(() => {
   }
 }
 
-/* 末尾留白：滚动到最右时最后一个标签不贴边 */
-.layout-tabbar__spacer {
-  flex: none;
-  width: 24px;
-}
+/* 末尾留白 24px（照 vben 容器的 pr-6）：滚动到最右时最后一个标签不贴边。
+ *
+ * ⚠️ 必须写成【轨道自身的 padding-right】，不能用一个末尾的 <span> 兄弟节点占位。
+ * plain 的「最后一个页签右边那条竖线」靠 .layout-tabbar__item:last-child 实现，
+ * 一旦在 item 之后插入 spacer，最后一个 item 就不再是 :last-child，
+ * last:border-r 永远不生效 —— 最后一个页签会缺一条右边框。
+ * vben 正是用容器的 pr-6 而非兄弟节点，就是这个原因。 */
 
 /* 页签槽位：撑满轨道高度 + -12px 负右边距（相邻标签重叠，实现「标签块连排」） */
 .layout-tabbar__item {
@@ -503,7 +558,11 @@ const activeTabContextItems = computed<DropdownItemData[]>(() => {
   z-index: 2;
 }
 
-/* 内层容器：承载绝对定位的背景层与文字区（对应 vben 的 px-1 容器） */
+/* 内层容器：承载绝对定位的背景层与文字区。
+ * 宽度/高度撑满即可 —— 内边距是【分风格】的，见下：
+ *   chrome 对应 vben tabs-chrome 的 'px-1'（4px），写在 .is-chrome 里；
+ *   plain  对应 vben tabs 的 'size-full'，【无内边距】。
+ * 所以这里不能写死 padding，否则 plain 会凭空多出 8px 宽。 */
 .layout-tabbar__inner {
   position: relative;
   z-index: 0;
@@ -511,7 +570,6 @@ const activeTabContextItems = computed<DropdownItemData[]>(() => {
   align-items: center;
   width: 100%;
   height: 100%;
-  padding: 0 4px;
 }
 
 /* 分隔线：非首个、非激活的页签左侧一条 16px 竖线 */
@@ -600,7 +658,20 @@ const activeTabContextItems = computed<DropdownItemData[]>(() => {
   }
 }
 
-/* 主内容：决定页签宽度（照 FMS / vben：左右 14px 外边距 + 右侧 16px 内边距给关闭按钮留位） */
+/* 主内容：决定页签宽度。
+ *
+ * 【布局意图】文字靠左、关闭按钮贴右 —— 一个页签的两端。
+ * 这是 vben 的结构（文字 flex-1 撑满并靠左，X 绝对定位在右侧），也是页签的通用范式：
+ * 文字从固定的一侧起排，扫视一排页签时视线不用来回找起点。
+ *
+ * ⚠️ 不要把这里改成 justify-content: center（曾这么改过，观感是错的）：
+ * 关闭按钮（__extra）是 position:absolute、不占文档流宽度，
+ * 文字居中后视觉重心会偏右 —— 右边看着「文字和 X 挤在一起」，左边却空着。
+ *
+ * 内外边距因此是不对称的，右边多出来的部分就是给关闭按钮让位：
+ *   左 = inner 4 + margin 14 + padding 8  = 26px
+ *   右 = inner 4 + margin 14 + padding 16 = 34px
+ * （与 vben chrome 的「左 26 / 右 34」完全一致：px-1 + mx-3.5 + pl-2/pr-4） */
 .layout-tabbar__main {
   position: relative;
   z-index: 2;
@@ -619,23 +690,40 @@ const activeTabContextItems = computed<DropdownItemData[]>(() => {
   transition: color 150ms ease;
 }
 
+/* 文字：flex-1 撑满剩余宽度 —— 这是「文字靠左」的关键。
+ * 去掉 flex-1 后文字盒会收缩成内容宽度，再配合父级的 justify-content 就会居中；
+ * 保留 flex-1 则文字盒始终占满左侧空间，文字自然靠左，右侧把关闭按钮的位置空出来。
+ * 超长标题靠 overflow/ellipsis 截断，不会挤压关闭按钮。 */
+.layout-tabbar__label {
+  flex: 1;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
 /* 不可关闭的页签（工作台）：没有关闭按钮，右侧不必预留 16px，
  * 左右对称 8px，文字在标签内居中 */
 .layout-tabbar__item.is-unclosable .layout-tabbar__main {
   padding: 0 8px;
 }
 
-/* 照 FMS：flex-1 + 溢出隐藏，不设宽度上限 */
-.layout-tabbar__label {
-  flex: 1;
-  overflow: hidden;
-  white-space: nowrap;
-}
-
 /* ---- 状态：激活 / 悬停 ---- */
 
 /* 激活：浅主色标签块 + 主色文字，底部外弧与标签块同色 */
 .layout-tabbar.is-chrome {
+  /* 顶部留 3px（vben 的 pt-0.75，见 tabs-view.vue：'pt-0.75': styleType === 'chrome'）。
+   * chrome 标签从留白下沿延伸到底边线，所以这 3px 是 chrome 形态的一部分；
+   * plain / card 是满高连排，不能吃这 3px，否则内容整体下移、不居中。 */
+  .layout-tabbar__track {
+    padding-top: 3px;
+  }
+
+  /* 内层 4px 内边距：vben tabs-chrome 的 'px-1'（tabs-chrome/tabs.vue L110）。
+   * chrome 专属 —— plain 对应 tabs.vue 的 'size-full'，没有内边距。 */
+  .layout-tabbar__inner {
+    padding: 0 4px;
+  }
+
   .layout-tabbar__item.is-active {
     .layout-tabbar__background-content {
       background: var(--g3-color-primary-soft, hsl(212 100% 45% / 15%));
@@ -678,14 +766,59 @@ const activeTabContextItems = computed<DropdownItemData[]>(() => {
   }
 }
 
-/* ---- card 风格 ---- */
+/* ---- card 风格（照 vben 的 tabs/tabs.vue 的 card 类名） ----
+ *
+ * 来源：packages/@core/ui-kit/tabs-ui/src/components/tabs/tabs.vue
+ *   card 类（L37-40）：
+ *     'h-[calc(100%-6px)] rounded-md ml-2 border border-border transition-all'
+ *
+ * ⚠️ 关键差异 —— vben 与本项目的「卡片边界」落在不同元素上，不能照抄几何参数：
+ *
+ *   vben：item 自带 'rounded-md border border-border'（卡片 = 整个 item）。
+ *         所以它【继续沿用 plain 的 __main 参数】（mx-3 mr-4 pr-3）没问题 ——
+ *         那 12/16px 的外边距是在卡片【内部】给文字让位的，卡片本身仍撑满 item。
+ *
+ *   本项目：卡片外形（border + radius）画在 __main 上（见下方），item 只负责
+ *         margin-left 8px 的相邻间隔与缩高。此时若再套 plain 的 mx-3 mr-4，
+ *         就会变成「带边框的卡片外面再留 12/16px」—— 卡片被挤小、文字紧贴左边框，
+ *         视觉上就是错乱的。所以 card 的 __main 必须：
+ *           margin: 0（卡片直接占满 item，左右间隔由 item 的 margin-left 负责）
+ *           padding 左右对称（文字在卡片内居中，而不是靠左）
+ *
+ * 另：vben 容器是 items-center，缩高 6px 的卡片会垂直居中；
+ *     本项目 __track 用 align-items: stretch，所以显式加 align-self: center。 */
 .layout-tabbar.is-card .layout-tabbar__item {
+  align-self: center;
   height: calc(100% - 6px);
   margin: 0 0 0 8px;
 
+  /* 卡片本体：边框 + 圆角画在这里。
+   *
+   * 【为什么 margin-right 必须是 0 —— 它决定卡片之间的间距】
+   * 边框画在 __main 上，所以 __main 的右 margin 会跑到【卡片外面】，
+   * 与下一个 item 的 margin-left 叠加成「卡片间距」：
+   *   曾经 margin-right: 16 → 间距 = 16 + 8(item margin-left) = 24px，观感过疏
+   *   vben 的卡片间距只有 8px（card 类名的 ml-2，边框在 item 上、__main 的 mr-4 在卡内）
+   * 故这里取 0，让卡片边框直接贴到 item 右缘 → 间距回到 8px。
+   *
+   * 【给 X 让位的空间改由 padding-right 承担】
+   * 记 D(x) = x 距 __inner 右缘的距离（__extra 的包含块是 __inner；【D 越小越靠右】）：
+   *   D(X 右边界)   = extra.right
+   *   D(X 左边界)   = extra.right + 16        （X 宽 16）
+   *   D(卡片右缘)   = margin-right = 0
+   *   D(文字右边界) = margin-right + padding-right + 1(border)
+   *
+   * 取 inset = 6（X 距卡片右缘，与 plain 的 right-1.5 同观感）、gap = 6（与 plain 实测一致）：
+   *   extra.right   = 0 + 6 = 6        （于是与 plain 的 6px 一致了）
+   *   padding-right = 6 + 16 + 1 - 1  → 27
+   *
+   * CDP 实测走过的弯路（别再试这些组合）：
+   *   margin:0 + padding:16        → 文字压住 X（gap = -5）
+   *   margin:16 + right:6          → X 露在卡片外
+   *   margin:16 + right:16/22      → X 在卡内了，但卡片间距 24px（本次要修的问题） */
   .layout-tabbar__main {
     margin: 0;
-    padding: 0 8px;
+    padding: 0 27px 0 8px;
     border: 1px solid var(--g3-color-border, #e5e6eb);
     border-radius: 6px;
   }
@@ -694,21 +827,78 @@ const activeTabContextItems = computed<DropdownItemData[]>(() => {
     background: var(--g3-color-primary-soft, hsl(212 100% 45% / 15%));
     border-color: var(--g3-color-primary-soft, hsl(212 100% 45% / 15%));
   }
+
+  /* 关闭按钮：6px = inset（X 距卡片右缘），与 plain 同值。
+   * 与 __main 的 padding-right 是【联立关系】，单独改任一个都会让 X 露到卡外、或压住文字。 */
+  .layout-tabbar__extra {
+    right: 6px;
+  }
 }
 
-/* ---- plain 风格 ---- */
-.layout-tabbar.is-plain .layout-tabbar__item {
-  margin-right: 0;
+/* ---- plain 风格（照 vben 的 tabs/tabs.vue 逐条移植） ----
+ *
+ * 来源：packages/@core/ui-kit/tabs-ui/src/components/tabs/tabs.vue
+ *
+ *   item 的类（typeWithClass.plain，L43）：
+ *     'h-full [&:not(:first-child)]:border-l last:border-r border-border'
+ *   item 自身的类（L101 / L94）：
+ *     '[&:not(.is-active)]:hover:bg-accent' + 'is-active bg-primary/15'
+ *   内层容器（L112）：'relative flex size-full items-center'   ← 注意：无 px-1
+ *   主内容（L132）：  'mx-3 mr-4 ... pr-3'                      ← margin L12/R16，padding R12
+ *   关闭按钮（L115）：'absolute ... right-1.5'                   ← 6px
+ *
+ * 与 chrome（tabs-chrome/tabs.vue）的关键差异：
+ *   - chrome 的内层有 px-1（4px）、__extra 在 right-(--gap)=7px、__main 是 pl-2 pr-4；
+ *     plain 内层【无内边距】、__extra 在 6px、__main 是 pr-3。两者数值并不通用。
+ *   - chrome 的 item 有 -mr-3（-12px）让标签块重叠；plain 无负边距 ——
+ *     竖分割线一旦重叠就会被盖住。
+ *   - 边框挂在 item 上而不是 __main：竖线要撑满整条页签栏高度，
+ *     挂 __main 会被它的 margin 截断。 */
+.layout-tabbar.is-plain {
+  .layout-tabbar__item {
+    /* 1. 无重叠：每个页签独立占位（chrome 是 -12px） */
+    margin-right: 0;
 
-  .layout-tabbar__main {
-    margin: 0;
-    padding: 0 12px;
-    border-left: 1px solid var(--g3-color-border, #e5e6eb);
-    border-radius: 0;
+    /* 2. 满高竖分割线：[&:not(:first-child)]:border-l + last:border-r
+     * last:border-r 就是「最后一个页签右边缘那条竖线」——两个伪类缺一不可。 */
+    &:not(:first-child) {
+      border-left: 1px solid var(--g3-color-border, #e5e6eb);
+    }
+
+    &:last-child {
+      border-right: 1px solid var(--g3-color-border, #e5e6eb);
+    }
+
+    /* 3. 悬停（非激活）：整格浅灰底 */
+    &:hover:not(.is-active) {
+      background: var(--g3-color-accent, #f2f3f5);
+    }
+
+    /* 4. 激活：整格主色 15% 底 */
+    &.is-active {
+      background: var(--g3-color-primary-soft, hsl(212 100% 45% / 15%));
+
+      .layout-tabbar__close {
+        color: var(--g3-color-primary, #165dff);
+      }
+    }
+
+    /* 主内容：照 vben 的 'mx-3 mr-4 ... pr-3'
+     *   margin: 0 16px 0 12px   ← mx-3(12) 被 mr-4(16) 覆盖右侧，所以右是 16
+     *   padding: 0 12px 0 0     ← pr-3，只有右侧内边距
+     * 底色铺在 item 上，这里保持透明。 */
+    .layout-tabbar__main {
+      margin: 0 16px 0 12px;
+      padding: 0 12px 0 0;
+      border-radius: 5px 5px 0 0;
+      background: transparent;
+    }
   }
 
-  &.is-active .layout-tabbar__main {
-    background: var(--g3-color-primary-soft, hsl(212 100% 45% / 15%));
+  /* 关闭按钮：照 vben 的 right-1.5（6px）。
+   * plain 的右留白比 chrome 小（16+12=28 vs 14+16=30），X 也相应更靠右。 */
+  .layout-tabbar__extra {
+    right: 6px;
   }
 }
 
diff --git a/code/g3soft-erp/web/src/main.ts b/code/g3soft-erp/web/src/main.ts
index fc3d1fdc..2f9099bf 100644
--- a/code/g3soft-erp/web/src/main.ts
+++ b/code/g3soft-erp/web/src/main.ts
@@ -1,5 +1,5 @@
 import { createApp } from 'vue'
-import { G3UI, zhCN } from '@g3soft/ui'
+import { G3Message, G3UI, zhCN } from '@g3soft/ui'
 
 import App from './App.vue'
 import router from './router'
@@ -16,6 +16,27 @@ G3UI.config({
   locale: zhCN,
 })
 
+/**
+ * 全局错误兜底。
+ *
+ * App.vue 的 ErrorBoundary 只捕获【后代组件的渲染错误】；这里补上它够不到的两类：
+ *   1. 事件回调（@click 里抛错）—— Vue 会走到 errorHandler，不会触发 onErrorCaptured
+ *   2. 异步链（未被 catch 的 Promise / 生命周期钩子里的抛错）
+ *
+ * 这两类不处理的话，用户点了按钮没反应、控制台有报错但界面毫无提示。
+ *
+ * 用 G3Message 而非渲染错误页：这类错误通常【不破坏页面结构】，
+ * 给一条提示、让用户能继续操作，比整屏换掉更合适。
+ * 真正该换页的渲染崩溃已由 ErrorBoundary 处理。
+ */
+app.config.errorHandler = (error, _instance, info) => {
+  // 控制台保留完整现场（含 Vue 给的 info：是哪个钩子/回调抛的），便于排查
+  console.error('[global errorHandler]', info, error)
+
+  const message = error instanceof Error ? error.message : String(error)
+  G3Message.error(message || '应用发生未知错误')
+}
+
 app.use(pinia)
 
 // 提前初始化偏好设置：store 内部的 watch 是 immediate 的，
@@ -23,4 +44,73 @@ app.use(pinia)
 usePreferencesStore()
 
 app.use(router)
-app.mount('#app')
+
+/**
+ * 启动失败时把开屏加载屏切换成错误态（不再无限转圈）。
+ *
+ * 与 index.html 里那段 window.onerror 分工不同：那段兜的是「模块都没加载进来」
+ * （file:// 直接打开、网络断了拿不到 chunk）；这里兜的是「模块进来了，但
+ * router.isReady() 或 mount 抛错」，比如路由守卫里的异常。
+ */
+function showBootstrapError(error: unknown): void {
+  console.error('Application bootstrap failed', error)
+
+  const boot = document.getElementById('app-boot')
+  const message = document.getElementById('app-boot-message')
+  const retry = document.getElementById('app-boot-retry')
+  if (!boot || !message || !retry) return
+
+  boot.classList.add('app-boot--error')
+  boot.setAttribute('aria-busy', 'false')
+  boot.setAttribute('aria-label', '应用加载失败')
+  message.textContent = '应用加载失败，请检查网络后重试'
+  message.hidden = false
+  retry.hidden = false
+  retry.addEventListener('click', () => window.location.reload(), { once: true })
+}
+
+/**
+ * 应用启动流程（对照 fms-vue 的 src/main.js bootstrap）。
+ *
+ * 关键取舍：先把首屏数据准备好，再挂载、再淡出加载屏 ——
+ * 顺序反了会出现「加载屏淡出后菜单才跳出来」的闪动。
+ *   1. await router.isReady()：等首个路由解析完（权限/菜单在守卫里同步加载完，
+ *      首屏 beforeEach 在 mount 前 return，菜单一次性到位）
+ *   2. 把 #app-boot 移出 #app 之外（它是 #app 的兄弟节点，这里再确认一次），
+ *      避免 mount 时 #app 被整体替换导致加载屏瞬间消失（那样没有过渡、还卡顿）
+ *   3. mount 首屏：布局含完整菜单一次性渲染出来
+ *   4. 下一帧加 .app-boot--hide：opacity 淡出由合成器驱动，不被渲染阻塞；
+ *      此时完整页面已在底下就位，淡出过程不会「跳出」
+ *   5. transitionend 移除节点并清掉加载屏用的临时主题类 boot-dark
+ *      （真正的主题由 applyPreferencesToCss 写入的 .dark / data-g3-theme 管理）
+ */
+async function bootstrap(): Promise<void> {
+  try {
+    await router.isReady()
+
+    const boot = document.getElementById('app-boot')
+    if (boot) document.body.appendChild(boot)
+
+    app.mount('#app')
+
+    requestAnimationFrame(() => {
+      boot?.classList.add('app-boot--hide')
+    })
+
+    if (boot) {
+      const cleanupBoot = () => {
+        boot.remove()
+        document.documentElement.classList.remove('boot-dark')
+      }
+      boot.addEventListener('transitionend', cleanupBoot, { once: true })
+      // 兜底：transitionend 未触发（如被 prefers-reduced-motion 关掉动画）时也要移除节点
+      setTimeout(() => {
+        if (boot.isConnected) cleanupBoot()
+      }, 600)
+    }
+  } catch (error) {
+    showBootstrapError(error)
+  }
+}
+
+void bootstrap()
diff --git a/code/g3soft-erp/web/src/preferences/config.ts b/code/g3soft-erp/web/src/preferences/config.ts
index fba27a35..c50ce1e5 100644
--- a/code/g3soft-erp/web/src/preferences/config.ts
+++ b/code/g3soft-erp/web/src/preferences/config.ts
@@ -60,6 +60,8 @@ export const defaultPreferences: Preferences = {
     mode: 'fixed',
     menuAlign: 'start',
     showFullscreen: true,
+    showLanguage: true,
+    showNotification: true,
     theme: 'light',
   },
 
diff --git a/code/g3soft-erp/web/src/preferences/types.ts b/code/g3soft-erp/web/src/preferences/types.ts
index f25214c7..1959ed97 100644
--- a/code/g3soft-erp/web/src/preferences/types.ts
+++ b/code/g3soft-erp/web/src/preferences/types.ts
@@ -145,6 +145,10 @@ export interface HeaderPreferences {
   menuAlign: HeaderMenuAlignType
   /** 显示页面全屏按钮（整页走原生 Fullscreen API） */
   showFullscreen: boolean
+  /** 显示语言切换按钮（i18n 未接入，当前为提示占位） */
+  showLanguage: boolean
+  /** 显示消息提醒按钮（功能未实现，当前为提示占位） */
+  showNotification: boolean
   /** 顶栏主题 */
   theme: 'dark' | 'light'
 }
diff --git a/code/g3soft-erp/web/src/preferences/update-css-variables.ts b/code/g3soft-erp/web/src/preferences/update-css-variables.ts
index 2c418d0f..b4a194f6 100644
--- a/code/g3soft-erp/web/src/preferences/update-css-variables.ts
+++ b/code/g3soft-erp/web/src/preferences/update-css-variables.ts
@@ -39,7 +39,15 @@ export function applyPreferencesToCss(preferences: Preferences): void {
   const { theme, app, sidebar, header } = preferences
 
   // ---- 深色模式：给 html 加 .dark 类，样式里用 .dark { ... } 覆盖变量 ----
-  root.classList.toggle('dark', isDarkTheme(theme.mode))
+  const dark = isDarkTheme(theme.mode)
+  root.classList.toggle('dark', dark)
+
+  // 业务 token（--g3-color-*）用上面的 .dark 类；@g3soft/ui 自己的令牌
+  // （--g3-text-1 / --g3-bg-container / --g3-border-color ...）走
+  // html[data-g3-theme='dark']（见 @g3soft/tokens/scss/theme.scss）。
+  // 两条线必须一起切，否则深色下 G3 组件仍吃浅色令牌 —— 表现为表单 label、
+  // 输入框文字发黑看不见，下拉/弹窗底色依旧雪白。
+  root.dataset.g3Theme = dark ? 'dark' : 'light'
 
   // ---- 主题色 ----
   const colors: Array<[string, string]> = [
@@ -56,11 +64,13 @@ export function applyPreferencesToCss(preferences: Preferences): void {
   // 跟随主题色动态派生：选中背景 = 当前主色 + 15%/20% 透明度，
   // 这样在偏好里换主题色时，选中背景会一起变，而不是停在写死的蓝色。
   // 透明度对齐 vben：浅色 15%，深色 20%。
-  const isDark = isDarkTheme(theme.mode)
-  root.style.setProperty(
-    '--g3-color-primary-soft',
-    toColor(theme.colorPrimary, isDark ? 0.2 : 0.15),
-  )
+  root.style.setProperty('--g3-color-primary-soft', toColor(theme.colorPrimary, dark ? 0.2 : 0.15))
+
+  // ---- 主色的悬停 / 按下态（@g3soft/ui 的按钮、链接 hover/active 读这两个变量）----
+  // 组件库在 @g3soft/tokens 里给的是「种子色 + 90% / 80% 透明度」，而种子色是 #18181b（近黑）：
+  // 只覆盖 --g3-color-primary 的话，蓝色按钮 hover 会直接变成黑色。这里按同一套算法跟随主题色。
+  root.style.setProperty('--g3-color-primary-hover', toColor(theme.colorPrimary, 0.9))
+  root.style.setProperty('--g3-color-primary-active', toColor(theme.colorPrimary, 0.8))
 
   // ---- 圆角与字号 ----
   root.style.setProperty('--g3-radius-base', `${theme.radius}rem`)
@@ -78,6 +88,6 @@ export function applyPreferencesToCss(preferences: Preferences): void {
   root.style.setProperty('--g3-content-padding', `${app.contentPadding}px`)
 
   // ---- 半深色：仅浅色模式下生效，用 class 表达 ----
-  root.classList.toggle('semi-dark-header', theme.semiDarkHeader && !isDarkTheme(theme.mode))
-  root.classList.toggle('semi-dark-sidebar', theme.semiDarkSidebar && !isDarkTheme(theme.mode))
+  root.classList.toggle('semi-dark-header', theme.semiDarkHeader && !dark)
+  root.classList.toggle('semi-dark-sidebar', theme.semiDarkSidebar && !dark)
 }
diff --git a/code/g3soft-erp/web/src/router/index.ts b/code/g3soft-erp/web/src/router/index.ts
index 8e8bab18..bdd6ec10 100644
--- a/code/g3soft-erp/web/src/router/index.ts
+++ b/code/g3soft-erp/web/src/router/index.ts
@@ -3,6 +3,7 @@ import 'nprogress/nprogress.css'
 import { createRouter, createWebHistory, type RouteRecordRaw } from 'vue-router'
 
 import airRoutes from './modules/air'
+import authRoutes from './modules/auth'
 import containerRoutes from './modules/container'
 import crmRoutes from './modules/crm'
 import financeRoutes from './modules/finance'
@@ -19,6 +20,8 @@ NProgress.configure({ showSpinner: false })
 const firstMenuPath = menuItems[0]?.path ?? '/ocean'
 
 const routes: RouteRecordRaw[] = [
+  // 认证域（登录等）：顶层路由，与主框架平级、不套 DefaultLayout
+  ...authRoutes,
   {
     path: '/',
     component: () => import('@/layouts/DefaultLayout.vue'),
@@ -30,12 +33,31 @@ const routes: RouteRecordRaw[] = [
       ...financeRoutes,
       ...crmRoutes,
       ...systemRoutes,
+      // 403 / 500：作为主框架的子路由（保留侧栏/顶栏/页签，用户可直接切走），
+      // 与 fms-vue 一致（routes.js 里 /403 /500 挂在布局下）。
+      // 渲染崩溃的兜底不经过这里 —— 那由 App 层的 ErrorBoundary 全屏渲染。
+      //
+      // 页签 / 面包屑 / 文档标题统一用「403 / 500」状态码（与 URL 一一对应），
+      // 页面内的标题仍由 G3Result 按 locale 显示「无权访问 / 页面出错了」。
+      {
+        path: '/403',
+        name: 'forbidden',
+        component: () => import('@/views/fallback/Forbidden.vue'),
+        meta: { title: '403' },
+      },
+      {
+        path: '/500',
+        name: 'server-error',
+        component: () => import('@/views/fallback/ServerError.vue'),
+        meta: { title: '500' },
+      },
     ],
   },
+  // 通配 404：独立布局（无外壳），放最后
   {
     path: '/:pathMatch(.*)*',
     name: 'not-found',
-    component: () => import('@/views/error/NotFound.vue'),
+    component: () => import('@/views/fallback/NotFound.vue'),
     meta: { title: '页面不存在' },
   },
 ]
@@ -80,6 +102,26 @@ export function findMenuItemByPath(path: string): MenuItem | undefined {
   return walk(menuItems)
 }
 
+/**
+ * 在菜单树中按 key 查找菜单项（含子级）。
+ * 面包屑用它把祖先 key 链还原成「分组名称」。
+ */
+export function findMenuItemByKey(key: string): MenuItem | undefined {
+  const walk = (items: MenuItem[]): MenuItem | undefined => {
+    for (const item of items) {
+      if (item.key === key) return item
+
+      if (item.children?.length) {
+        const found = walk(item.children)
+        if (found) return found
+      }
+    }
+    return undefined
+  }
+
+  return walk(menuItems)
+}
+
 /**
  * 由当前路径反查它的所有祖先分组 key（从顶级到最近一级）。
  * 支持多级嵌套与详情页：/ocean/booking/123 会命中「海运」「订舱业务」。
diff --git a/code/g3soft-erp/web/src/router/modules/auth.ts b/code/g3soft-erp/web/src/router/modules/auth.ts
new file mode 100644
index 00000000..7f5da908
--- /dev/null
+++ b/code/g3soft-erp/web/src/router/modules/auth.ts
@@ -0,0 +1,19 @@
+import type { RouteRecordRaw } from 'vue-router'
+
+/**
+ * 认证域路由（登录 / 忘记密码 / 重置密码 / SSO 回调…）。
+ *
+ * ⚠️ 与其它 modules/*.ts 的展开位置不同：这些是**顶层**路由，与主框架平级、
+ * 不套 DefaultLayout —— 登录时还没有侧栏 / 顶栏 / 页签。
+ * 所以它们在 router/index.ts 里于顶层展开，而不是塞进 DefaultLayout 的 children。
+ */
+const authRoutes: RouteRecordRaw[] = [
+  {
+    path: '/login',
+    name: 'login',
+    component: () => import('@/views/auth/Login.vue'),
+    meta: { title: '登录' },
+  },
+]
+
+export default authRoutes
diff --git a/code/g3soft-erp/web/src/services/request.ts b/code/g3soft-erp/web/src/services/request.ts
index d6cd60a2..fb894bab 100644
--- a/code/g3soft-erp/web/src/services/request.ts
+++ b/code/g3soft-erp/web/src/services/request.ts
@@ -1,16 +1,46 @@
-import axios, { type AxiosInstance, type AxiosResponse } from 'axios'
+import axios, { type AxiosInstance, type AxiosResponse, type AxiosRequestConfig } from 'axios'
+import { G3Message } from '@g3soft/ui'
 import { API_BASE } from '@/constants/common'
 
-/** 后端统一响应结构。骨架阶段的最小契约，引擎设计确定后再扩展。 */
+/**
+ * HTTP 层：统一拆包、鉴权注入、错误提示。
+ *
+ * 设计对照 fms-vue 的 src/services/http.js，四处关键取舍一并沿用：
+ *
+ *   1. 【只有鉴权类错误才跳登录】—— 网络异常、5xx 不能把用户登出。
+ *      早先的实现（本文件上一版）在 401 时只 removeItem('token')，
+ *      既没跳转、也没清 store，用户会停在「页面看着正常但所有请求都失败」的状态。
+ *
+ *   2. 【全局性问题才自动弹提示】—— 服务端不可达 / 5xx 属全局性问题，统一弹；
+ *      4xx 业务错误交给调用方决定（不同的业务错误该有不同的展示位置与文案）。
+ *
+ *   3. 【toasted 标记去重】—— 已经自动弹过的错误打上 toasted，
+ *      调用方若自己也要提示，据此判断避免弹两次。这是 fms-vue 踩过的坑。
+ *
+ *   4. 【跳登录去重】—— 并发请求同时 401 时，只跳一次。
+ */
+
+/** 业务成功的 code 约定。 */
+const SUCCESS_CODE = 0
+
+/** 鉴权失败：HTTP 401 与业务码 401 都算。 */
+const AUTH_ERROR_CODES = new Set([401])
+
+/** 业务错误对象：带上 code / data / toasted，供调用方分支处理。 */
+export interface RequestError extends Error {
+  code: number
+  data?: unknown
+  /** 已由拦截器统一提示过，调用方不要重复弹 */
+  toasted?: boolean
+}
+
+/** 后端统一响应结构。 */
 export interface ApiResult<T = unknown> {
   code: number
   message: string
   data: T
 }
 
-/** 业务成功的 code 约定。 */
-const SUCCESS_CODE = 0
-
 const request: AxiosInstance = axios.create({
   baseURL: import.meta.env.VITE_API_BASE || API_BASE,
   timeout: 30_000,
@@ -19,7 +49,38 @@ const request: AxiosInstance = axios.create({
   },
 })
 
-// 请求拦截：附加鉴权信息
+/* ---------------- 鉴权失败处理 ---------------- */
+
+/** 跳转去重：并发请求同时 401 时只跳一次 */
+let redirectingToLogin = false
+
+/**
+ * 跳登录页，带上 redirect 参数回到原地址。
+ *
+ * 用 window.location.assign 而非 router.push：这是【会话已失效】的硬跳转，
+ * 整页重载能顺带清掉内存里所有旧状态（store、keep-alive 缓存、定时器），
+ * 比在 SPA 内软跳更干净。
+ */
+function redirectToLogin(): void {
+  const { pathname, search, hash } = window.location
+  const current = pathname.replace(/\/+$/, '') || '/'
+  if (current === '/login' || redirectingToLogin) return
+
+  redirectingToLogin = true
+  const redirect = `${pathname}${search}${hash}`
+  const query = new URLSearchParams({ redirect, reason: 'expired' })
+  window.location.assign(`/login?${query.toString()}`)
+}
+
+/** 清会话并跳登录页 */
+function handleUnauthorized(): void {
+  // 清 token（user store 尚未落地；接入后改为 userStore.clear()）
+  localStorage.removeItem('g3erp:token')
+  redirectToLogin()
+}
+
+/* ---------------- 请求拦截 ---------------- */
+
 request.interceptors.request.use(
   (config) => {
     const token = localStorage.getItem('g3erp:token')
@@ -31,34 +92,62 @@ request.interceptors.request.use(
   (error) => Promise.reject(error),
 )
 
-// 响应拦截：拆包 + 统一错误提示
+/* ---------------- 响应拦截 ---------------- */
+
 request.interceptors.response.use(
   (response: AxiosResponse<ApiResult>) => {
     const body = response.data
 
-    // 非标准响应（如文件流）直接透传
+    // 非标准响应直接透传：
+    //   - 文件流（blob）：没有 code 字段，调用方需要读 headers（Content-Disposition 里的文件名）
+    //   - 其它无 code 的响应：视为成功
     if (body == null || typeof body !== 'object' || !('code' in body)) {
       return response
     }
 
-    if (body.code !== SUCCESS_CODE) {
-      return Promise.reject(new Error(body.message || '请求失败'))
-    }
+    if (body.code === SUCCESS_CODE) return response
 
-    return response
+    if (AUTH_ERROR_CODES.has(body.code)) handleUnauthorized()
+
+    const err = new Error(body.message || '请求失败') as RequestError
+    err.code = body.code
+    err.data = body.data
+    throw err
   },
   (error) => {
-    const status = error?.response?.status
-    if (status === 401) {
-      // 骨架阶段先清 token，登录页与跳转逻辑待用户模块落地后接入
-      localStorage.removeItem('g3erp:token')
+    const status: number | undefined = error?.response?.status
+    const body = error?.response?.data as ApiResult | undefined
+    const code = body?.code ?? status ?? -1
+
+    // 仅鉴权类错误清会话跳登录；网络异常 / 5xx 不能把用户登出
+    if (AUTH_ERROR_CODES.has(code)) handleUnauthorized()
+
+    const message =
+      body?.message ||
+      (error?.code === 'ECONNABORTED' ? '请求超时，请稍后重试' : '网络异常，请检查服务是否正常')
+
+    const requestError = new Error(message) as RequestError
+    requestError.code = code
+    requestError.data = body?.data
+
+    // 服务端不可达（无 status）/ 5xx 属全局性问题，统一提示；
+    // 4xx 业务错误交由调用方决定展示方式。
+    if (!status || status >= 500) {
+      G3Message.error(message)
+      requestError.toasted = true
     }
-    return Promise.reject(error)
+
+    throw requestError
   },
 )
 
-/** 发起请求并直接拿到 data，避免每个调用点都写 res.data.data。 */
-export async function http<T = unknown>(config: Parameters<AxiosInstance['request']>[0]) {
+/**
+ * 发起请求并直接拿到 data，避免每个调用点都写 res.data.data。
+ *
+ * ⚠️ 失败时 reject 的是 RequestError（带 code / data / toasted）。
+ * 调用方若需自行提示，先判断 `err.toasted` —— 已自动提示过的不要重复弹。
+ */
+export async function http<T = unknown>(config: AxiosRequestConfig): Promise<T> {
   const response = await request.request<ApiResult<T>>(config)
   return response.data.data
 }
diff --git a/code/g3soft-erp/web/src/stores/app.ts b/code/g3soft-erp/web/src/stores/app.ts
index 1ced95c2..1ca8c786 100644
--- a/code/g3soft-erp/web/src/stores/app.ts
+++ b/code/g3soft-erp/web/src/stores/app.ts
@@ -1,5 +1,6 @@
 import { defineStore } from 'pinia'
-import { computed, ref } from 'vue'
+import { computed, ref, watch } from 'vue'
+import { usePreferencesStore } from '@/preferences'
 
 /**
  * 应用壳层状态：主题、侧栏折叠、页签、内容区局部全屏。
@@ -127,6 +128,54 @@ export const useAppStore = defineStore(
       routeRefreshKeys.value[key] = (routeRefreshKeys.value[key] ?? 0) + 1
     }
 
+    /* ---------------- 页签持久化（受 tabbar.persist 控制） ---------------- */
+
+    /**
+     * 手写读写，替代 pinia-plugin-persistedstate 的静态 persist。
+     *
+     * 时机说明：store setup 在 pinia 实例化时执行，此时可以安全地调
+     * usePreferencesStore()（preferences store 自身没有对 app store 的依赖，
+     * 无循环；且 pinia 在 main.ts 里 app.use(pinia) 之后、首个 store 使用前已就绪）。
+     *
+     * 但为了稳妥，这里用「首次 watch 时惰性读取偏好」的方式 ——
+     * watch 的回调第一次触发是在 store 挂到 pinia 之后，那时偏好 store 一定可用。
+     */
+    const prefStore = usePreferencesStore()
+
+    /** 从 localStorage 恢复页签（仅在 persist 开启时） */
+    function hydrateTabs(): void {
+      if (!prefStore.preferences.tabbar.persist) return
+      try {
+        const raw = localStorage.getItem(STORAGE_KEY)
+        if (!raw) return
+        const parsed = JSON.parse(raw) as { tabs?: TabItem[] }
+        if (Array.isArray(parsed.tabs)) {
+          tabs.value = parsed.tabs
+        }
+      } catch {
+        /* 持久化数据损坏时静默忽略，回到空页签 */
+      }
+    }
+
+    /** 把页签写回 localStorage；persist 关闭时清掉旧数据 */
+    function persistTabs(): void {
+      if (prefStore.preferences.tabbar.persist) {
+        localStorage.setItem(STORAGE_KEY, JSON.stringify({ tabs: tabs.value }))
+      } else {
+        localStorage.removeItem(STORAGE_KEY)
+      }
+    }
+
+    // 首次进入：恢复页签（若 persist 开启）
+    hydrateTabs()
+
+    // 页签变化 → 写回；偏好 persist 变化 → 立即写/清一次
+    watch(() => tabs.value, persistTabs, { deep: true })
+    watch(
+      () => prefStore.preferences.tabbar.persist,
+      () => persistTabs(),
+    )
+
     return {
       tabs,
       cachedKeys,
@@ -144,10 +193,21 @@ export const useAppStore = defineStore(
     }
   },
   {
-    // 页签是否持久化由偏好设置 tabbar.persist 决定，这里不做无条件持久化。
-    persist: {
-      key: STORAGE_KEY,
-      pick: ['tabs'],
-    },
+    // 页签是否持久化由偏好设置 tabbar.persist 决定。
+    //
+    // 为什么【不用】 pinia-plugin-persistedstate 的 persist 选项：
+    //   它的 persist 是【静态】的（boolean | PersistenceOptions | 数组），
+    //   无法在运行时根据偏好开关切换。若写死 persist: true，
+    //   用户在偏好里关掉「页签/刷新后保留」也不会生效（正是本次要修的 bug）。
+    //
+    // 所以这里【不做插件持久化】，改为在 store 内部手写读写 localStorage，
+    // 由 tabbar.persist 控制。做法：
+    //   1. 初始化时若 tabbar.persist 为 true，从 localStorage 恢复 tabs；
+    //   2. watch tabs，persist 为 true 时写回，false 时【清除】已存的旧数据，
+    //      避免「关了开关，旧页签下次还冒出来」。
+    //
+    // 读取偏好用 usePreferencesStore：它自身也是 pinia store、且不依赖 app store，
+    // 无循环依赖。但 store setup 里不能直接调 usePreferencesStore（会在 pinia 激活前
+    // 实例化），所以持久化的读写逻辑放到一个懒初始化的 watch 里。
   },
 )
diff --git a/code/g3soft-erp/web/src/views/auth/Login.vue b/code/g3soft-erp/web/src/views/auth/Login.vue
new file mode 100644
index 00000000..9170413e
--- /dev/null
+++ b/code/g3soft-erp/web/src/views/auth/Login.vue
@@ -0,0 +1,600 @@
+<script setup lang="ts">
+import { computed, reactive, ref } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+import { Languages, Lock, Moon, Sun, User } from '@lucide/vue'
+import {
+  G3Button,
+  G3Checkbox,
+  G3Form,
+  G3FormItem,
+  G3Input,
+  G3Message,
+  G3SliderCaptcha,
+} from '@g3soft/ui'
+
+import { APP_TITLE } from '@/constants/common'
+import { usePreferencesStore } from '@/preferences'
+
+/**
+ * 登录页。
+ *
+ * 结构照抄 vue-vben-admin 的认证壳（packages/effects/layouts/src/authentication）：
+ *   - 左侧 slogan 面板：bg-background-deep + 模糊光晕 + 浮动插画 + 标题/描述，lg（1024px）以下隐藏
+ *   - 右侧表单面板：px-6 py-10（lg:px-8）、内容 md:max-w-md、垂直水平居中，底部绝对定位版权
+ *   - 左上角 logo + 应用名、右上角 bg-accent 圆角药丸工具条
+ * 表单卡片细节（标题/副标题/纵向表单/底部版权）参考 fms-vue 的 src/views/login/index.vue。
+ *
+ * ⚠️ 登录接口与用户模块尚未落地：提交只做前端校验后进系统，鉴权 / 路由守卫待后续接入。
+ */
+defineOptions({ name: 'Login' })
+
+const router = useRouter()
+const route = useRoute()
+const prefStore = usePreferencesStore()
+
+/** 表单数据：接入接口后直接作为请求参数 */
+const formModel = reactive({
+  username: '',
+  password: '',
+  captcha: false,
+})
+
+/** 记住我：默认勾选，对照 vben 的 rememberMe（是否落本地存储待接口接入后定） */
+const rememberMe = ref(true)
+
+/** 主题跟随偏好设置：mode 为 auto 时由 store 按系统偏好解析 */
+const isDark = computed(() => prefStore.isDark)
+
+/**
+ * 切换主题：与顶栏 LayoutHeader 同一套逻辑 ——
+ * mode 是 'auto' 时按当前实际明暗收敛到 'dark' / 'light'，
+ * 避免「auto → 点一下变 light（却看不到变化）」的困惑。
+ */
+function toggleTheme(): void {
+  prefStore.update({ theme: { mode: isDark.value ? 'light' : 'dark' } })
+}
+
+/** 语言：项目尚未引入 i18n，先给提示占位（与 fms-vue 登录页的做法一致） */
+function toggleLang(): void {
+  G3Message.info('语言切换待接入 i18n 后生效')
+}
+
+/** 必填规则：G3Form 的声明式配置，纯前端校验（校验失败时按钮不会触发 submit） */
+const formRules = {
+  username: [{ required: true, message: '请输入账号' }],
+  password: [{ required: true, message: '请输入密码' }],
+  captcha: [{ validator: (value: unknown) => value === true, message: '请完成滑块验证' }],
+}
+
+/**
+ * 提交：G3Form 校验通过后先直接进系统。
+ *
+ * TODO 用户模块落地后替换：调登录接口 → 写用户 store → 拉起权限 → 再跳转；
+ *      失败时提示并清空密码；未登录访问内页由 router 守卫重定向回本页
+ *      （redirect 参数就是守卫带过来的原目标地址）。
+ */
+function onSubmit(): void {
+  const redirect = route.query.redirect
+  router.replace(typeof redirect === 'string' && redirect ? redirect : '/')
+}
+</script>
+
+<template>
+  <div class="login">
+    <!-- 装饰光晕：照搬 vben authentication.vue 的 .login-background（154deg 渐变 + blur(100px)） -->
+    <div class="login__glow" aria-hidden="true"></div>
+
+    <!-- 左上角 logo + 应用名（vben 认证壳的 logo 槽位：absolute top-0 left-0 + mt-4 ml-4） -->
+    <div class="login__logo">
+      <span class="login__logo-mark">G3</span>
+      <span class="login__logo-text">{{ APP_TITLE }}</span>
+    </div>
+
+    <!-- 右上角工具条（vben Toolbar：bg-accent 药丸容器 + 语言 / 主题按钮） -->
+    <div class="login__toolbar">
+      <button class="login__toolbar-btn" type="button" title="切换语言" @click="toggleLang">
+        <Languages :size="16" />
+      </button>
+      <button
+        class="login__toolbar-btn"
+        type="button"
+        :title="isDark ? '切换为浅色' : '切换为深色'"
+        @click="toggleTheme"
+      >
+        <Sun v-if="isDark" :size="16" />
+        <Moon v-else :size="16" />
+      </button>
+    </div>
+
+    <!-- 左侧 slogan 面板：lg 以下整块隐藏，窄屏只留表单 -->
+    <section class="login__slogan">
+      <svg class="login__art" viewBox="0 0 320 240" fill="none" aria-hidden="true">
+        <!-- 主窗口 -->
+        <rect
+          x="24"
+          y="28"
+          width="272"
+          height="184"
+          rx="14"
+          fill="var(--g3-color-bg-container, #fff)"
+          stroke="var(--g3-color-border, #e5e6eb)"
+        />
+        <!-- 顶部栏 -->
+        <path
+          d="M24 42a14 14 0 0 1 14-14h244a14 14 0 0 1 14 14v14H24V42Z"
+          fill="var(--g3-color-accent, #f2f3f5)"
+        />
+        <circle cx="44" cy="49" r="4" fill="var(--g3-color-primary, #165dff)" opacity="0.9" />
+        <rect
+          x="56"
+          y="46"
+          width="52"
+          height="6"
+          rx="3"
+          fill="var(--g3-color-text-tertiary, #86909c)"
+          opacity="0.5"
+        />
+        <!-- 左侧菜单列 -->
+        <rect
+          x="24"
+          y="56"
+          width="76"
+          height="156"
+          fill="var(--g3-color-accent, #f2f3f5)"
+          opacity="0.6"
+        />
+        <rect
+          x="38"
+          y="74"
+          width="48"
+          height="8"
+          rx="4"
+          fill="var(--g3-color-primary, #165dff)"
+          opacity="0.55"
+        />
+        <rect
+          x="38"
+          y="94"
+          width="40"
+          height="8"
+          rx="4"
+          fill="var(--g3-color-text-tertiary, #86909c)"
+          opacity="0.35"
+        />
+        <rect
+          x="38"
+          y="114"
+          width="44"
+          height="8"
+          rx="4"
+          fill="var(--g3-color-text-tertiary, #86909c)"
+          opacity="0.35"
+        />
+        <rect
+          x="38"
+          y="134"
+          width="36"
+          height="8"
+          rx="4"
+          fill="var(--g3-color-text-tertiary, #86909c)"
+          opacity="0.35"
+        />
+        <!-- 内容区：标题 + 数据卡片 -->
+        <rect
+          x="116"
+          y="74"
+          width="84"
+          height="10"
+          rx="5"
+          fill="var(--g3-color-text, #1f2329)"
+          opacity="0.25"
+        />
+        <rect
+          x="116"
+          y="92"
+          width="56"
+          height="8"
+          rx="4"
+          fill="var(--g3-color-text-tertiary, #86909c)"
+          opacity="0.35"
+        />
+        <rect
+          x="116"
+          y="116"
+          width="76"
+          height="48"
+          rx="8"
+          fill="var(--g3-color-primary, #165dff)"
+          opacity="0.14"
+        />
+        <rect
+          x="200"
+          y="116"
+          width="76"
+          height="48"
+          rx="8"
+          fill="var(--g3-color-primary, #165dff)"
+          opacity="0.22"
+        />
+        <rect
+          x="116"
+          y="176"
+          width="160"
+          height="20"
+          rx="6"
+          fill="var(--g3-color-accent, #f2f3f5)"
+        />
+        <!-- 悬浮指标卡 -->
+        <rect
+          x="228"
+          y="20"
+          width="84"
+          height="56"
+          rx="10"
+          fill="var(--g3-color-bg-container, #fff)"
+          stroke="var(--g3-color-border, #e5e6eb)"
+        />
+        <rect
+          x="242"
+          y="34"
+          width="40"
+          height="7"
+          rx="3.5"
+          fill="var(--g3-color-text-tertiary, #86909c)"
+          opacity="0.45"
+        />
+        <rect
+          x="242"
+          y="50"
+          width="56"
+          height="10"
+          rx="5"
+          fill="var(--g3-color-primary, #165dff)"
+          opacity="0.7"
+        />
+      </svg>
+
+      <p class="login__slogan-title">{{ APP_TITLE }} 企业管理平台</p>
+      <p class="login__slogan-desc">海运 / 空运 / 集装箱 / 财务 / CRM 一体化协同</p>
+    </section>
+
+    <!-- 右侧表单面板 -->
+    <section class="login__panel">
+      <div class="login__form">
+        <!-- 标题块：对照 vben auth-title.vue（h2 30px/36px 粗体 → lg 36px，描述 14px → lg 16px，下间距 28px） -->
+        <header class="login__heading">
+          <h2 class="login__heading-title">欢迎回来 👋🏻</h2>
+          <p class="login__heading-desc">请输入您的账号和密码登录系统</p>
+        </header>
+
+        <!-- 纵向表单：label 在上、控件在下，与 fms-vben 登录页一致。
+             requiredMark 保持默认（开），账号 / 密码这类「规则里写了 required」的字段会带红色星号；
+             滑块项没有 label 行，不会出现星号。 -->
+        <G3Form
+          class="login__fields"
+          :model="formModel"
+          :rules="formRules"
+          layout="vertical"
+          label-align="left"
+          :gap="20"
+          @submit="onSubmit"
+        >
+          <G3FormItem name="username" label="账号">
+            <G3Input
+              v-model="formModel.username"
+              placeholder="请输入账号"
+              autocomplete="username"
+              :maxlength="32"
+            >
+              <template #prefix><User :size="16" /></template>
+            </G3Input>
+          </G3FormItem>
+
+          <G3FormItem name="password" label="密码">
+            <!-- type="password" 时 G3Input 自带「显示 / 隐藏密码」按钮，无需自绘 -->
+            <G3Input
+              v-model="formModel.password"
+              type="password"
+              placeholder="请输入密码"
+              autocomplete="current-password"
+              :maxlength="32"
+            >
+              <template #prefix><Lock :size="16" /></template>
+            </G3Input>
+          </G3FormItem>
+
+          <!-- 滑块验证：@g3soft/ui 的 G3SliderCaptcha（v-model 布尔值，拖到位即通过）。
+               容器高 40px，这里用 size="large" 与输入框对齐；文案取语言包，不用手写。 -->
+          <G3FormItem name="captcha">
+            <G3SliderCaptcha v-model="formModel.captcha" size="large" />
+          </G3FormItem>
+
+          <!-- 记住我：对照 vben login.vue 的 rememberMe 行 -->
+          <div class="login__options">
+            <G3Checkbox v-model="rememberMe" name="rememberMe">记住我</G3Checkbox>
+          </div>
+
+          <!-- html-type="submit"：点击与回车都走 G3Form 的 submit，校验通过后交给 onSubmit -->
+          <G3Button class="login__submit" type="primary" size="large" block html-type="submit">
+            登录
+          </G3Button>
+        </G3Form>
+      </div>
+
+      <!-- 版权：对照 vben form.vue 的 absolute bottom-3 right-0 left-0 居中 -->
+      <p class="login__copyright">Copyright © 2026 G3Soft</p>
+    </section>
+  </div>
+</template>
+
+<style lang="scss" scoped>
+/* ===========================================================================
+ * 登录页样式
+ *
+ * 尺寸换算自 vue-vben-admin 的 tailwind 类（1 单位 = 4px）：
+ *   slogan 面板 hidden lg:block / flex-1         → 1024px 断点
+ *   表单面板 px-6 py-10 lg:px-8                  → 24px/40px → 32px
+ *   表单容器 md:max-w-md                          → 448px
+ *   h2 text-3xl/9 lg:text-4xl                     → 30px/36px → 36px
+ *   toolbar top-4 right-2 rounded-3xl px-3 py-1   → 16px/8px, 24px, 12px/4px
+ *   copyright absolute bottom-3                   → 12px
+ * 配色一律用本项目 token（--g3-*），浅色 / 深色随 :root / .dark 自动切换。
+ * =========================================================================== */
+
+.login {
+  position: relative;
+  display: flex;
+  min-height: 100svh;
+  overflow: hidden;
+  background: var(--g3-color-bg, #f5f6f8);
+  color: var(--g3-color-text, #1f2329);
+}
+
+/* ---- 装饰光晕：只在左侧 slogan 区出现，向右自然淡出 ---- */
+.login__glow {
+  position: absolute;
+  inset: 0 50% 0 0;
+  background: linear-gradient(
+    154deg,
+    rgb(7 7 9 / 8%) 30%,
+    color-mix(in srgb, var(--g3-color-primary, #165dff) 30%, transparent) 48%,
+    rgb(7 7 9 / 8%) 64%
+  );
+  filter: blur(100px);
+  pointer-events: none;
+}
+
+/* ---- 左上角品牌区 ---- */
+.login__logo {
+  position: absolute;
+  top: 16px;
+  left: 16px;
+  z-index: 10;
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  user-select: none;
+}
+
+.login__logo-mark {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  width: 36px;
+  height: 36px;
+  font-size: 14px;
+  font-weight: 700;
+  color: #fff;
+  background: var(--g3-color-primary, #165dff);
+  border-radius: 8px;
+}
+
+.login__logo-text {
+  margin: 0;
+  font-size: 20px;
+  font-weight: 500;
+  color: var(--g3-color-text, #1f2329);
+  white-space: nowrap;
+}
+
+/* ---- 右上角工具条 ---- */
+.login__toolbar {
+  position: absolute;
+  top: 16px;
+  right: 8px;
+  z-index: 10;
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  padding: 4px 12px;
+  background: var(--g3-color-accent, #f2f3f5);
+  border-radius: 24px;
+}
+
+.login__toolbar-btn {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 4px;
+  height: 28px;
+  padding: 0 6px;
+  font-size: 14px;
+  color: var(--g3-color-text-secondary, #4e5969);
+  cursor: pointer;
+  background: none;
+  border: 0;
+  border-radius: 6px;
+
+  &:hover {
+    color: var(--g3-color-text, #1f2329);
+    background: var(--g3-color-fill-hover, rgb(0 0 0 / 4%));
+  }
+}
+
+/* ---- 左侧 slogan ---- */
+.login__slogan {
+  display: none;
+  flex: 1 1 0;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  min-width: 0;
+  padding: 48px;
+  user-select: none;
+}
+
+.login__art {
+  width: 40%;
+  max-width: 320px;
+  height: auto;
+  animation: login-float 6s ease-in-out infinite;
+}
+
+.login__slogan-title {
+  margin: 24px 0 0;
+  font-size: 24px;
+  font-weight: 600;
+  color: var(--g3-color-text, #1f2329);
+  text-align: center;
+}
+
+.login__slogan-desc {
+  margin: 8px 0 0;
+  font-size: 14px;
+  color: var(--g3-color-text-secondary, #4e5969);
+  text-align: center;
+}
+
+/* ---- 右侧表单面板 ---- */
+.login__panel {
+  position: relative;
+  display: flex;
+  flex: 1 1 0;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  min-width: 0;
+  padding: 40px 24px;
+  background: var(--g3-color-bg-container, #fff);
+}
+
+.login__form {
+  width: 100%;
+  max-width: 448px;
+
+  /* 输入框与按钮统一 40px 高（G3 组件的控件高度令牌），避免一大一小 */
+  --g3-control-height: 40px;
+}
+
+/* ---- 标题块 ---- */
+.login__heading {
+  margin-bottom: 28px;
+}
+
+.login__heading-title {
+  margin: 0 0 12px;
+  font-size: 30px;
+  font-weight: 700;
+  line-height: 36px;
+  letter-spacing: -0.025em;
+  color: var(--g3-color-text, #1f2329);
+}
+
+.login__heading-desc {
+  margin: 0;
+  font-size: 14px;
+  color: var(--g3-color-text-secondary, #4e5969);
+}
+
+/* ---- 表单 ---- */
+.login__fields {
+  width: 100%;
+}
+
+/* 输入框前缀图标：次要色，和控件文字拉开层次 */
+.login__fields :deep(.g3-input__prefix) {
+  color: var(--g3-color-text-tertiary, #86909c);
+}
+
+/* 纵向表单项的 label ↔ 控件间距：组件库默认 4px（--g3-space-1）是为 32px 的紧凑控件配的，
+   登录页控件高 40px，这里提到 8px（--g3-space-2，与横向布局同档），
+   顺带把「label 与错误提示都离控件 4px」的层级感拉开。 */
+.login__fields :deep(.g3-form-item--vertical) {
+  gap: var(--g3-space-2, 8px);
+}
+
+/* ---- 记住我 ---- */
+.login__options {
+  display: flex;
+  align-items: center;
+}
+
+.login__submit {
+  width: 100%;
+  font-size: 15px;
+}
+
+/* ---- 版权 ---- */
+.login__copyright {
+  position: absolute;
+  right: 0;
+  bottom: 12px;
+  left: 0;
+  margin: 0;
+  font-size: 12px;
+  color: var(--g3-color-text-secondary, #4e5969);
+  text-align: center;
+}
+
+/* 插画轻微上下浮动（对照 vben 的 animate-float） */
+@keyframes login-float {
+  0%,
+  100% {
+    transform: translateY(0);
+  }
+
+  50% {
+    transform: translateY(-12px);
+  }
+}
+
+/* 窄屏：只留表单，左右内边距收紧 */
+@media (max-width: 767px) {
+  .login__panel {
+    padding: 40px 20px;
+  }
+
+  .login__logo-text {
+    display: none;
+  }
+}
+
+/* 大屏：slogan 面板登场并加宽左右内边距（lg:px-8） */
+@media (min-width: 1024px) {
+  .login__slogan {
+    display: flex;
+  }
+
+  /* 表单面板固定占 2/5（对照 vben 表单面板的 w-2/5），剩下 3/5 全给左侧 slogan ——
+     两边都用 flex:1 会平分 50/50，左侧就不够宽了 */
+  .login__panel {
+    flex: 0 0 40%;
+    padding: 40px 32px;
+  }
+
+  .login__heading-title {
+    font-size: 36px;
+  }
+
+  .login__heading-desc {
+    font-size: 16px;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .login__art {
+    animation: none;
+  }
+}
+</style>
diff --git a/code/g3soft-erp/web/src/views/error/NotFound.vue b/code/g3soft-erp/web/src/views/error/NotFound.vue
deleted file mode 100644
index 8b5cdc12..00000000
--- a/code/g3soft-erp/web/src/views/error/NotFound.vue
+++ /dev/null
@@ -1,42 +0,0 @@
-<script setup lang="ts">
-import { FileQuestionMark } from '@lucide/vue'
-</script>
-
-<template>
-  <div class="not-found">
-    <FileQuestionMark :size="40" />
-    <h2 class="not-found__title">404</h2>
-    <p class="not-found__desc">页面不存在或已被移除</p>
-    <RouterLink class="not-found__link" to="/">返回首页</RouterLink>
-  </div>
-</template>
-
-<style lang="scss" scoped>
-.not-found {
-  display: flex;
-  flex-direction: column;
-  align-items: center;
-  justify-content: center;
-  gap: 8px;
-  height: 100%;
-  color: var(--g3-color-text-secondary, #4e5969);
-
-  &__title {
-    margin: 0;
-    font-size: 28px;
-    font-weight: 600;
-    color: var(--g3-color-text, #1f2329);
-  }
-
-  &__desc {
-    margin: 0;
-    font-size: 14px;
-  }
-
-  &__link {
-    margin-top: 8px;
-    font-size: 14px;
-    color: var(--g3-color-primary, #165dff);
-  }
-}
-</style>
diff --git a/code/g3soft-erp/web/src/views/fallback/ErrorBoundary.vue b/code/g3soft-erp/web/src/views/fallback/ErrorBoundary.vue
new file mode 100644
index 00000000..69029052
--- /dev/null
+++ b/code/g3soft-erp/web/src/views/fallback/ErrorBoundary.vue
@@ -0,0 +1,27 @@
+<script setup lang="ts">
+import { onErrorCaptured, ref } from 'vue'
+import FallbackPage from './FallbackPage.vue'
+
+/**
+ * 渲染错误边界：捕获子树（布局 + 页面）的未处理错误，就地渲染 500 缺省页，替代白屏。
+ *
+ * 移植自 fms-vue 的 src/views/fallback/ErrorBoundary.vue。
+ * 500 页的「重新加载」按钮即恢复手段（整页刷新重置一切状态）。
+ *
+ * onErrorCaptured 返回 false 的语义：
+ *   标记该错误「已处理」，阻止它继续向上冒泡到 app.config.errorHandler。
+ *   但这里仍保留 console.error —— 兜底页只是让用户不白屏，排查线索不能丢。
+ */
+const hasError = ref(false)
+
+onErrorCaptured((error) => {
+  hasError.value = true
+  console.error('[ErrorBoundary]', error)
+  return false
+})
+</script>
+
+<template>
+  <FallbackPage v-if="hasError" status="500" />
+  <slot v-else />
+</template>
diff --git a/code/g3soft-erp/web/src/views/fallback/FallbackPage.vue b/code/g3soft-erp/web/src/views/fallback/FallbackPage.vue
new file mode 100644
index 00000000..8292a77a
--- /dev/null
+++ b/code/g3soft-erp/web/src/views/fallback/FallbackPage.vue
@@ -0,0 +1,70 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import { useRouter } from 'vue-router'
+import { ArrowLeft, RefreshCw } from '@lucide/vue'
+import { G3Button, G3Result, type ResultStatus } from '@g3soft/ui'
+
+/**
+ * 缺省页（403 / 404 / 500 / 离线）—— 应用层的薄包装。
+ *
+ * 分工（这是本次拆分的核心）：
+ *   @g3soft/ui 的 G3Result  —— 只管「插图 + 标题 + 描述 + 操作区」的呈现，
+ *                              文案走 locale，不碰路由。
+ *   本组件                  —— 只管【应用约定】：哪个状态配哪个按钮、
+ *                              按钮点了跳到哪 / 要不要刷新。
+ *
+ * 之前插图与文案都写在这里，现在它们下沉到了组件库；
+ * 本文件剩下的都是「只有本应用才知道」的东西。
+ *
+ * 按钮分工照 fms-vue / vben：
+ *   403 / 404 → 「返回首页」（用户走错路了，需要回到正轨）
+ *   500 / 离线 → 「重新加载」（整页刷新就是恢复手段）
+ */
+const props = withDefaults(
+  defineProps<{
+    /** 缺省页类型 */
+    status?: Extract<ResultStatus, '403' | '404' | '500' | 'offline'>
+    /** 403 / 404 的返回目标 */
+    homePath?: string
+  }>(),
+  {
+    status: '404',
+    homePath: '/',
+  },
+)
+
+const router = useRouter()
+
+/** 哪些状态用「返回首页」，其余用「重新加载」—— 应用级约定 */
+const isHome = computed(() => props.status === '403' || props.status === '404')
+const actionText = computed(() => (isHome.value ? '返回首页' : '重新加载'))
+
+function onAction(): void {
+  if (isHome.value) {
+    router.push(props.homePath)
+  } else {
+    // 整页刷新即恢复手段：重置所有内存状态（store、keep-alive 缓存、定时器）
+    window.location.reload()
+  }
+}
+</script>
+
+<template>
+  <!--
+    高度说明：G3Result 内部用 min-height: 100%（不是 100vh），
+    因为本组件同时挂在两种容器里 ——
+      独立路由（404）：外层是 #app（height:100%），100% 即视口高；
+      布局内（403/500）：外层是 .layout__content，100vh 会撑出滚动条，100% 正好吃满。
+    一种写法覆盖两种场景，这里不必再补样式。
+  -->
+  <G3Result :status="props.status">
+    <template #extra>
+      <G3Button type="primary" @click="onAction">
+        <template #icon>
+          <component :is="isHome ? ArrowLeft : RefreshCw" :size="16" />
+        </template>
+        {{ actionText }}
+      </G3Button>
+    </template>
+  </G3Result>
+</template>
diff --git a/code/g3soft-erp/web/src/views/fallback/Forbidden.vue b/code/g3soft-erp/web/src/views/fallback/Forbidden.vue
new file mode 100644
index 00000000..879f7daa
--- /dev/null
+++ b/code/g3soft-erp/web/src/views/fallback/Forbidden.vue
@@ -0,0 +1,15 @@
+<script setup lang="ts">
+import FallbackPage from './FallbackPage.vue'
+
+/**
+ * 403 缺省页，挂在 DefaultLayout 内（保留侧栏 / 顶栏 / 页签，用户可直接切走）。
+ *
+ * ⚠️ status 在组件内写死，不走路由 props：
+ * DefaultLayout 的 keep-alive 包装（formatComponentInstance）只把 fullPath 透给组件，
+ * 路由的 props 配置不会到达页面组件 —— 与 fms-vue 同样的约束。
+ */
+</script>
+
+<template>
+  <FallbackPage status="403" />
+</template>
diff --git a/code/g3soft-erp/web/src/views/fallback/NotFound.vue b/code/g3soft-erp/web/src/views/fallback/NotFound.vue
new file mode 100644
index 00000000..c10aa5aa
--- /dev/null
+++ b/code/g3soft-erp/web/src/views/fallback/NotFound.vue
@@ -0,0 +1,12 @@
+<script setup lang="ts">
+import FallbackPage from './FallbackPage.vue'
+
+/**
+ * 404 缺省页，独立路由（不套 DefaultLayout）。
+ * 走通配路由 `/:pathMatch(.*)*`，所以能覆盖任意未匹配路径。
+ */
+</script>
+
+<template>
+  <FallbackPage status="404" />
+</template>
diff --git a/code/g3soft-erp/web/src/views/fallback/ServerError.vue b/code/g3soft-erp/web/src/views/fallback/ServerError.vue
new file mode 100644
index 00000000..9823294f
--- /dev/null
+++ b/code/g3soft-erp/web/src/views/fallback/ServerError.vue
@@ -0,0 +1,12 @@
+<script setup lang="ts">
+import FallbackPage from './FallbackPage.vue'
+
+/**
+ * 500 缺省页，挂在 DefaultLayout 内供直接访问排查。
+ * 渲染崩溃的兜底由 App 层的 ErrorBoundary 全屏渲染，不经过本路由。
+ */
+</script>
+
+<template>
+  <FallbackPage status="500" />
+</template>
diff --git a/code/g3soft-libs/.changeset/attachment.md b/code/g3soft-libs/.changeset/attachment.md
new file mode 100644
index 00000000..72759847
--- /dev/null
+++ b/code/g3soft-libs/.changeset/attachment.md
@@ -0,0 +1,18 @@
+---
+'@g3soft/ui': minor
+---
+
+新增 `G3Attachment` 附件管理器（分类 / 列表 / 预览三栏）。
+
+**与业务解耦**：组件不发任何请求，只消费 `files` + `categories` 两份数据，用户意图全部以事件抛出；需要组件代跑请求时传 `uploadRequest` / `removeRequest`。
+
+- 布局走 `G3Splitter`：默认「分类 200 + 列表自适应」两栏；`showPreview`（默认 `false`）打开后追加 360 的预览栏。`showCategory` / `showPreview` 为假时对应面板不渲染；预览栏关掉时 `preview` 事件照常抛出，业务可自行开弹窗。
+- 分类用 `G3Tree`，在传入的 `categories` 之上合成「全部」根节点（对外用 `categoryKey === ''` 表示），`categoryChange` 会把原始分类对象一并带出。
+- 上传三条入口：底栏选择、拖拽、`pasteUpload`（opt-in，默认关，避免多实例抢 `document`）。入队前按 `accept` / `maxSize` / `maxCount` 校验，被拒文件走 `invalid` 事件（`info.message` 已按语言包生成）。
+- 待上传队列在列表最前面渲染（带「待上传」标记）；未传 `uploadRequest` 时点上传即抛 `upload` 并清空队列（所有权移交业务），传了则托管请求、失败保留队列可重试。blob 预览地址由组件统一释放。
+- 多选批量下载 / 删除；删除内建确认 `Modal`（`confirmRemove` 可关，不使用命令式 `Modal.confirm`，避免依赖全局挂载容器）；下载默认按 `item.url` 内建触发（`builtinDownload` 可关）。
+- 分页：未传 `total` 视为客户端分页（组件切片），传了则为服务端分页（`files` 即当前页）；`page` / `pageSize` 非受控，不传时组件内部维护。
+- 字段名中性（`id` / `name` / `size` / `ext` / `url` / `categoryId`），业务字段走 `item.raw` 原样回传；文件族配色映射到 `--g3-color-danger` / `success` / `warning` / `primary`，并留 `--g3-attachment-type-*` 供主题覆盖。
+- 视觉与交互按当前设计语言落地：尺寸 / 间距 / 圆角 / 过渡全部走令牌；工具栏整行统一 12px 字 / 24px 控件、高度写死并用 1px 竖线分组，窄面板（容器查询）下文字收成图标，勾选前后高度恒定；操作默认藏在 hover / `:focus-within` 里（`@media (hover: none)` 常显）；空态就是虚线投放区并顺带写明 `accept` / `maxSize` / `maxCount` 限制；待上传队列非空时底栏整块染主色淡底（脏状态）；上传与分页合成一块，不再出现两条并排分隔线；卡片封面用 `aspect-ratio` + `object-fit: cover`，封面底边是 2px 上传进度条；面板之间的分割线常显且收成 1px。
+- 语言包新增 `attachment` 分组（zh-CN / en-US）：**自定义 `Locale` 对象的项目需要补上这一组**，否则类型不完整。
+- 附单测（`src/attachment/Attachment.test.ts` 组件契约 + `file.test.ts` 纯函数）与文档 / 4 个示例，文档见 `docs/content/ui/data/attachment.md`。
diff --git a/code/g3soft-libs/.changeset/form-item-vertical-stretch.md b/code/g3soft-libs/.changeset/form-item-vertical-stretch.md
new file mode 100644
index 00000000..e12fe452
--- /dev/null
+++ b/code/g3soft-libs/.changeset/form-item-vertical-stretch.md
@@ -0,0 +1,5 @@
+---
+'@g3soft/ui': patch
+---
+
+修复 `FormItem` 纵向布局下控件区不撑满：`.g3-form-item--vertical` 只改了 `flex-direction`，没有重置基础类的 `align-items: flex-start`（那是给横向布局写的），于是控件区按内容宽度收缩 —— 表现为 `layout="vertical"` 的输入框只有十几个字符宽。现在纵向布局显式 `align-items: stretch`。
diff --git a/code/g3soft-libs/.changeset/rich-text-format.md b/code/g3soft-libs/.changeset/rich-text-format.md
new file mode 100644
index 00000000..14216ce6
--- /dev/null
+++ b/code/g3soft-libs/.changeset/rich-text-format.md
@@ -0,0 +1,44 @@
+---
+'@g3soft/ui': minor
+---
+
+`RichText` 工具条补齐对齐与颜色，表格操作栏收敛为结构操作；修复内容区空白处点不聚焦。
+
+**新增（聚焦反馈）**
+
+- 编辑器获得焦点时，**正文区**四周亮起 2px 主色描边（工具条不参与，参考 TinyMCE 给 `.tox-edit-area` 做的激活反馈）。用 `inset box-shadow` + `border-radius`（与外框 1px 边框同心）实现：不参与布局所以聚焦不会挤动正文，且滚动容器的阴影不随内容滚动 —— 换成 `::after` 覆盖层滚一下就跟着正文跑掉了。触发条件取根节点的 `:focus-within`，这样点工具条按钮（焦点临时落在按钮上）描边不会闪。
+
+**修复**
+
+- 内容区（`.g3-rich-text__content`）里只有可编辑区那一小块能点：`.tiptap` 原本写的 `min-height: inherit` 继承的是 EditorContent 那层包裹 DOM 的 computed 值（恒为 0，与 `minHeight` / `maxHeight` 无关），于是空文档时 200px 的内容区里只有约 45px 能点，下方全是「点上去既不聚焦也不落光标」的死区。现改为两层都用 `flex: 1 0 auto` 撑满：内容短时整块都是可编辑区，内容长时按内容撑开、由内容区滚动（不裁切）；另外落在编辑器 DOM 之外的 `mousedown` 会兜底聚焦并把光标放到正文末尾（宿主样式改坏撑高时也有效）。
+
+**新增（工具条）**
+
+- 对齐：左 / 居中 / 右三个按钮（`@tiptap/extension-text-align`，作用于 `paragraph` / `heading`）。用 `toggleTextAlign`，再点当前档位即取消对齐，不需要额外的「取消」按钮。
+- 字体颜色 / 背景颜色：两个取色按钮（图标 + 当前色条）。面板给出预设色板一屏、`无颜色` 清除属性、系统取色器选任意色；取色后面板自动收起，两个面板不会同时打开。
+- 工具条与正文之间改为双层柔和投影（`0 2px 2px -2px` + `0 8px 8px -4px`，观感对齐 TinyMCE），同时去掉原来的 1px `border-bottom`（线会把投影的起笔压死）；投影颜色抽成 `--g3-rich-text-toolbar-shadow-near/-far` 两个局部变量便于调深浅。工具条 `position: relative; z-index: 1` 抬在正文之上，内容滚到工具条下沿时投影不会被正文盖住；`toolbar="bottom"` 时两层投影翻到上方。
+
+**调整（工具条）**
+
+- **图标分量**：图标 16px、描边保持 lucide 原生粗细，前景从 ghost 默认的 `text-2`（65% 黑）提到 `text-1`（88%）—— 实测「发虚」的主因是浅灰前景而不是线宽，只加深颜色、不加重描边（试过描边 2.5 与放大到 24px，都偏重）。工具条与表格操作栏一起改，保持同一分量。
+- **重排**：撤销 / 重做移到最前（历史先于格式），正文格式下拉紧接其后；按钮 32px（等于 `--g3-control-height`）、组内间隙 4px、内边距 8px / 10px（左右 10px 让首列图标与正文的 12px 内边距对齐），高度 36 → 48px。
+- **字体 / 字号收进 `⋯ 更多`**：改为二级菜单（`字体` / `字号`），选中态跟随光标，工具条上不再有那两个会随内容改宽度的下拉。另收起删除线 / 上标 / 下标 / 引用（`格式` 组）与视频（`插入` 组）；表格插入按钮仍留在工具条（要先选行列）。自然宽度从 928px 降到 **744px**：760px 以上的容器都是一行。
+- **`⋯` 菜单**带分组标题、快捷键提示与选中态，与工具条共用同一份 `ToolButton` 定义。
+
+**调整（G3Dropdown）**
+
+- 菜单面板上限从写死的 `256px` 改为**按视口算**：`--g3-dropdown-max-height` 兜底 `calc(100vh - 48px)`。256px 只够放 8 个菜单项，10 项的操作菜单就会在面板内部出滚动条（富文本 `⋯` 菜单 295px 即如此）。现在菜单随内容长、长到屏幕放不下才滚，短菜单不再无谓地滚。
+- 新增 `menuMaxHeight?: boolean | number | string` 按实例调整：`false` 不限制、数字按 px、字符串原样（如 `'320px'` / `'min(480px, 70vh)'`）、不传/`true` 用默认；子菜单沿用同一个值。面板 Teleport 到 body，调用方没法用 CSS 局部覆盖那个变量，所以要按实例控制只能靠它。注意 `withDefaults` 里显式写了 `default: undefined` —— 类型含 `boolean` 时 Vue 会把缺省值转成 `false`（正好等于「不限制」），不写就改掉了默认行为。
+
+**修复（G3Dropdown 子菜单）**
+
+- 鼠标点击子菜单项此前**完全无效**：`useFloating` 在 `document` 的 pointerdown **捕获阶段**判定「点击外部」，而子菜单面板 Teleport 到 body、不在父面板 DOM 里 → 父浮层先关闭，子项的 `click` 永远收不到（键盘路径同理）。现给 `Popover` 增加 `popupScope`（同一条浮层链的标识），Dropdown 的根面板与各级子菜单带上同一个值，链内面板不再算外部点击。回归用例见 `packages/ui/src/dropdown/DropdownSubmenu.test.ts`（此前只覆盖 hover 高亮与根层键盘导航，所以漏了这条）。
+
+**调整（表格操作栏）**
+
+- 移除单元格左 / 中 / 右对齐与「取消单元格对齐」——单元格内容是 `paragraph`，对齐统一走顶部工具条（文档已注明）。
+- 移除「切换表头行」（插入表格面板已有「包含表头行」开关）；保留切换表头列 / 表头单元格。
+- 「合并或拆分单元格」拆成两个独立按钮：`mergeCells` / `splitCell`，各自按 `can()` 置灰。
+- 删除行 / 删除列的图标改为按 lucide 规范手绘的「表格 + × 角标」——原先复用的 `table-rows-split` / `table-columns-split` 是「拆分行列」的画法，看不出删除语义。
+
+文档见 `docs/content/ui/form/rich-text.md`；e2e 见 `packages/ui/e2e/rich-text-focus.spec.ts`（内容区几何 / 聚焦）、`packages/ui/e2e/rich-text-toolbar.spec.ts`（对齐 / 颜色）与 `packages/ui/e2e/rich-text-table.spec.ts`（合并拆分 / 删除行列 / 单元格对齐）。
diff --git a/code/g3soft-libs/.changeset/rich-text-table.md b/code/g3soft-libs/.changeset/rich-text-table.md
new file mode 100644
index 00000000..e6e70ae5
--- /dev/null
+++ b/code/g3soft-libs/.changeset/rich-text-table.md
@@ -0,0 +1,31 @@
+---
+'@g3soft/ui': minor
+---
+
+修复并增强 `RichText` 表格编辑。
+
+**修复**
+
+- 初始为 `disabled` / `readonly` 的编辑器恢复可编辑后，列宽拖拽仍失效：Tiptap 在创建时按 `isEditable` 决定是否注册 `columnResizing` 插件，而 `setEditable` 不会重建插件。现改为始终按可编辑创建、挂载后按 props 降级，插件集完整保留。
+- 光标落在单元格文本内时，操作浮层定位崩溃（`domAtPos().node` 返回文本节点，`closest` 不存在抛 `TypeError`）。已归一化节点类型后再取表格元素。
+- 浮层 `z-index` 硬编码 `1000`，会被 modal（1101+）盖住；改用 `nextZIndex('popup')` 领取、隐藏即归还。
+- 页面级滚动 / 窗口缩放时浮层位置漂移：新增 `window` 捕获阶段 `scroll` / `resize` 监听跟随重定位。
+- 插入表格面板行列数不校验，输入 0 / 负数 / 超大值会生成畸形表格：现在插入时夹回 1–20。
+
+**增强**
+
+- 补齐表头能力：切换表头列、切换表头单元格（此前仅表头行）。
+- 单元格水平对齐：左 / 中 / 右对齐（写入 `style="text-align: …"`），激活态高亮，支持一键取消。
+- 「合并或拆分」单键智能操作：选中多格合并、单格有合并则拆分。
+- 分组分隔线 + 去重图标，危险操作（删除表格）单独分组防误点。
+- 插入面板新增「包含表头行」开关、Enter 键提交；只读 / 禁用态浮层自动隐藏。
+
+**列宽拖拽重构**
+
+- 布局从 `table-layout: auto` 改为 `fixed`：拖拽只动被拖列、其余列纹丝不动，不再出现「拖第 2/3 列线时第 1 列被动变窄」的联动错位。
+- 拖拽结束 / 插入表格后自动把整表各列实际宽度固化回 `colwidth`，保证后续每次拖拽严格隔离相邻列。
+- 最小列宽从 80px 调整为 10px。
+- 移除拖拽时的黑色竖线指示条（只保留 `col-resize` 光标提示）。
+- fixed 布局消除 auto 布局下每次 mousemove 的整表重排，拖拽不再卡顿。
+
+文档见 `docs/content/ui/form/rich-text.md`，e2e 见 `packages/ui/e2e/rich-text-table.spec.ts`。
diff --git a/code/g3soft-libs/.changeset/slider-captcha.md b/code/g3soft-libs/.changeset/slider-captcha.md
new file mode 100644
index 00000000..db27da8c
--- /dev/null
+++ b/code/g3soft-libs/.changeset/slider-captcha.md
@@ -0,0 +1,12 @@
+---
+'@g3soft/ui': minor
+---
+
+新增 `G3SliderCaptcha` 滑块验证码。
+
+- 按住手柄拖到**行内结束端**即通过；`v-model` 绑 `boolean`，`success` 在通过瞬间触发一次，`resume()` 供校验失败后复位。
+- 拖拽走 Pointer Events + `setPointerCapture`（与 `bindDrag` / `bindResize` 同一套），指针移出组件、触屏、手写笔都能正确收尾，不往 `document` 挂全局监听。
+- 键盘可达：`role="slider"` + `aria-valuenow` / `aria-valuetext`，← → 微调、Home 复位、End 直达终点（`keyboard={false}` 可关）。
+- RTL：位置用逻辑属性 `inset-inline-start`，位移按行内方向折算，方向键左右随方向翻转。
+- 文案走语言包（新增 `captcha` 分组：`slide` / `verified` / `sliderLabel`），`text` / `successText` 只作覆盖；`size` 支持 small / medium / large。
+- 附单测（拖拽 / 回弹 / 禁用 / 键盘 / RTL / 受控 / resume）与真浏览器 e2e（真实指针拖拽、回弹、RTL 起步边），文档见 `docs/content/ui/form/slider-captcha.md`。
diff --git a/code/g3soft-libs/docs/.vitepress/config.mts b/code/g3soft-libs/docs/.vitepress/config.mts
index 9633b591..145a7443 100644
--- a/code/g3soft-libs/docs/.vitepress/config.mts
+++ b/code/g3soft-libs/docs/.vitepress/config.mts
@@ -136,7 +136,9 @@ export default defineConfig({
             { text: 'Form 表单', link: '/ui/form/form' },
             { text: 'Input 输入框', link: '/ui/form/input' },
             { text: 'Radio 单选框', link: '/ui/form/radio' },
+            { text: 'RichText 富文本编辑器', link: '/ui/form/rich-text' },
             { text: 'Select 选择器', link: '/ui/form/select' },
+            { text: 'SliderCaptcha 滑块验证码', link: '/ui/form/slider-captcha' },
             { text: 'Switch 开关', link: '/ui/form/switch' },
           ],
         },
@@ -168,6 +170,7 @@ export default defineConfig({
           icon: 'table-properties',
           collapsed: false,
           items: [
+            { text: 'Attachment 附件管理器', link: '/ui/data/attachment' },
             { text: 'DatePicker 日期选择', link: '/ui/data/date' },
             { text: 'Pagination 分页器', link: '/ui/data/pagination' },
             { text: 'Splitter 分割面板', link: '/ui/data/splitter' },
diff --git a/code/g3soft-libs/docs/content/ui/data/attachment.md b/code/g3soft-libs/docs/content/ui/data/attachment.md
new file mode 100644
index 00000000..11d2f19d
--- /dev/null
+++ b/code/g3soft-libs/docs/content/ui/data/attachment.md
@@ -0,0 +1,234 @@
+---
+title: Attachment 附件管理器
+description: 分类 / 列表（可选预览）的附件管理面板，上传（选择、拖拽、粘贴）、批量下载删除与分页
+---
+
+# Attachment 附件管理器
+
+`Attachment` 是「一个业务对象的附件集合」管理器：左栏分类、中栏文件（卡片 / 列表双视图），支持选择、拖拽、粘贴上传，多选批量下载 / 删除与分页。右栏预览默认关闭，需要时 `show-preview` 打开。
+
+它**不请求任何接口**，也不认识「模块 / 业务主键」这类概念：数据从 `files` / `categories` 进来，用户意图以事件出去；需要组件代跑请求时，传 `uploadRequest` / `removeRequest` 即可。
+
+## 何时使用
+
+- 需要管理某个业务单据 / 项目的附件集合（上传、分类、下载、删除）；
+- 文件可能有很多，需要分类过滤、分页、批量操作；
+- 只需要一个简单的「选择文件」入口时，用 [Input](/ui/form/input) 或原生 `<input type="file">` 更轻。
+
+## 基础用法
+
+给 `files`（附件）和 `categories`（分类，可选）两份数据，上传与删除交给业务：
+
+<demo vue="attachment/basic.vue" />
+
+## 多选与批量操作
+
+没勾选时工具栏只有「全选」；一旦勾选，工具栏浮出「已选 N 项 + 下载 + 删除」。示例关掉了 `builtin-download`，下载只上报事件：
+
+<demo vue="attachment/select.vue" />
+
+## 只读
+
+`readonly` 会隐藏上传 / 删除入口，并让拖拽、粘贴失效，适合审批查看场景：
+
+<demo vue="attachment/readonly.vue" />
+
+## 弹窗用法
+
+附件组件本身不是弹窗，需要弹窗时用 [Modal](/ui/overlay/modal) 包一层即可（高度用 `height` 给）：
+
+<demo vue="attachment/modal.vue" />
+
+## 上传与校验
+
+三种入队方式：点底栏「选择」、把文件拖进列表区、`paste-upload` 打开后在页面任意处 `Ctrl/Cmd + V`。
+
+入队前按 `accept` / `maxSize` / `maxCount` 校验，被拒的文件通过 `invalid` 事件抛出（`info.message` 是组件按当前语言包生成的提示原文，可直接 toast）：
+
+```ts
+function onInvalid(info: AttachmentInvalidInfo) {
+  // reason: 'accept' | 'max-size' | 'max-count'
+  message.warning(info.message)
+}
+```
+
+队列里的文件先渲染在列表最前面（带「待上传」标记），点「上传」后组件把它们交出去：
+
+- **没传 `upload-request`**：emit `upload(files, ctx)`，并**立即清空队列**（文件所有权移交业务）；
+- **传了 `upload-request`**：组件托管请求，期间「上传」按钮 loading；成功后 emit `upload-success(files, result)`，`result` 是数组时自动追加进 `files`；失败 emit `upload-error(err, files)` 且**保留队列**（可重试）。
+
+## 数据契约
+
+列表项的字段是中性的，不含任何业务字段名：
+
+```ts
+const files = ref<AttachmentItem[]>([
+  { id: 12, name: '合同.pdf', size: 512_000, categoryId: 'contract', url: '/files/12.pdf' },
+])
+```
+
+业务侧字段名不同也没关系 —— 组件的所有事件都把原始数据放在 `item.raw` 里原样回传，字段映射写在业务侧的一个 adapter 就够：
+
+```ts
+// 后端行 → 组件项
+const toItem = (row: BfFilesRow): AttachmentItem => ({
+  id: row.subid,
+  name: row.mx_filename,
+  size: Number(row.mx_filesize),
+  ext: row.mx_fileext,
+  url: row.mx_mapfilename,
+  categoryId: row.mx_cate_id,
+  raw: row,
+})
+```
+
+## 分页
+
+两种模式，由 `total` 区分：
+
+| 模式 | 传参 | 行为 |
+| --- | --- | --- |
+| 客户端分页 | 只给 `files` | `files` 是完整列表，组件按 `page` / `pageSize` 自行切片 |
+| 服务端分页 | 再给 `total` | `files` 已经是当前页数据，组件只画不切，翻页靠 `update:page` |
+
+`page` / `pageSize` 是**非受控**的：不传时组件内部维护（默认 1 / 20），传了就完全听你的（`v-model:page-size` 等）。
+
+## API
+
+### Props
+
+| 名称 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `files` | `AttachmentItem[]` | `[]` | 附件列表，配合 `v-model:files` |
+| `categories` | `AttachmentCategory[]` | `[]` | 分类数据；为空则不渲染左栏 |
+| `categoryKey` | `string \| number` | `''` | 选中分类，`''` 表示「全部」，配合 `v-model:categoryKey` |
+| `showCategory` | `boolean` | `true` | 是否显示左栏（无 `categories` 时自动隐藏） |
+| `showPreview` | `boolean` | `false` | 是否显示右栏预览；关掉时 `preview` 事件照常抛出，可自行开弹窗预览 |
+| `readonly` | `boolean` | `false` | 只读：隐藏上传 / 删除，拖拽与粘贴失效 |
+| `loading` | `boolean` | `false` | 列表加载中 |
+| `categoryLoading` | `boolean` | `false` | 分类加载中 |
+| `selectable` | `boolean` | `true` | 是否可勾选 |
+| `multiple` | `boolean` | `true` | 是否允许多选 |
+| `accept` | `string` | — | 接受的文件类型，同原生 `accept`（支持 `.pdf` / `image/*` / `application/pdf`） |
+| `maxSize` | `number` | `0` | 单文件大小上限（字节），`0` 表示不限制 |
+| `maxCount` | `number` | `0` | 待上传队列上限，`0` 表示不限制 |
+| `pasteUpload` | `boolean` | `false` | 监听 `document` 的粘贴上传（多实例场景请只开一个） |
+| `confirmRemove` | `boolean` | `true` | 删除前二次确认（内建 Modal） |
+| `builtinDownload` | `boolean` | `true` | 依据 `item.url` 内建触发下载；关掉后只上报 `download` |
+| `pagination` | `boolean` | `true` | 是否显示分页（数据不足一页时自动隐藏） |
+| `page` | `number` | — | 当前页，非受控（内部默认 `1`） |
+| `pageSize` | `number` | — | 每页条数，非受控（内部默认 `20`） |
+| `total` | `number` | — | 总条数；**传了即为服务端分页**，`files` 视为当前页 |
+| `pageSizeOptions` | `Array<number \| string>` | `[10, 20, 50, 100]` | 每页条数选项 |
+| `showSizeChanger` | `boolean` | `false` | 显示每页条数切换器 |
+| `height` | `number \| string` | — | 根容器高度，数字按 px；默认撑满父容器（父级无高度时保底 320px） |
+| `uploadRequest` | `(files: File[], ctx: AttachmentUploadContext) => Promise<AttachmentItem[] \| void> \| AttachmentItem[] \| void` | — | 托管上传 |
+| `removeRequest` | `(items: AttachmentItem[]) => Promise<void> \| void` | — | 托管删除 |
+
+### Events
+
+| 名称 | 参数 | 说明 |
+| --- | --- | --- |
+| `update:files` | `(files: AttachmentItem[])` | 删除成功 / 托管上传回填后更新列表 |
+| `update:categoryKey` | `(key: string \| number)` | 分类切换 |
+| `update:page` | `(page: number)` | 翻页 |
+| `update:pageSize` | `(size: number)` | 每页条数变化 |
+| `change` | `(files: AttachmentItem[])` | 列表增删（上传成功 / 删除成功） |
+| `select` | `(items: AttachmentItem[])` | 勾选变化 |
+| `categoryChange` | `(key: string \| number, category: AttachmentCategory \| null)` | 分类切换，带原始分类对象 |
+| `preview` | `(item: AttachmentItem \| null)` | 点击某项预览（翻页同样触发） |
+| `download` | `(items: AttachmentItem[])` | 下载 |
+| `remove` | `(items: AttachmentItem[])` | 用户确认删除且请求成功 |
+| `removeError` | `(error: unknown, items: AttachmentItem[])` | 删除失败 |
+| `upload` | `(files: File[], ctx: AttachmentUploadContext)` | 未传 `uploadRequest` 时把待上传文件交给业务 |
+| `uploadSuccess` | `(files: File[], result: AttachmentItem[] \| void)` | 托管上传成功 |
+| `uploadError` | `(error: unknown, files: File[])` | 托管上传失败（队列保留） |
+| `invalid` | `(info: AttachmentInvalidInfo)` | 文件被 `accept` / `maxSize` / `maxCount` 拒绝 |
+
+### Exposed（通过 ref 调用）
+
+| 名称 | 类型 | 说明 |
+| --- | --- | --- |
+| `selectedItems` | `AttachmentItem[]` | 当前勾选的附件 |
+| `pendingFiles` | `AttachmentPendingFile[]` | 待上传队列 |
+| `openFileDialog()` | — | 打开系统文件选择框 |
+| `clearSelection()` | — | 清空勾选 |
+| `selectAll()` | — | 全选当前页 |
+| `addFiles(files)` | `File[] \| FileList => File[]` | 入队（走 `accept` / `maxSize` / `maxCount` 校验），返回被接受的文件 |
+| `clearPending()` | — | 清空待上传队列（业务自行接管上传时调用） |
+
+### 类型定义
+
+```ts
+interface AttachmentItem {
+  id: string | number
+  name: string
+  size?: number
+  ext?: string
+  url?: string
+  thumbnailUrl?: string
+  categoryId?: string | number
+  status?: 'ready' | 'uploading' | 'error'
+  percent?: number
+  raw?: unknown
+  [key: string]: unknown
+}
+
+interface AttachmentCategory {
+  id: string | number
+  name: string
+  count?: number
+  disabled?: boolean
+  children?: AttachmentCategory[]
+}
+
+interface AttachmentPendingFile {
+  file: File
+  name: string
+  size: number
+  ext: string
+  url?: string
+}
+
+interface AttachmentInvalidInfo {
+  reason: 'accept' | 'max-size' | 'max-count'
+  files: File[]
+  message: string
+}
+
+interface AttachmentUploadContext {
+  categoryId?: string | number
+}
+```
+
+### 样式变量
+
+类型色（图标 + 扩展名那一小块）按文件族取色，全部可覆盖；`--g3-color-*` 未加载时组件自带兜底值：
+
+| 变量 | 说明 |
+| --- | --- |
+| `--g3-attachment-type-image` | 图片：默认 `--g3-color-primary` |
+| `--g3-attachment-type-doc` | 文档（pdf / doc / txt …）：默认 `--g3-color-danger` |
+| `--g3-attachment-type-sheet` | 表格：默认 `--g3-color-success` |
+| `--g3-attachment-type-slide` | 演示：默认 `--g3-color-warning` |
+| `--g3-attachment-type-archive` | 压缩包：默认 `#d98e04`（暗色 `#e0a63c`） |
+| `--g3-attachment-type-media` | 音视频：默认 `#1f9ea8`（暗色 `#38bcc6`） |
+| `--g3-attachment-type-other` | 未知类型：默认 `--g3-text-3` |
+
+其余尺寸 / 间距 / 圆角 / 过渡全部走令牌（`--g3-control-height`、`--g3-space-*`、`--g3-radius*`、`--g3-duration*`），换肤时不需要动组件。
+
+## 实现说明
+
+- **默认两栏，预览按需开**：布局用 [Splitter](/ui/data/splitter)——分类栏固定 200px（150–320 可拖），列表栏自适应（≥280）；`show-preview` 打开后追加 360px（≥280）的预览栏。`showCategory` / `showPreview` 为假时对应面板直接不渲染，只剩两栏或一栏。预览栏关闭时 `preview` 事件照常抛出，业务可以接自己的弹窗 / 抽屉。
+- **面板之间有常显的分割线**：关掉了 Splitter 的 `barOnHover`（默认只在 hover 时显示），并把线宽收成 1px——否则分类栏与卡片区之间看不出边界。拖拽命中区仍是 10px，只是视觉线更细。
+- **工具栏整行同一档规格**：全选（复选框文案）、已选计数、批量按钮统一到 **12px 字 / 24px 控件**（按钮 `size="small"`），高度**写死** `24px + 上下各 8px`——必须用 `height` 而不是 `min-height`：默认 `content-box` 下 `min-height` 只管内容盒，实际高度 = 内容盒 + 上下 padding，勾选前后仍会变。行内元素一律 `flex: none`（不收缩）+ `flex-wrap: nowrap` + `overflow: hidden`。勾选后浮出「｜ 已选 N 项 · 下载 · 删除」，用 1px 竖线把「选择」与「操作」分组——字号一致、控件等高，才不会看着"歪"或空荡。删除与下载用 [Button](/ui/general/button) 的 `danger-outline` / `outline` 变体，在工具栏里有明确边界（`ghost` 的纯文字按钮会像裸文本飘着）。**窄面板**走容器查询（按面板宽度、不是视口宽度）：先收掉按钮文案只留图标，再窄一点连「全选」文案也收起，保证一行永远放得下。
+- **操作藏在 hover 里**：卡片右下角的「下载 / 删除」平时不显示，hover 或键盘聚焦（`:focus-within`）才浮现，`@media (hover: none)` 的触屏设备下常显。工具栏同理——没勾选任何文件时不渲染「下载 / 删除」，只留全选；勾选后浮出「已选 N 项 + 操作」。
+- **空态就是投放区**：虚线框铺满列表区，hover 转主色；文案两行（「暂无文件」+「拖拽文件到此处，或点击选择」），并把 `accept` / `maxSize` / `maxCount` 的限制拼成第三行提示，省得用户上传后才被拒。
+- **底栏是"脏"状态指示**：待上传队列非空时，底栏整块染主色淡底、计数变主色；上传与分页合成同一块（只有一条顶边），不会出现两条并排的分隔线。
+- **分类树用 [Tree](/ui/data/tree)**：`categories` 之上合成了一个「全部」根节点（对外用 `categoryKey === ''` 表示），因此可以给层级数据；`categoryChange` 会把原始分类对象一起带出来。
+- **删除确认是内建 Modal**：不走 `Modal.confirm()` 命令式（那会让组件依赖全局挂载容器）。`confirmRemove` 关掉后直接进请求。
+- **`update:files` 的语义**：受控组件不擅自改数据。删除成功、或托管上传返回数组时，组件会 emit 过滤 / 追加后的新数组，方便 `v-model:files` 一行接上；完全自管数据时忽略它即可。
+- **blob URL 的回收**：待上传图片的本地预览地址由组件创建，在出队、清空、切换分类、卸载时释放，业务无需关心。
+- **上传进度**：`files` 里某项 `status: 'uploading'` 时，卡片封面底边出现 2px 进度条、列表视图在大小列显示细轨 + 百分比（进度值读 `percent`）。
+- **粘贴上传默认关闭**：它监听 `document`，一个页面多个附件组件同时开会互相抢，所以做成显式 opt-in。
+- **RTL**：布局全部用逻辑属性（`inset-inline-start` / `inset-block-end` / `text-align: start` 等），宿主 `<html dir="rtl">` 下自动镜像，分隔条拖拽与键盘方向由 Splitter 的 `useDirection` 处理。
diff --git a/code/g3soft-libs/docs/content/ui/form/rich-text.md b/code/g3soft-libs/docs/content/ui/form/rich-text.md
new file mode 100644
index 00000000..8abc1053
--- /dev/null
+++ b/code/g3soft-libs/docs/content/ui/form/rich-text.md
@@ -0,0 +1,173 @@
+---
+title: RichText 富文本编辑器
+description: 基于 Tiptap 的富文本编辑，支持字体、字号、对齐、文字与背景色、上下标、图片视频上传与表格
+---
+
+# RichText 富文本编辑器
+
+`RichText` 是基于 [Tiptap](https://tiptap.dev) 封装的富文本编辑器，`v-model` 输出干净的 HTML 字符串，可直接作为邮件正文、公告正文等场景使用。
+
+## 何时使用
+
+- 录入需要富文本格式的正文（公告、邮件、通知、帮助文档）；
+- 需要字体 / 字号 / 对齐 / 文字颜色 / 背景颜色 / 上标 / 下标等排版能力时；
+- 需要在正文中嵌入图片 / 视频、插入表格时。
+
+> 纯文本或短文本请用 [Input](/ui/form/input)（`type="textarea"`），不要用富文本承载简单字段。
+
+## 基础用法
+
+`v-model` 双向绑定 HTML 字符串，工具条默认置顶，内置字体 / 字号 / 对齐 / 颜色 / 上下标 / 表格 / 撤销重做。
+
+<demo vue="rich-text/basic.vue" />
+
+## 工具条
+
+工具条按「一天点几次」而不是「功能重不重要」排布，**始终一行、高度恒定 48px**：
+
+- **常驻**（顺序：历史 → 正文格式 → 行内格式 → 对齐 → 颜色 → 列表与插入）：撤销、重做 ｜ 段落格式（正文 / 标题 1-3）｜ 加粗、斜体、下划线 ｜ 对齐（左 / 中 / 右）｜ 字体颜色、背景颜色 ｜ 无序列表、有序列表、链接、图片、插入表格；
+- **收进 `⋯ 更多`**：`字体` / `字号`（二级菜单，选中态跟随光标）、`格式` 组（删除线 / 上标 / 下标 / 引用）、`插入` 组（视频）。菜单项带分组标题与快捷键提示（对着 Tiptap 的真实键位写的，如删除线 `Ctrl+Shift+S`）。
+
+图标 16px、按钮 32px（等于 `--g3-control-height`）、组内间隙 4px、内边距 8px / 10px（左右 10px 让首列图标与正文的 12px 内边距对齐）；图标前景用 `text-1`（88% 黑）而不是 ghost 按钮默认的 `text-2`（65%），描边保持 lucide 原生粗细 —— 实测「发虚」的主因是浅灰前景而不是线宽，所以只加深颜色、不加重描边。整条工具条自然宽度约 **744px**：760px 以上的容器都是一行，再窄才折行，且折行以「组」为单位，不会把分隔线甩到行首/行尾。表格插入按钮留在工具条上而不是进 `⋯`：它要先选行列，收起后承载不了那个面板。
+
+## 对齐与颜色
+
+工具条提供三组排版能力，均作用于选区所在的块（正文段落 / 标题，表格单元格里的内容同样是段落）：
+
+- **对齐**（左 / 居中 / 右）：写 `text-align` 到块元素上；点当前档位即取消对齐，不需要单独的「取消」按钮；
+- **字体颜色**（`A` 图标 + 当前色条）：写 `color`；
+- **背景颜色**（荧光笔图标 + 当前色条）：写 `background-color`。
+
+两个取色按钮都是「图标 + 当前色条」的形式，色条显示选区当前的颜色（未设色时是空位）。点开后是预设色板面板：常用色一屏排满，`无颜色` 清除该属性，右侧彩虹色块打开系统取色器选任意颜色。选完色面板自动收起。
+
+## 图片 / 视频上传
+
+图片和视频通过 `upload-image` / `upload-video` 两个 prop 注入上传函数。上传函数接收 `File`，返回 `{ fileUrl, ... }` 元数据；上传完成后组件会触发 `upload-inline` 事件，把内联资源元数据上报给外层（对齐邮件「inline 附件」模型）。
+
+<demo vue="rich-text/upload.vue" />
+
+```ts
+// 上传函数约定
+type Upload = (file: File) => Promise<{
+  fileUrl: string      // 正文 img / video 的 src
+  fileId?: string      // 后端文件 id
+  cid?: string         // 内联资源 cid（邮件场景）
+  fileName?: string
+  fileSize?: number
+}>
+```
+
+## 只读 / 禁用
+
+`readonly` 可聚焦可复制但不可编辑；`disabled` 整体灰化不可交互。
+
+<demo vue="rich-text/readonly.vue" />
+
+## 表格
+
+工具条「插入表格」按钮弹出行 / 列选择面板（支持关闭表头行）；光标进入表格后，表格下方会浮出就近操作栏：
+
+- **行**：上方插入行、下方插入行、删除行；
+- **列**：左侧插入列、右侧插入列、删除列；
+- **单元格**：合并单元格、拆分单元格（两个独立按钮，不可用时各自置灰）；
+- **表头**：切换表头列、切换表头单元格；
+- **删除**：整表删除（与增删行列用分隔线隔开，防误点）。
+
+单元格内文字的对齐、颜色在顶部工具条里设置（单元格内容也是普通段落），操作栏不再重复提供。
+
+列宽拖拽：悬停列分隔线出现 `col-resize` 光标，左右拖动调整列宽。拖拽采用 `table-layout: fixed`，**只动被拖列、其余列纹丝不动**（Excel 语义）；列宽以 `colwidth` 属性持久化进 HTML，最小列宽 10px。拖宽后表格总宽超过容器时，在表格容器内横向滚动，不撑破编辑器内容区。`Tab` / `Shift+Tab` 在单元格间跳转，末格 `Tab` 自动追加行。
+
+> 行列数限制为 1–20，超出会在插入时自动夹回，避免一次性生成超大表格卡死编辑器。
+
+## 获取纯文本
+
+通过 `ref` 调用 `getText()` 拿到纯文本（邮件 `text/plain` 备选），`getHTML()` 拿 HTML，`clear()` 清空。
+
+<demo vue="rich-text/methods.vue" />
+
+## API
+
+### Props
+
+| 名称 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `modelValue` | `string` | `''` | 双向绑定的 HTML 字符串 |
+| `placeholder` | `string` | — | 占位文案 |
+| `disabled` | `boolean` | `false` | 禁用态 |
+| `readonly` | `boolean` | `false` | 只读态：可聚焦、可复制，但不可编辑 |
+| `toolbar` | `'top' \| 'bottom' \| false` | `'top'` | 工具条位置；`false` 隐藏工具条 |
+| `minHeight` | `number \| string` | `200` | 编辑区最小高度 |
+| `maxHeight` | `number \| string` | — | 编辑区最大高度（超出滚动） |
+| `uploadImage` | `(file: File) => Promise<RichTextUploadResult>` | — | 图片上传函数，返回完整元数据 |
+| `uploadVideo` | `(file: File) => Promise<RichTextUploadResult>` | — | 视频上传函数，返回完整元数据 |
+| `fonts` | `RichTextFontOption[]` | 内置字体表 | 「更多」菜单里字体子菜单的选项 |
+| `fontSizes` | `RichTextFontSizeOption[]` | 内置字号表 | 「更多」菜单里字号子菜单的选项 |
+
+### Events
+
+| 名称 | 参数 | 说明 |
+| --- | --- | --- |
+| `update:modelValue` | `(html: string)` | 内容变化时触发 |
+| `focus` | `(event: FocusEvent)` | 获得焦点 |
+| `blur` | `(event: FocusEvent)` | 失去焦点 |
+| `upload-inline` | `(result: RichTextUploadResult, kind: 'image' \| 'video')` | 内联资源上传完成，上报给外层收集 |
+| `upload-error` | `(error: Error, kind: 'image' \| 'video')` | 上传失败 |
+
+### Exposed（通过 ref 调用）
+
+| 名称 | 签名 | 说明 |
+| --- | --- | --- |
+| `editor` | `Editor` | 底层 Tiptap 实例（进阶用法） |
+| `getHTML` | `() => string` | 当前 HTML |
+| `getText` | `() => string` | 纯文本（邮件 text/plain） |
+| `focus` | `() => void` | 聚焦 |
+| `clear` | `() => void` | 清空内容 |
+
+### 类型定义
+
+```ts
+export interface RichTextUploadResult {
+  fileUrl: string
+  fileId?: string
+  cid?: string
+  fileName?: string
+  fileSize?: number
+  [key: string]: unknown
+}
+
+export interface RichTextFontOption {
+  label: string
+  value: string
+}
+
+export interface RichTextFontSizeOption {
+  label: string
+  value: string
+}
+```
+
+### 样式变量
+
+| 变量 | 默认值 | 说明 |
+| --- | --- | --- |
+| `--g3-border-color` | `#d9d9d9` | 容器 / 表格边框 |
+| `--g3-radius` | `6px` | 容器圆角 |
+| `--g3-fill` | `rgba(0,0,0,.04)` | 工具条背景、表头背景 |
+| `--g3-color-primary` | `#18181b` | 激活态、链接、引用竖线颜色、聚焦时正文区的 2px 描边 |
+| `--g3-color-primary-soft` | 主色 12% | 按钮激活底、选中单元格底 |
+| `--g3-rich-text-toolbar-shadow-near` | `rgba(34,47,62,.1)` | 工具条投影近层（`0 2px 2px -2px`，`toolbar="bottom"` 时翻到上方） |
+| `--g3-rich-text-toolbar-shadow-far` | `rgba(34,47,62,.07)` | 工具条投影远层（`0 8px 8px -4px` 弥散） |
+
+## 实现说明
+
+- **选型 Tiptap**：MIT 协议、Vue 3 官方绑定（`@tiptap/vue-3`）、headless 架构便于贴合 G3 设计体系；相比 HugeRTE（TinyMCE 的 MIT fork）在 Vue 集成与 UI 定制上更契合组件库封装；
+- **不含代码块**：从 `starter-kit` 剔除了 Code / CodeBlock（ERP 场景不需要）；
+- **字体 / 字号 / 颜色 / 背景色**：用官方 `TextStyleKit`（内置 `setFontFamily` / `setFontSize` / `setColor` / `setBackgroundColor` 命令），行高保持关闭；颜色只写 `textStyle` 记号（`<span style="color: …">`），不引入额外的 mark；
+- **对齐**：官方 `@tiptap/extension-text-align`，只挂到 `heading` / `paragraph`，`alignments` 限左中右；面板里是 `toggleTextAlign`，点当前档位即取消；
+- **内容区即编辑区**：`minHeight` / `maxHeight` 作用在内容区上，可编辑区（`.tiptap`）用 `flex: 1 0 auto` 撑满 —— 内容短时整块都能点（点空白即聚焦、光标落到正文末尾），内容长时按内容高度撑开、由内容区滚动且不裁切。注意 EditorContent 会在内容区与可编辑区之间再插一层包裹 DOM，所以 `.tiptap` 上的 `min-height: inherit` 取的是那一层的值（恒为 0），撑不高可编辑区；
+- **聚焦高亮只给正文区**：编辑器获得焦点时（根节点 `:focus-within`），正文区四周亮起 2px 主色内描边，工具条不参与 —— 谁可编辑谁亮。用 `inset box-shadow` 而不是 `border`（不参与布局，聚焦不挤动正文），也不用 TinyMCE 那种 `::after` 覆盖层（正文区就是滚动容器，覆盖层会跟着正文滚走，而滚动容器的阴影不随内容滚动，天然钉在内容盒上）；
+- **工具条密度与「更多」**：按钮 32px（等于 `--g3-control-height`）+ 组内 4px 间隙，字体 / 字号与低频功能收进 `⋯` 菜单，自然宽度从 928px 降到 744px；`⋯` 用 `G3Dropdown` 现成的 `type: 'label'`（分组标题）/ `children`（子菜单）/ `shortcut` / `selected` 能力拼出来，与工具条共用同一份 `ToolButton` 定义，激活态与禁用态一致。菜单内容约 295px，靠 Dropdown 默认的视口上限（`calc(100vh - 48px)`）保证面板内部不出滚动条，不需要额外传 `menuMaxHeight`；
+- **图标分量**：16px 图标 + lucide 原生描边（16px 下约 1.33px），只把前景从 ghost 默认的 `text-2`（65%）提到 `text-1`（88%）。试过描边 2.5 与放大到 24px，都偏重；实测「发虚」的主因是浅灰前景，动颜色这一项性价比最高；
+- **视频自写 node**：Tiptap 官方无视频扩展，`VideoNode.ts` 定义了轻量 `video` block node，输出 `<video controls>` 标签；邮件场景由业务层决定是否降级为「封面图 + 附件」（编辑器不绑定邮件语义）；
+- **内联资源上报**：图片 / 视频上传后 `emit('upload-inline', result, kind)`，外层把 `result` 收集进 `inlines` 数组，与邮件「inline 附件」模型对齐（参考 Email-Vue 的 `@upload-image`）；
+- **依赖策略**：Tiptap 核心走 `peerDependencies`，扩展走 `dependencies`，不把编辑器全家桶强塞给所有 `@g3soft/ui` 使用者。
diff --git a/code/g3soft-libs/docs/content/ui/form/slider-captcha.md b/code/g3soft-libs/docs/content/ui/form/slider-captcha.md
new file mode 100644
index 00000000..3c74ca31
--- /dev/null
+++ b/code/g3soft-libs/docs/content/ui/form/slider-captcha.md
@@ -0,0 +1,124 @@
+---
+title: SliderCaptcha 滑块验证码
+description: 按住滑块拖到行内结束端完成验证，支持键盘操作与 RTL
+---
+
+# SliderCaptcha 滑块验证码
+
+`SliderCaptcha` 是一个「按住滑块拖到最右端」的验证控件，`v-model` 绑 `boolean`，`true` 表示**已验证通过**。
+
+## 何时使用
+
+- 登录 / 注册 / 短信验证码等需要「一次人为停顿」的入口；
+- 轻量混淆脚本、降低误触强度的场景；
+- **不要**把它当安全边界：拖拽与键盘都能被脚本模拟，它能挡住的只是「顺手连点」，真正的风控要靠服务端。
+
+## 基础用法
+
+`v-model` 绑 `boolean`；`success` 在通过的那一刻触发一次，方便埋点或联动下一步。
+
+<demo vue="captcha/basic.vue" />
+
+`text` / `successText` 可覆盖语言包文案（默认取 `captcha` 语言包分组）。
+
+## 尺寸
+
+`size` 取 `small` / `medium` / `large`，高度分别跟随 `--g3-control-height-sm` / `--g3-control-height` / `--g3-control-height-lg`；手柄是正方形，宽度自动等于高度。
+
+<demo vue="captcha/sizes.vue" />
+
+## 与表单一起使用
+
+放进 `G3FormItem` 时，label 与校验交给表单，滑块只负责提供值。验证是有状态的，**每轮提交都要复位**：清掉绑定值后调 `resume()`，让用户重新拖一次。
+
+<demo vue="captcha/in-form.vue" />
+
+## 键盘与无障碍
+
+手柄是 `role="slider"`，带 `aria-valuemin` / `aria-valuemax` / `aria-valuenow`（0~100 的完成度）与 `aria-valuetext`（当前提示文案，通过后是成功文案），读屏可直接播报状态。
+
+| 按键 | 行为 |
+| --- | --- |
+| `Tab` | 聚焦手柄（未通过时才可聚焦，通过后 `tabindex="-1"`） |
+| `→` / `↑` | 沿屏幕上「向右」推进一档（行程的 1/10，最少 20px） |
+| `←` / `↓` | 回退一档 |
+| `Home` | 回到起点（不复位通过状态） |
+| `End` | 直达终点并通过验证 |
+
+`keyboard={false}` 可关掉键盘通道（只保留指针拖拽）。
+
+## RTL
+
+位置用逻辑属性 `inset-inline-start` 表达，镜像由 `dir` 自动完成：RTL 下手柄从**右侧**起步、向**左**拖到终点。指针位移按行内方向折算（`useDirection`），方向键的左右也随方向翻转 —— 对用户而言始终是「朝屏幕上那个方向推到底」。
+
+## API
+
+### Props
+
+| 名称 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `modelValue` | `boolean` | `false` | 双向绑定：是否已验证通过 |
+| `text` | `string` | 语言包 | 未通过时的提示文案 |
+| `successText` | `string` | 语言包 | 通过后的文案 |
+| `disabled` | `boolean` | `false` | 禁用态：不响应拖拽与键盘（样式不作整体半透明） |
+| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | 尺寸 |
+| `keyboard` | `boolean` | `true` | 是否支持键盘操作 |
+
+### Events
+
+| 名称 | 参数 | 说明 |
+| --- | --- | --- |
+| `update:modelValue` | `(value: boolean)` | 验证状态变化 |
+| `success` | `({ isPassing: true })` | 通过时触发一次 |
+| `start` | `(event: PointerEvent)` | 开始拖拽 |
+| `move` | `({ event, moveDistance, offset })` | 拖拽过程中触发（键盘操作不触发） |
+| `end` | `(event: PointerEvent)` | 拖拽结束（含取消） |
+
+### Slots
+
+| 名称 | 参数 | 说明 |
+| --- | --- | --- |
+| `text` | `{ isPassing }` | 覆盖提示文案 |
+| `action` | `{ isPassing }` | 覆盖手柄里的图标（默认 `ChevronsRight` / 通过后 `Check`，RTL 下由全库的图标镜像规则翻面） |
+
+### 实例方法
+
+| 名称 | 签名 | 说明 |
+| --- | --- | --- |
+| `resume` | `() => void` | 复位到未通过状态（清绑定值 + 回弹动画），校验失败后调用 |
+
+### 类型定义
+
+```ts
+export type SliderCaptchaSize = 'small' | 'medium' | 'large'
+
+export interface SliderCaptchaProps {
+  modelValue?: boolean
+  text?: string
+  successText?: string
+  disabled?: boolean
+  size?: SliderCaptchaSize
+  keyboard?: boolean
+}
+```
+
+### 样式变量
+
+| 变量 | 默认值 | 说明 |
+| --- | --- | --- |
+| `--g3-control-height` | `32px` | 默认高度（手柄宽 = 高度） |
+| `--g3-control-height-sm` | `24px` | `size="small"` 的高度 |
+| `--g3-control-height-lg` | `40px` | `size="large"` 的高度 |
+| `--g3-fill` | `rgba(0, 0, 0, 0.04)` | 轨道底色 |
+| `--g3-border-color` | `#d9d9d9` | 轨道描边 |
+| `--g3-color-success` | `hsl(144 57% 58%)` | 进度条与通过后的手柄图标色 |
+| `--g3-bg-container` | `#fff` | 手柄底色 |
+
+## 实现说明
+
+- **拖拽走 Pointer Events + `setPointerCapture`**（与 `bindDrag` / `bindResize` 同一套）：指针移出组件、触屏、手写笔都能正确收尾，不需要往 `document` 上挂全局监听；捕获失败的老环境会退化成「移出即松手」，不会卡住。
+- **跟手不加过渡**：拖拽期间进度条与手柄必须实时跟随指针，只有回弹 / `Home` / `End` 跳转才启用 300ms 过渡（`is-returning`），否则会有「拖不动」的手感。
+- **行程 = 容器宽 - 手柄宽**：每次交互开始时量一次 `getBoundingClientRect()`，因此容器宽度自适应、字体缩放、`size` 变化都不需要监听 resize。
+- **只有从「已通过」回退时才 `emit('update:modelValue', false)`**：中途松手的回弹不该对外重复报一次 `false`。
+- **文案不硬编码**：默认值来自语言包 `captcha.slide` / `captcha.verified` / `captcha.sliderLabel`。
+- 初始 `modelValue = true`（回填已通过状态）时，手柄在挂载后一帧落到行程末端，不会停在起点。
diff --git a/code/g3soft-libs/docs/content/ui/overlay/dropdown.md b/code/g3soft-libs/docs/content/ui/overlay/dropdown.md
index b70208d0..1454f9f6 100644
--- a/code/g3soft-libs/docs/content/ui/overlay/dropdown.md
+++ b/code/g3soft-libs/docs/content/ui/overlay/dropdown.md
@@ -81,6 +81,7 @@ description: 点击 / 悬停 / 右键触发的操作列表，支持子菜单与
 | `mouseLeaveDelay` | `number` | `200` | hover 关闭延迟（ms）。有子菜单时适当调大 |
 | `offset` | `number` | `4` | 与触发器的间距（px） |
 | `unwrapped` | `boolean` | `true` | 零包裹模式，触发器不额外包 `<span>` |
+| `menuMaxHeight` | `boolean \| number \| string` | — | 菜单面板最大高度（超出才滚动）。不传 / `true` 用默认上限（`--g3-dropdown-max-height`，兜底 `calc(100vh - 48px)`）；`false` 不限制（面板随内容撑开，菜单很短时才用）；数字按 px；字符串原样（如 `'320px'` / `'min(480px, 70vh)'`）。面板 Teleport 到 `body`，调用方没法用 CSS 局部覆盖那个变量，所以按实例调整用这个 prop。子菜单面板沿用同一个值 |
 
 ### Events
 
@@ -138,7 +139,7 @@ export interface DropdownClickPayload {
 | 变量 | 默认值 | 说明 |
 | --- | --- | --- |
 | `--g3-dropdown-min-width` | `180px` | 菜单最小宽度 |
-| `--g3-dropdown-max-height` | `256px` | 菜单最大高度（超出滚动） |
+| `--g3-dropdown-max-height` | `calc(100vh - 48px)` | 菜单最大高度（超出滚动）；按视口算，菜单长到屏幕放不下才滚 |
 | `--g3-dropdown-item-padding-y` / `-x` | `5px` / `8px` | 菜单项内边距 |
 | `--g3-dropdown-item-radius` | `4px` | 菜单项圆角 |
 | `--g3-dropdown-divider-margin` | `4px 0` | 分隔线外边距 |
diff --git a/code/g3soft-libs/docs/content/ui/overlay/popover.md b/code/g3soft-libs/docs/content/ui/overlay/popover.md
index f59ecf50..d95786fa 100644
--- a/code/g3soft-libs/docs/content/ui/overlay/popover.md
+++ b/code/g3soft-libs/docs/content/ui/overlay/popover.md
@@ -67,6 +67,7 @@ description: 浮层基座：12 方位定位、自动翻转、外部点击与 Esc
 | `followTriggerWidth` | `boolean` | `false` | 浮层宽度以触发器宽度为下限 |
 | `unwrapped` | `boolean` | `false` | 零包裹模式：把事件注入触发器单个根节点，不再包一层 `<span>` |
 | `popupContainer` | `string \| HTMLElement \| (() => …)` | ConfigProvider 配置 | 浮层挂载容器，默认 `body` |
+| `popupScope` | `string` | — | 「同一条浮层链」标识：父面板与各级子浮层传同一个值，点击链内任意面板都不算点击外部（Dropdown 的子菜单靠它才能用鼠标点子项） |
 
 ### Events
 
diff --git a/code/g3soft-libs/docs/examples/attachment/basic.vue b/code/g3soft-libs/docs/examples/attachment/basic.vue
new file mode 100644
index 00000000..582b097b
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/attachment/basic.vue
@@ -0,0 +1,80 @@
+<script setup lang="ts">
+// 最小用法：只喂 files + categories，上传 / 删除交给业务（组件不发请求）
+import { ref } from 'vue'
+import { G3Attachment } from '@g3soft/ui'
+import type { AttachmentCategory, AttachmentItem, AttachmentUploadContext } from '@g3soft/ui'
+
+// 分类（可选）：不给 categories 就只渲染「列表 + 预览」两栏
+const categories: AttachmentCategory[] = [
+  { id: 'contract', name: '合同文件' },
+  { id: 'invoice', name: '发票凭证' },
+  { id: 'photo', name: '现场照片' },
+]
+
+// 内联 SVG，保证文档站离线也能看到图片预览
+const PHOTO = `data:image/svg+xml;utf8,${encodeURIComponent(
+  '<svg xmlns="http://www.w3.org/2000/svg" width="320" height="200"><rect width="320" height="200" fill="#e5e7eb"/><text x="160" y="108" font-size="18" text-anchor="middle" fill="#6b7280">现场照片</text></svg>',
+)}`
+
+const files = ref<AttachmentItem[]>([
+  { id: 1, name: '2026年度框架合同.pdf', size: 512_000, categoryId: 'contract' },
+  { id: 2, name: '供应商报价明细.xlsx', size: 86_000, categoryId: 'invoice' },
+  { id: 3, name: '现场照片.jpg', size: 1_240_000, categoryId: 'photo', url: PHOTO },
+  { id: 4, name: '验收纪要.docx', size: 24_000, categoryId: 'contract' },
+])
+
+const lastEvent = ref('等待操作…')
+
+// 没传 upload-request 时，组件把待上传文件抛出来，落库由业务决定
+function onUpload(incoming: File[], context: AttachmentUploadContext) {
+  files.value = [
+    ...files.value,
+    ...incoming.map((file, index) => ({
+      id: `local-${Date.now()}-${index}`,
+      name: file.name,
+      size: file.size,
+      categoryId: context.categoryId,
+      // 真实项目换成接口返回的地址；示例用 blob 地址即时预览
+      url: URL.createObjectURL(file),
+    })),
+  ]
+  lastEvent.value = `upload：${incoming.map((file) => file.name).join('、')}`
+}
+
+function onRemove(items: AttachmentItem[]) {
+  const removed = new Set(items.map((item) => item.id))
+  files.value = files.value.filter((file) => !removed.has(file.id))
+  lastEvent.value = `remove：${items.map((item) => item.name).join('、')}`
+}
+
+function onDownload(items: AttachmentItem[]) {
+  lastEvent.value = `download：${items.map((item) => item.name).join('、')}`
+}
+
+function onInvalid(info: { message: string }) {
+  lastEvent.value = `invalid：${info.message}`
+}
+</script>
+
+<template>
+  <div>
+    <G3Attachment
+      v-model:files="files"
+      :categories="categories"
+      :height="560"
+      @upload="onUpload"
+      @remove="onRemove"
+      @download="onDownload"
+      @invalid="onInvalid"
+    />
+    <p class="hint">{{ lastEvent }}</p>
+  </div>
+</template>
+
+<style scoped>
+.hint {
+  margin: 8px 0 0;
+  color: #8c8c8c;
+  font-size: 12px;
+}
+</style>
diff --git a/code/g3soft-libs/docs/examples/attachment/modal.vue b/code/g3soft-libs/docs/examples/attachment/modal.vue
new file mode 100644
index 00000000..2b1c5279
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/attachment/modal.vue
@@ -0,0 +1,58 @@
+<script setup lang="ts">
+// 弹窗用法：业务自己用 G3Modal 包一层，附件组件并不知道「弹窗」的存在
+import { ref } from 'vue'
+import { G3Attachment, G3Button, G3Modal } from '@g3soft/ui'
+import type { AttachmentItem, AttachmentUploadContext } from '@g3soft/ui'
+
+const open = ref(false)
+
+// 从空列表开始：正好看到空态投放区 → 入队（底栏变"脏"）→ 上传的完整过程
+const files = ref<AttachmentItem[]>([])
+
+const lastEvent = ref('')
+
+function onUpload(incoming: File[], context: AttachmentUploadContext) {
+  files.value = [
+    ...files.value,
+    ...incoming.map((file, index) => ({
+      id: `local-${Date.now()}-${index}`,
+      name: file.name,
+      size: file.size,
+      categoryId: context.categoryId,
+      url: URL.createObjectURL(file),
+    })),
+  ]
+  lastEvent.value = `已加入 ${incoming.length} 个文件`
+}
+
+function onRemove(items: AttachmentItem[]) {
+  const removed = new Set(items.map((item) => item.id))
+  files.value = files.value.filter((file) => !removed.has(file.id))
+  lastEvent.value = `已删除 ${items.length} 个文件`
+}
+</script>
+
+<template>
+  <div>
+    <G3Button @click="open = true">打开附件管理</G3Button>
+    <p class="hint">{{ lastEvent }}</p>
+
+    <!-- 弹窗高度用 vh，附件组件再按 100% 撑满；不给 categories 就只有列表一栏 -->
+    <G3Modal v-model:open="open" title="附件管理" width="80%" :fullscreen="false">
+      <G3Attachment
+        v-model:files="files"
+        height="60vh"
+        @upload="onUpload"
+        @remove="onRemove"
+      />
+    </G3Modal>
+  </div>
+</template>
+
+<style scoped>
+.hint {
+  margin: 8px 0 0;
+  color: #8c8c8c;
+  font-size: 12px;
+}
+</style>
diff --git a/code/g3soft-libs/docs/examples/attachment/readonly.vue b/code/g3soft-libs/docs/examples/attachment/readonly.vue
new file mode 100644
index 00000000..fc2e2563
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/attachment/readonly.vue
@@ -0,0 +1,20 @@
+<script setup lang="ts">
+// 只读：隐藏上传 / 删除入口，只保留浏览与下载
+import { G3Attachment } from '@g3soft/ui'
+import type { AttachmentItem } from '@g3soft/ui'
+
+const PHOTO = `data:image/svg+xml;utf8,${encodeURIComponent(
+  '<svg xmlns="http://www.w3.org/2000/svg" width="320" height="200"><rect width="320" height="200" fill="#dbeafe"/><text x="160" y="108" font-size="18" text-anchor="middle" fill="#1d4ed8">现场照片</text></svg>',
+)}`
+
+const files: AttachmentItem[] = [
+  { id: 1, name: '立项批复.pdf', size: 320_000 },
+  { id: 2, name: '现场照片.jpg', size: 1_024_000, url: PHOTO },
+  { id: 3, name: '预算表.xlsx', size: 64_000 },
+]
+</script>
+
+<template>
+  <!-- readonly 同时关掉「全选 / 批量删除 / 底栏上传」，拖拽与粘贴也会失效 -->
+  <G3Attachment :files="files" readonly :height="420" />
+</template>
diff --git a/code/g3soft-libs/docs/examples/attachment/select.vue b/code/g3soft-libs/docs/examples/attachment/select.vue
new file mode 100644
index 00000000..088f3e54
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/attachment/select.vue
@@ -0,0 +1,61 @@
+<script setup lang="ts">
+// 多选与批量操作：勾选后工具栏浮出「下载 / 删除」，行为全部走事件
+import { ref } from 'vue'
+import { G3Attachment } from '@g3soft/ui'
+import type { AttachmentItem } from '@g3soft/ui'
+
+const files = ref<AttachmentItem[]>([
+  { id: 'a1', name: '设备清单.xlsx', size: 128_000 },
+  { id: 'a2', name: '施工方案.pdf', size: 2_048_000 },
+  { id: 'a3', name: '进度汇报.pptx', size: 640_000 },
+  { id: 'a4', name: '材料验收单.docx', size: 32_000 },
+  { id: 'a5', name: '现场记录.zip', size: 8_192_000 },
+])
+
+const selected = ref<AttachmentItem[]>([])
+const lastEvent = ref('')
+
+function onSelect(items: AttachmentItem[]) {
+  selected.value = items
+}
+
+function onRemove(items: AttachmentItem[]) {
+  const removed = new Set(items.map((item) => item.id))
+  files.value = files.value.filter((file) => !removed.has(file.id))
+  lastEvent.value = `remove：${items.map((item) => item.name).join('、')}`
+}
+
+function onDownload(items: AttachmentItem[]) {
+  // 真实项目里在这里调接口拿签名地址再下载
+  lastEvent.value = `download：${items.map((item) => item.name).join('、')}`
+}
+</script>
+
+<template>
+  <div>
+    <!-- 每页 3 条演示分页；builtin-download 关掉后「下载」只上报事件 -->
+    <G3Attachment
+      v-model:files="files"
+      :height="420"
+      :builtin-download="false"
+      :show-size-changer="true"
+      :page-size="3"
+      :page-size-options="[3, 5]"
+      @select="onSelect"
+      @remove="onRemove"
+      @download="onDownload"
+    />
+    <p class="hint">
+      已选 {{ selected.length }} 个<span v-if="selected.length">：{{ selected.map((item) => item.name).join('、') }}</span>
+      <template v-if="lastEvent"> ｜ {{ lastEvent }}</template>
+    </p>
+  </div>
+</template>
+
+<style scoped>
+.hint {
+  margin: 8px 0 0;
+  color: #8c8c8c;
+  font-size: 12px;
+}
+</style>
diff --git a/code/g3soft-libs/docs/examples/captcha/basic.vue b/code/g3soft-libs/docs/examples/captcha/basic.vue
new file mode 100644
index 00000000..239c3a5b
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/captcha/basic.vue
@@ -0,0 +1,16 @@
+<script setup lang="ts">
+// 最基础用法：v-model 绑 boolean，true 表示已验证通过
+import { ref } from 'vue'
+import { G3SliderCaptcha } from '@g3soft/ui'
+
+const passed = ref(false)
+</script>
+
+<template>
+  <div style="max-width: 360px">
+    <G3SliderCaptcha v-model="passed" />
+    <p style="margin: 8px 0 0; font-size: 13px">
+      当前状态：{{ passed ? '已验证' : '未验证' }}
+    </p>
+  </div>
+</template>
diff --git a/code/g3soft-libs/docs/examples/captcha/in-form.vue b/code/g3soft-libs/docs/examples/captcha/in-form.vue
new file mode 100644
index 00000000..db65a731
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/captcha/in-form.vue
@@ -0,0 +1,43 @@
+<script setup lang="ts">
+// 与表单配合：FormItem 负责 label 与校验；提交后复位滑块（真实场景是校验失败 / 接口报错时）
+import { reactive, ref } from 'vue'
+import { G3Button, G3Form, G3FormItem, G3Input, G3Message, G3SliderCaptcha } from '@g3soft/ui'
+
+const model = reactive({ account: '', captcha: false })
+
+const rules = {
+  account: [{ required: true, message: '请输入账号' }],
+  captcha: [{ validator: (value: unknown) => value === true, message: '请完成滑块验证' }],
+}
+
+const captchaRef = ref<{ resume: () => void } | null>(null)
+
+function onSubmit(values: Record<string, unknown>) {
+  G3Message.success(`提交：${JSON.stringify(values)}`)
+  // 每轮提交都要重新验证：清值 + 复位滑块
+  model.captcha = false
+  captchaRef.value?.resume()
+}
+</script>
+
+<template>
+  <G3Form
+    :model="model"
+    :rules="rules"
+    layout="vertical"
+    label-align="left"
+    :required-mark="false"
+    style="max-width: 360px"
+    @submit="onSubmit"
+  >
+    <G3FormItem name="account" label="账号">
+      <G3Input v-model="model.account" placeholder="请输入账号" />
+    </G3FormItem>
+    <G3FormItem name="captcha">
+      <G3SliderCaptcha ref="captchaRef" v-model="model.captcha" />
+    </G3FormItem>
+    <G3FormItem>
+      <G3Button type="primary" block html-type="submit">提交</G3Button>
+    </G3FormItem>
+  </G3Form>
+</template>
diff --git a/code/g3soft-libs/docs/examples/captcha/sizes.vue b/code/g3soft-libs/docs/examples/captcha/sizes.vue
new file mode 100644
index 00000000..9bc2edc3
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/captcha/sizes.vue
@@ -0,0 +1,17 @@
+<script setup lang="ts">
+// 三种尺寸：高度分别取 --g3-control-height-sm / -height / -height-lg
+import { ref } from 'vue'
+import { G3SliderCaptcha } from '@g3soft/ui'
+
+const small = ref(false)
+const medium = ref(false)
+const large = ref(false)
+</script>
+
+<template>
+  <div style="display: grid; gap: 12px; max-width: 360px">
+    <G3SliderCaptcha v-model="small" size="small" />
+    <G3SliderCaptcha v-model="medium" />
+    <G3SliderCaptcha v-model="large" size="large" />
+  </div>
+</template>
diff --git a/code/g3soft-libs/docs/examples/rich-text/basic.vue b/code/g3soft-libs/docs/examples/rich-text/basic.vue
new file mode 100644
index 00000000..e3a0631c
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/rich-text/basic.vue
@@ -0,0 +1,11 @@
+<script setup lang="ts">
+// 基础用法：v-model 输出 HTML，工具条内置字体/字号/上下标/表格/撤销重做
+import { ref } from 'vue'
+import { G3RichText } from '@g3soft/ui'
+
+const html = ref('<p>你好，<strong>G3RichText</strong>！</p>')
+</script>
+
+<template>
+  <G3RichText v-model="html" placeholder="请输入正文…" />
+</template>
diff --git a/code/g3soft-libs/docs/examples/rich-text/methods.vue b/code/g3soft-libs/docs/examples/rich-text/methods.vue
new file mode 100644
index 00000000..96fac2c5
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/rich-text/methods.vue
@@ -0,0 +1,34 @@
+<script setup lang="ts">
+// 通过 ref 调用 getText / getHTML / clear / focus
+import { ref } from 'vue'
+import { G3Button, G3RichText, G3Space } from '@g3soft/ui'
+import type { RichTextExpose } from '@g3soft/ui'
+
+const html = ref('<p>富文本<b>正文</b>示例</p>')
+const editorRef = ref<RichTextExpose | null>(null)
+const plainText = ref('')
+
+function showPlainText() {
+  plainText.value = editorRef.value?.getText() ?? ''
+}
+
+function clearContent() {
+  editorRef.value?.clear()
+  plainText.value = ''
+}
+</script>
+
+<template>
+  <G3Space vertical :size="12" style="display: flex">
+    <G3Space :size="8">
+      <G3Button size="small" type="outline" @click="showPlainText">取纯文本</G3Button>
+      <G3Button size="small" type="outline" @click="clearContent">清空</G3Button>
+    </G3Space>
+
+    <G3RichText ref="editorRef" v-model="html" />
+
+    <p v-if="plainText" style="font-size: 13px; color: #666">
+      纯文本：{{ plainText }}
+    </p>
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/rich-text/readonly.vue b/code/g3soft-libs/docs/examples/rich-text/readonly.vue
new file mode 100644
index 00000000..73fa97a4
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/rich-text/readonly.vue
@@ -0,0 +1,26 @@
+<script setup lang="ts">
+// readonly 可聚焦可复制但不可编辑；disabled 整体灰化不可交互
+import { ref } from 'vue'
+import { G3RichText, G3Segmented, G3Space } from '@g3soft/ui'
+
+const mode = ref<'normal' | 'readonly' | 'disabled'>('readonly')
+const html = ref('<p>这是一段<strong>只读</strong>的内容，可以选中复制，但不能编辑。</p>')
+
+const options = [
+  { label: '只读', value: 'readonly' },
+  { label: '禁用', value: 'disabled' },
+  { label: '正常', value: 'normal' },
+]
+</script>
+
+<template>
+  <G3Space vertical :size="12" style="display: flex">
+    <G3Segmented v-model="mode" :options="options" />
+
+    <G3RichText
+      v-model="html"
+      :readonly="mode === 'readonly'"
+      :disabled="mode === 'disabled'"
+    />
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/rich-text/upload.vue b/code/g3soft-libs/docs/examples/rich-text/upload.vue
new file mode 100644
index 00000000..05a83de5
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/rich-text/upload.vue
@@ -0,0 +1,45 @@
+<script setup lang="ts">
+// 图片/视频上传：注入 uploadImage / uploadVideo，返回 { fileUrl, ... } 元数据；
+// 上传完成后触发 upload-inline，把内联资源上报给外层（对齐邮件 inline 附件模型）
+import { ref } from 'vue'
+import { G3RichText } from '@g3soft/ui'
+import type { RichTextUploadResult } from '@g3soft/ui'
+
+const html = ref('')
+
+// 演示用假上传：用 FileReader 转 data URL，模拟「上传 → 返回 URL」的完整流程
+function fakeUpload(file: File): Promise<RichTextUploadResult> {
+  return new Promise((resolve) => {
+    const reader = new FileReader()
+    reader.onload = () => {
+      resolve({
+        fileUrl: reader.result as string,
+        fileId: `demo-${Date.now()}`,
+        fileName: file.name,
+        fileSize: file.size,
+      })
+    }
+    reader.readAsDataURL(file)
+  })
+}
+
+const inlines = ref<RichTextUploadResult[]>([])
+
+function onUploadInline(result: RichTextUploadResult, kind: 'image' | 'video') {
+  inlines.value.push(result)
+}
+</script>
+
+<template>
+  <G3RichText
+    v-model="html"
+    :upload-image="fakeUpload"
+    :upload-video="fakeUpload"
+    placeholder="点击工具条的图片/视频按钮上传…"
+    @upload-inline="onUploadInline"
+  />
+
+  <p v-if="inlines.length" style="font-size: 13px; color: #666; margin-top: 12px">
+    已上传 {{ inlines.length }} 个内联资源：{{ inlines.map((i) => i.fileName).join('、') }}
+  </p>
+</template>
diff --git a/code/g3soft-libs/docs/examples/spin/delay.vue b/code/g3soft-libs/docs/examples/spin/delay.vue
index 0618ccd9..b3b63964 100644
--- a/code/g3soft-libs/docs/examples/spin/delay.vue
+++ b/code/g3soft-libs/docs/examples/spin/delay.vue
@@ -1,36 +1,55 @@
 <script setup lang="ts">
 // delay：请求很快时根本不显示，避免「闪一下」；慢请求才出现
 import { ref } from 'vue'
-import { G3Button, G3Spin, G3Space } from '@g3soft/ui'
+import { G3Button, G3Segmented, G3Space, G3Spin } from '@g3soft/ui'
 
 const fastLoading = ref(false)
 const slowLoading = ref(false)
 
-async function run(duration: number, target: typeof fastLoading) {
-  target.value = true
-  await new Promise((resolve) => setTimeout(resolve, duration))
-  target.value = false
+// 可调的 delay 时长，直观对比「延迟多久后才出现」
+const delay = ref(300)
+const delayOptions = [
+  { label: '0ms', value: 0 },
+  { label: '300ms', value: 300 },
+  { label: '800ms', value: 800 },
+]
+
+// 注意：模板里 @click="run(200, fastLoading)" 会把 ref 自动解包成布尔值，
+// 因此这里不接收 ref 对象，而是接收「设置加载态」的回调，避免在布尔值上写 .value 报错。
+function run(duration: number, setLoading: (v: boolean) => void) {
+  setLoading(true)
+  setTimeout(() => setLoading(false), duration)
 }
 </script>
 
 <template>
   <G3Space vertical :size="16" style="display: flex">
-    <G3Space :size="8">
-      <G3Button size="small" type="outline" @click="run(200, fastLoading)">200ms 请求</G3Button>
-      <G3Button size="small" type="outline" @click="run(1500, slowLoading)">1500ms 请求</G3Button>
+    <G3Space :size="8" align="center">
+      <span class="label">delay</span>
+      <G3Segmented v-model="delay" :options="delayOptions" />
     </G3Space>
 
-    <G3Spin :spinning="fastLoading" :delay="400">
-      <div class="box">内容区域</div>
+    <G3Space :size="8">
+      <G3Button size="small" type="outline" @click="run(200, (v) => (fastLoading = v))">200ms 请求</G3Button>
+      <G3Button size="small" type="outline" @click="run(1500, (v) => (slowLoading = v))">1500ms 请求</G3Button>
+    </G3Space>
+
+    <G3Spin :spinning="fastLoading" :delay="delay">
+      <div class="box">200ms 请求（短于 delay 时不显示加载态）</div>
     </G3Spin>
 
-    <G3Spin :spinning="slowLoading" :delay="400">
-      <div class="box">内容区域</div>
+    <G3Spin :spinning="slowLoading" :delay="delay">
+      <div class="box">1500ms 请求（超过 delay 后显示加载态）</div>
     </G3Spin>
   </G3Space>
 </template>
 
 <style scoped>
+.label {
+  font-size: 13px;
+  color: #666;
+}
+
 .box {
   padding: 20px;
   border: 1px solid #d9d9d9;
diff --git a/code/g3soft-libs/packages/ui/e2e/attachment.spec.ts b/code/g3soft-libs/packages/ui/e2e/attachment.spec.ts
new file mode 100644
index 00000000..09ea892c
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/e2e/attachment.spec.ts
@@ -0,0 +1,56 @@
+import { expect, test } from '@playwright/test'
+
+/**
+ * Attachment 的几何 / 命中类断言 —— happy-dom 没有布局引擎，这些只能在真浏览器里量。
+ *
+ * 回归背景（都踩过）：
+ * 1. 工具栏勾选后浮出批量按钮，一度把整条工具栏撑高、下方内容跟着下移；
+ * 2. 分隔线依赖 Splitter 的 barOnHover，默认只在 hover 时显示，
+ *    表现为「分类栏右侧看不见边界」。
+ */
+test.describe('Attachment 附件管理器', () => {
+  test.beforeEach(async ({ page }) => {
+    await page.goto('/')
+    await page.locator('[data-testid="attachment"]').scrollIntoViewIfNeeded()
+  })
+
+  test('工具栏高度恒定：勾选前后、宽窄面板下都是 40px', async ({ page }) => {
+    // 40 = --g3-control-height-sm(24) + --g3-space-2(8) * 2
+    const EXPECTED_HEIGHT = 40
+
+    for (const testId of ['attachment', 'attachment-narrow']) {
+      const toolbar = page.locator(`[data-testid="${testId}"] .g3-attachment__toolbar`)
+      const before = await toolbar.boundingBox()
+
+      await toolbar.locator('.g3-checkbox').first().click()
+      await expect(toolbar.locator('.g3-attachment__toolbar-count')).toBeVisible()
+      const after = await toolbar.boundingBox()
+
+      expect(before, `${testId}: 工具栏应可测量`).not.toBeNull()
+      expect(after, `${testId}: 工具栏应可测量`).not.toBeNull()
+      expect(before!.height, `${testId}: 未勾选时工具栏高度`).toBe(EXPECTED_HEIGHT)
+      // 勾选后浮出「已选 N 项 + 下载 + 删除」，高度必须纹丝不动
+      expect(after!.height, `${testId}: 勾选后工具栏高度`).toBe(EXPECTED_HEIGHT)
+
+      // 复位，避免影响下一个实例的断言
+      await toolbar.locator('.g3-checkbox').first().click()
+      await expect(toolbar.locator('.g3-attachment__toolbar-count')).toBeHidden()
+    }
+  })
+
+  test('分类栏右侧的分割线常显（不依赖 hover）', async ({ page }) => {
+    const line = page
+      .locator('[data-testid="attachment"] .g3-attachment__splitter .g3-splitter__bar-line')
+      .first()
+
+    await expect(line).toBeVisible()
+
+    const background = await line.evaluate((el) => getComputedStyle(el).backgroundColor)
+    // 默认是 --g3-border-color(#d9d9d9)；只要不是透明的，就说明线是画出来的
+    expect(background).not.toBe('rgba(0, 0, 0, 0)')
+
+    const box = await line.boundingBox()
+    expect(box!.width).toBeLessThanOrEqual(2)
+    expect(box!.height).toBeGreaterThan(100)
+  })
+})
diff --git a/code/g3soft-libs/packages/ui/e2e/captcha.spec.ts b/code/g3soft-libs/packages/ui/e2e/captcha.spec.ts
new file mode 100644
index 00000000..249272ab
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/e2e/captcha.spec.ts
@@ -0,0 +1,155 @@
+import { expect, test, type Locator, type Page } from '@playwright/test'
+
+/**
+ * 滑块验证码（L3，真浏览器）。
+ *
+ * 为什么必须在真实浏览器里跑：这一层的断言全是**几何**与**指针轨迹** —— 手柄最终停在哪、
+ * 进度条盖住多少、拖到容器外松手会不会收尾。happy-dom 没有布局引擎，单测只能把 rect
+ * 钉死后验逻辑（见 src/captcha/SliderCaptcha.test.ts）。
+ *
+ * 两个踩过的坑（写在这里防复发）：
+ *  1. playground 是一整页长文档，滑块区在首屏之下，而 `boundingBox()` 返回**视口坐标** ——
+ *     不先 `scrollIntoViewIfNeeded()` 就往那儿发鼠标事件，会落到视口外，表现为「拖了没反应」；
+ *  2. 拖拽终点要**越过容器边缘**几像素：行程是按 padding box 算的，贴着边缘算容易因为
+ *     1px 取整「差一点不通过」，越界部分本来就会被组件夹住。
+ *
+ * 进 RTL 统一走 `?dir=rtl`（playground 写到 `<html dir>`），不依赖点击开关的顺序。
+ */
+
+const url = (dir: 'ltr' | 'rtl') => `/?dir=${dir}`
+
+async function gotoDir(page: Page, dir: 'ltr' | 'rtl') {
+  await page.goto(url(dir))
+  await expect(page.locator('html')).toHaveAttribute('dir', dir)
+}
+
+async function isRtl(page: Page): Promise<boolean> {
+  return (await page.locator('html').getAttribute('dir')) === 'rtl'
+}
+
+/**
+ * 用真实鼠标把滑块从起点拖向行内结束端；`releaseRatio` 传 0.5 表示拖到一半就松手。
+ */
+async function dragHandle(
+  page: Page,
+  root: Locator,
+  options: { releaseRatio?: number } = {},
+): Promise<void> {
+  await root.scrollIntoViewIfNeeded()
+  const rtl = await isRtl(page)
+  const handle = root.locator('.g3-slider-captcha__action')
+  const handleBox = (await handle.boundingBox())!
+  const rootBox = (await root.boundingBox())!
+
+  const y = handleBox.y + handleBox.height / 2
+  const startX = handleBox.x + handleBox.width / 2
+  // 越界 8px：行内结束端在 LTR 是右边缘、RTL 是左边缘
+  const endX = rtl ? rootBox.x - 8 : rootBox.x + rootBox.width + 8
+  const targetX = startX + (endX - startX) * (options.releaseRatio ?? 1)
+
+  await page.mouse.move(startX, y)
+  await page.mouse.down()
+  await page.mouse.move(targetX, y, { steps: 12 })
+  await page.mouse.up()
+}
+
+test.describe('SliderCaptcha', () => {
+  test('真实拖拽到末端即通过：进度 100、文案切换、状态回传', async ({ page }) => {
+    await page.goto('/')
+    const root = page.locator('[data-testid="slider-captcha"]')
+    const handle = root.locator('.g3-slider-captcha__action')
+
+    await root.scrollIntoViewIfNeeded()
+    await expect(root.locator('.g3-slider-captcha__text')).toHaveText('按住滑块拖动')
+    await expect(handle).toHaveAttribute('aria-valuenow', '0')
+    // 未通过时才可聚焦，通过后要让出 Tab 顺序
+    await expect(handle).toHaveAttribute('tabindex', '0')
+
+    await dragHandle(page, root)
+
+    await expect(root).toHaveClass(/is-passed/)
+    await expect(root.locator('.g3-slider-captcha__text')).toHaveText('验证通过')
+    await expect(handle).toHaveAttribute('aria-valuenow', '100')
+    await expect(handle).toHaveAttribute('tabindex', '-1')
+    await expect(page.locator('[data-testid="slider-captcha-state"]')).toHaveText('passed')
+
+    // 手柄右缘贴住轨道末端（取整误差 1px 内）
+    const rootBox = (await root.boundingBox())!
+    const handleBox = (await handle.boundingBox())!
+    expect(handleBox.x + handleBox.width).toBeLessThanOrEqual(rootBox.x + rootBox.width + 1)
+    // 进度条盖住手柄的一半
+    const barBox = (await root.locator('.g3-slider-captcha__bar').boundingBox())!
+    expect(barBox.width).toBeGreaterThan(rootBox.width - handleBox.width)
+  })
+
+  test('中途松手回弹到起点，不报通过', async ({ page }) => {
+    await page.goto('/')
+    const root = page.locator('[data-testid="slider-captcha"]')
+    const handle = root.locator('.g3-slider-captcha__action')
+
+    await dragHandle(page, root, { releaseRatio: 0.5 })
+
+    await expect(root).not.toHaveClass(/is-passed/)
+    await expect(page.locator('[data-testid="slider-captcha-state"]')).toHaveText('idle')
+    await expect(handle).toHaveAttribute('aria-valuenow', '0')
+    // 回弹有 300ms 过渡，用 poll 等它归位到行程起点
+    const rootBox = (await root.boundingBox())!
+    await expect
+      .poll(async () => (await handle.boundingBox())!.x, { timeout: 3000 })
+      .toBeLessThanOrEqual(rootBox.x + 2)
+  })
+
+  test('禁用态拖不动，且带 is-disabled 类', async ({ page }) => {
+    await page.goto('/')
+    const root = page.locator('[data-testid="slider-captcha-disabled"]')
+    const handle = root.locator('.g3-slider-captcha__action')
+
+    await root.scrollIntoViewIfNeeded()
+    await expect(root).toHaveClass(/is-disabled/)
+    await expect(handle).toHaveAttribute('tabindex', '-1')
+
+    await dragHandle(page, root)
+    await expect(root).not.toHaveClass(/is-passed/)
+  })
+
+  test('键盘：End 直达终点并通过，Home 复位', async ({ page }) => {
+    await page.goto('/')
+    const root = page.locator('[data-testid="slider-captcha"]')
+    const handle = root.locator('.g3-slider-captcha__action')
+
+    await root.scrollIntoViewIfNeeded()
+    await handle.focus()
+    await page.keyboard.press('End')
+    await expect(root).toHaveClass(/is-passed/)
+    await expect(page.locator('[data-testid="slider-captcha-state"]')).toHaveText('passed')
+  })
+
+  test.describe('RTL', () => {
+    test('手柄从右侧起步，向左拖到末端才通过', async ({ page }) => {
+      await gotoDir(page, 'rtl')
+      const root = page.locator('[data-testid="slider-captcha"]')
+      const handle = root.locator('.g3-slider-captcha__action')
+
+      await root.scrollIntoViewIfNeeded()
+      const rootBox = (await root.boundingBox())!
+      const handleBox = (await handle.boundingBox())!
+      // 起点贴行内起始边 = RTL 下的右边
+      expect(handleBox.x + handleBox.width).toBeGreaterThanOrEqual(rootBox.x + rootBox.width - 2)
+
+      // 未通过时的方向性图标按全库规则翻面（chevrons-right 在 RTL 下镜像）；
+      // 必须在拖拽前断言 —— 通过后图标会换成 Check，那条镜像规则就不适用了
+      const iconTransform = await handle
+        .locator('svg')
+        .evaluate((el) => getComputedStyle(el).transform)
+      expect(iconTransform).toBe('matrix(-1, 0, 0, 1, 0, 0)')
+
+      await dragHandle(page, root)
+
+      await expect(root).toHaveClass(/is-passed/)
+      // 终点贴行内结束边 = RTL 下的左边
+      await expect
+        .poll(async () => (await handle.boundingBox())!.x, { timeout: 3000 })
+        .toBeLessThanOrEqual(rootBox.x + 2)
+    })
+  })
+})
diff --git a/code/g3soft-libs/packages/ui/e2e/rich-text-focus.spec.ts b/code/g3soft-libs/packages/ui/e2e/rich-text-focus.spec.ts
new file mode 100644
index 00000000..c390f11e
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/e2e/rich-text-focus.spec.ts
@@ -0,0 +1,188 @@
+import { expect, test, type Page } from '@playwright/test'
+
+/**
+ * 富文本内容区的几何与聚焦回归。
+ *
+ * 背景：`minHeight` / `maxHeight` 作用在内容区（`.g3-rich-text__content`）上，而
+ * EditorContent 会再套一层包裹 DOM，`.tiptap` 原本写的 `min-height: inherit` 继承的是
+ * 那一层的 computed 值（恒为 0），于是可编辑区只跟内容一样高 —— 空文档时 200px 的内容区
+ * 里只有约 45px 能点，下方全是「点上去既不聚焦也不落光标」的死区。
+ *
+ * 这三个用例分别锁：内容区短时「可编辑区撑满 + 点空白聚焦到末尾」、宿主样式破坏撑高时的
+ * 兜底聚焦、内容长时「可编辑区按内容撑开 + 由内容区滚动（不裁切）」。
+ *
+ * 聚焦、caret 落位与滚动都必须真浏览器：happy-dom 没有真实聚焦、选区与布局。
+ */
+
+const EDITOR = '[data-testid="rich-text"]'
+
+/** 清空正文并输入一段文本（光标停在输入末尾） */
+async function resetContent(page: Page, text: string): Promise<void> {
+  const editor = page.getByTestId('rich-text')
+  await editor.scrollIntoViewIfNeeded()
+  await editor.locator('.tiptap').click()
+  await page.keyboard.press('Control+A')
+  await page.keyboard.press('Delete')
+  await page.keyboard.type(text)
+}
+
+/** 内容区 / 可编辑区的实测高度 */
+function heights(page: Page) {
+  return page.evaluate(() => {
+    const content = document.querySelector('.g3-rich-text__content') as HTMLElement
+    const tiptap = content.querySelector('.tiptap') as HTMLElement
+    return {
+      content: Math.round(content.getBoundingClientRect().height),
+      tiptap: Math.round(tiptap.getBoundingClientRect().height),
+      focused: tiptap.classList.contains('ProseMirror-focused'),
+    }
+  })
+}
+
+test.describe('RichText 聚焦', () => {
+  test('可编辑区撑满内容区，点内容区空白即聚焦、光标落在正文末尾', async ({ page }) => {
+    await page.goto('/')
+    await resetContent(page, '第一行')
+
+    const editor = page.getByTestId('rich-text')
+    const content = editor.locator('.g3-rich-text__content')
+    const tiptap = editor.locator('.tiptap')
+
+    // 布局：空文档时内容区还是最小高度（200px），可编辑区必须一样高
+    const before = await heights(page)
+    expect(before.content).toBeGreaterThanOrEqual(200)
+    expect(before.tiptap).toBe(before.content)
+
+    // 点内容区底部（正文下方那片空白）
+    const box = (await content.boundingBox())!
+    await page.mouse.click(box.x + box.width / 2, box.y + box.height - 10)
+
+    await expect(tiptap).toHaveClass(/ProseMirror-focused/)
+    await expect
+      .poll(() =>
+        page.evaluate(() => document.activeElement?.classList.contains('ProseMirror') ?? false),
+      )
+      .toBe(true)
+
+    // 光标在末尾：继续输入会追加在正文后面
+    await page.keyboard.type('！')
+    await expect(editor.locator('.tiptap')).toContainText('第一行！')
+  })
+
+  test('宿主样式破坏撑高时，点编辑器 DOM 之外的空白仍能聚焦到末尾', async ({ page }) => {
+    await page.goto('/')
+    await resetContent(page, '第二行')
+
+    // 模拟宿主样式把「可编辑区撑满内容区」改掉：包裹层收回到内容高度
+    await page.addStyleTag({ content: '.g3-rich-text__content > div { flex: 0 0 auto !important; }' })
+
+    const editor = page.getByTestId('rich-text')
+    const content = editor.locator('.g3-rich-text__content')
+    const gap = await heights(page)
+    expect(gap.tiptap).toBeLessThan(gap.content)
+
+    const box = (await content.boundingBox())!
+    await page.mouse.click(box.x + box.width / 2, box.y + box.height - 10)
+
+    await expect(editor.locator('.tiptap')).toHaveClass(/ProseMirror-focused/)
+    await page.keyboard.type('！！')
+    await expect(editor.locator('.tiptap')).toContainText('第二行！！')
+  })
+
+  test('编辑器内部的点击仍按坐标落光标（不被空白聚焦抢走）', async ({ page }) => {
+    await page.goto('/')
+    await resetContent(page, '第一行')
+    await page.keyboard.press('Enter')
+    await page.keyboard.type('第二行')
+
+    const editor = page.getByTestId('rich-text')
+    const second = editor.locator('.tiptap p').nth(1)
+    const box = (await second.boundingBox())!
+    // 点第二行最左侧 —— 光标应落在该行句首，而不是被挪到全文末尾
+    await page.mouse.click(box.x + 8, box.y + box.height / 2)
+
+    const caret = await page.evaluate(() => {
+      const selection = window.getSelection()
+      const node = selection?.anchorNode
+      const element = node?.nodeType === 3 ? node.parentElement : (node as HTMLElement | null)
+      return { text: element?.closest('p')?.textContent ?? '', offset: selection?.anchorOffset ?? -1 }
+    })
+    expect(caret.text).toBe('第二行')
+    expect(caret.offset).toBeLessThan(2)
+  })
+
+  test('聚焦时正文区四周亮起 2px 主色描边（工具条不参与）', async ({ page }) => {
+    await page.goto('/')
+    const editor = page.getByTestId('rich-text')
+    const content = editor.locator('.g3-rich-text__content')
+    const ring = () => content.evaluate((el) => getComputedStyle(el).boxShadow)
+
+    // 未聚焦：正文区没有描边
+    await expect.poll(ring).toBe('none')
+
+    // 点正文 → 正文区四周亮起
+    await editor.locator('.tiptap').click()
+    await expect.poll(ring).toContain('inset')
+    await expect.poll(ring).toContain('rgb(24, 24, 27)')
+
+    // 描边必须挂在滚动容器自己身上（背景/阴影不随内容滚动）；挂在伪元素覆盖层上会跟着正文滚走
+    const owners = await page.evaluate(() => {
+      const el = document.querySelector('.g3-rich-text__content') as HTMLElement
+      return { own: getComputedStyle(el).boxShadow, pseudo: getComputedStyle(el, '::after').boxShadow }
+    })
+    expect(owners.own).toContain('inset')
+    expect(owners.pseudo).toBe('none')
+
+    // 点工具条按钮：焦点临时落在按钮上，编辑器整体仍是聚焦态 → 描边不熄
+    await editor.locator('button[aria-label="加粗"]').click()
+    await expect.poll(ring).toContain('inset')
+
+    // 点到编辑器之外 → 熄灭（用 > 限定，编辑器正文里也有 h2）
+    await page.locator('#s-richtext > h2').click()
+    await expect.poll(ring).toBe('none')
+  })
+
+  test('正文超出内容区时按内容撑开、由内容区滚动（正文不被裁切）', async ({ page }) => {
+    await page.goto('/')
+    // 宿主给内容区一个 max-height（等价于 maxHeight prop）
+    await page.addStyleTag({ content: '.g3-rich-text__content { max-height: 220px !important; }' })
+    await resetContent(page, '第 1 行')
+    for (let i = 1; i < 20; i++) {
+      await page.keyboard.press('Enter')
+      await page.keyboard.type(`第 ${i + 1} 行`)
+    }
+
+    const measure = () =>
+      page.evaluate(() => {
+        const content = document.querySelector('.g3-rich-text__content') as HTMLElement
+        const tiptap = content.querySelector('.tiptap') as HTMLElement
+        const last = tiptap.lastElementChild as HTMLElement
+        const viewportBottom = content.getBoundingClientRect().bottom
+        return {
+          client: content.clientHeight,
+          scroll: content.scrollHeight,
+          tiptap: Math.round(tiptap.getBoundingClientRect().height),
+          lastText: last.textContent ?? '',
+          lastVisible: last.getBoundingClientRect().bottom <= viewportBottom + 1,
+        }
+      })
+
+    // 停在顶部：可编辑区必须按内容撑开（大于内容区），而不是被压到视口高度裁掉正文
+    await page.evaluate(() => {
+      ;(document.querySelector('.g3-rich-text__content') as HTMLElement).scrollTop = 0
+    })
+    const top = await measure()
+    expect(top.tiptap).toBeGreaterThan(top.client)
+    expect(top.scroll).toBeGreaterThan(top.client)
+    expect(top.lastText).toBe('第 20 行')
+    expect(top.lastVisible).toBe(false)
+
+    // 滚到底：最后一行完整可见
+    await page.evaluate(() => {
+      const content = document.querySelector('.g3-rich-text__content') as HTMLElement
+      content.scrollTop = content.scrollHeight
+    })
+    const bottom = await measure()
+    expect(bottom.lastVisible).toBe(true)
+  })
+})
diff --git a/code/g3soft-libs/packages/ui/e2e/rich-text-table.spec.ts b/code/g3soft-libs/packages/ui/e2e/rich-text-table.spec.ts
new file mode 100644
index 00000000..b99859d8
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/e2e/rich-text-table.spec.ts
@@ -0,0 +1,445 @@
+import { expect, test, type Page } from '@playwright/test'
+
+/**
+ * 富文本表格的样式 / 交互回归。
+ *
+ * 1. 抗宿主页面全局样式：文档站（VitePress 默认主题）会在 `.vp-doc` 下写全局表格样式 ——
+ *    `table { display: block }` 让表格退化为块级收缩布局、网格宽度不再是 100%；
+ *    `tr:nth-child(2n) { background-color: … }` 把斑马纹染到表体行。组件必须在自身样式里
+ *    显式复位这些属性（与 Drawer 的 `section { margin }` 是同一类坑）。
+ * 2. 空内容插入表格要与顶部留出间距（`.tiptap` 需有纵向内边距）。
+ * 3. 单元格单行行高不能被 `<p>` 的 UA 外边距撑高。
+ * 4. 列宽拖拽：光标为 col-resize、hover 不改变行高、表格不被拖出容器、列宽有下限。
+ *
+ * 这些都是布局结果，只能放 E2E（happy-dom 没有布局引擎）。
+ */
+
+/** 插入表格（cols 为列数，默认 3 行 3 列） */
+async function insertTable(page: Page, cols?: number): Promise<void> {
+  const editor = page.getByTestId('rich-text')
+  await editor.scrollIntoViewIfNeeded()
+  await editor.locator('button[aria-label="插入表格"]').click()
+  if (cols) await page.locator('.g3-rich-text__table-input').nth(1).fill(String(cols))
+  await page.getByRole('button', { name: '插入', exact: true }).click()
+  await expect(editor.locator('table')).toHaveCount(1)
+  await editor.locator('table').scrollIntoViewIfNeeded()
+}
+
+/** 表格几何 / 样式快照 */
+function tableSnapshot(page: Page) {
+  return page.evaluate(() => {
+    const root = document.querySelector('[data-testid="rich-text"]')!
+    const content = root.querySelector('.g3-rich-text__content')!
+    const tiptap = root.querySelector('.tiptap')!
+    const table = root.querySelector('table')!
+    const wrapper = table.parentElement!
+    const headerCells = Array.from(table.querySelectorAll('tr:first-child th'))
+    const rows = Array.from(table.querySelectorAll('tr'))
+    const handle = table.querySelector('.column-resize-handle')
+    return {
+      // .tiptap 左右各 12px 内边距，减掉才是表格可用的内容宽度
+      containerWidth: Math.round(tiptap.getBoundingClientRect().width) - 24,
+      tableWidth: Math.round(table.getBoundingClientRect().width),
+      contentOverflowsX: content.scrollWidth > content.clientWidth,
+      wrapperScrollsX: wrapper.scrollWidth > wrapper.clientWidth,
+      columnWidths: headerCells.map((cell) => Math.round(cell.getBoundingClientRect().width)),
+      rowHeights: rows.map((row) => Math.round(row.getBoundingClientRect().height)),
+      cursor: getComputedStyle(tiptap).cursor,
+      handlePosition: handle ? getComputedStyle(handle).position : null,
+    }
+  })
+}
+
+/** 第一列表头右边缘（列分隔线）的视口坐标 */
+function dividerPoint(page: Page) {
+  return page.evaluate(() => {
+    const cell = document.querySelector('[data-testid="rich-text"] table tr:first-child th')!
+    const box = cell.getBoundingClientRect()
+    return { x: Math.round(box.right) - 2, y: Math.round(box.y + box.height / 2) }
+  })
+}
+
+/** 拖动第一列右侧的分隔线 dx 像素 */
+async function dragDivider(page: Page, dx: number): Promise<void> {
+  const from = await dividerPoint(page)
+  await page.mouse.move(from.x, from.y)
+  await page.mouse.down()
+  await page.mouse.move(from.x + dx, from.y, { steps: 8 })
+  await page.mouse.up()
+  await page.waitForTimeout(150)
+}
+
+test.describe('RichText 表格', () => {
+  test('表格保持满宽，且仅表头行有底色', async ({ page }) => {
+    await page.goto('/')
+
+    // 等价于 VitePress `.vp-doc` 的宿主全局表格样式
+    await page.addStyleTag({
+      content: [
+        'table { display: block; margin: 20px 0; overflow-x: auto; }',
+        'tr { border-top: 1px solid #e2e2e3; background-color: #fff; }',
+        'tr:nth-child(2n) { background-color: #f6f6f7; }',
+      ].join('\n'),
+    })
+
+    await insertTable(page)
+    const editor = page.getByTestId('rich-text')
+    const table = editor.locator('table')
+
+    // 1) 布局：表格铺满容器（display:block 时网格会收缩到内容宽）
+    const tableBox = (await table.boundingBox())!
+    const wrapperBox = (await table.locator('xpath=..').boundingBox())!
+    expect(Math.round(tableBox.width)).toBeCloseTo(Math.round(wrapperBox.width), 0)
+
+    const headerCells = table.locator('tr').first().locator('th')
+    await expect(headerCells).toHaveCount(3)
+    const cellWidths = await headerCells.evaluateAll((els) =>
+      els.map((el) => el.getBoundingClientRect().width),
+    )
+    // 三列均分：每列约为 1/3 表宽（收缩布局下会远小于此）
+    for (const width of cellWidths) expect(width).toBeGreaterThan(tableBox.width / 3 - 4)
+
+    // 2) 背景：宿主斑马纹不得染到表体行，只有表头行（th）保留组件自身的底色
+    const rowBackgrounds = await table
+      .locator('tr')
+      .evaluateAll((rows) => rows.map((row) => getComputedStyle(row).backgroundColor))
+    expect(rowBackgrounds.slice(1).every((bg) => bg === 'rgba(0, 0, 0, 0)')).toBe(true)
+
+    const headerBg = await headerCells
+      .first()
+      .evaluate((el) => getComputedStyle(el).backgroundColor)
+    expect(headerBg).not.toBe('rgba(0, 0, 0, 0)')
+  })
+
+  test('空内容时插入的表格保留顶部间距', async ({ page }) => {
+    await page.goto('/')
+    const editor = page.getByTestId('rich-text')
+    await editor.scrollIntoViewIfNeeded()
+
+    // 清空内容，让表格成为首个块
+    await editor.locator('.tiptap').click()
+    await page.keyboard.press('Control+A')
+    await page.keyboard.press('Delete')
+
+    await insertTable(page)
+
+    // 表格（无 UA 外边距的块）作为首块时，必须与内容区顶部留出间距，不能贴顶
+    const gap = await page.evaluate(() => {
+      const root = document.querySelector('[data-testid="rich-text"]')!
+      const tiptap = root.querySelector('.tiptap')!
+      const table = root.querySelector('table')!
+      return Math.round(table.getBoundingClientRect().top - tiptap.getBoundingClientRect().top)
+    })
+    expect(gap).toBeGreaterThanOrEqual(8)
+  })
+
+  test('单元格单行行高不被段落默认外边距撑高', async ({ page }) => {
+    await page.goto('/')
+    await insertTable(page)
+
+    // 单元格内 <p> 的 UA 上下外边距（各 1em）曾把单行行高从 ~38px 撑到 ~66px
+    const { rowHeights } = await tableSnapshot(page)
+    for (const height of rowHeights) {
+      expect(height).toBeGreaterThan(30)
+      expect(height).toBeLessThan(50)
+    }
+  })
+
+  test('插入表格面板：label 与输入框上下排列且输入框不溢出', async ({ page }) => {
+    await page.goto('/')
+    const editor = page.getByTestId('rich-text')
+    await editor.scrollIntoViewIfNeeded()
+    await editor.locator('button[aria-label="插入表格"]').click()
+
+    const fields = page.locator('.g3-rich-text__table-field')
+    // 行数 / 列数 / 包含表头行 三个字段
+    await expect(fields).toHaveCount(3)
+
+    // 只对含数字输入框的两个字段做上下排列 + 不溢出校验
+    const geometry = await fields.evaluateAll((els) =>
+      els.flatMap((el) => {
+        const label = el.querySelector('.g3-rich-text__table-label')!.getBoundingClientRect()
+        const input = el.querySelector('.g3-rich-text__table-input')
+        if (!input) return []
+        const rect = input.getBoundingClientRect()
+        return [
+          {
+            labelBottom: label.bottom,
+            inputTop: rect.top,
+            inputWidth: rect.width,
+            fieldWidth: el.getBoundingClientRect().width,
+          },
+        ]
+      }),
+    )
+
+    expect(geometry).toHaveLength(2)
+    for (const item of geometry) {
+      // 输入框在 label 下方
+      expect(item.inputTop).toBeGreaterThanOrEqual(item.labelBottom)
+      // content-box + width:100% 曾让输入框比容器宽 18px（padding + border）
+      expect(Math.round(item.inputWidth)).toBeLessThanOrEqual(Math.round(item.fieldWidth) + 1)
+    }
+  })
+})
+
+test.describe('RichText 表格 · 列宽拖拽', () => {
+  // 用窄视口，更容易触及列宽的上下限
+  test.use({ viewport: { width: 720, height: 900 } })
+
+  test('悬停分隔线：光标为 col-resize，且行高不跳动', async ({ page }) => {
+    await page.goto('/')
+    await insertTable(page)
+
+    const before = await tableSnapshot(page)
+    expect(before.handlePosition).toBeNull()
+
+    const point = await dividerPoint(page)
+    await page.mouse.move(point.x, point.y)
+    await page.waitForTimeout(200)
+
+    const hover = await tableSnapshot(page)
+    expect(hover.cursor).toBe('col-resize')
+    // 拖拽手柄必须脱离文档流 —— 回归：它曾作为流内块把行高从 38px 撑到 45px
+    expect(hover.handlePosition).toBe('absolute')
+    expect(hover.rowHeights).toEqual(before.rowHeights)
+
+    // 手柄只在表头行显示 —— 回归：曾在每一行都画一段，看起来是一列断开的虚线
+    const handles = await page.evaluate(() => {
+      const all = Array.from(
+        document.querySelectorAll('[data-testid="rich-text"] table .column-resize-handle'),
+      )
+      return {
+        total: all.length,
+        visible: all.filter((el) => getComputedStyle(el).display !== 'none').length,
+      }
+    })
+    expect(handles.total).toBeGreaterThan(1)
+    expect(handles.visible).toBe(1)
+  })
+
+  test('拖拽列宽精确跟手，且溢出只发生在表格容器层', async ({ page }) => {
+    await page.goto('/')
+    await insertTable(page)
+
+    const before = await tableSnapshot(page)
+    await dragDivider(page, 150)
+    const after = await tableSnapshot(page)
+
+    // 拖宽第一列 150px：第一列精确变宽，其余列纹丝不动
+    expect(after.columnWidths[0]).toBeCloseTo(before.columnWidths[0] + 150, -1)
+    expect(after.columnWidths[1]).toBeCloseTo(before.columnWidths[1], -1)
+    expect(after.columnWidths[2]).toBeCloseTo(before.columnWidths[2], -1)
+    // 表格总宽超出容器时，横向滚动只发生在 .tableWrapper 层，不进编辑器内容区
+    expect(after.contentOverflowsX).toBe(false)
+    expect(after.wrapperScrollsX).toBe(true)
+  })
+
+  test('列宽被夹在最小宽度内，相邻列不会被挤没', async ({ page }) => {
+    await page.goto('/')
+    await insertTable(page)
+
+    // 向右拖到远超容器：被拖列变宽、其余列保持原宽，不被挤到看不见
+    await dragDivider(page, 430)
+    const wide = await tableSnapshot(page)
+    expect(wide.contentOverflowsX).toBe(false)
+    expect(wide.wrapperScrollsX).toBe(true)
+    // 其余列纹丝不动（既不被挤没，也不被拉伸）
+    expect(wide.columnWidths.slice(1).every((width) => width >= 9)).toBe(true)
+
+    // 再向左拖到极窄：应停在最小列宽，而不是细到看不见
+    await dragDivider(page, -400)
+    const narrow = await tableSnapshot(page)
+    expect(narrow.columnWidths[0]).toBeGreaterThanOrEqual(9)
+  })
+
+  test('拖拽后的列宽不会被随后输入的内容重排', async ({ page }) => {
+    await page.goto('/')
+    await insertTable(page)
+    await dragDivider(page, 150)
+    const dragged = await tableSnapshot(page)
+
+    // 在相邻单元格塞一个超长不可断词：fixed 布局下内容不会重算列宽
+    await page.locator('[data-testid="rich-text"] table tr:first-child th').nth(1).click()
+    await page.keyboard.type('A'.repeat(40))
+    await page.waitForTimeout(200)
+
+    const after = await tableSnapshot(page)
+    expect(after.columnWidths[0]).toBeCloseTo(dragged.columnWidths[0], -1)
+    expect(after.contentOverflowsX).toBe(false)
+  })
+
+  test('列宽总和超过容器时，横向滚动只发生在表格容器内，不进入编辑器内容区', async ({ page }) => {
+    await page.goto('/')
+    // 用较窄的视口 + 拖宽第一列，制造「总列宽 > 容器」的溢出场景
+    await insertTable(page)
+
+    // 拖宽第一列，让表格总宽超过容器
+    await dragDivider(page, 500)
+    const snapshot = await tableSnapshot(page)
+    expect(snapshot.contentOverflowsX).toBe(false)
+    expect(snapshot.wrapperScrollsX).toBe(true)
+  })
+})
+
+test.describe('RichText 表格 · 操作浮层', () => {
+  test.use({ viewport: { width: 900, height: 900 } })
+
+  async function openMenuInCell(page: Page, rowIndex: number): Promise<void> {
+    const editor = page.getByTestId('rich-text')
+    await editor.locator('table tr').nth(rowIndex).locator('td, th').first().click()
+    await expect(page.locator('.g3-rich-text-table-menu')).toBeVisible()
+  }
+
+  test('光标在表格内出现浮层，离开后隐藏', async ({ page }) => {
+    await page.goto('/')
+    await insertTable(page)
+    const editor = page.getByTestId('rich-text')
+    const menu = page.locator('.g3-rich-text-table-menu')
+
+    // 初始（表格外 / 文档其它位置）：不显示
+    await editor.locator('.tiptap').click({ position: { x: 10, y: 10 } })
+    await expect(menu).toBeHidden()
+
+    await openMenuInCell(page, 1)
+    // 点击编辑器内容区空白处，光标离开表格 → 浮层隐藏
+    await editor.locator('.tiptap').click({ position: { x: 10, y: 10 } })
+    await expect(menu).toBeHidden()
+  })
+
+  test('浮层操作：上方插入行 / 左侧插入列 / 删除表格', async ({ page }) => {
+    await page.goto('/')
+    await insertTable(page)
+    const editor = page.getByTestId('rich-text')
+    const menu = page.locator('.g3-rich-text-table-menu')
+
+    await openMenuInCell(page, 1)
+    await menu.getByRole('button', { name: '上方插入行' }).click()
+    await expect(editor.locator('table tr')).toHaveCount(4)
+
+    await menu.getByRole('button', { name: '左侧插入列' }).click()
+    await expect(editor.locator('table tr:first-child th')).toHaveCount(4)
+
+    await menu.getByRole('button', { name: '删除表格' }).click()
+    await expect(editor.locator('table')).toHaveCount(0)
+    await expect(menu).toBeHidden()
+  })
+
+  test('合并单元格后置灰关系：合并 / 拆分各自独立', async ({ page }) => {
+    await page.goto('/')
+    await insertTable(page)
+    const editor = page.getByTestId('rich-text')
+    const menu = page.locator('.g3-rich-text-table-menu')
+    const merge = () => menu.getByRole('button', { name: '合并单元格' })
+    const split = () => menu.getByRole('button', { name: '拆分单元格' })
+
+    // 单格选区：没有相邻格可合并、自身也没合并过 → 两个按钮都不可用
+    await openMenuInCell(page, 1)
+    await expect(merge()).toBeDisabled()
+    await expect(split()).toBeDisabled()
+
+    // 拖过同一行相邻两格（prosemirror-tables 在 mousemove 进另一格时建立 CellSelection）
+    const cells = editor.locator('table tr').nth(1).locator('td')
+    const first = (await cells.nth(0).boundingBox())!
+    const second = (await cells.nth(1).boundingBox())!
+    await page.mouse.move(first.x + 10, first.y + first.height / 2)
+    await page.mouse.down()
+    await page.mouse.move(second.x + second.width / 2, second.y + second.height / 2, { steps: 6 })
+    await page.mouse.up()
+    await expect(menu).toBeVisible()
+
+    await expect(merge()).toBeEnabled()
+    await expect(split()).toBeDisabled()
+    await merge().click()
+    await expect(editor.locator('table tr').nth(1).locator('td[colspan="2"]')).toHaveCount(1)
+
+    // 合并后选区落在跨列格里：拆分为可用、合并不可用
+    await expect(split()).toBeEnabled()
+    await expect(merge()).toBeDisabled()
+    await split().click()
+    await expect(editor.locator('table tr').nth(1).locator('td')).toHaveCount(3)
+  })
+
+  test('删除行 / 删除列与增删行列分组同排', async ({ page }) => {
+    await page.goto('/')
+    await insertTable(page)
+    const editor = page.getByTestId('rich-text')
+    const menu = page.locator('.g3-rich-text-table-menu')
+
+    await openMenuInCell(page, 1)
+
+    // 操作栏里已不再出现单元格对齐按钮（对齐统一走顶部工具条）
+    await expect(menu.getByRole('button', { name: '单元格居中' })).toHaveCount(0)
+    await expect(menu.getByRole('button', { name: '取消单元格对齐' })).toHaveCount(0)
+    await expect(menu.getByRole('button', { name: '切换表头行' })).toHaveCount(0)
+
+    // 删除行 / 删除列的图标是自绘 SVG（不再是拆分行列的 lucide 图标）
+    for (const name of ['删除行', '删除列']) {
+      const icon = menu.getByRole('button', { name })
+      await expect(icon).toBeVisible()
+      await expect(icon.locator('svg')).toHaveCount(1)
+      await expect(icon.locator('svg path')).toHaveCount(3)
+    }
+
+    await menu.getByRole('button', { name: '删除行' }).click()
+    await expect(editor.locator('table tr')).toHaveCount(2)
+    await menu.getByRole('button', { name: '删除列' }).click()
+    await expect(editor.locator('table tr:first-child th')).toHaveCount(2)
+  })
+
+  test('切换表头列 / 表头单元格', async ({ page }) => {    await page.goto('/')
+    await insertTable(page)
+    const editor = page.getByTestId('rich-text')
+    const menu = page.locator('.g3-rich-text-table-menu')
+
+    // 表头单元格：把普通单元格切换为 th
+    await openMenuInCell(page, 1)
+    await menu.getByRole('button', { name: '切换表头单元格' }).click()
+    await expect(editor.locator('table tr').nth(1).locator('th')).toHaveCount(1)
+
+    // 表头列：整列切换为 th（第 2、3 行的首格都变 th；首行本就是表头行不受影响）
+    await menu.getByRole('button', { name: '切换表头列' }).click()
+    await expect(editor.locator('table tr').nth(1).locator('th')).toHaveCount(1)
+    await expect(editor.locator('table tr').nth(2).locator('th')).toHaveCount(1)
+    await expect(editor.locator('table tr').nth(1).locator('td')).toHaveCount(2)
+  })
+
+  test('单元格内文字的对齐走顶部工具条', async ({ page }) => {
+    await page.goto('/')
+    await insertTable(page)
+    const editor = page.getByTestId('rich-text')
+    const cell = editor.locator('table tr').nth(1).locator('td').first()
+
+    await openMenuInCell(page, 1)
+    await cell.click()
+    await editor.locator('.g3-rich-text__toolbar').getByRole('button', { name: '居中' }).click()
+
+    // 单元格内容是 paragraph，对齐写在这层（不再是单元格自身的 align 属性）
+    await expect(cell.locator('p')).toHaveAttribute('style', /text-align:\s*center/)
+  })
+
+  test('插入面板行列数超界被夹回合法范围，且可关闭表头行', async ({ page }) => {
+    await page.goto('/')
+    const editor = page.getByTestId('rich-text')
+    await editor.scrollIntoViewIfNeeded()
+    await editor.locator('button[aria-label="插入表格"]').click()
+
+    // 输入非法值（0 行 / 99 列）
+    await page.locator('.g3-rich-text__table-input').nth(0).fill('0')
+    await page.locator('.g3-rich-text__table-input').nth(1).fill('99')
+    await page.getByRole('button', { name: '插入', exact: true }).click()
+
+    const table = editor.locator('table')
+    await expect(table).toHaveCount(1)
+    // 0 → 1 行，99 → 20 列
+    await expect(table.locator('tr')).toHaveCount(1)
+    await expect(table.locator('tr:first-child th')).toHaveCount(20)
+
+    // 关闭表头行：插入后首行是 td 而非 th
+    await editor.locator('button[aria-label="插入表格"]').click()
+    await page.locator('.g3-rich-text__table-checkbox').uncheck()
+    await page.getByRole('button', { name: '插入', exact: true }).click()
+    await expect(editor.locator('table')).toHaveCount(2)
+    await expect(editor.locator('table').nth(1).locator('tr:first-child th')).toHaveCount(0)
+  })
+})
diff --git a/code/g3soft-libs/packages/ui/e2e/rich-text-toolbar.spec.ts b/code/g3soft-libs/packages/ui/e2e/rich-text-toolbar.spec.ts
new file mode 100644
index 00000000..beced501
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/e2e/rich-text-toolbar.spec.ts
@@ -0,0 +1,233 @@
+import { expect, test, type Page } from '@playwright/test'
+
+/**
+ * 富文本工具条的排版能力回归：对齐（左 / 中 / 右）与颜色（字体色 / 背景色）。
+ *
+ * 这两组能力都落在 Tiptap 扩展的 HTML 输出上（`text-align` 写块元素、
+ * `color` / `background-color` 写 `textStyle` 记号），happy-dom 里没有真实的
+ * contenteditable + 选区，只能放 E2E 验证「点按钮 → 选区真的被改了」。
+ *
+ * 取色面板与表格操作浮层一样 Teleport 到 body，所以色块要用全局定位找。
+ */
+
+const EDITOR = '[data-testid="rich-text"]'
+
+/** 清空编辑器后输入一段文本并全选（保证选区落在同一段落内） */
+async function typeAndSelectAll(page: Page, text = '对齐与颜色'): Promise<void> {
+  const editor = page.getByTestId('rich-text')
+  await editor.scrollIntoViewIfNeeded()
+  await editor.locator('.tiptap').click()
+  await page.keyboard.press('Control+A')
+  await page.keyboard.press('Delete')
+  await page.keyboard.type(text)
+  await page.keyboard.press('Control+A')
+}
+
+/** 光标所在段落的 style 属性（对齐写在这里） */
+function paragraphStyle(page: Page): Promise<string> {
+  return page
+    .locator(`${EDITOR} .tiptap p`)
+    .first()
+    .evaluate((el) => el.getAttribute('style') ?? '')
+}
+
+/** 段落内所有 span 的实测颜色（颜色写在内联 span 上） */
+function spanColors(page: Page): Promise<{ color: string; background: string }[]> {
+  return page.locator(`${EDITOR} .tiptap span`).evaluateAll((els) =>
+    els.map((el) => {
+      const style = getComputedStyle(el)
+      return { color: style.color, background: style.backgroundColor }
+    }),
+  )
+}
+
+test.describe('RichText 工具条 · 对齐', () => {
+  test('左 / 中 / 右写进段落，点当前档位即取消', async ({ page }) => {
+    await page.goto('/')
+    await typeAndSelectAll(page)
+
+    const toolbar = page.locator(`${EDITOR} .g3-rich-text__toolbar`)
+    const center = toolbar.getByRole('button', { name: '居中' })
+
+    await center.click()
+    await expect.poll(() => paragraphStyle(page)).toContain('text-align: center')
+    await expect(center).toHaveAttribute('aria-pressed', 'true')
+
+    // 换成右对齐：仍只有一个对齐属性
+    await toolbar.getByRole('button', { name: '右对齐' }).click()
+    await expect.poll(() => paragraphStyle(page)).toContain('text-align: right')
+    await expect.poll(() => paragraphStyle(page)).not.toContain('center')
+
+    // 再点当前档位 → 取消对齐（不需要单独的「取消对齐」按钮）
+    await toolbar.getByRole('button', { name: '右对齐' }).click()
+    await expect.poll(() => paragraphStyle(page)).not.toContain('text-align')
+  })
+})
+
+test.describe('RichText 工具条 · 颜色', () => {
+  test('字体颜色与背景颜色：色板取色写进选区，面板随即收起', async ({ page }) => {
+    await page.goto('/')
+    await typeAndSelectAll(page)
+
+    const editor = page.getByTestId('rich-text')
+    const toolbar = page.locator(`${EDITOR} .g3-rich-text__toolbar`)
+    const panel = page.locator('.g3-rich-text__color-panel')
+
+    // 取字体颜色：色块按 hex 作为 aria-label（Ant Design 的红色 6 号色）
+    await toolbar.getByRole('button', { name: '字体颜色' }).click()
+    await expect(panel).toBeVisible()
+    await page.locator('.g3-rich-text__color-swatch[aria-label="#f5222d"]').click()
+    await expect(panel).toHaveCount(0)
+
+    await expect
+      .poll(async () => (await spanColors(page)).map((item) => item.color))
+      .toContain('rgb(245, 34, 45)')
+
+    // 触发器的当前色条跟着变（未设色时是空位，不写内联 background）
+    await expect
+      .poll(() =>
+        page
+          .locator(`${EDITOR} .g3-rich-text__color-bar`)
+          .first()
+          .evaluate((el) => getComputedStyle(el).backgroundColor),
+      )
+      .toBe('rgb(245, 34, 45)')
+
+    // 取背景颜色：浅色档底色
+    await toolbar.getByRole('button', { name: '背景颜色' }).click()
+    await page.locator('.g3-rich-text__color-swatch[aria-label="#fff1f0"]').click()
+    await expect
+      .poll(async () => (await spanColors(page)).map((item) => item.background))
+      .toContain('rgb(255, 241, 240)')
+
+    // 两个取色面板不会同时开着
+    await expect(panel).toHaveCount(0)
+
+    // 清除字体颜色：记号里的 color 被移除，背景色保留
+    await toolbar.getByRole('button', { name: '字体颜色' }).click()
+    await page.getByRole('button', { name: '清除字体颜色' }).click()
+    await expect
+      .poll(async () => (await spanColors(page)).map((item) => item.color))
+      .not.toContain('rgb(245, 34, 45)')
+    await expect
+      .poll(async () => (await spanColors(page)).map((item) => item.background))
+      .toContain('rgb(255, 241, 240)')
+  })
+})
+
+test.describe('RichText 工具条 · 更多菜单', () => {
+  test('低频功能收进「更多」，打开后按组展示且可用', async ({ page }) => {
+    await page.goto('/')
+    await typeAndSelectAll(page)
+
+    const editor = page.getByTestId('rich-text')
+    const toolbar = editor.locator('.g3-rich-text__toolbar')
+
+    // 工具条上不再平铺这些低频按钮（平铺会把工具条顶到 928px 宽）
+    for (const name of ['删除线', '上标', '下标', '引用', '视频']) {
+      await expect(toolbar.getByRole('button', { name })).toHaveCount(0)
+    }
+    // 字体 / 字号下拉也收进菜单：工具条上只剩「段落格式」一个带当前值的触发器
+    await expect(toolbar.locator('.g3-rich-text__trigger')).toHaveCount(1)
+
+    await toolbar.getByRole('button', { name: '更多' }).click()
+    const menu = page.locator('.g3-dropdown__menu')
+    await expect(menu).toBeVisible()
+    // 菜单内容约 295px，比 Dropdown 默认的 256px 上限高 —— 面板内部不该出现滚动条
+    const menuBox = await menu.evaluate((el) => ({
+      scroll: el.scrollHeight,
+      client: el.clientHeight,
+    }))
+    expect(menuBox.scroll).toBeLessThanOrEqual(menuBox.client)
+    // 分组标题 + 快捷键提示（快捷键对着 Tiptap 的真实键位）
+    await expect(menu.getByRole('group')).toHaveText(['格式', '插入'])
+    await expect(menu.locator('.g3-dropdown__item-shortcut').first()).toHaveText('Ctrl+Shift+S')
+
+    // 点「删除线」：作用于选区，菜单随即收起
+    await menu.getByRole('menuitem', { name: /删除线/ }).click()
+    await expect(editor.locator('.tiptap s')).toHaveCount(1)
+    await expect(menu).toHaveCount(0)
+  })
+
+  test('字体 / 字号在「更多」的二级菜单里，选中态跟随光标', async ({ page }) => {
+    await page.goto('/')
+    await typeAndSelectAll(page)
+
+    const editor = page.getByTestId('rich-text')
+    await editor.locator('.g3-rich-text__toolbar').getByRole('button', { name: '更多' }).click()
+    await page.getByRole('menuitem', { name: /^字体/ }).hover()
+
+    const submenu = page.locator('.g3-dropdown__menu').last()
+    await expect(submenu).toBeVisible()
+    // 子菜单沿用根面板的 max-height：8 个字体正好压着默认上限，也不该出滚动条
+    const subBox = await submenu.evaluate((el) => ({ scroll: el.scrollHeight, client: el.clientHeight }))
+    expect(subBox.scroll).toBeLessThanOrEqual(subBox.client)
+    await submenu.getByRole('menuitem', { name: '宋体' }).click()
+
+    const span = editor.locator('.tiptap span[style*="font-family"]')
+    await expect(span).toHaveCount(1)
+    await expect(span).toHaveAttribute('style', /SimSun/)
+
+    // 再打开时当前字体带选中态
+    await editor.locator('.g3-rich-text__toolbar').getByRole('button', { name: '更多' }).click()
+    await page.getByRole('menuitem', { name: /^字体/ }).hover()
+    await expect(
+      page.locator('.g3-dropdown__menu').last().getByRole('menuitem', { name: '宋体' }),
+    ).toHaveAttribute('aria-current', 'page')
+  })
+})
+
+/** 工具条当前占几行（同一行的元素共享垂直中心） */
+function toolbarRows(page: Page): Promise<number> {
+  return page.evaluate(() => {
+    const toolbar = document.querySelector('.g3-rich-text__toolbar') as HTMLElement
+    const centers = new Set<number>()
+    for (const el of Array.from(toolbar.children) as HTMLElement[]) {
+      const rect = el.getBoundingClientRect()
+      centers.add(Math.round(rect.top + rect.height / 2))
+    }
+    return centers.size
+  })
+}
+
+test.describe('RichText 工具条 · 外观', () => {
+  test('窄到 780px 仍保持一行（低频收进「更多」的预算）', async ({ page }) => {
+    await page.goto('/')
+    const editor = page.getByTestId('rich-text')
+    await editor.scrollIntoViewIfNeeded()
+    await editor.locator('.tiptap').click()
+
+    await page.evaluate(() => {
+      ;(document.querySelector('[data-testid="rich-text"]') as HTMLElement).style.width = '780px'
+    })
+
+    await expect
+      .poll(() => toolbarRows(page), {
+        message: '工具条自然宽度约 744px（32px 按钮 + 左右 10px 内边距）；新增按钮前先想清楚该不该挪进「更多」',
+      })
+      .toBe(1)
+  })
+
+  test('工具条带下投影，且抬在正文之上（滚动时投影不被正文盖住）', async ({ page }) => {
+    await page.goto('/')
+    const editor = page.getByTestId('rich-text')
+    const toolbar = editor.locator('.g3-rich-text__toolbar')
+    await expect(toolbar).toBeVisible()
+
+    const style = await toolbar.evaluate((el) => {
+      const computed = getComputedStyle(el)
+      return {
+        shadow: computed.boxShadow,
+        position: computed.position,
+        zIndex: computed.zIndex,
+      }
+    })
+
+    // 双层柔和投影（观感对齐 TinyMCE）：近层 2px 硬边 + 远层 8px 弥散，y 偏移为正 = 朝下
+    expect(style.shadow).toMatch(/0px 2px 2px -2px/)
+    expect(style.shadow).toMatch(/0px 8px 8px -4px/)
+    // 抬层：positioned + z-index > 0，否则滚动到工具条下沿的正文会盖住投影
+    expect(style.position).toBe('relative')
+    expect(Number(style.zIndex)).toBeGreaterThan(0)
+  })
+})
diff --git a/code/g3soft-libs/packages/ui/package.json b/code/g3soft-libs/packages/ui/package.json
index e86642ac..1295394b 100644
--- a/code/g3soft-libs/packages/ui/package.json
+++ b/code/g3soft-libs/packages/ui/package.json
@@ -37,10 +37,25 @@
   },
   "dependencies": {
     "@g3soft/tokens": "workspace:*",
-    "@lucide/vue": "^1.31.0"
+    "@lucide/vue": "^1.31.0",
+    "@tiptap/extension-image": "^3.31.4",
+    "@tiptap/extension-link": "^3.31.4",
+    "@tiptap/extension-placeholder": "^3.31.4",
+    "@tiptap/extension-subscript": "^3.31.4",
+    "@tiptap/extension-superscript": "^3.31.4",
+    "@tiptap/extension-table": "^3.31.4",
+    "@tiptap/extension-table-cell": "^3.31.4",
+    "@tiptap/extension-table-header": "^3.31.4",
+    "@tiptap/extension-table-row": "^3.31.4",
+    "@tiptap/extension-text-align": "^3.31.4",
+    "@tiptap/extension-text-style": "^3.31.4",
+    "@tiptap/starter-kit": "^3.31.4"
   },
   "devDependencies": {
     "@playwright/test": "^1.63.0",
+    "@tiptap/core": "^3.31.4",
+    "@tiptap/pm": "^3.31.4",
+    "@tiptap/vue-3": "^3.31.4",
     "@vitejs/plugin-vue": "^6.0.0",
     "@vue/test-utils": "^2.5.1",
     "happy-dom": "^20.14.5",
diff --git a/code/g3soft-libs/packages/ui/playground/main.ts b/code/g3soft-libs/packages/ui/playground/main.ts
index 0f344770..6a8487d6 100644
--- a/code/g3soft-libs/packages/ui/playground/main.ts
+++ b/code/g3soft-libs/packages/ui/playground/main.ts
@@ -1,6 +1,7 @@
 import { createApp, reactive, ref } from 'vue'
 import { Plus, Search, Settings } from '@lucide/vue'
 import {
+  G3Attachment,
   G3Button,
   G3ButtonGroup,
   G3ButtonGroupSeparator,
@@ -23,10 +24,12 @@ import {
   G3Radio,
   G3RadioGroup,
   G3RangePicker,
+  G3RichText,
   G3Row,
   G3Scrollbar,
   G3Segmented,
   G3Select,
+  G3SliderCaptcha,
   G3Space,
   G3Spin,
   G3Splitter,
@@ -39,6 +42,7 @@ import {
   G3Tooltip,
   G3Tree,
 } from '@g3soft/ui'
+import type { AttachmentCategory, AttachmentItem } from '@g3soft/ui'
 import '@g3soft/tokens'
 
 /**
@@ -70,6 +74,7 @@ const LONG_TEXT = Array.from({ length: 40 }, (_, index) => `第 ${index + 1} 行
 
 const App = {
   components: {
+    G3Attachment,
     G3Button,
     G3ButtonGroup,
     G3ButtonGroupSeparator,
@@ -90,10 +95,12 @@ const App = {
     G3Radio,
     G3RadioGroup,
     G3RangePicker,
+    G3RichText,
     G3Row,
     G3Scrollbar,
     G3Segmented,
     G3Select,
+    G3SliderCaptcha,
     G3Space,
     G3Spin,
     G3Splitter,
@@ -135,6 +142,11 @@ const App = {
     const popoverBOpen = ref(true)
     // 颜色选择器：给 RTL 用例验「取色区/色相条不镜像」用
     const color = ref('#165dff')
+    // 滑块验证码：给 E2E 验真实指针拖拽、键盘与 RTL 起步边
+    const captchaPassed = ref(false)
+    const captchaDisabled = ref(false)
+    // 富文本编辑器：给样式核对用
+    const richHtml = ref('<h2>标题</h2><p>这是<b>加粗</b>、<i>斜体</i>、<sup>上标</sup>、<sub>下标</sub>的正文。</p><ul><li>列表项一</li><li>列表项二</li></ul>')
 
     // RTL 开关：直接翻 <html dir>。CSS 侧靠 [dir='rtl'] 选择器，JS 侧靠 useDirection
     // 观察 documentElement，两边都跟得上。也支持 ?dir=rtl 直接以 RTL 进入，
@@ -181,7 +193,24 @@ const App = {
       })
     }
 
+    /* ---- Attachment 附件管理器 ---- */
+    const attachmentFiles = ref<AttachmentItem[]>([
+      { id: 1, name: '2026年度框架合同.pdf', size: 512_000, categoryId: 'contract' },
+      { id: 2, name: '供应商报价明细.xlsx', size: 86_000, categoryId: 'invoice' },
+      { id: 3, name: '现场照片.jpg', size: 1_240_000, categoryId: 'photo' },
+      { id: 4, name: '验收纪要.docx', size: 24_000, categoryId: 'contract' },
+      { id: 5, name: '进度汇报.pptx', size: 640_000, categoryId: 'photo' },
+      { id: 6, name: '现场记录.zip', size: 8_192_000, categoryId: 'invoice' },
+    ])
+    const attachmentCategories: AttachmentCategory[] = [
+      { id: 'contract', name: '合同文件' },
+      { id: 'invoice', name: '发票凭证' },
+      { id: 'photo', name: '现场照片' },
+    ]
+
     return {
+      attachmentFiles,
+      attachmentCategories,
       rtl,
       toggleRtl,
       model,
@@ -196,6 +225,9 @@ const App = {
       popoverAOpen,
       popoverBOpen,
       color,
+      captchaPassed,
+      captchaDisabled,
+      richHtml,
       flatTreeData,
       treeMenuItems,
       roleOptions: ROLE_OPTIONS,
@@ -348,6 +380,21 @@ const App = {
       </G3FormGroup>
     </section>
 
+    <section id="s-captcha">
+      <h2>SliderCaptcha 滑块验证码</h2>
+      <div class="row" style="align-items: flex-start">
+        <div style="width: 320px">
+          <G3SliderCaptcha v-model="captchaPassed" data-testid="slider-captcha" />
+          <div data-testid="slider-captcha-state" style="margin-top: 8px; font-size: 12px">
+            {{ captchaPassed ? 'passed' : 'idle' }}
+          </div>
+        </div>
+        <div style="width: 320px">
+          <G3SliderCaptcha v-model="captchaDisabled" disabled data-testid="slider-captcha-disabled" />
+        </div>
+      </div>
+    </section>
+
     <section id="s-data">
       <h2>Tabs / Tree / Pagination / Splitter / Scrollbar / TimeSelect</h2>
       <div class="row" style="align-items: flex-start">
@@ -426,6 +473,32 @@ const App = {
       </div>
     </section>
 
+    <section id="s-richtext">
+      <h2>RichText 富文本编辑器</h2>
+      <G3RichText v-model="richHtml" data-testid="rich-text" placeholder="请输入正文…" />
+    </section>
+
+    <section id="s-attachment">
+      <h2>Attachment 附件管理器</h2>
+      <!-- 根节点是单元素 div，data-testid 直接落在组件上即可 -->
+      <G3Attachment
+        data-testid="attachment"
+        :files="attachmentFiles"
+        :categories="attachmentCategories"
+        :height="420"
+      />
+      <!-- 窄实例：分类栏 200 + 分割条 10 之后列表只剩 ~210px，
+           压到一行的极限（工具栏必须裁切 / 省略，而不是长高）-->
+      <div style="width: 420px; margin-top: 12px">
+        <G3Attachment
+          data-testid="attachment-narrow"
+          :files="attachmentFiles"
+          :categories="attachmentCategories"
+          :height="360"
+        />
+      </div>
+    </section>
+
     <section id="s-feedback">
       <h2>Modal / Drawer / Message / Notification</h2>
       <div class="row">
diff --git a/code/g3soft-libs/packages/ui/src/_composables/useFloating.ts b/code/g3soft-libs/packages/ui/src/_composables/useFloating.ts
index cac3b9d4..d6e96fae 100644
--- a/code/g3soft-libs/packages/ui/src/_composables/useFloating.ts
+++ b/code/g3soft-libs/packages/ui/src/_composables/useFloating.ts
@@ -11,6 +11,12 @@ import {
 import { useDirection } from './useDirection'
 import { computePosition, type Placement, type RectLike } from '../_utils/position'
 
+/**
+ * 浮层链标识写进 DOM 的属性名（Popover 负责写、这里负责读）。
+ * 用属性而不是类名：它纯属内部机制，不该出现在可被宿主覆盖的类名体系里。
+ */
+export const POPUP_SCOPE_ATTR = 'data-popup-scope'
+
 export interface UseFloatingOptions {
   /** 是否展开 */
   open: Ref<boolean> | ComputedRef<boolean>
@@ -28,6 +34,15 @@ export interface UseFloatingOptions {
   onClickOutside?: () => void
   /** 打开时按 Esc 的回调 */
   onEscape?: () => void
+  /**
+   * 同一条浮层链的标识。链上的每个浮层（如 Dropdown 的子菜单）带同一个值，
+   * 点击链内任意面板都不算「点在外面」。
+   *
+   * 必需：子菜单面板 Teleport 到 body，不在父浮层的 DOM 里，而这里是在
+   * `document` 的 pointerdown **捕获阶段**判定的（早于点到的那个元素的 click），
+   * 于是鼠标点子菜单项会先把整条链关掉，子项的 click 永远等不到。
+   */
+  popupScope?: () => string | undefined
 }
 
 export interface UseFloatingReturn {
@@ -116,7 +131,13 @@ export function useFloating(options: UseFloatingOptions): UseFloatingReturn {
     const target = event.target as Node
     const inTrigger = options.triggerRef.value?.contains(target) === true
     const inFloating = floatingRef.value?.contains(target) === true
-    if (!inTrigger && !inFloating) options.onClickOutside?.()
+    // 同一条浮层链上的其它面板（如子菜单，Teleport 到 body）也算「在里面」
+    const scope = options.popupScope?.()
+    const inScope =
+      !!scope &&
+      target instanceof Element &&
+      target.closest(`[${POPUP_SCOPE_ATTR}="${scope}"]`) !== null
+    if (!inTrigger && !inFloating && !inScope) options.onClickOutside?.()
   }
 
   function onDocumentKeydown(event: KeyboardEvent): void {
diff --git a/code/g3soft-libs/packages/ui/src/attachment/Attachment.test.ts b/code/g3soft-libs/packages/ui/src/attachment/Attachment.test.ts
new file mode 100644
index 00000000..3210a093
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/attachment/Attachment.test.ts
@@ -0,0 +1,273 @@
+import { mount } from '@vue/test-utils'
+import { describe, expect, it } from 'vitest'
+import { nextTick } from 'vue'
+import G3Attachment from './Attachment.vue'
+import type { AttachmentInvalidInfo, AttachmentItem } from './types'
+
+/**
+ * 契约测试：组件与业务解耦的那几条线必须成立 ——
+ * 数据只从 prop 进、动作只从事件出、校验失败走 invalid、待上传队列的生命周期。
+ * 三栏几何 / 拖拽分隔条依赖真实布局，放 E2E。
+ */
+
+const FILES: AttachmentItem[] = [
+  { id: 1, name: '合同.pdf', size: 100 },
+  { id: 2, name: '报价.xlsx', size: 200 },
+  { id: 3, name: '照片.png', size: 300 },
+]
+
+const CATEGORIES = [
+  { id: 'c1', name: '合同资料' },
+  { id: 'c2', name: '报价资料' },
+]
+
+function makeFile(name: string, bytes = 4): File {
+  return new File(['a'.repeat(bytes)], name, { type: 'application/octet-stream' })
+}
+
+function emitted<T>(wrapper: ReturnType<typeof mount>, name: string): T[] {
+  return (wrapper.emitted(name) ?? []) as unknown as T[]
+}
+
+describe('G3Attachment 渲染', () => {
+  it('按 files 渲染卡片，分类树补上「全部」根', () => {
+    const wrapper = mount(G3Attachment, { props: { files: FILES, categories: CATEGORIES } })
+
+    expect(wrapper.findAll('.g3-attachment__card')).toHaveLength(3)
+    const categoryText = wrapper.find('.g3-attachment__category').text()
+    expect(categoryText).toContain('全部')
+    expect(categoryText).toContain('合同资料')
+  })
+
+  it('分隔线常显：Splitter 不带 is-bar-on-hover，否则分类栏右侧看不出边界', () => {
+    const wrapper = mount(G3Attachment, { props: { files: FILES, categories: CATEGORIES } })
+    const splitter = wrapper.find('.g3-attachment__splitter')
+
+    expect(splitter.exists()).toBe(true)
+    expect(splitter.classes()).not.toContain('is-bar-on-hover')
+  })
+
+  it('默认不渲染预览栏，只留列表（没有 categories 时连左栏也没有）', () => {
+    const wrapper = mount(G3Attachment, { props: { files: FILES } })
+
+    expect(wrapper.find('.g3-attachment__category').exists()).toBe(false)
+    expect(wrapper.find('.g3-attachment__preview').exists()).toBe(false)
+  })
+
+  it('showPreview 打开时才渲染右栏', () => {
+    const wrapper = mount(G3Attachment, {
+      props: { files: FILES, categories: CATEGORIES, showPreview: true },
+    })
+
+    expect(wrapper.find('.g3-attachment__category').exists()).toBe(true)
+    expect(wrapper.find('.g3-attachment__preview').exists()).toBe(true)
+  })
+
+  it('readonly 隐藏上传入口与删除按钮（底栏保留计数）', () => {
+    const wrapper = mount(G3Attachment, { props: { files: FILES, readonly: true } })
+
+    expect(wrapper.find('.g3-attachment__footer').exists()).toBe(true)
+    expect(wrapper.find('.g3-attachment__footer-actions').exists()).toBe(false)
+    expect(wrapper.find('.g3-attachment__file-input').exists()).toBe(false)
+    expect(wrapper.find('.g3-attachment__card-btn--danger').exists()).toBe(false)
+  })
+
+  it('空态是投放区：带限制提示，readonly 下不可点', () => {
+    const wrapper = mount(G3Attachment, {
+      props: { files: [], accept: '.pdf', maxSize: 1024, maxCount: 3 },
+    })
+    const empty = wrapper.find('.g3-attachment__empty')
+
+    expect(empty.exists()).toBe(true)
+    expect(empty.text()).toContain('.pdf')
+    expect(empty.text()).toContain('1.0 KB')
+    expect(empty.text()).toContain('3')
+    expect(empty.classes()).not.toContain('is-readonly')
+  })
+
+  it('readonly 下空态不可点', () => {
+    const wrapper = mount(G3Attachment, { props: { files: [], readonly: true } })
+
+    expect(wrapper.find('.g3-attachment__empty').classes()).toContain('is-readonly')
+  })
+})
+
+describe('G3Attachment 批量操作', () => {
+  it('未勾选时不渲染批量操作，勾选后浮出并显示已选数量', async () => {
+    const wrapper = mount(G3Attachment, { props: { files: FILES } })
+    expect(wrapper.find('.g3-attachment__toolbar-count').exists()).toBe(false)
+
+    wrapper.vm.selectAll()
+    await nextTick()
+
+    expect(wrapper.find('.g3-attachment__toolbar-count').text()).toBe('已选 3 项')
+    expect(emitted<[AttachmentItem[]]>(wrapper, 'select')[0][0]).toHaveLength(3)
+
+    // 批量按钮要有边界（outline / danger-outline）且同属 small 档：
+    // 整行才是同一字号，也不会像 ghost 裸文本那样飘着
+    const buttons = wrapper.findAll('.g3-attachment__toolbar .g3-button')
+    expect(buttons.map((button) => button.text())).toEqual(['下载', '删除'])
+    expect(buttons[0].classes()).toContain('g3-button--outline')
+    expect(buttons[0].classes()).toContain('g3-button--small')
+    expect(buttons[1].classes()).toContain('g3-button--danger-outline')
+  })
+})
+
+describe('G3Attachment 分类与预览', () => {
+  it('点分类抛 categoryChange（带原始分类对象）与 update:categoryKey', async () => {
+    const wrapper = mount(G3Attachment, { props: { files: FILES, categories: CATEGORIES } })
+    const nodes = wrapper.findAll('.g3-tree-node')
+    expect(nodes.length).toBe(CATEGORIES.length + 1)
+
+    await nodes[1].trigger('click')
+
+    expect(emitted<[string | number, unknown]>(wrapper, 'categoryChange')[0]).toEqual([
+      'c1',
+      CATEGORIES[0],
+    ])
+    expect(emitted<[string | number]>(wrapper, 'update:categoryKey')[0][0]).toBe('c1')
+  })
+
+  it('点卡片抛 preview，开着右栏时同步展示', async () => {
+    const wrapper = mount(G3Attachment, { props: { files: FILES, showPreview: true } })
+
+    await wrapper.findAll('.g3-attachment__card')[0].trigger('click')
+
+    expect(emitted<[AttachmentItem]>(wrapper, 'preview')[0][0]).toEqual(FILES[0])
+    expect(wrapper.find('.g3-attachment__preview-title').text()).toBe('合同.pdf')
+    expect(wrapper.find('.g3-attachment__preview-counter').text()).toBe('1 / 3')
+  })
+
+  it('关掉预览栏时 preview 事件照常抛出（业务自己开弹窗）', async () => {
+    const wrapper = mount(G3Attachment, { props: { files: FILES } })
+
+    await wrapper.findAll('.g3-attachment__card')[0].trigger('click')
+
+    expect(emitted<[AttachmentItem]>(wrapper, 'preview')[0][0]).toEqual(FILES[0])
+    expect(wrapper.find('.g3-attachment__preview').exists()).toBe(false)
+  })
+})
+
+describe('G3Attachment 分页', () => {  it('不传 total 按客户端分页切片', () => {
+    const wrapper = mount(G3Attachment, { props: { files: FILES, pageSize: 2 } })
+
+    expect(wrapper.findAll('.g3-attachment__card')).toHaveLength(2)
+    expect(wrapper.find('.g3-attachment__pagination').exists()).toBe(true)
+  })
+
+  it('传了 total 视为服务端分页，files 已是当前页不再切', () => {
+    const wrapper = mount(G3Attachment, { props: { files: FILES, pageSize: 2, total: 99 } })
+
+    expect(wrapper.findAll('.g3-attachment__card')).toHaveLength(3)
+  })
+})
+
+describe('G3Attachment 待上传队列', () => {
+  it('按 accept / maxSize 拒绝并抛 invalid，只有合法文件入队', async () => {
+    const wrapper = mount(G3Attachment, { props: { accept: '.pdf', maxSize: 100 } })
+
+    const accepted = wrapper.vm.addFiles([
+      makeFile('small.pdf', 10),
+      makeFile('big.pdf', 200),
+      makeFile('bad.exe', 10),
+    ])
+    await nextTick()
+
+    expect(accepted.map((file) => file.name)).toEqual(['small.pdf'])
+    expect(wrapper.vm.pendingFiles.map((pending) => pending.name)).toEqual(['small.pdf'])
+
+    const reasons = emitted<[AttachmentInvalidInfo]>(wrapper, 'invalid').map(
+      ([info]) => info.reason,
+    )
+    expect(reasons).toEqual(['max-size', 'accept'])
+  })
+
+  it('未提供 uploadRequest 时点上传：抛出 upload 并清空队列', async () => {
+    const wrapper = mount(G3Attachment, { props: {} })
+    wrapper.vm.addFiles([makeFile('a.pdf'), makeFile('b.pdf')])
+    await nextTick()
+    expect(wrapper.findAll('.g3-attachment__card')).toHaveLength(2)
+
+    const uploadButton = wrapper.findAll('.g3-attachment__footer .g3-button').at(-1)
+    await uploadButton?.trigger('click')
+
+    const uploads = emitted<[File[]]>(wrapper, 'upload')
+    expect(uploads).toHaveLength(1)
+    expect(uploads[0][0].map((file) => file.name)).toEqual(['a.pdf', 'b.pdf'])
+    expect(wrapper.vm.pendingFiles).toHaveLength(0)
+    expect(wrapper.findAll('.g3-attachment__card')).toHaveLength(0)
+  })
+
+  it('提供 uploadRequest 时组件托管：成功回调后回填列表', async () => {
+    const wrapper = mount(G3Attachment, {
+      props: {
+        uploadRequest: (files: File[]) =>
+          files.map((file, index) => ({ id: `remote-${index}`, name: file.name })),
+      },
+    })
+    wrapper.vm.addFiles([makeFile('a.pdf')])
+    await nextTick()
+
+    await wrapper.findAll('.g3-attachment__footer .g3-button').at(-1)?.trigger('click')
+    await nextTick()
+
+    const success = emitted<[File[], AttachmentItem[]]>(wrapper, 'uploadSuccess')
+    expect(success).toHaveLength(1)
+    const [, result] = success[0]
+    expect(result.map((item) => item.name)).toEqual(['a.pdf'])
+    expect(emitted<[AttachmentItem[]]>(wrapper, 'update:files')[0][0]).toEqual(result)
+    expect(wrapper.vm.pendingFiles).toHaveLength(0)
+  })
+})
+
+describe('G3Attachment 删除', () => {
+  it('confirmRemove 关闭时直接抛 remove 与新的 files', async () => {
+    const wrapper = mount(G3Attachment, { props: { files: FILES, confirmRemove: false } })
+
+    await wrapper.findAll('.g3-attachment__card-btn--danger')[0].trigger('click')
+    await nextTick()
+
+    expect(emitted<[AttachmentItem[]]>(wrapper, 'remove')[0][0]).toEqual([FILES[0]])
+    expect(emitted<[AttachmentItem[]]>(wrapper, 'update:files')[0][0]).toEqual([FILES[1], FILES[2]])
+  })
+
+  it('默认先出确认框，点确认后才删', async () => {
+    const wrapper = mount(G3Attachment, { props: { files: FILES } })
+
+    await wrapper.findAll('.g3-attachment__card-btn--danger')[0].trigger('click')
+    await nextTick()
+
+    const footer = document.body.querySelector('.g3-modal__footer')
+    expect(footer).not.toBeNull()
+    expect(document.body.textContent).toContain('确定删除')
+
+    const buttons = footer?.querySelectorAll('button') ?? []
+    expect(buttons).toHaveLength(2)
+    buttons[1].click()
+    await nextTick()
+    await nextTick()
+
+    expect(emitted<[AttachmentItem[]]>(wrapper, 'remove')).toHaveLength(1)
+    expect(emitted<[AttachmentItem[]]>(wrapper, 'update:files')[0][0]).toEqual([FILES[1], FILES[2]])
+  })
+
+  it('removeRequest 抛错时抛 removeError 且不动列表', async () => {
+    const error = new Error('server down')
+    const wrapper = mount(G3Attachment, {
+      props: {
+        files: FILES,
+        confirmRemove: false,
+        removeRequest: () => {
+          throw error
+        },
+      },
+    })
+
+    await wrapper.findAll('.g3-attachment__card-btn--danger')[0].trigger('click')
+    await nextTick()
+
+    expect(emitted<[unknown, AttachmentItem[]]>(wrapper, 'removeError')[0][0]).toBe(error)
+    expect(wrapper.emitted('update:files')).toBeUndefined()
+    expect(wrapper.emitted('remove')).toBeUndefined()
+  })
+})
diff --git a/code/g3soft-libs/packages/ui/src/attachment/Attachment.vue b/code/g3soft-libs/packages/ui/src/attachment/Attachment.vue
new file mode 100644
index 00000000..8529484f
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/attachment/Attachment.vue
@@ -0,0 +1,393 @@
+<script setup lang="ts">
+import { computed, ref } from 'vue'
+import { G3Button } from '../button'
+import { G3Modal } from '../modal'
+import { G3Spin } from '../spin'
+import { G3Splitter, G3SplitterPanel } from '../splitter'
+import { G3Tree } from '../tree'
+import { useLocale } from '../_composables/useLocale'
+import { useNamespace } from '../_composables/useNamespace'
+import AttachmentList from './AttachmentList.vue'
+import AttachmentPreview from './AttachmentPreview.vue'
+import type { TreeKey, TreeNodeData } from '../tree'
+import type {
+  AttachmentCategory,
+  AttachmentEmits,
+  AttachmentItem,
+  AttachmentProps,
+  AttachmentUploadContext,
+} from './types'
+
+/**
+ * 附件管理器 —— 分类 / 列表 / 预览三栏，上传（选择 / 拖拽 / 粘贴）、多选下载删除、分页。
+ *
+ * 三条解耦线：
+ * 1. **数据**：只吃 `files` + `categories` 两个 prop，不请求接口、不感知业务主键；
+ * 2. **动作**：用户意图一律以事件抛出（`upload` / `remove` / `download` …）；
+ * 3. **可选托管**：传 `uploadRequest` / `removeRequest` 时组件替你跑请求，
+ *    成功后自行 emit `update:files`，不想接管就只用事件。
+ */
+defineOptions({ name: 'G3Attachment' })
+
+const props = withDefaults(defineProps<AttachmentProps>(), {
+  files: () => [],
+  categories: () => [],
+  categoryKey: '',
+  showCategory: true,
+  showPreview: false,
+  readonly: false,
+  loading: false,
+  categoryLoading: false,
+  selectable: true,
+  multiple: true,
+  accept: undefined,
+  maxSize: 0,
+  maxCount: 0,
+  pasteUpload: false,
+  confirmRemove: true,
+  builtinDownload: true,
+  pagination: true,
+  page: undefined,
+  pageSize: undefined,
+  total: undefined,
+  pageSizeOptions: () => [10, 20, 50, 100],
+  showSizeChanger: false,
+  height: undefined,
+  uploadRequest: undefined,
+  removeRequest: undefined,
+})
+
+const emit = defineEmits<AttachmentEmits>()
+
+const { b, e } = useNamespace('attachment')
+const locale = useLocale()
+
+/** 分类树里的「全部」节点 key（对外用 `''` 表示全部） */
+const ALL_CATEGORY_KEY = '__g3_attachment_all__'
+
+const listRef = ref<InstanceType<typeof AttachmentList> | null>(null)
+const activeItem = ref<AttachmentItem | null>(null)
+const pendingRemove = ref<AttachmentItem[]>([])
+const uploading = ref(false)
+const removing = ref(false)
+
+const rootStyle = computed(() => {
+  const height = props.height
+  if (height == null || height === '') return undefined
+  return { height: typeof height === 'number' ? `${height}px` : String(height) }
+})
+
+const showCategories = computed(() => props.showCategory && props.categories.length > 0)
+
+/* ---------- 分类 ---------- */
+function toCategoryNode(category: AttachmentCategory): TreeNodeData {
+  return {
+    key: category.id,
+    title: category.name,
+    disabled: category.disabled,
+    children: category.children?.map(toCategoryNode),
+  }
+}
+
+const categoryTree = computed<TreeNodeData[]>(() => {
+  if (!showCategories.value) return []
+  return [
+    {
+      key: ALL_CATEGORY_KEY,
+      title: locale.value.attachment.allCategory,
+      children: props.categories.map(toCategoryNode),
+    },
+  ]
+})
+
+const selectedCategoryKeys = computed<TreeKey[]>(() => {
+  const key = props.categoryKey
+  if (key === '' || key == null) return [ALL_CATEGORY_KEY]
+  return [String(key)]
+})
+
+/** 按字符串 key 找回原始分类对象（保留业务侧 id 的原始类型） */
+function findCategory(key: string): AttachmentCategory | null {
+  const stack: AttachmentCategory[] = [...props.categories]
+  while (stack.length) {
+    const current = stack.shift() as AttachmentCategory
+    if (String(current.id) === key) return current
+    if (current.children?.length) stack.push(...current.children)
+  }
+  return null
+}
+
+function onCategorySelect(keys: TreeKey[]) {
+  const key = keys.length ? String(keys[0]) : ALL_CATEGORY_KEY
+  const category = key === ALL_CATEGORY_KEY ? null : findCategory(key)
+  const next = category ? category.id : ''
+  activeItem.value = null
+  emit('update:categoryKey', next)
+  emit('categoryChange', next, category)
+}
+
+/* ---------- 预览 ---------- */
+/** 预览翻页就按当前页附件的顺序 */
+const previewList = computed(() => props.files)
+
+function onPreview(item: AttachmentItem) {
+  if (props.showPreview) activeItem.value = item
+  emit('preview', item)
+}
+
+function step(delta: number) {
+  const list = previewList.value
+  const current = activeItem.value
+  if (!current) return
+  const index = list.findIndex((file) => file.id === current.id)
+  const target = index + delta
+  if (index < 0 || target < 0 || target >= list.length) return
+  activeItem.value = list[target]
+  emit('preview', list[target])
+}
+
+/* ---------- 下载 ---------- */
+function onDownload(items: AttachmentItem[]) {
+  emit('download', items)
+}
+
+/* ---------- 上传 ---------- */
+const uploadContext = computed<AttachmentUploadContext>(() => ({
+  categoryId: props.categoryKey === '' ? undefined : props.categoryKey,
+}))
+
+async function onUpload(files: File[]) {
+  const request = props.uploadRequest
+  if (!request) {
+    // 交给业务：清空队列（业务拿到 File[] 后自行上传 / 落库）
+    listRef.value?.clearPending()
+    emit('upload', files, uploadContext.value)
+    return
+  }
+  uploading.value = true
+  try {
+    const result = await request(files, uploadContext.value)
+    listRef.value?.clearPending()
+    if (Array.isArray(result) && result.length) {
+      const next = [...props.files, ...result]
+      emit('update:files', next)
+      emit('change', next)
+    }
+    emit('uploadSuccess', files, result)
+  } catch (error) {
+    emit('uploadError', error, files)
+  } finally {
+    uploading.value = false
+  }
+}
+
+/* ---------- 删除 ---------- */
+const confirmOpen = computed({
+  get: () => pendingRemove.value.length > 0,
+  set: (value: boolean) => {
+    if (!value) pendingRemove.value = []
+  },
+})
+
+const confirmTitle = computed(() => {
+  const items = pendingRemove.value
+  if (items.length === 1) {
+    return locale.value.attachment.removeConfirmSingle.replace('{name}', items[0].name)
+  }
+  return locale.value.attachment.removeConfirm.replace('{count}', String(items.length))
+})
+
+async function performRemove(items: AttachmentItem[]) {
+  removing.value = true
+  try {
+    if (props.removeRequest) await props.removeRequest(items)
+    const removed = new Set(items.map((item) => item.id))
+    const next = props.files.filter((file) => !removed.has(file.id))
+    emit('update:files', next)
+    emit('change', next)
+    emit('remove', items)
+    if (activeItem.value && removed.has(activeItem.value.id)) activeItem.value = null
+    pendingRemove.value = []
+  } catch (error) {
+    emit('removeError', error, items)
+  } finally {
+    removing.value = false
+  }
+}
+
+function onRemove(items: AttachmentItem[]) {
+  if (props.readonly || !items.length) return
+  if (!props.confirmRemove) {
+    void performRemove(items)
+    return
+  }
+  pendingRemove.value = items
+}
+
+/* ---------- 对外能力 ---------- */
+function openFileDialog() {
+  listRef.value?.openFileDialog()
+}
+
+function clearSelection() {
+  listRef.value?.clearSelection()
+}
+
+function selectAll() {
+  listRef.value?.selectAll()
+}
+
+function addFiles(files: File[] | FileList) {
+  return listRef.value?.addFiles(files) ?? []
+}
+
+function clearPending() {
+  listRef.value?.clearPending()
+}
+
+defineExpose({
+  get selectedItems() {
+    return listRef.value?.selectedItems ?? []
+  },
+  get pendingFiles() {
+    return listRef.value?.pendingFiles ?? []
+  },
+  openFileDialog,
+  clearSelection,
+  selectAll,
+  addFiles,
+  clearPending,
+  listRef,
+})
+</script>
+
+<template>
+  <div :class="b()" :style="rootStyle" data-slot="attachment">
+    <G3Splitter :class="e('splitter')" :bar-on-hover="false">
+      <G3SplitterPanel v-if="showCategories" :default-size="200" :min="150" :max="320">
+        <div :class="e('category')">
+          <G3Spin :spinning="categoryLoading">
+            <G3Tree
+              :class="e('category-tree')"
+              :tree-data="categoryTree"
+              :selected-keys="selectedCategoryKeys"
+              :default-expand-all="true"
+              block-node
+              @select="onCategorySelect"
+            />
+          </G3Spin>
+        </div>
+      </G3SplitterPanel>
+
+      <G3SplitterPanel :min="280">
+        <AttachmentList
+          ref="listRef"
+          :files="files"
+          :category-id="categoryKey"
+          :loading="loading"
+          :uploading="uploading"
+          :removing="removing"
+          :readonly="readonly"
+          :selectable="selectable"
+          :multiple="multiple"
+          :accept="accept"
+          :max-size="maxSize"
+          :max-count="maxCount"
+          :paste-upload="pasteUpload"
+          :builtin-download="builtinDownload"
+          :pagination="pagination"
+          :page="page"
+          :page-size="pageSize"
+          :total="total"
+          :page-size-options="pageSizeOptions"
+          :show-size-changer="showSizeChanger"
+          @update:page="emit('update:page', $event)"
+          @update:page-size="emit('update:pageSize', $event)"
+          @select="emit('select', $event)"
+          @preview="onPreview"
+          @download="onDownload"
+          @remove="onRemove"
+          @upload="onUpload"
+          @invalid="emit('invalid', $event)"
+        />
+      </G3SplitterPanel>
+
+      <G3SplitterPanel v-if="showPreview" :default-size="360" :min="280">
+        <AttachmentPreview
+          :item="activeItem"
+          :list="previewList"
+          @prev="step(-1)"
+          @next="step(1)"
+        />
+      </G3SplitterPanel>
+    </G3Splitter>
+
+    <!-- 删除二次确认 -->
+    <G3Modal
+      v-model:open="confirmOpen"
+      :title="confirmTitle"
+      :width="416"
+      centered
+      :closable="false"
+      :fullscreen="false"
+      :resizable="false"
+      :mask-closable="false"
+      :confirm-loading="removing"
+    >
+      <template #footer>
+        <G3Button type="outline" :disabled="removing" @click="confirmOpen = false">
+          {{ locale.common.cancel }}
+        </G3Button>
+        <G3Button
+          type="danger"
+          :loading="removing"
+          @click="performRemove(pendingRemove)"
+        >
+          {{ locale.attachment.remove }}
+        </G3Button>
+      </template>
+    </G3Modal>
+  </div>
+</template>
+
+<style lang="scss">
+@use '@g3soft/tokens/scss' as *;
+
+.#{b('attachment')} {
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+  height: 100%;
+  min-height: 320px;
+  overflow: hidden;
+  border: 1px solid v('border-color', #d9d9d9);
+  border-radius: v('radius-lg', 8px);
+  background: v('bg-container', #fff);
+}
+
+.#{e('attachment', 'splitter')} {
+  flex: 1;
+  min-height: 0;
+}
+
+/* 分割线常显（Splitter 的 barOnHover 已关）并收成 1px：
+   默认 3px 在「分类栏 | 卡片区」这种窄栏之间更像一根竖条而非分隔线。
+   选择器带上自己的 block 类（3 个类）以盖过 Splitter 自身的 2 类规则。 */
+.#{e('attachment', 'splitter')}.#{m('splitter', 'horizontal')} .#{e('splitter', 'bar-line')} {
+  width: 1px;
+}
+
+.#{e('attachment', 'category')} {
+  width: 100%;
+  height: 100%;
+  min-width: 0;
+  min-height: 0;
+  overflow: auto;
+  padding: v('space-2', 8px) v('space-1', 4px);
+  box-sizing: border-box;
+}
+
+.#{e('attachment', 'category-tree')} {
+  min-width: 100%;
+}
+</style>
diff --git a/code/g3soft-libs/packages/ui/src/attachment/AttachmentCard.vue b/code/g3soft-libs/packages/ui/src/attachment/AttachmentCard.vue
new file mode 100644
index 00000000..9079ee37
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/attachment/AttachmentCard.vue
@@ -0,0 +1,376 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import { Download, Trash2 } from '@lucide/vue'
+import { G3Button } from '../button'
+import { G3Checkbox } from '../checkbox'
+import { G3Tag } from '../tag'
+import { useLocale } from '../_composables/useLocale'
+import { useNamespace } from '../_composables/useNamespace'
+import { ATTACHMENT_KIND_ICONS } from './icons'
+import { formatFileSize, getExtension, getFileKind, isImageFile } from './file'
+import type { AttachmentListItem } from './types'
+
+/**
+ * 附件卡片 —— 网格视图的单项。
+ *
+ * 视觉要点：卡片本体只有「预览图 + 文件名」，操作按钮平时隐在预览图右下角，
+ * hover / 键盘聚焦（`focus-within`）才浮现；触屏设备常显。信息区不再压一条操作栏，
+ * 少一层边框与两条分隔线。
+ *
+ * 纯展示 + 事件上报，不做任何数据请求；勾选 / 预览 / 下载 / 删除均交给父级。
+ */
+defineOptions({ name: 'G3AttachmentCard' })
+
+const props = withDefaults(
+  defineProps<{
+    item: AttachmentListItem
+    /** 是否勾选 */
+    selected?: boolean
+    /** 是否显示勾选框 */
+    selectable?: boolean
+    /** 只读：隐藏删除入口 */
+    readonly?: boolean
+  }>(),
+  { selected: false, selectable: true, readonly: false },
+)
+
+const emit = defineEmits<{
+  select: [item: AttachmentListItem, checked: boolean]
+  preview: [item: AttachmentListItem]
+  download: [item: AttachmentListItem]
+  remove: [item: AttachmentListItem]
+}>()
+
+const { e, em, is } = useNamespace('attachment')
+const locale = useLocale()
+
+const kind = computed(() => getFileKind(props.item.name))
+const kindIcon = computed(() => ATTACHMENT_KIND_ICONS[kind.value])
+const extension = computed(
+  () => props.item.ext || getExtension(props.item.name) || '?',
+)
+const uploading = computed(() => props.item.status === 'uploading')
+/** 信息行：上传中显示进度百分比，否则显示大小 */
+const metaText = computed(() =>
+  uploading.value ? `${props.item.percent ?? 0}%` : formatFileSize(props.item.size),
+)
+
+/** 缩略图：待上传项用 blob URL，已上传项优先 thumbnailUrl 再回退 url */
+const thumbnail = computed(() => {
+  const item = props.item
+  if (!isImageFile(item.name)) return ''
+  return item.thumbnailUrl || item.url || ''
+})
+
+const classes = computed(() => [
+  e('card'),
+  {
+    [is('selected')]: props.selected,
+    [is('pending')]: !!props.item.pending,
+  },
+])
+
+function onCheck(checked: boolean) {
+  emit('select', props.item, checked)
+}
+
+function onPreview() {
+  emit('preview', props.item)
+}
+</script>
+
+<template>
+  <div :class="classes" :title="item.name" data-slot="attachment-card" @click="onPreview">
+    <div :class="e('card-thumb')">
+      <img v-if="thumbnail" :src="thumbnail" :alt="item.name" />
+      <span v-else :class="[e('type'), em('type', kind)]">
+        <component :is="kindIcon" :size="20" :stroke-width="1.75" aria-hidden="true" />
+        <span :class="e('type-ext')">{{ extension }}</span>
+      </span>
+
+      <span v-if="selectable" :class="e('card-check')" @click.stop>
+        <G3Checkbox :model-value="selected" @update:model-value="onCheck" />
+      </span>
+
+      <span
+        v-if="uploading"
+        :class="e('card-progress')"
+        role="progressbar"
+        :aria-valuenow="item.percent ?? 0"
+      >
+        <span :style="{ inlineSize: `${item.percent ?? 0}%` }" />
+      </span>
+
+      <div :class="e('card-actions')" @click.stop>
+        <G3Button
+          type="ghost"
+          :class="e('card-btn')"
+          :disabled="!!item.pending"
+          :title="locale.attachment.download"
+          :aria-label="locale.attachment.download"
+          @click="emit('download', item)"
+        >
+          <Download :size="14" />
+        </G3Button>
+        <G3Button
+          v-if="!readonly"
+          type="ghost"
+          :class="[e('card-btn'), em('card-btn', 'danger')]"
+          :title="locale.attachment.remove"
+          :aria-label="locale.attachment.remove"
+          @click="emit('remove', item)"
+        >
+          <Trash2 :size="14" />
+        </G3Button>
+      </div>
+    </div>
+
+    <div :class="e('card-info')">
+      <span :class="e('card-name')">{{ item.name }}</span>
+      <span :class="e('card-meta')">
+        <G3Tag v-if="item.pending" variant="outline" :class="e('card-tag')">
+          {{ locale.attachment.pending }}
+        </G3Tag>
+        <span :class="e('card-size')">{{ metaText }}</span>
+      </span>
+    </div>
+  </div>
+</template>
+
+<style lang="scss">
+@use '@g3soft/tokens/scss' as *;
+
+.#{e('attachment', 'card')} {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  box-sizing: border-box;
+  overflow: hidden;
+  border: 1px solid v('border-color', #d9d9d9);
+  border-radius: v('radius', 6px);
+  background: v('bg-container', #fff);
+  cursor: pointer;
+  transition:
+    border-color v('duration-fast', 0.1s) v('ease', ease),
+    background-color v('duration-fast', 0.1s) v('ease', ease);
+}
+
+.#{e('attachment', 'card')}:hover,
+.#{e('attachment', 'card')}:focus-within {
+  border-color: v('text-3', rgba(0, 0, 0, 0.45));
+}
+
+/* 选中：主色描边 + 主色淡底（与 Tree 选中态同一套视觉） */
+.#{e('attachment', 'card')}.#{is('selected')} {
+  border-color: v('color-primary', #18181b);
+  background: v('color-primary-soft', rgba(24, 24, 27, 0.12));
+
+  &:hover {
+    border-color: v('color-primary', #18181b);
+  }
+}
+
+/* 待上传：虚线边，一眼区分「还没提交」 */
+.#{e('attachment', 'card')}.#{is('pending')} {
+  border-style: dashed;
+}
+
+/* ---------- 预览图 ---------- */
+.#{e('attachment', 'card-thumb')} {
+  position: relative;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  aspect-ratio: 16 / 10;
+  overflow: hidden;
+  /* 与信息区的分界靠底色差，不再画线 */
+  background: v('fill', rgba(0, 0, 0, 0.04));
+
+  img {
+    width: 100%;
+    height: 100%;
+    object-fit: cover;
+  }
+}
+
+/* ---------- 类型块：图标 + 扩展名，颜色由文件族变量决定 ---------- */
+.#{e('attachment', 'type')} {
+  #{css-var('attachment-type-image')}: #{v('color-primary', #18181b)};
+  #{css-var('attachment-type-doc')}: #{v('color-danger', #ec4246)};
+  #{css-var('attachment-type-sheet')}: #{v('color-success', #45b114)};
+  #{css-var('attachment-type-slide')}: #{v('color-warning', #e79a0d)};
+  #{css-var('attachment-type-archive')}: #d98e04;
+  #{css-var('attachment-type-media')}: #1f9ea8;
+  #{css-var('attachment-type-other')}: #{v('text-3', rgba(0, 0, 0, 0.45))};
+
+  display: inline-flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 2px;
+  min-width: 52px;
+  padding: v('space-1', 4px) 6px;
+  box-sizing: border-box;
+  border-radius: v('radius', 6px);
+  /* 淡底 + 同色前景，不再叠 1px 同色描边 */
+  background: color-mix(
+    in srgb,
+    var(#{css-var('attachment-type-color')}) 10%,
+    #{v('bg-container', #fff)}
+  );
+  color: var(#{css-var('attachment-type-color')});
+}
+
+@each $kind in image, doc, sheet, slide, archive, media, other {
+  .#{em('attachment', 'type', $kind)} {
+    #{css-var('attachment-type-color')}: var(#{css-var('attachment-type-#{$kind}')});
+  }
+}
+
+.#{e('attachment', 'type-ext')} {
+  font-size: 10px;
+  font-weight: 600;
+  letter-spacing: 0.06em;
+  line-height: 1;
+  text-transform: uppercase;
+}
+
+/* 暗色下两个非令牌色提亮一档，保证在深底上仍有对比 */
+html[data-g3-theme='dark'],
+.dark {
+  .#{e('attachment', 'type')} {
+    #{css-var('attachment-type-archive')}: #e0a63c;
+    #{css-var('attachment-type-media')}: #38bcc6;
+  }
+}
+
+/* ---------- 勾选：浮在预览图左上角 ---------- */
+.#{e('attachment', 'card-check')} {
+  position: absolute;
+  top: 6px;
+  inset-inline-start: 6px;
+  z-index: 2;
+  padding: 2px;
+  line-height: 1;
+  border-radius: v('radius-sm', 4px);
+  background: v('bg-container', #fff);
+}
+
+/* ---------- 操作：默认隐藏，hover / 键盘聚焦浮现 ---------- */
+.#{e('attachment', 'card-actions')} {
+  position: absolute;
+  inset-block-end: 6px;
+  inset-inline-end: 6px;
+  z-index: 2;
+  display: flex;
+  gap: 2px;
+  padding: 2px;
+  border-radius: v('radius-sm', 4px);
+  background: color-mix(in srgb, #{v('bg-container', #fff)} 88%, transparent);
+  opacity: 0;
+  pointer-events: none;
+  transform: translateY(2px);
+  transition:
+    opacity v('duration-fast', 0.1s) v('ease', ease),
+    transform v('duration-fast', 0.1s) v('ease', ease);
+}
+
+.#{e('attachment', 'card')}:hover .#{e('attachment', 'card-actions')},
+.#{e('attachment', 'card')}:focus-within .#{e('attachment', 'card-actions')} {
+  opacity: 1;
+  pointer-events: auto;
+  transform: none;
+}
+
+/* 触屏没有 hover：直接常显 */
+@media (hover: none) {
+  .#{e('attachment', 'card-actions')} {
+    opacity: 1;
+    pointer-events: auto;
+    transform: none;
+  }
+}
+
+.#{e('attachment', 'card-btn')} {
+  width: 24px;
+  height: 24px;
+  min-height: 0;
+  padding: 0;
+  border-radius: v('radius-sm', 4px);
+  color: v('text-2', rgba(0, 0, 0, 0.65));
+
+  svg {
+    width: 14px;
+    height: 14px;
+  }
+
+  &:hover:not(:disabled) {
+    background: v('fill-hover', rgba(0, 0, 0, 0.08));
+    color: v('text-1', rgba(0, 0, 0, 0.88));
+  }
+}
+
+.#{em('attachment', 'card-btn', 'danger')}:hover:not(:disabled) {
+  background: color-mix(in srgb, #{v('color-danger', #ec4246)} 12%, transparent);
+  color: v('color-danger', #ec4246);
+}
+
+/* ---------- 上传进度：贴着预览图底边 ---------- */
+.#{e('attachment', 'card-progress')} {
+  position: absolute;
+  inset-inline: 0;
+  inset-block-end: 0;
+  height: 2px;
+  background: v('fill-hover', rgba(0, 0, 0, 0.08));
+
+  > span {
+    display: block;
+    height: 100%;
+    background: v('color-primary', #18181b);
+    transition: inline-size v('duration', 0.2s) v('ease', ease);
+  }
+}
+
+/* ---------- 信息区 ---------- */
+.#{e('attachment', 'card-info')} {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  min-width: 0;
+  padding: v('space-2', 8px);
+}
+
+.#{e('attachment', 'card-name')} {
+  overflow: hidden;
+  color: v('text-1', rgba(0, 0, 0, 0.88));
+  font-size: v('font-size', 14px);
+  line-height: v('line-height', 1.5);
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+
+.#{e('attachment', 'card-meta')} {
+  display: flex;
+  align-items: center;
+  gap: v('space-1', 4px);
+  min-width: 0;
+  font-size: v('font-size-sm', 12px);
+  line-height: 1.4;
+}
+
+.#{e('attachment', 'card-size')} {
+  color: v('text-3', rgba(0, 0, 0, 0.45));
+  font-variant-numeric: tabular-nums;
+}
+
+/* 待上传标签：压到 16px 高，不与文件名抢视线 */
+.#{e('attachment', 'card-tag')} {
+  flex: none;
+  height: 16px;
+  margin: 0;
+  padding: 0 4px;
+  font-size: 10px;
+  font-weight: 500;
+  line-height: 1;
+}
+</style>
diff --git a/code/g3soft-libs/packages/ui/src/attachment/AttachmentList.vue b/code/g3soft-libs/packages/ui/src/attachment/AttachmentList.vue
new file mode 100644
index 00000000..c0e720db
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/attachment/AttachmentList.vue
@@ -0,0 +1,848 @@
+<script setup lang="ts">
+import { computed, onBeforeUnmount, onMounted, ref, watch } from 'vue'
+import { CloudUpload, Download, Trash2, Upload } from '@lucide/vue'
+import { G3Button } from '../button'
+import { G3Checkbox } from '../checkbox'
+import { G3Pagination } from '../pagination'
+import { G3Spin } from '../spin'
+import { useLocale } from '../_composables/useLocale'
+import { useNamespace } from '../_composables/useNamespace'
+import AttachmentCard from './AttachmentCard.vue'
+import { formatFileSize, getExtension, isImageFile, matchesAccept } from './file'
+import type {
+  AttachmentInvalidInfo,
+  AttachmentInvalidReason,
+  AttachmentItem,
+  AttachmentListItem,
+  AttachmentPendingFile,
+} from './types'
+
+/** 待上传项的内部形态：多了稳定 uid，供选择 / 删除定位 */
+type PendingEntry = AttachmentPendingFile & { uid: string }
+
+/** 待上传项的 id 前缀（与已上传附件区分） */
+const PENDING_PREFIX = '__g3_pending__'
+
+/**
+ * 附件列表 —— 工具栏 + 卡片网格 + 待上传队列 + 底栏与分页。
+ *
+ * 只负责「拿到的数据怎么画」与「用户想干什么」；上传 / 删除是否由组件托管，
+ * 由父级（G3Attachment）决定。
+ */
+defineOptions({ name: 'G3AttachmentList' })
+
+const props = withDefaults(
+  defineProps<{
+    /** 当前页已上传附件 */
+    files?: AttachmentItem[]
+    /** 当前分类（透传给上传上下文） */
+    categoryId?: string | number
+    /** 列表请求中 */
+    loading?: boolean
+    /** 上传请求中 */
+    uploading?: boolean
+    /** 删除请求中 */
+    removing?: boolean
+    readonly?: boolean
+    selectable?: boolean
+    multiple?: boolean
+    /** 原生 accept 语法 */
+    accept?: string
+    /** 单文件大小上限（字节） */
+    maxSize?: number
+    /** 待上传队列上限 */
+    maxCount?: number
+    /** 监听 document 的粘贴上传 */
+    pasteUpload?: boolean
+    /** 内建触发下载（依据 item.url） */
+    builtinDownload?: boolean
+    /** 是否显示分页 */
+    pagination?: boolean
+    page?: number
+    pageSize?: number
+    /** 总条数，不传取 files.length */
+    total?: number
+    pageSizeOptions?: Array<number | string>
+    showSizeChanger?: boolean
+  }>(),
+  {
+    files: () => [],
+    categoryId: undefined,
+    loading: false,
+    uploading: false,
+    removing: false,
+    readonly: false,
+    selectable: true,
+    multiple: true,
+    accept: undefined,
+    maxSize: 0,
+    maxCount: 0,
+    pasteUpload: false,
+    builtinDownload: true,
+    pagination: true,
+    page: undefined,
+    pageSize: undefined,
+    total: undefined,
+    pageSizeOptions: () => [10, 20, 50, 100],
+    showSizeChanger: false,
+  },
+)
+
+const emit = defineEmits<{
+  'update:page': [page: number]
+  'update:pageSize': [size: number]
+  select: [items: AttachmentItem[]]
+  preview: [item: AttachmentItem]
+  download: [items: AttachmentItem[]]
+  remove: [items: AttachmentItem[]]
+  upload: [files: File[]]
+  invalid: [info: AttachmentInvalidInfo]
+}>()
+
+const { e, is } = useNamespace('attachment')
+const locale = useLocale()
+
+/* ---------- 待上传队列 ---------- */
+const pendingFiles = ref<PendingEntry[]>([])
+const inputRef = ref<HTMLInputElement | null>(null)
+let uidSeed = 0
+
+const pendingItems = computed<AttachmentListItem[]>(() =>
+  pendingFiles.value.map((entry) => ({
+    id: entry.uid,
+    name: entry.name,
+    size: entry.size,
+    ext: entry.ext,
+    url: entry.url,
+    pending: true,
+  })),
+)
+
+/* ---------- 分页 ---------- */
+// 未传 page / pageSize 时按非受控处理，组件内部维护并自行切片
+const innerPage = ref(1)
+const innerPageSize = ref(20)
+const currentPage = computed(() => props.page ?? innerPage.value)
+const currentPageSize = computed(() => props.pageSize ?? innerPageSize.value)
+
+/**
+ * 未传 `total` 视为客户端分页：`files` 是完整列表，由组件切片；
+ * 传了 `total` 则是服务端分页，`files` 已经是当前页数据，不再切。
+ */
+const clientPaging = computed(() => props.total == null && props.pagination)
+const pagedFiles = computed(() => {
+  if (!clientPaging.value) return props.files
+  const start = (currentPage.value - 1) * currentPageSize.value
+  return props.files.slice(start, start + currentPageSize.value)
+})
+
+/** 渲染项：待上传在前，已上传在后 */
+const items = computed<AttachmentListItem[]>(() => [...pendingItems.value, ...pagedFiles.value])
+const hasItems = computed(() => items.value.length > 0)
+const pendingCount = computed(() => pendingFiles.value.length)
+const resolvedTotal = computed(() =>
+  props.total == null ? props.files.length : Number(props.total) || 0,
+)
+
+/* ---------- 勾选 ---------- */
+const selectedIds = ref<Set<string | number>>(new Set())
+const selectedCount = computed(() => selectedIds.value.size)
+const allChecked = computed(
+  () => hasItems.value && items.value.every((item) => selectedIds.value.has(item.id)),
+)
+const indeterminate = computed(() => !allChecked.value && selectedCount.value > 0)
+
+const selectedItems = computed<AttachmentItem[]>(() =>
+  items.value.filter((item) => selectedIds.value.has(item.id)),
+)
+
+const selectedText = computed(() =>
+  locale.value.attachment.selected.replace('{count}', String(selectedCount.value)),
+)
+
+function isPendingId(id: string | number) {
+  return String(id).startsWith(PENDING_PREFIX)
+}
+
+function patchSelection(updater: (next: Set<string | number>) => void) {
+  const next = new Set(selectedIds.value)
+  updater(next)
+  selectedIds.value = next
+  emit(
+    'select',
+    items.value.filter((item) => next.has(item.id)),
+  )
+}
+
+function onItemSelect(item: AttachmentListItem, checked: boolean) {
+  patchSelection((next) => {
+    if (checked) {
+      if (!props.multiple) next.clear()
+      next.add(item.id)
+    } else {
+      next.delete(item.id)
+    }
+  })
+}
+
+function selectAll() {
+  patchSelection((next) => items.value.forEach((item) => next.add(item.id)))
+}
+
+function clearSelection() {
+  patchSelection((next) => next.clear())
+}
+
+function toggleAll(checked: boolean) {
+  if (checked) selectAll()
+  else clearSelection()
+}
+
+/* ---------- 分页 ---------- */
+const paginationVisible = computed(
+  () => props.pagination && resolvedTotal.value > currentPageSize.value,
+)
+
+function onPageChange(page: number, pageSize: number) {
+  innerPage.value = page
+  if (pageSize !== currentPageSize.value) innerPageSize.value = pageSize
+  emit('update:page', page)
+  if (pageSize !== props.pageSize) emit('update:pageSize', pageSize)
+}
+
+/* ---------- 空态里的限制说明 ---------- */
+/** 顺带说明限制，省得用户上传后才被拒 */
+const limitHints = computed(() => {
+  const text = locale.value.attachment
+  const hints: string[] = []
+  if (props.accept) hints.push(text.limitAccept.replace('{accept}', props.accept))
+  if (props.maxSize > 0) {
+    hints.push(text.limitSize.replace('{size}', formatFileSize(props.maxSize)))
+  }
+  if (props.maxCount > 0) {
+    hints.push(text.limitCount.replace('{count}', String(props.maxCount)))
+  }
+  return hints.join(' · ')
+})
+
+/* ---------- 入队与校验 ---------- */
+function reject(reason: AttachmentInvalidReason, files: File[]) {
+  const names = files.map((file) => file.name).join('、')
+  const text = locale.value.attachment
+  let message = ''
+  if (reason === 'accept') message = text.invalidAccept.replace('{name}', names)
+  else if (reason === 'max-size') {
+    message = text.invalidMaxSize
+      .replace('{name}', names)
+      .replace('{size}', formatFileSize(props.maxSize))
+  } else {
+    message = text.invalidMaxCount.replace('{count}', String(props.maxCount))
+  }
+  emit('invalid', { reason, files, message })
+}
+
+function createObjectUrl(file: File): string {
+  if (!isImageFile(file.name)) return ''
+  if (typeof URL === 'undefined' || typeof URL.createObjectURL !== 'function') return ''
+  return URL.createObjectURL(file)
+}
+
+function revokeObjectUrl(url?: string) {
+  if (url && typeof URL !== 'undefined' && typeof URL.revokeObjectURL === 'function') {
+    URL.revokeObjectURL(url)
+  }
+}
+
+/** 把本地文件加入待上传队列，返回被接受的文件（被拒绝的走 invalid 事件） */
+function addFiles(input: File[] | FileList): File[] {
+  const list = Array.from(input ?? [])
+  if (!list.length) return []
+  const accepted: File[] = []
+  for (const file of list) {
+    if (!matchesAccept(file.name, props.accept)) {
+      reject('accept', [file])
+      continue
+    }
+    if (props.maxSize > 0 && file.size > props.maxSize) {
+      reject('max-size', [file])
+      continue
+    }
+    if (props.maxCount > 0 && pendingFiles.value.length + accepted.length >= props.maxCount) {
+      reject('max-count', [file])
+      continue
+    }
+    accepted.push(file)
+  }
+  for (const file of accepted) {
+    uidSeed += 1
+    pendingFiles.value.push({
+      uid: `${PENDING_PREFIX}${uidSeed}`,
+      file,
+      name: file.name,
+      size: file.size,
+      ext: getExtension(file.name),
+      url: createObjectUrl(file),
+    })
+  }
+  return accepted
+}
+
+function dropPending(ids: Array<string | number>) {
+  const targets = new Set(ids.map(String))
+  const kept: PendingEntry[] = []
+  for (const entry of pendingFiles.value) {
+    if (targets.has(entry.uid)) revokeObjectUrl(entry.url)
+    else kept.push(entry)
+  }
+  pendingFiles.value = kept
+}
+
+function clearPending() {
+  pendingFiles.value.forEach((entry) => revokeObjectUrl(entry.url))
+  pendingFiles.value = []
+}
+
+function openFileDialog() {
+  if (props.readonly) return
+  inputRef.value?.click()
+}
+
+function onInputChange(event: Event) {
+  const target = event.target as HTMLInputElement
+  if (target.files?.length) addFiles(target.files)
+  target.value = ''
+}
+
+/* ---------- 拖拽 / 粘贴 ---------- */
+const dragOver = ref(false)
+let dragDepth = 0
+
+function onDragEnter(event: DragEvent) {
+  if (props.readonly) return
+  event.preventDefault()
+  if (event.currentTarget !== event.target) return
+  dragDepth += 1
+  dragOver.value = true
+}
+
+function onDragOver(event: DragEvent) {
+  if (props.readonly) return
+  event.preventDefault()
+  if (event.dataTransfer) event.dataTransfer.dropEffect = 'copy'
+}
+
+function onDragLeave(event: DragEvent) {
+  if (event.currentTarget !== event.target) return
+  dragDepth = Math.max(0, dragDepth - 1)
+  if (!dragDepth) dragOver.value = false
+}
+
+function onDrop(event: DragEvent) {
+  if (props.readonly) return
+  event.preventDefault()
+  dragDepth = 0
+  dragOver.value = false
+  const dropped = event.dataTransfer?.files
+  if (dropped?.length) addFiles(dropped)
+}
+
+function onPaste(event: ClipboardEvent) {
+  if (props.readonly) return
+  const items = event.clipboardData?.items
+  if (!items) return
+  const pasted: File[] = []
+  for (const item of items) {
+    if (item.kind !== 'file') continue
+    const file = item.getAsFile()
+    if (file) pasted.push(file)
+  }
+  if (!pasted.length) return
+  if (addFiles(pasted).length) event.preventDefault()
+}
+
+/* ---------- 上传 / 下载 / 删除 ---------- */
+function submitUpload() {
+  if (!pendingFiles.value.length || props.uploading) return
+  emit(
+    'upload',
+    pendingFiles.value.map((entry) => entry.file),
+  )
+}
+
+function triggerDownload(targets: AttachmentItem[]) {
+  if (!props.builtinDownload || typeof document === 'undefined') return
+  for (const item of targets) {
+    if (!item.url) continue
+    const anchor = document.createElement('a')
+    anchor.href = item.url
+    anchor.download = item.name
+    anchor.rel = 'noopener'
+    anchor.style.display = 'none'
+    document.body.appendChild(anchor)
+    anchor.click()
+    document.body.removeChild(anchor)
+  }
+}
+
+function downloadItems(targets: AttachmentItem[]) {
+  if (!targets.length) return
+  emit('download', targets)
+  triggerDownload(targets)
+}
+
+function onDownloadSelected() {
+  downloadItems(selectedItems.value.filter((item) => !item.pending))
+}
+
+function onDownloadItem(item: AttachmentListItem) {
+  downloadItems([item])
+}
+
+function removeSelected() {
+  const ids = [...selectedIds.value]
+  if (!ids.length) return
+  const pendingIds = ids.filter(isPendingId)
+  if (pendingIds.length) {
+    dropPending(pendingIds)
+    patchSelection((next) => pendingIds.forEach((id) => next.delete(id)))
+  }
+  const uploaded = props.files.filter((file) => selectedIds.value.has(file.id))
+  if (uploaded.length) emit('remove', uploaded)
+}
+
+function onRemoveItem(item: AttachmentListItem) {
+  if (item.pending) {
+    dropPending([item.id])
+    patchSelection((next) => next.delete(item.id))
+    return
+  }
+  emit('remove', [item])
+}
+
+/* ---------- 生命周期 ---------- */
+onMounted(() => {
+  if (props.pasteUpload) document.addEventListener('paste', onPaste)
+})
+
+onBeforeUnmount(() => {
+  if (props.pasteUpload) document.removeEventListener('paste', onPaste)
+  clearPending()
+})
+
+// 切分类：清空待上传队列与勾选，回到第一页
+watch(
+  () => props.categoryId,
+  () => {
+    clearPending()
+    innerPage.value = 1
+    if (selectedIds.value.size) clearSelection()
+  },
+)
+
+// 列表被父级刷新后，剔除已不存在的勾选
+watch(
+  () => props.files,
+  (files) => {
+    if (!selectedIds.value.size) return
+    const alive = new Set(files.map((file) => file.id))
+    const next = new Set([...selectedIds.value].filter((id) => isPendingId(id) || alive.has(id)))
+    if (next.size !== selectedIds.value.size) selectedIds.value = next
+  },
+)
+
+defineExpose({
+  pendingFiles,
+  selectedItems,
+  openFileDialog,
+  clearSelection,
+  selectAll,
+  addFiles,
+  clearPending,
+})
+</script>
+
+<template>
+  <div :class="e('list')" data-slot="attachment-list">
+    <!-- 工具栏：勾选后才浮出批量操作，平时只有全选 -->
+    <div :class="e('toolbar')">
+      <G3Checkbox
+        v-if="selectable"
+        :model-value="allChecked"
+        :indeterminate="indeterminate"
+        :disabled="!hasItems"
+        @update:model-value="toggleAll"
+      >
+        {{ locale.attachment.selectAll }}
+      </G3Checkbox>
+
+      <template v-if="selectedCount">
+        <span :class="e('toolbar-divider')" aria-hidden="true" />
+        <span :class="e('toolbar-count')">{{ selectedText }}</span>
+        <G3Button
+          type="outline"
+          size="small"
+          :title="locale.attachment.download"
+          :aria-label="locale.attachment.download"
+          @click="onDownloadSelected"
+        >
+          <Download :size="14" />
+          <span :class="e('toolbar-label')">{{ locale.attachment.download }}</span>
+        </G3Button>
+        <G3Button
+          v-if="!readonly"
+          type="danger-outline"
+          size="small"
+          :title="locale.attachment.remove"
+          :aria-label="locale.attachment.remove"
+          :disabled="removing"
+          @click="removeSelected"
+        >
+          <Trash2 :size="14" />
+          <span :class="e('toolbar-label')">{{ locale.attachment.remove }}</span>
+        </G3Button>
+      </template>
+    </div>
+
+    <!-- 卡片区 -->
+    <div
+      :class="[e('main'), { [is('dragover')]: dragOver && !readonly }]"
+      @dragenter="onDragEnter"
+      @dragover="onDragOver"
+      @dragleave="onDragLeave"
+      @drop="onDrop"
+    >
+      <G3Spin :spinning="loading" :class="e('spin')">
+        <div v-if="hasItems" :class="e('grid')">
+          <AttachmentCard
+            v-for="item in items"
+            :key="item.id"
+            :item="item"
+            :selected="selectedIds.has(item.id)"
+            :selectable="selectable"
+            :readonly="readonly"
+            @select="onItemSelect"
+            @preview="emit('preview', $event)"
+            @download="onDownloadItem"
+            @remove="onRemoveItem"
+          />
+        </div>
+
+        <!-- 空态即投放区：虚线框吸收拖拽，也顺手说明限制 -->
+        <div
+          v-else-if="!loading"
+          :class="[e('empty'), { [is('readonly')]: readonly }]"
+          @click="openFileDialog"
+        >
+          <CloudUpload :size="28" :stroke-width="1.5" :class="e('empty-icon')" />
+          <span :class="e('empty-title')">{{ locale.attachment.empty }}</span>
+          <span v-if="!readonly" :class="e('empty-hint')">
+            {{ locale.attachment.emptyHint }}
+          </span>
+          <span v-if="!readonly && limitHints" :class="e('empty-limit')">{{ limitHints }}</span>
+        </div>
+      </G3Spin>
+
+      <div v-if="dragOver && !readonly" :class="e('drop-mask')">
+        <Upload :size="24" :stroke-width="1.5" />
+        <span>{{ locale.attachment.dropHint }}</span>
+      </div>
+    </div>
+
+    <!-- 底栏：计数 + 上传入口 + 分页合成一块（只有一条顶边） -->
+    <div :class="[e('footer'), { [is('dirty')]: pendingCount > 0 }]">
+      <div :class="e('footer-bar')">
+        <span :class="[e('footer-count'), { [is('pending')]: pendingCount > 0 }]">
+          <template v-if="pendingCount">
+            {{ locale.attachment.pendingCount.replace('{count}', String(pendingCount)) }}
+          </template>
+          <template v-else>
+            {{ locale.attachment.total.replace('{count}', String(resolvedTotal)) }}
+          </template>
+        </span>
+
+        <div v-if="!readonly" :class="e('footer-actions')">
+          <input
+            ref="inputRef"
+            type="file"
+            :class="e('file-input')"
+            :multiple="multiple"
+            :accept="accept"
+            @change="onInputChange"
+          />
+          <G3Button type="outline" @click="openFileDialog">
+            <CloudUpload :size="14" />
+            {{ locale.attachment.select }}
+          </G3Button>
+          <G3Button
+            type="primary"
+            :disabled="!pendingCount"
+            :loading="uploading"
+            @click="submitUpload"
+          >
+            <Upload :size="14" />
+            {{ locale.attachment.upload }}
+          </G3Button>
+        </div>
+      </div>
+
+      <div v-if="paginationVisible" :class="e('pagination')">
+        <G3Pagination
+          :current="currentPage"
+          :page-size="currentPageSize"
+          :total="resolvedTotal"
+          :show-size-changer="showSizeChanger"
+          :page-size-options="pageSizeOptions"
+          @change="onPageChange"
+        />
+      </div>
+    </div>
+  </div>
+</template>
+
+<style lang="scss">
+@use '@g3soft/tokens/scss' as *;
+
+.#{e('attachment', 'list')} {
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+  height: 100%;
+  min-width: 0;
+  min-height: 0;
+  background: v('bg-container', #fff);
+  /* 工具栏的窄面板适配走容器查询（按面板宽度，而不是视口宽度） */
+  container-type: inline-size;
+}
+
+/* ---------- 工具栏 ----------
+   整行统一到「24px 小控件」这一档：复选框文案 12px、按钮 size="small"、
+   计数 12px。之前混了 14px / 12px 三套字号 + 无边框 ghost 按钮，
+   一行里元素高矮不一又没有边界，看着就是歪的。 */
+.#{e('attachment', 'toolbar')} {
+  display: flex;
+  flex: none;
+  align-items: center;
+  gap: v('space-2', 8px);
+  box-sizing: border-box;
+  /* 高度写死，不用 min-height：
+     - 勾选前只有「全选」一行文字（约 18px），勾选后浮出 24px 的批量按钮 ——
+       用 min-height 兜底仍会随内容变（默认 content-box 下 min-height 只管内容盒，
+       实际高度 = 内容盒 + 上下 padding）；
+     - 一旦高度恒定，「勾选时整条工具栏长高」这类问题从结构上就不可能出现。 */
+  height: calc(#{v('control-height-sm', 24px)} + #{v('space-2', 8px)} * 2);
+  padding: 0 v('space-3', 12px);
+  border-bottom: 1px solid v('border-color', #d9d9d9);
+  /* 不换行：窄面板宁可裁切也不让工具栏变高 */
+  flex-wrap: nowrap;
+  overflow: hidden;
+}
+
+/* 行内元素一律不收缩（按钮 / 复选框的文字被压扁或折行同样会改变高度），
+   只有「已选 N 项」这个纯文本可以省略号收尾 */
+.#{e('attachment', 'toolbar')} > * {
+  flex: none;
+}
+
+/* 复选框文案跟按钮同一档字号：字号不同，文字基线看着就是歪的 */
+.#{e('attachment', 'toolbar')} .#{b('checkbox')} {
+  font-size: v('font-size-sm', 12px);
+  white-space: nowrap;
+}
+
+.#{e('attachment', 'toolbar')} .#{b('button')} svg {
+  width: 14px;
+  height: 14px;
+}
+
+/* 竖向分组线：把「选择」与「操作」分开。
+   只靠 gap 的话，间距数字一样，但左松右紧看起来不齐。 */
+.#{e('attachment', 'toolbar-divider')} {
+  flex: none;
+  width: 1px;
+  height: 16px;
+  background: v('border-color', #d9d9d9);
+}
+
+.#{e('attachment', 'toolbar-count')} {
+  flex: 0 1 auto;
+  min-width: 0;
+  overflow: hidden;
+  color: v('text-2', rgba(0, 0, 0, 0.65));
+  font-size: v('font-size-sm', 12px);
+  font-variant-numeric: tabular-nums;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/* 窄面板：批量按钮只留图标。宁可少显示文案，也不让工具栏换行 / 变高。
+   按「面板宽度」而不是视口宽度判断 —— 组件可能被嵌在弹窗或窄侧栏里。 */
+@container (max-width: 340px) {
+  .#{e('attachment', 'toolbar-label')} {
+    display: none;
+  }
+}
+
+/* 更窄：连「全选」文案也收起，只留勾选框 */
+@container (max-width: 260px) {
+  .#{e('attachment', 'toolbar')} .#{e('checkbox', 'label')} {
+    display: none;
+  }
+}
+
+/* ---------- 卡片区 ---------- */
+.#{e('attachment', 'main')} {
+  position: relative;
+  flex: 1;
+  min-height: 0;
+  overflow: auto;
+  padding: v('space-3', 12px);
+
+  &.#{is('dragover')} {
+    background: color-mix(in srgb, var(#{css-var('color-primary')}) 4%, transparent);
+  }
+}
+
+.#{e('attachment', 'spin')} {
+  min-height: 100%;
+}
+
+.#{e('attachment', 'grid')} {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(150px, 1fr));
+  gap: v('space-3', 12px);
+  align-content: start;
+}
+
+/* ---------- 空态（= 投放区）---------- */
+/* 绝对铺满列表区（相对 __main 定位），不依赖 Spin / 内容容器的高度链 */
+.#{e('attachment', 'empty')} {
+  position: absolute;
+  inset: v('space-3', 12px);
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: v('space-1', 4px);
+  box-sizing: border-box;
+  padding: v('space-5', 24px);
+  border: 1px dashed v('border-color', #d9d9d9);
+  border-radius: v('radius', 6px);
+  color: v('text-3', rgba(0, 0, 0, 0.45));
+  text-align: center;
+  cursor: pointer;
+  transition:
+    border-color v('duration-fast', 0.1s) v('ease', ease),
+    background-color v('duration-fast', 0.1s) v('ease', ease),
+    color v('duration-fast', 0.1s) v('ease', ease);
+
+  &:hover {
+    border-color: v('color-primary', #18181b);
+    background: v('color-primary-soft', rgba(24, 24, 27, 0.12));
+    color: v('color-primary', #18181b);
+  }
+
+  &.#{is('readonly')} {
+    cursor: default;
+    background: transparent;
+
+    &:hover {
+      border-color: v('border-color', #d9d9d9);
+      color: v('text-3', rgba(0, 0, 0, 0.45));
+    }
+  }
+}
+
+.#{e('attachment', 'empty-icon')} {
+  margin-bottom: v('space-1', 4px);
+}
+
+.#{e('attachment', 'empty-title')} {
+  color: v('text-2', rgba(0, 0, 0, 0.65));
+  font-size: v('font-size', 14px);
+}
+
+.#{e('attachment', 'empty-hint')} {
+  font-size: v('font-size-sm', 12px);
+}
+
+.#{e('attachment', 'empty-limit')} {
+  margin-top: v('space-1', 4px);
+  font-size: v('font-size-sm', 12px);
+  opacity: 0.8;
+}
+
+/* ---------- 拖拽遮罩 ---------- */
+.#{e('attachment', 'drop-mask')} {
+  position: absolute;
+  inset: v('space-2', 8px);
+  z-index: 10;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: v('space-2', 8px);
+  border: 1px dashed v('color-primary', #18181b);
+  border-radius: v('radius', 6px);
+  background: color-mix(
+    in srgb,
+    var(#{css-var('color-primary')}) 6%,
+    var(#{css-var('bg-container')})
+  );
+  color: v('color-primary', #18181b);
+  font-size: v('font-size', 14px);
+  pointer-events: none;
+}
+
+/* ---------- 底栏（计数 + 上传 + 分页合成一块） ---------- */
+.#{e('attachment', 'footer')} {
+  flex: none;
+  border-top: 1px solid v('border-color', #d9d9d9);
+  background: v('bg-container', #fff);
+  transition: background-color v('duration', 0.2s) v('ease', ease);
+}
+
+/* 队列里有未提交文件：整块染主色淡底，做成「脏」状态 */
+.#{e('attachment', 'footer')}.#{is('dirty')} {
+  background: v('color-primary-soft', rgba(24, 24, 27, 0.12));
+}
+
+.#{e('attachment', 'footer-bar')} {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: v('space-2', 8px);
+  padding: v('space-2', 8px) v('space-3', 12px);
+}
+
+.#{e('attachment', 'footer-count')} {
+  color: v('text-3', rgba(0, 0, 0, 0.45));
+  font-size: v('font-size-sm', 12px);
+  font-variant-numeric: tabular-nums;
+
+  &.#{is('pending')} {
+    color: v('color-primary', #18181b);
+    font-weight: 500;
+  }
+}
+
+.#{e('attachment', 'footer-actions')} {
+  display: flex;
+  align-items: center;
+  gap: v('space-2', 8px);
+
+  svg {
+    width: 14px;
+    height: 14px;
+  }
+}
+
+.#{e('attachment', 'file-input')} {
+  display: none;
+}
+
+.#{e('attachment', 'pagination')} {
+  display: flex;
+  justify-content: flex-end;
+  padding: 0 v('space-3', 12px) v('space-2', 8px);
+}
+</style>
diff --git a/code/g3soft-libs/packages/ui/src/attachment/AttachmentPreview.vue b/code/g3soft-libs/packages/ui/src/attachment/AttachmentPreview.vue
new file mode 100644
index 00000000..6c4cb133
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/attachment/AttachmentPreview.vue
@@ -0,0 +1,241 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import { ChevronLeft, ChevronRight, Inbox } from '@lucide/vue'
+import { G3Button } from '../button'
+import { useLocale } from '../_composables/useLocale'
+import { useNamespace } from '../_composables/useNamespace'
+import { ATTACHMENT_KIND_ICONS } from './icons'
+import { formatFileSize, getExtension, getFileKind, isImageFile } from './file'
+import type { AttachmentItem } from './types'
+
+/**
+ * 附件预览 —— 右侧预览栏（默认不显示，`:show-preview="true"` 才挂载）。
+ *
+ * 图片直接展示，其他类型用「文件族图标 + 扩展名」占位；
+ * 上下翻页在 `list` 内按 id 定位，翻页只上报事件、不改数据。
+ */
+defineOptions({ name: 'G3AttachmentPreview' })
+
+const props = withDefaults(
+  defineProps<{
+    /** 当前预览项，null 表示未选中 */
+    item?: AttachmentItem | null
+    /** 参与翻页的列表（通常是当前页附件） */
+    list?: AttachmentItem[]
+  }>(),
+  { item: null, list: () => [] },
+)
+
+const emit = defineEmits<{
+  prev: []
+  next: []
+}>()
+
+const { e, em } = useNamespace('attachment')
+const locale = useLocale()
+
+const index = computed(() => {
+  if (!props.item) return -1
+  return props.list.findIndex((file) => file.id === props.item?.id)
+})
+
+const canPrev = computed(() => index.value > 0)
+const canNext = computed(() => index.value >= 0 && index.value < props.list.length - 1)
+
+const imageUrl = computed(() => {
+  const item = props.item
+  if (!item || !isImageFile(item.name)) return ''
+  return item.url || ''
+})
+
+const kind = computed(() => getFileKind(props.item?.name || ''))
+const kindIcon = computed(() => ATTACHMENT_KIND_ICONS[kind.value])
+const extension = computed(() =>
+  (props.item?.ext || getExtension(props.item?.name || '') || '?').toUpperCase(),
+)
+const sizeText = computed(() => formatFileSize(props.item?.size))
+</script>
+
+<template>
+  <aside :class="e('preview')" data-slot="attachment-preview">
+    <div :class="e('preview-toolbar')">
+      <G3Button
+        type="ghost"
+        :class="e('icon-btn')"
+        :disabled="!canPrev"
+        :title="locale.attachment.prev"
+        :aria-label="locale.attachment.prev"
+        @click="emit('prev')"
+      >
+        <ChevronLeft :size="14" />
+      </G3Button>
+      <span v-if="index >= 0" :class="e('preview-counter')">
+        {{ index + 1 }} / {{ list.length }}
+      </span>
+      <G3Button
+        type="ghost"
+        :class="e('icon-btn')"
+        :disabled="!canNext"
+        :title="locale.attachment.next"
+        :aria-label="locale.attachment.next"
+        @click="emit('next')"
+      >
+        <ChevronRight :size="14" />
+      </G3Button>
+      <span :class="e('preview-name')" :title="item?.name">{{ item?.name || '' }}</span>
+    </div>
+
+    <div :class="e('preview-body')">
+      <template v-if="item">
+        <img v-if="imageUrl" :class="e('preview-image')" :src="imageUrl" :alt="item.name" />
+        <div v-else :class="e('preview-generic')">
+          <span :class="[e('type'), em('type', kind)]">
+            <component :is="kindIcon" :size="26" :stroke-width="1.5" aria-hidden="true" />
+            <span :class="e('type-ext')">{{ extension }}</span>
+          </span>
+          <div :class="e('preview-info')">
+            <div :class="e('preview-title')">{{ item.name }}</div>
+            <div :class="e('preview-meta')">
+              <span>{{ sizeText }}</span>
+              <span v-if="item.ext">· {{ extension }}</span>
+            </div>
+          </div>
+        </div>
+      </template>
+
+      <div v-else :class="e('preview-empty')">
+        <Inbox :size="28" :stroke-width="1.5" />
+        <span>{{ locale.attachment.previewEmpty }}</span>
+      </div>
+    </div>
+  </aside>
+</template>
+
+<style lang="scss">
+@use '@g3soft/tokens/scss' as *;
+
+.#{e('attachment', 'preview')} {
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+  height: 100%;
+  min-width: 0;
+  min-height: 0;
+  background: v('bg-container', #fff);
+}
+
+.#{e('attachment', 'preview-toolbar')} {
+  display: flex;
+  flex: none;
+  align-items: center;
+  gap: v('space-1', 4px);
+  /* 与列表工具栏同高：控件高 + 上下各一份 space-2 */
+  min-height: calc(#{v('control-height', 32px)} + #{v('space-2', 8px)} * 2);
+  padding: 0 v('space-3', 12px);
+  border-bottom: 1px solid v('border-color', #d9d9d9);
+}
+
+.#{e('attachment', 'preview-counter')} {
+  min-width: 44px;
+  color: v('text-3', rgba(0, 0, 0, 0.45));
+  font-size: v('font-size-sm', 12px);
+  font-variant-numeric: tabular-nums;
+  text-align: center;
+}
+
+.#{e('attachment', 'preview-name')} {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  color: v('text-1', rgba(0, 0, 0, 0.88));
+  font-size: v('font-size', 14px);
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+
+.#{e('attachment', 'preview-body')} {
+  flex: 1;
+  min-height: 0;
+  overflow: auto;
+  background: v('fill', rgba(0, 0, 0, 0.04));
+}
+
+.#{e('attachment', 'preview-image')} {
+  display: block;
+  max-width: 100%;
+  max-height: 100%;
+  margin: auto;
+  padding: v('space-3', 12px);
+  box-sizing: border-box;
+  object-fit: contain;
+}
+
+.#{e('attachment', 'preview-generic')} {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: v('space-4', 16px);
+  min-height: 100%;
+  padding: v('space-4', 16px);
+  box-sizing: border-box;
+
+  /* 预览里的类型块比卡片里大一号 */
+  .#{e('attachment', 'type')} {
+    min-width: 72px;
+    padding: v('space-2', 8px);
+  }
+}
+
+.#{e('attachment', 'preview-info')} {
+  text-align: center;
+}
+
+.#{e('attachment', 'preview-title')} {
+  color: v('text-1', rgba(0, 0, 0, 0.88));
+  font-size: v('font-size', 14px);
+  font-weight: 600;
+  word-break: break-all;
+}
+
+.#{e('attachment', 'preview-meta')} {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: v('space-1', 4px);
+  margin-top: 4px;
+  color: v('text-3', rgba(0, 0, 0, 0.45));
+  font-size: v('font-size-sm', 12px);
+}
+
+.#{e('attachment', 'preview-empty')} {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: v('space-3', 12px);
+  min-height: 100%;
+  color: v('text-3', rgba(0, 0, 0, 0.45));
+  font-size: v('font-size', 14px);
+}
+
+/* 翻页按钮与卡片 / 表格里的小图标按钮同一规格 */
+.#{e('attachment', 'preview-toolbar')} .#{e('attachment', 'icon-btn')} {
+  width: 24px;
+  height: 24px;
+  min-height: 0;
+  padding: 0;
+  border-radius: v('radius-sm', 4px);
+  color: v('text-3', rgba(0, 0, 0, 0.45));
+
+  svg {
+    width: 14px;
+    height: 14px;
+  }
+
+  &:hover:not(:disabled) {
+    background: v('fill', rgba(0, 0, 0, 0.04));
+    color: v('text-1', rgba(0, 0, 0, 0.88));
+  }
+}
+</style>
diff --git a/code/g3soft-libs/packages/ui/src/attachment/file.test.ts b/code/g3soft-libs/packages/ui/src/attachment/file.test.ts
new file mode 100644
index 00000000..437ed1ea
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/attachment/file.test.ts
@@ -0,0 +1,90 @@
+import { describe, expect, it } from 'vitest'
+import {
+  formatFileSize,
+  getExtension,
+  getFileKind,
+  getMimeType,
+  isImageFile,
+  matchesAccept,
+} from './file'
+
+describe('getExtension', () => {
+  it('取小写扩展名', () => {
+    expect(getExtension('合同.PDF')).toBe('pdf')
+  })
+
+  it('无扩展名 / 点开头 / 结尾是点都算没有扩展名', () => {
+    expect(getExtension('README')).toBe('')
+    expect(getExtension('.gitignore')).toBe('')
+    expect(getExtension('table.')).toBe('')
+    expect(getExtension('')).toBe('')
+  })
+
+  it('多点文件名取最后一段', () => {
+    expect(getExtension('2026.10.11 报表.xlsx')).toBe('xlsx')
+  })
+})
+
+describe('getFileKind', () => {
+  it('按扩展名归类', () => {
+    expect(getFileKind('a.pdf')).toBe('doc')
+    expect(getFileKind('a.xlsx')).toBe('sheet')
+    expect(getFileKind('a.pptx')).toBe('slide')
+    expect(getFileKind('a.png')).toBe('image')
+    expect(getFileKind('a.zip')).toBe('archive')
+    expect(getFileKind('a.mp4')).toBe('media')
+  })
+
+  it('未知扩展名落到 other', () => {
+    expect(getFileKind('a.unknownext')).toBe('other')
+    expect(getFileKind('noext')).toBe('other')
+  })
+})
+
+describe('isImageFile / getMimeType', () => {
+  it('图片判定不受大小写影响', () => {
+    expect(isImageFile('photo.JPG')).toBe(true)
+    expect(isImageFile('photo.svg')).toBe(true)
+    expect(isImageFile('photo.pdf')).toBe(false)
+  })
+
+  it('已登记的 MIME', () => {
+    expect(getMimeType('a.docx')).toContain('wordprocessingml')
+    expect(getMimeType('a.unknown')).toBe('')
+  })
+})
+
+describe('formatFileSize', () => {
+  it('按 1024 进制换算', () => {
+    expect(formatFileSize(0)).toBe('0 B')
+    expect(formatFileSize(512)).toBe('512 B')
+    expect(formatFileSize(2048)).toBe('2.0 KB')
+    expect(formatFileSize(1024 * 1024 * 3)).toBe('3.0 MB')
+    expect(formatFileSize(1024 * 1024 * 1024 * 2)).toBe('2.00 GB')
+  })
+
+  it('非法输入退化为 0 B', () => {
+    expect(formatFileSize(undefined)).toBe('0 B')
+    expect(formatFileSize(-1)).toBe('0 B')
+    expect(formatFileSize('abc')).toBe('0 B')
+  })
+})
+
+describe('matchesAccept', () => {
+  it('未设置 accept 一律通过', () => {
+    expect(matchesAccept('a.exe', undefined)).toBe(true)
+    expect(matchesAccept('a.exe', '')).toBe(true)
+  })
+
+  it('支持扩展名写法', () => {
+    expect(matchesAccept('a.pdf', '.pdf,.docx')).toBe(true)
+    expect(matchesAccept('a.PDF', '.pdf')).toBe(true)
+    expect(matchesAccept('a.png', '.pdf')).toBe(false)
+  })
+
+  it('支持 mime 通配与精确写法', () => {
+    expect(matchesAccept('a.png', 'image/*')).toBe(true)
+    expect(matchesAccept('a.mp4', 'image/*')).toBe(false)
+    expect(matchesAccept('a.pdf', 'application/pdf')).toBe(true)
+  })
+})
diff --git a/code/g3soft-libs/packages/ui/src/attachment/file.ts b/code/g3soft-libs/packages/ui/src/attachment/file.ts
new file mode 100644
index 00000000..2d9dce88
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/attachment/file.ts
@@ -0,0 +1,116 @@
+/**
+ * 附件视觉与校验工具（纯函数，无副作用，可单测）。
+ *
+ * 文件族只决定**语义色令牌名**，实际颜色由样式层从 `--g3-color-*` 取，
+ * 因此换肤 / 暗色主题下无需改动这里。
+ */
+
+/** 图片扩展名 */
+export const IMAGE_EXTENSIONS = ['jpg', 'jpeg', 'png', 'gif', 'bmp', 'webp', 'svg', 'avif', 'ico']
+
+/** 文件族：决定类型色块的颜色 */
+export type AttachmentFileKind = 'image' | 'doc' | 'sheet' | 'slide' | 'archive' | 'media' | 'other'
+
+const KIND_EXTENSIONS: Record<Exclude<AttachmentFileKind, 'other'>, string[]> = {
+  image: IMAGE_EXTENSIONS,
+  doc: ['doc', 'docx', 'pdf', 'txt', 'md', 'rtf', 'odt', 'wps'],
+  sheet: ['xls', 'xlsx', 'csv', 'ods', 'et'],
+  slide: ['ppt', 'pptx', 'odp', 'dps'],
+  archive: ['zip', 'rar', '7z', 'tar', 'gz', 'bz2'],
+  media: ['mp3', 'wav', 'flac', 'aac', 'mp4', 'mov', 'avi', 'mkv', 'webm'],
+}
+
+const MIME_BY_EXT: Record<string, string> = {
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  png: 'image/png',
+  gif: 'image/gif',
+  bmp: 'image/bmp',
+  webp: 'image/webp',
+  svg: 'image/svg+xml',
+  avif: 'image/avif',
+  ico: 'image/x-icon',
+  pdf: 'application/pdf',
+  txt: 'text/plain',
+  md: 'text/markdown',
+  csv: 'text/csv',
+  rtf: 'application/rtf',
+  doc: 'application/msword',
+  docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  xls: 'application/vnd.ms-excel',
+  xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  ppt: 'application/vnd.ms-powerpoint',
+  pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+  zip: 'application/zip',
+  rar: 'application/vnd.rar',
+  '7z': 'application/x-7z-compressed',
+  tar: 'application/x-tar',
+  gz: 'application/gzip',
+  mp3: 'audio/mpeg',
+  wav: 'audio/wav',
+  flac: 'audio/flac',
+  aac: 'audio/aac',
+  mp4: 'video/mp4',
+  mov: 'video/quicktime',
+  avi: 'video/x-msvideo',
+  mkv: 'video/x-matroska',
+  webm: 'video/webm',
+}
+
+/** 取扩展名（小写、不含点）；无扩展名返回 '' */
+export function getExtension(name: string): string {
+  const text = name || ''
+  const index = text.lastIndexOf('.')
+  if (index <= 0 || index === text.length - 1) return ''
+  return text.slice(index + 1).toLowerCase()
+}
+
+/** 推断文件族 */
+export function getFileKind(name: string): AttachmentFileKind {
+  const ext = getExtension(name)
+  if (!ext) return 'other'
+  for (const [kind, extensions] of Object.entries(KIND_EXTENSIONS)) {
+    if (extensions.includes(ext)) return kind as AttachmentFileKind
+  }
+  return 'other'
+}
+
+/** 是否图片 */
+export function isImageFile(name: string): boolean {
+  return IMAGE_EXTENSIONS.includes(getExtension(name))
+}
+
+/** 扩展名 → MIME（未知返回 ''） */
+export function getMimeType(name: string): string {
+  return MIME_BY_EXT[getExtension(name)] || ''
+}
+
+/** 格式化文件大小（B / KB / MB / GB） */
+export function formatFileSize(bytes?: number | string | null): string {
+  const size = Number(bytes || 0)
+  if (!Number.isFinite(size) || size <= 0) return '0 B'
+  if (size < 1024) return `${size} B`
+  if (size < 1024 * 1024) return `${(size / 1024).toFixed(1)} KB`
+  if (size < 1024 * 1024 * 1024) return `${(size / 1024 / 1024).toFixed(1)} MB`
+  return `${(size / 1024 / 1024 / 1024).toFixed(2)} GB`
+}
+
+/**
+ * 是否命中原生 accept 语法（`.pdf,image/*,application/pdf`）。
+ * 未设置 accept 时一律通过。
+ */
+export function matchesAccept(name: string, accept?: string): boolean {
+  if (!accept) return true
+  const ext = getExtension(name)
+  const mime = getMimeType(name)
+  const tokens = accept
+    .split(',')
+    .map((token) => token.trim().toLowerCase())
+    .filter(Boolean)
+  if (!tokens.length) return true
+  return tokens.some((token) => {
+    if (token.startsWith('.')) return token.slice(1) === ext
+    if (token.endsWith('/*')) return mime.startsWith(`${token.slice(0, token.indexOf('/'))}/`)
+    return mime === token
+  })
+}
diff --git a/code/g3soft-libs/packages/ui/src/attachment/icons.ts b/code/g3soft-libs/packages/ui/src/attachment/icons.ts
new file mode 100644
index 00000000..ff85cb2f
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/attachment/icons.ts
@@ -0,0 +1,26 @@
+import {
+  FileArchive,
+  FileImage,
+  FileSpreadsheet,
+  FileText,
+  Files,
+  Film,
+  Presentation,
+} from '@lucide/vue'
+import type { Component } from 'vue'
+import type { AttachmentFileKind } from './file'
+
+/**
+ * 文件族 → 图标。卡片、表格、预览三处共用，保证同一文件在任何视图里长得一样。
+ *
+ * 比「扩展名三个字母」的方块信息量更高：图标先传达类型，扩展名文字只是补充。
+ */
+export const ATTACHMENT_KIND_ICONS: Record<AttachmentFileKind, Component> = {
+  image: FileImage,
+  doc: FileText,
+  sheet: FileSpreadsheet,
+  slide: Presentation,
+  archive: FileArchive,
+  media: Film,
+  other: Files,
+}
diff --git a/code/g3soft-libs/packages/ui/src/attachment/index.ts b/code/g3soft-libs/packages/ui/src/attachment/index.ts
new file mode 100644
index 00000000..275af32d
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/attachment/index.ts
@@ -0,0 +1,29 @@
+export { default as G3Attachment } from './Attachment.vue'
+export { default as G3AttachmentList } from './AttachmentList.vue'
+export { default as G3AttachmentCard } from './AttachmentCard.vue'
+export { default as G3AttachmentPreview } from './AttachmentPreview.vue'
+export {
+  IMAGE_EXTENSIONS,
+  formatFileSize,
+  getExtension,
+  getFileKind,
+  getMimeType,
+  isImageFile,
+  matchesAccept,
+} from './file'
+export type { AttachmentFileKind } from './file'
+export type {
+  AttachmentCategory,
+  AttachmentEmits,
+  AttachmentExpose,
+  AttachmentInvalidInfo,
+  AttachmentInvalidReason,
+  AttachmentItem,
+  AttachmentListItem,
+  AttachmentPendingFile,
+  AttachmentProps,
+  AttachmentRemoveRequest,
+  AttachmentStatus,
+  AttachmentUploadContext,
+  AttachmentUploadRequest,
+} from './types'
diff --git a/code/g3soft-libs/packages/ui/src/attachment/types.ts b/code/g3soft-libs/packages/ui/src/attachment/types.ts
new file mode 100644
index 00000000..da3ca088
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/attachment/types.ts
@@ -0,0 +1,204 @@
+/**
+ * 附件管理器类型定义。
+ *
+ * 设计原则：**与业务解耦**。组件不请求接口、不感知「模块 / 业务主键」等概念，
+ * 只消费 `files` / `categories` 两份数据，并把用户意图以事件抛给业务；
+ * 需要开箱即用时可传 `uploadRequest` / `removeRequest` 让组件托管请求过程。
+ */
+
+/** 附件状态：ready 已上传、uploading 上传中、error 上传失败 */
+export type AttachmentStatus = 'ready' | 'uploading' | 'error'
+
+/** 附件项（组件不解读业务字段，事件里原样回传） */
+export interface AttachmentItem {
+  /** 唯一标识 */
+  id: string | number
+  /** 文件名（含扩展名） */
+  name: string
+  /** 文件大小（字节） */
+  size?: number
+  /** 扩展名（小写、不含点）；不传时从 name 推断 */
+  ext?: string
+  /** 预览 / 下载地址 */
+  url?: string
+  /** 缩略图地址；图片类型不传时回退到 url */
+  thumbnailUrl?: string
+  /** 所属分类标识，与 AttachmentCategory.id 对应 */
+  categoryId?: string | number
+  /** 状态，默认 ready */
+  status?: AttachmentStatus
+  /** 上传进度 0-100，status 为 uploading 时展示 */
+  percent?: number
+  /** 业务原始数据，组件不解读 */
+  raw?: unknown
+  /** 允许附加业务字段 */
+  [key: string]: unknown
+}
+
+/** 分类节点；提供 categories 时左侧渲染分类树 */
+export interface AttachmentCategory {
+  /** 唯一标识 */
+  id: string | number
+  /** 分类名称 */
+  name: string
+  /** 数量角标（预留字段，组件不渲染） */
+  count?: number
+  /** 禁用该分类 */
+  disabled?: boolean
+  /** 子分类 */
+  children?: AttachmentCategory[]
+  /** 允许附加业务字段 */
+  [key: string]: unknown
+}
+
+/** 待上传的本地文件（尚未提交给业务） */
+export interface AttachmentPendingFile {
+  /** 本地 File 对象 */
+  file: File
+  /** 文件名 */
+  name: string
+  /** 字节大小 */
+  size: number
+  /** 扩展名（小写、不含点） */
+  ext: string
+  /** 本地预览地址（图片为 blob URL） */
+  url?: string
+}
+
+/** 列表渲染项：已上传附件 或 待上传本地文件 */
+export interface AttachmentListItem extends AttachmentItem {
+  /** 是否为待上传（本地队列）项 */
+  pending?: boolean
+}
+
+/** 校验未通过的原因 */
+export type AttachmentInvalidReason = 'accept' | 'max-size' | 'max-count'
+
+/** 校验未通过信息 */
+export interface AttachmentInvalidInfo {
+  /** 原因：类型不接受 / 超出大小 / 超出数量 */
+  reason: AttachmentInvalidReason
+  /** 被拒绝的本地文件 */
+  files: File[]
+  /** 组件按 locale 生成的提示原文（业务可直接 toast） */
+  message: string
+}
+
+/** 上传上下文（把当前分类透传给业务） */
+export interface AttachmentUploadContext {
+  /** 当前选中分类；「全部」时为 undefined */
+  categoryId?: string | number
+}
+
+/** 上传请求：组件托管上传，成功后可返回落库结果用于回填列表 */
+export type AttachmentUploadRequest = (
+  files: File[],
+  context: AttachmentUploadContext,
+) => Promise<AttachmentItem[] | void> | AttachmentItem[] | void
+
+/** 删除请求：组件托管删除 */
+export type AttachmentRemoveRequest = (items: AttachmentItem[]) => Promise<void> | void
+
+export interface AttachmentProps {
+  /** 附件列表（受控，配合 `update:files` 使用 v-model:files） */
+  files?: AttachmentItem[]
+  /** 分类数据；为空则不渲染左栏 */
+  categories?: AttachmentCategory[]
+  /** 选中分类标识，`''` 表示「全部」（v-model:categoryKey） */
+  categoryKey?: string | number
+  /** 是否显示左侧分类栏（无 categories 时自动隐藏） */
+  showCategory?: boolean
+  /**
+   * 是否显示右侧预览栏。
+   * 默认 `false`（只留分类 + 列表）—— 关掉时 `preview` 事件照常抛出，
+   * 业务可以自己开弹窗或抽屉做预览。
+   */
+  showPreview?: boolean
+  /** 只读：隐藏上传 / 删除入口 */
+  readonly?: boolean
+  /** 列表请求中（骨架 / 遮罩） */
+  loading?: boolean
+  /** 分类数据请求中 */
+  categoryLoading?: boolean
+  /** 是否可勾选 */
+  selectable?: boolean
+  /** 是否允许多选 */
+  multiple?: boolean
+  /** 接受的文件类型，同原生 `accept`（`.pdf,image/*`） */
+  accept?: string
+  /** 单文件大小上限（字节），0 或未传表示不限制 */
+  maxSize?: number
+  /** 待上传队列上限（不含已上传文件） */
+  maxCount?: number
+  /** 允许在列表区域 Ctrl/Cmd+V 粘贴上传（监听 document，默认关闭） */
+  pasteUpload?: boolean
+  /** 删除前二次确认（默认开启） */
+  confirmRemove?: boolean
+  /** 下载时由组件内建触发（依据 `item.url` 造 a[download]），默认开启 */
+  builtinDownload?: boolean
+  /** 是否显示分页（默认开启，数据不足一页时自动隐藏） */
+  pagination?: boolean
+  /** 当前页（v-model:page） */
+  page?: number
+  /** 每页条数（v-model:pageSize） */
+  pageSize?: number
+  /** 总条数；不传时取 `files.length` */
+  total?: number
+  /** 每页条数选项 */
+  pageSizeOptions?: Array<number | string>
+  /** 显示每页条数切换器 */
+  showSizeChanger?: boolean
+  /** 根容器高度，数字按 px；默认撑满父容器（父级无高度时保底 320px） */
+  height?: number | string
+  /** 托管上传：不传时改为 emit `upload` 交给业务 */
+  uploadRequest?: AttachmentUploadRequest
+  /** 托管删除：不传时改为 emit `remove` 交给业务 */
+  removeRequest?: AttachmentRemoveRequest
+}
+
+export interface AttachmentEmits {
+  /** files 受控更新（删除成功 / 上传回填后触发） */
+  (e: 'update:files', files: AttachmentItem[]): void
+  (e: 'update:categoryKey', key: string | number): void
+  (e: 'update:page', page: number): void
+  (e: 'update:pageSize', size: number): void
+  /** 列表发生增删（上传成功 / 删除成功） */
+  (e: 'change', files: AttachmentItem[]): void
+  /** 勾选变化 */
+  (e: 'select', items: AttachmentItem[]): void
+  /** 分类切换 */
+  (e: 'categoryChange', key: string | number, category: AttachmentCategory | null): void
+  /** 点击某项预览（取消选中时 item 为 null） */
+  (e: 'preview', item: AttachmentItem | null): void
+  /** 下载（配合 `builtin-download` 可关闭内建行为） */
+  (e: 'download', items: AttachmentItem[]): void
+  /** 用户确认删除（`confirm-remove` 通过且请求成功后才触发） */
+  (e: 'remove', items: AttachmentItem[]): void
+  /** 删除失败 */
+  (e: 'removeError', error: unknown, items: AttachmentItem[]): void
+  /** 未提供 `uploadRequest` 时把待上传文件交给业务 */
+  (e: 'upload', files: File[], context: AttachmentUploadContext): void
+  /** 托管上传成功 */
+  (e: 'uploadSuccess', files: File[], result: AttachmentItem[] | void): void
+  /** 上传失败（待上传队列保留，可重试） */
+  (e: 'uploadError', error: unknown, files: File[]): void
+  /** 文件被 accept / maxSize / maxCount 拒绝 */
+  (e: 'invalid', info: AttachmentInvalidInfo): void
+}
+
+export interface AttachmentExpose {
+  /** 当前勾选的附件 */
+  readonly selectedItems: AttachmentItem[]
+  /** 待上传的本地文件 */
+  readonly pendingFiles: AttachmentPendingFile[]
+  /** 打开系统文件选择框 */
+  openFileDialog: () => void
+  /** 清空勾选 */
+  clearSelection: () => void
+  /** 全选当前页 */
+  selectAll: () => void
+  /** 直接入队待上传文件（返回被接受的文件） */
+  addFiles: (files: File[] | FileList) => File[]
+  /** 清空待上传队列（业务自行接管上传时调用） */
+  clearPending: () => void
+}
diff --git a/code/g3soft-libs/packages/ui/src/button/Button.vue b/code/g3soft-libs/packages/ui/src/button/Button.vue
index 8622e528..06e1585f 100644
--- a/code/g3soft-libs/packages/ui/src/button/Button.vue
+++ b/code/g3soft-libs/packages/ui/src/button/Button.vue
@@ -153,6 +153,27 @@ function handleClick(ev: MouseEvent) {
   animation: #{b('button')}-spin 0.7s linear infinite;
 }
 
+/**
+ * 图标容器与文字容器：都做成 flex 并垂直居中。
+ *
+ * ⚠️ 这两条是必须的 —— 缺了会造成「图标偏上」：
+ *   span 默认 display:inline，内部的 svg 会按 vertical-align:baseline 对齐，
+ *   于是 svg 坐在文字基线上而不是容器中心，实测比文字中心高约 1.5px。
+ *   按钮自身的 align-items:center 只能居中【span】这一层，
+ *   治不了 span 【内部】的 svg 基线对齐。
+ * 所以给两个容器都加 flex 居中，让 svg 与文字在同一水平中线上。
+ */
+.#{e('button', 'icon')},
+.#{e('button', 'content')} {
+  display: inline-flex;
+  align-items: center;
+}
+
+/* 图标不参与压缩：文字过长时优先压文字，图标保持原尺寸 */
+.#{e('button', 'icon')} {
+  flex-shrink: 0;
+}
+
 @keyframes #{b('button')}-spin {
   to {
     transform: rotate(360deg);
diff --git a/code/g3soft-libs/packages/ui/src/captcha/SliderCaptcha.test.ts b/code/g3soft-libs/packages/ui/src/captcha/SliderCaptcha.test.ts
new file mode 100644
index 00000000..2361b31d
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/captcha/SliderCaptcha.test.ts
@@ -0,0 +1,291 @@
+import { mount } from '@vue/test-utils'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { defineComponent, ref } from 'vue'
+import G3ConfigProvider from '../config-provider/ConfigProvider.vue'
+import { enUS } from '../locale'
+import G3SliderCaptcha from './SliderCaptcha.vue'
+
+/**
+ * 滑块验证码单测。
+ *
+ * happy-dom 没有布局引擎：`getBoundingClientRect()` 恒为 0，所以每个用例先用
+ * `mockWidth()` 把「容器宽 / 手柄宽」钉死（真实浏览器里这两个值由 CSS 与令牌决定）。
+ *
+ * 拖拽走 Pointer Events；happy-dom 不保证有 PointerEvent 构造器，也不保证实现了
+ * setPointerCapture，因此事件用 `Event` + 手工挂属性派发 —— 组件只读
+ * clientX / button / pointerId 这几个字段，与真实指针路径等价。
+ */
+
+const CONTAINER_WIDTH = 200
+const ACTION_WIDTH = 32
+const TRACK_MAX = CONTAINER_WIDTH - ACTION_WIDTH
+
+afterEach(() => {
+  vi.useRealTimers()
+})
+
+/** 把元素的量测宽度钉死（happy-dom 没有布局，默认全是 0） */
+function mockWidth(element: Element, width: number): void {
+  element.getBoundingClientRect = () =>
+    ({
+      width,
+      height: 32,
+      top: 0,
+      left: 0,
+      right: width,
+      bottom: 32,
+      x: 0,
+      y: 0,
+      toJSON: () => ({}),
+    }) as DOMRect
+}
+
+function dispatchPointer(
+  element: Element,
+  type: string,
+  init: { clientX?: number; button?: number; pointerId?: number } = {},
+): void {
+  const options = { bubbles: true, cancelable: true, clientX: 0, button: 0, pointerId: 1, ...init }
+  let event: Event
+  if (typeof PointerEvent === 'function') {
+    event = new PointerEvent(type, options)
+  } else {
+    event = new Event(type, { bubbles: true, cancelable: true })
+    Object.assign(event, options)
+  }
+  element.dispatchEvent(event)
+}
+
+/** 挂载并钉死量测尺寸，返回常用的定位器 */
+function mountCaptcha(props: Record<string, unknown> = {}) {
+  const wrapper = mount(G3SliderCaptcha, { props: { modelValue: false, ...props } })
+  const action = wrapper.find('.g3-slider-captcha__action')
+  mockWidth(wrapper.element, CONTAINER_WIDTH)
+  mockWidth(action.element, ACTION_WIDTH)
+  return { wrapper, action }
+}
+
+/** v-model 宿主：RTL / 受控场景看这个 ref 比翻 emitted 更直观 */
+function mountWithModel(direction: 'ltr' | 'rtl' = 'ltr') {
+  const value = ref(false)
+  const Host = defineComponent({
+    components: { G3ConfigProvider, G3SliderCaptcha },
+    props: { direction: { type: String, default: 'ltr' } },
+    setup: () => ({ value }),
+    template: `
+      <G3ConfigProvider :direction="direction">
+        <G3SliderCaptcha v-model="value" />
+      </G3ConfigProvider>
+    `,
+  })
+  const wrapper = mount(Host, { props: { direction } })
+  const action = wrapper.find('.g3-slider-captcha__action')
+  mockWidth(wrapper.find('.g3-slider-captcha').element, CONTAINER_WIDTH)
+  mockWidth(action.element, ACTION_WIDTH)
+  return { wrapper, action, value }
+}
+
+describe('SliderCaptcha 基础渲染', () => {
+  it('文案默认取语言包，手柄带 slider 语义', () => {
+    const { wrapper, action } = mountCaptcha()
+
+    expect(wrapper.find('.g3-slider-captcha__text').text()).toBe('按住滑块拖动')
+    expect(action.attributes('role')).toBe('slider')
+    expect(action.attributes('aria-orientation')).toBe('horizontal')
+    expect(action.attributes('aria-valuemin')).toBe('0')
+    expect(action.attributes('aria-valuemax')).toBe('100')
+    expect(action.attributes('aria-valuenow')).toBe('0')
+    expect(action.attributes('aria-valuetext')).toBe('按住滑块拖动')
+    expect(action.attributes('aria-label')).toBe('滑动验证')
+    expect(action.attributes('tabindex')).toBe('0')
+  })
+
+  it('text / successText 可覆盖语言包', () => {
+    const { wrapper } = mountCaptcha({ text: '按住拖到最右', successText: '已通过' })
+
+    expect(wrapper.find('.g3-slider-captcha__text').text()).toBe('按住拖到最右')
+    expect(wrapper.find('.g3-slider-captcha__action').attributes('aria-valuetext')).toBe(
+      '按住拖到最右',
+    )
+  })
+
+  it('语言包可整体替换（ConfigProvider 传 enUS）', () => {
+    const Host = defineComponent({
+      components: { G3ConfigProvider, G3SliderCaptcha },
+      setup: () => ({ enUS }),
+      template: `
+        <G3ConfigProvider :locale="enUS">
+          <G3SliderCaptcha :model-value="false" />
+        </G3ConfigProvider>
+      `,
+    })
+    const wrapper = mount(Host)
+
+    expect(wrapper.find('.g3-slider-captcha__text').text()).toBe('Slide to verify')
+  })
+
+  it('size 输出修饰类，medium 不加类', () => {
+    expect(mountCaptcha().wrapper.classes()).toContain('g3-slider-captcha')
+    expect(mountCaptcha({ size: 'large' }).wrapper.classes()).toContain('g3-slider-captcha--large')
+    expect(mountCaptcha({ size: 'small' }).wrapper.classes()).toContain('g3-slider-captcha--small')
+  })
+})
+
+describe('SliderCaptcha 拖拽', () => {
+  it('拖到行程末端即通过：emit true + success，手柄停在末端', async () => {
+    const { wrapper, action } = mountCaptcha()
+
+    dispatchPointer(action.element, 'pointerdown', { clientX: 0 })
+    dispatchPointer(action.element, 'pointermove', { clientX: TRACK_MAX })
+    await wrapper.vm.$nextTick()
+
+    expect(wrapper.emitted('update:modelValue')?.at(-1)).toEqual([true])
+    expect(wrapper.emitted('success')?.at(-1)).toEqual([{ isPassing: true }])
+    expect(action.attributes('aria-valuenow')).toBe('100')
+    expect(wrapper.find('.g3-slider-captcha__text').text()).toBe('验证通过')
+    expect(wrapper.classes()).toContain('is-passed')
+
+    const moves = wrapper.emitted('move') as Array<[{ offset: number }]> | undefined
+    expect(moves?.at(-1)?.[0].offset).toBe(TRACK_MAX)
+    expect(action.attributes('tabindex')).toBe('-1')
+  })
+
+  it('中途松手回弹到起点，不报通过', async () => {
+    vi.useFakeTimers()
+    const { wrapper, action } = mountCaptcha()
+
+    dispatchPointer(action.element, 'pointerdown', { clientX: 0 })
+    dispatchPointer(action.element, 'pointermove', { clientX: 100 })
+    dispatchPointer(action.element, 'pointerup', { clientX: 100 })
+    await wrapper.vm.$nextTick()
+
+    expect(wrapper.emitted('update:modelValue')).toBeUndefined()
+    expect(wrapper.classes()).not.toContain('is-passed')
+    expect(wrapper.emitted('end')).toHaveLength(1)
+
+    const moves = wrapper.emitted('move') as Array<[{ offset: number }]> | undefined
+    expect(moves?.at(-1)?.[0].offset).toBe(100)
+
+    // 回弹动画走完后要卸掉过渡类，否则下次拖拽会被过渡拖成「不跟手」
+    vi.advanceTimersByTime(320)
+    await wrapper.vm.$nextTick()
+    expect(wrapper.find('.g3-slider-captcha__action').classes()).not.toContain('is-returning')
+  })
+
+  it('未拖到末端不会通过（容差 2px 之外仍不放过）', () => {
+    const { wrapper, action } = mountCaptcha()
+
+    dispatchPointer(action.element, 'pointerdown', { clientX: 0 })
+    dispatchPointer(action.element, 'pointermove', { clientX: TRACK_MAX - 3 })
+
+    expect(wrapper.emitted('success')).toBeUndefined()
+    expect(wrapper.classes()).not.toContain('is-passed')
+  })
+
+  it('禁用态：拖拽无响应、tabindex 为 -1、带禁用修饰类', () => {
+    const { wrapper, action } = mountCaptcha({ disabled: true })
+
+    dispatchPointer(action.element, 'pointerdown', { clientX: 0 })
+    dispatchPointer(action.element, 'pointermove', { clientX: TRACK_MAX })
+
+    expect(wrapper.emitted('start')).toBeUndefined()
+    expect(wrapper.emitted('update:modelValue')).toBeUndefined()
+    expect(wrapper.classes()).toContain('is-disabled')
+    expect(action.attributes('tabindex')).toBe('-1')
+    expect(action.attributes('aria-disabled')).toBe('true')
+  })
+
+  it('量不到宽度（未布局）时拖拽直接忽略，不抛错', () => {
+    const wrapper = mount(G3SliderCaptcha, { props: { modelValue: false } })
+    const action = wrapper.find('.g3-slider-captcha__action')
+
+    dispatchPointer(action.element, 'pointerdown', { clientX: 0 })
+    dispatchPointer(action.element, 'pointermove', { clientX: 120 })
+
+    expect(wrapper.emitted('update:modelValue')).toBeUndefined()
+  })
+})
+
+describe('SliderCaptcha 方向与键盘', () => {
+  it('RTL：向左拖到行程末端同样通过', async () => {
+    const { action, value } = mountWithModel('rtl')
+
+    dispatchPointer(action.element, 'pointerdown', { clientX: CONTAINER_WIDTH })
+    dispatchPointer(action.element, 'pointermove', { clientX: ACTION_WIDTH })
+    await Promise.resolve()
+
+    expect(value.value).toBe(true)
+  })
+
+  it('LTR：向左拖（远离末端）不会通过', async () => {
+    const { action, value } = mountWithModel('ltr')
+
+    dispatchPointer(action.element, 'pointerdown', { clientX: TRACK_MAX })
+    dispatchPointer(action.element, 'pointermove', { clientX: 0 })
+    await Promise.resolve()
+
+    expect(value.value).toBe(false)
+  })
+
+  it('键盘：End 直达终点并通过；方向键按步长前进；Home 复位', async () => {
+    const { wrapper, action } = mountCaptcha()
+
+    await action.trigger('keydown', { key: 'End' })
+    expect(wrapper.emitted('update:modelValue')?.at(-1)).toEqual([true])
+
+    // 键盘不走 move（那是指针拖拽的载荷），进度看 aria-valuenow
+    const fresh = mountCaptcha()
+    const key = (k: string) => fresh.wrapper.find('.g3-slider-captcha__action').trigger('keydown', { key: k })
+
+    await key('ArrowRight')
+    const afterArrow = Number(
+      fresh.wrapper.find('.g3-slider-captcha__action').attributes('aria-valuenow'),
+    )
+    expect(afterArrow).toBeGreaterThan(0)
+    expect(afterArrow).toBeLessThan(100)
+
+    await key('Home')
+    expect(fresh.wrapper.find('.g3-slider-captcha__action').attributes('aria-valuenow')).toBe('0')
+
+    // 连续前进能顶到末端（步长 20px、行程 168px → 9 次足够）
+    for (let i = 0; i < 9; i += 1) await key('ArrowRight')
+    expect(fresh.wrapper.emitted('update:modelValue')?.at(-1)).toEqual([true])
+  })
+
+  it('keyboard=false 时不响应键盘', async () => {
+    const { wrapper, action } = mountCaptcha({ keyboard: false })
+
+    await action.trigger('keydown', { key: 'End' })
+    expect(wrapper.emitted('update:modelValue')).toBeUndefined()
+  })
+})
+
+describe('SliderCaptcha 受控与复位', () => {
+  it('外部置 true 时手柄落到末端；置 false 复位并 emit false', async () => {
+    const { wrapper, action } = mountCaptcha({ modelValue: true })
+
+    await wrapper.vm.$nextTick()
+    await wrapper.vm.$nextTick()
+    expect(action.attributes('aria-valuenow')).toBe('100')
+
+    await wrapper.setProps({ modelValue: false })
+    expect(wrapper.emitted('update:modelValue')?.at(-1)).toEqual([false])
+  })
+
+  it('resume() 从通过态复位并 emit false，之后可再次验证', async () => {
+    const { wrapper, action } = mountCaptcha({ modelValue: true })
+    await wrapper.vm.$nextTick()
+    await wrapper.vm.$nextTick()
+
+    ;(wrapper.vm as unknown as { resume: () => void }).resume()
+    await wrapper.vm.$nextTick()
+
+    expect(wrapper.emitted('update:modelValue')?.at(-1)).toEqual([false])
+    expect(wrapper.classes()).not.toContain('is-passed')
+
+    // 复位之后还能再验证一次
+    dispatchPointer(action.element, 'pointerdown', { clientX: 0 })
+    dispatchPointer(action.element, 'pointermove', { clientX: TRACK_MAX })
+    expect(wrapper.emitted('update:modelValue')?.at(-1)).toEqual([true])
+  })
+})
diff --git a/code/g3soft-libs/packages/ui/src/captcha/SliderCaptcha.vue b/code/g3soft-libs/packages/ui/src/captcha/SliderCaptcha.vue
new file mode 100644
index 00000000..457a818d
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/captcha/SliderCaptcha.vue
@@ -0,0 +1,480 @@
+<script setup lang="ts">
+import { computed, nextTick, onBeforeUnmount, onMounted, ref, watch } from 'vue'
+import { Check, ChevronsRight } from '@lucide/vue'
+import { useComponentDefaults } from '../_composables/useComponentDefaults'
+import { useDirection } from '../_composables/useDirection'
+import { useLocale } from '../_composables/useLocale'
+import { useNamespace } from '../_composables/useNamespace'
+import type { SliderCaptchaDragPayload, SliderCaptchaProps } from './types'
+
+/**
+ * 滑块验证码 —— 按住手柄拖到行内结束端即验证通过。
+ *
+ * 实现要点：
+ * - 拖拽走 **Pointer Events + setPointerCapture**（与 bindDrag / bindResize 同一套），
+ *   指针移出组件、触屏、手写笔都能正确收尾，不需要 document 级监听；
+ * - 位置用逻辑属性 `inset-inline-start`，RTL 下自动从右侧起步；位移量按方向折算
+ *   （`useDirection` 的分工注释里点名的「拖拽」场景）；
+ * - 手柄是 `role="slider"`：← → 微调、Home 复位、End 直达终点，`keyboard` 可关；
+ * - 文案一律走 `useLocale()`，不硬编码；`text` / `successText` 只作覆盖。
+ *
+ * 它不是安全边界：拖拽与键盘都能被脚本模拟，只承担「人为停顿一下」的交互仪式感。
+ */
+defineOptions({ name: 'G3SliderCaptcha' })
+
+const props = withDefaults(defineProps<SliderCaptchaProps>(), {
+  modelValue: false,
+  text: undefined,
+  successText: undefined,
+  disabled: false,
+  size: undefined,
+  keyboard: true,
+})
+
+const emit = defineEmits<{
+  'update:modelValue': [value: boolean]
+  success: [payload: { isPassing: boolean }]
+  start: [event: PointerEvent]
+  move: [payload: SliderCaptchaDragPayload]
+  end: [event: PointerEvent]
+}>()
+
+const { b, e, m, is } = useNamespace('slider-captcha')
+const locale = useLocale()
+const direction = useDirection()
+const merged = useComponentDefaults('slider-captcha', props)
+
+const wrapperRef = ref<HTMLElement | null>(null)
+const actionRef = ref<HTMLElement | null>(null)
+
+/** 手柄在「行内起始方向」上的偏移（px），0 = 起点；通过态固定为行程末端 */
+const offset = ref(0)
+/** 轨道可用行程 = 容器宽 - 手柄宽，每次交互开始时重新量 */
+const trackMax = ref(0)
+/** 容器宽度，仅用于把进度条宽度钳在容器内 */
+const trackWidth = ref(0)
+const isMoving = ref(false)
+/** 初始值直接取 modelValue：外部带着「已验证」状态挂载时不该显示成未验证 */
+const isPassing = ref(props.modelValue)
+/** 回弹 / 键盘跳转期间才启用过渡；拖拽过程必须跟手，不能有过渡 */
+const isReturning = ref(false)
+
+let returnTimer = 0
+let dragStartX = 0
+let dragStartOffset = 0
+
+/** 拖到末端的判定容差（px）：抵住边框、取整误差时不该「差 1px 就不通过」（对照参考实现） */
+const PASS_TOLERANCE = 2
+
+const isRtl = computed(() => direction.value === 'rtl')
+const isDisabled = computed(() => merged.value.disabled)
+const resolvedText = computed(() => merged.value.text ?? locale.value.captcha.slide)
+const resolvedSuccessText = computed(() => merged.value.successText ?? locale.value.captcha.verified)
+/** 0~1 的完成度，映射成 aria-valuenow 的 0~100 */
+const progress = computed(() =>
+  trackMax.value > 0 ? Math.min(1, offset.value / trackMax.value) : 0,
+)
+/** 手柄宽度（正方形，由容器高度决定），同时参与行程与进度条宽度计算 */
+const actionWidth = computed(() => actionRef.value?.getBoundingClientRect().width ?? 0)
+/** 进度条盖住手柄的一半（与「拖到位后条填满到末端」的观感一致） */
+const barWidth = computed(() =>
+  Math.min(trackWidth.value, offset.value + actionWidth.value / 2),
+)
+
+const classes = computed(() => [
+  b(),
+  {
+    [m('small')]: merged.value.size === 'small',
+    [m('large')]: merged.value.size === 'large',
+    [is('disabled')]: isDisabled.value,
+    [is('passed')]: isPassing.value,
+    [is('moving')]: isMoving.value,
+  },
+])
+
+/* ---------------- 尺寸测量 ---------------- */
+function measure(): void {
+  const wrapper = wrapperRef.value
+  if (!wrapper) return
+
+  // clientWidth = padding box：绝对定位的手柄以它为包含块，`inset-inline-start` 的最大值
+  // 就是「padding box 宽 - 手柄宽」。用 border-box 的 rect 宽度会多算两侧边框（各 1px），
+  // 结果是拖到最右仍差 1px 不通过。无布局引擎的环境（happy-dom）clientWidth 为 0，退回 rect。
+  trackWidth.value = wrapper.clientWidth || wrapper.getBoundingClientRect().width
+  trackMax.value = Math.max(0, trackWidth.value - actionWidth.value)
+}
+
+/* ---------------- 状态流转 ---------------- */
+function lockUserSelect(): void {
+  document.body.style.userSelect = 'none'
+  document.body.style.webkitUserSelect = 'none'
+}
+
+function releaseUserSelect(): void {
+  document.body.style.userSelect = ''
+  document.body.style.webkitUserSelect = ''
+}
+
+function checkPass(): void {
+  if (isPassing.value) return
+  isMoving.value = false
+  releaseUserSelect()
+  isPassing.value = true
+  // 吸附到行程末端：判定留了 PASS_TOLERANCE 的容差，视觉上必须真的到位
+  // （否则通过后进度停在 99%、手柄离边框还差 2px）
+  offset.value = trackMax.value
+  emit('update:modelValue', true)
+}
+
+/**
+ * 复位到未验证状态（回弹动画）。
+ *
+ * 只有从「已通过」回退时才 emit false —— 中途松手的回弹不该再对外报一次 false。
+ */
+function resume(): void {
+  isMoving.value = false
+  releaseUserSelect()
+
+  const wasPassing = isPassing.value
+  isPassing.value = false
+  if (wasPassing) emit('update:modelValue', false)
+
+  if (offset.value === 0) return
+  isReturning.value = true
+  nextTick(() => {
+    offset.value = 0
+    window.clearTimeout(returnTimer)
+    returnTimer = window.setTimeout(() => {
+      isReturning.value = false
+    }, 300)
+  })
+}
+
+/** 键盘 / 程序化移动：夹在 [0, trackMax] 内，顶到末端（含容差）即通过 */
+function moveTo(next: number): void {
+  const value = Math.min(Math.max(next, 0), trackMax.value)
+  offset.value = value
+  if (trackMax.value > 0 && value >= trackMax.value - PASS_TOLERANCE) checkPass()
+}
+
+/* ---------------- 拖拽 ---------------- */
+function onPointerDown(event: PointerEvent): void {
+  if (isDisabled.value || isPassing.value || event.button !== 0) return
+
+  measure()
+  if (trackMax.value <= 0) return
+
+  dragStartX = event.clientX
+  dragStartOffset = offset.value
+  isMoving.value = true
+  isReturning.value = false
+  window.clearTimeout(returnTimer)
+  // 捕获指针后，移出组件甚至移出窗口都还能收到 move/up；老环境没有该方法也不影响主流程
+  actionRef.value?.setPointerCapture?.(event.pointerId)
+  event.preventDefault()
+  lockUserSelect()
+  emit('start', event)
+}
+
+function onPointerMove(event: PointerEvent): void {
+  if (!isMoving.value) return
+  if (event.cancelable) event.preventDefault()
+
+  // 行内方向为正：LTR 是「指针右移」，RTL 是「指针左移」
+  const moveDistance = isRtl.value ? dragStartX - event.clientX : event.clientX - dragStartX
+  const next = Math.min(Math.max(dragStartOffset + moveDistance, 0), trackMax.value)
+
+  offset.value = next
+  emit('move', { event, moveDistance, offset: next })
+
+  if (next >= trackMax.value - PASS_TOLERANCE) checkPass()
+}
+
+function finishDrag(event: PointerEvent): void {
+  if (!isMoving.value) return
+
+  isMoving.value = false
+  releaseUserSelect()
+  emit('end', event)
+
+  if (!isPassing.value) resume()
+}
+
+/* ---------------- 键盘 ---------------- */
+function onKeydown(event: KeyboardEvent): void {
+  if (!merged.value.keyboard || isDisabled.value || isPassing.value) return
+
+  measure()
+  if (trackMax.value <= 0) return
+
+  // 屏幕上「向右」恒为前进；RTL 下对应行内方向的反向
+  const forward = isRtl.value ? -1 : 1
+  const step = Math.max(20, Math.round(trackMax.value / 10))
+
+  switch (event.key) {
+    case 'ArrowRight':
+    case 'ArrowUp': {
+      event.preventDefault()
+      moveTo(offset.value + forward * step)
+      break
+    }
+    case 'ArrowLeft':
+    case 'ArrowDown': {
+      event.preventDefault()
+      moveTo(offset.value - forward * step)
+      break
+    }
+    case 'Home': {
+      event.preventDefault()
+      isReturning.value = false
+      offset.value = 0
+      break
+    }
+    case 'End': {
+      event.preventDefault()
+      isReturning.value = false
+      moveTo(trackMax.value)
+      break
+    }
+    default:
+  }
+}
+
+/* ---------------- 受控同步 ---------------- */
+/** 通过态下手柄要停在行程末端；首次挂载还没布局，量不到宽度，等一帧再量 */
+function syncPassedOffset(): void {
+  nextTick(() => {
+    isReturning.value = false
+    measure()
+    offset.value = trackMax.value
+  })
+}
+
+watch(
+  () => props.modelValue,
+  (value) => {
+    if (value === isPassing.value) return
+    if (value) {
+      isPassing.value = true
+      syncPassedOffset()
+    } else {
+      resume()
+    }
+  },
+)
+
+watch(isPassing, (value) => {
+  if (value) emit('success', { isPassing: true })
+})
+
+onMounted(() => {
+  if (isPassing.value) syncPassedOffset()
+})
+
+onBeforeUnmount(() => {
+  window.clearTimeout(returnTimer)
+  releaseUserSelect()
+})
+
+defineExpose({ resume })
+</script>
+
+<template>
+  <div ref="wrapperRef" :class="classes">
+    <div
+      :class="[e('bar'), { [is('returning')]: isReturning, [is('passed')]: isPassing }]"
+      :style="{ width: `${barWidth}px` }"
+      aria-hidden="true"
+    ></div>
+
+    <div :class="[e('text'), { [is('passed')]: isPassing }]" aria-hidden="true">
+      <slot name="text" :is-passing="isPassing">
+        {{ isPassing ? resolvedSuccessText : resolvedText }}
+      </slot>
+    </div>
+
+    <div
+      ref="actionRef"
+      :class="[
+        e('action'),
+        {
+          [is('returning')]: isReturning,
+          [is('passed')]: isPassing,
+          [is('disabled')]: isDisabled,
+        },
+      ]"
+      :style="{ insetInlineStart: `${offset}px` }"
+      role="slider"
+      aria-orientation="horizontal"
+      :aria-label="locale.captcha.sliderLabel"
+      :aria-valuemin="0"
+      :aria-valuemax="100"
+      :aria-valuenow="Math.round(progress * 100)"
+      :aria-valuetext="isPassing ? resolvedSuccessText : resolvedText"
+      :aria-disabled="isDisabled || undefined"
+      :tabindex="isDisabled || isPassing ? -1 : 0"
+      @pointerdown="onPointerDown"
+      @pointermove="onPointerMove"
+      @pointerup="finishDrag"
+      @pointercancel="finishDrag"
+      @keydown="onKeydown"
+    >
+      <slot name="action" :is-passing="isPassing">
+        <Check v-if="isPassing" />
+        <ChevronsRight v-else />
+      </slot>
+    </div>
+  </div>
+</template>
+
+<style lang="scss">
+@use '@g3soft/tokens/scss' as *;
+
+.#{b('slider-captcha')} {
+  position: relative;
+  display: flex;
+  align-items: center;
+  box-sizing: border-box;
+  width: 100%;
+  height: v('control-height', 32px);
+  overflow: hidden;
+  background: v('fill', rgba(0, 0, 0, 0.04));
+  border: 1px solid v('border-color', #d9d9d9);
+  border-radius: v('radius', 6px);
+  user-select: none;
+}
+
+.#{m('slider-captcha', 'small')} {
+  height: v('control-height-sm', 24px);
+}
+
+.#{m('slider-captcha', 'large')} {
+  height: v('control-height-lg', 40px);
+}
+
+/* ---------- 进度条 ---------- */
+.#{e('slider-captcha', 'bar')} {
+  position: absolute;
+  inset-block: 0;
+  /* 逻辑属性：RTL 下从右侧开始铺开 */
+  inset-inline-start: 0;
+  pointer-events: none;
+  background: color-mix(
+    in srgb,
+    v('color-success', hsl(144 57% 58%)) 78%,
+    v('bg-container', #fff)
+  );
+  border-start-start-radius: v('radius', 6px);
+  border-end-start-radius: v('radius', 6px);
+}
+
+/* 只有回弹 / 键盘跳转才启用宽度过渡，拖拽中必须跟手 */
+.#{e('slider-captcha', 'bar')}.#{is('returning')} {
+  transition: width 300ms v('ease', ease);
+}
+
+/* ---------- 提示文字 ---------- */
+.#{e('slider-captcha', 'text')} {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  color: v('text-2', rgba(0, 0, 0, 0.65));
+  font-size: v('font-size', 14px);
+  pointer-events: none;
+}
+
+.#{e('slider-captcha', 'text')}.#{is('passed')} {
+  color: v('text-1', rgba(0, 0, 0, 0.88));
+}
+
+/* ---------- 手柄 ---------- */
+.#{e('slider-captcha', 'action')} {
+  position: absolute;
+  inset-block: 0;
+  inset-inline-start: 0;
+  z-index: 1;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  /* 正方形：宽随高度（高度由容器的 height: 100% 定死） */
+  aspect-ratio: 1;
+  color: v('text-3', rgba(0, 0, 0, 0.45));
+  background: v('bg-container', #fff);
+  border-radius: v('radius', 6px);
+  /* 无边框，只用阴影表现层次（对照 vben 的 shadow-md），拖拽中不出现边框 */
+  box-shadow: v('shadow', 0 2px 8px rgba(0, 0, 0, 0.15));
+  cursor: grab;
+  touch-action: none; /* 移动端不要把手势交给页面滚动 */
+  transition:
+    box-shadow v('duration-fast', 0.1s) v('ease', ease),
+    color v('duration', 0.2s) v('ease', ease);
+
+  svg {
+    /* 图标跟随字号缩放 */
+    width: 1em;
+    height: 1em;
+  }
+}
+
+.#{e('slider-captcha', 'action')}.#{is('returning')} {
+  transition:
+    inset-inline-start 300ms v('ease', ease),
+    box-shadow v('duration-fast', 0.1s) v('ease', ease),
+    color v('duration', 0.2s) v('ease', ease);
+}
+
+.#{e('slider-captcha', 'action')}:hover:not(.#{is('disabled')}) {
+  box-shadow: v('shadow-popup', 0 6px 16px rgba(0, 0, 0, 0.12));
+}
+
+.#{b('slider-captcha')}.#{is('moving')} .#{e('slider-captcha', 'action')} {
+  cursor: grabbing;
+  box-shadow: v('shadow', 0 2px 8px rgba(0, 0, 0, 0.15));
+}
+
+.#{e('slider-captcha', 'action')}:focus-visible {
+  @include focus-ring();
+}
+
+.#{e('slider-captcha', 'action')}.#{is('passed')} {
+  color: v('color-success', hsl(144 57% 58%));
+  cursor: default;
+}
+
+.#{e('slider-captcha', 'action')}.#{is('disabled')} {
+  cursor: not-allowed;
+}
+
+/* 尺寸：字号决定图标大小与提示文案大小 */
+.#{m('slider-captcha', 'small')} {
+  .#{e('slider-captcha', 'action')} {
+    font-size: v('font-size-sm', 12px);
+  }
+
+  .#{e('slider-captcha', 'text')} {
+    font-size: v('font-size-sm', 12px);
+  }
+}
+
+.#{m('slider-captcha', 'large')} {
+  .#{e('slider-captcha', 'action')} {
+    font-size: v('font-size-lg', 16px);
+  }
+}
+
+/* ---------- 禁用态：只禁交互，不压暗（通过后的绿 / 白不该被灰罩住） ---------- */
+.#{b('slider-captcha')}.#{is('disabled')} {
+  cursor: not-allowed;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .#{e('slider-captcha', 'bar')},
+  .#{e('slider-captcha', 'bar')}.#{is('returning')},
+  .#{e('slider-captcha', 'action')},
+  .#{e('slider-captcha', 'action')}.#{is('returning')} {
+    transition-duration: 0ms;
+  }
+}
+</style>
diff --git a/code/g3soft-libs/packages/ui/src/captcha/index.ts b/code/g3soft-libs/packages/ui/src/captcha/index.ts
new file mode 100644
index 00000000..8206c244
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/captcha/index.ts
@@ -0,0 +1,7 @@
+export { default as G3SliderCaptcha } from './SliderCaptcha.vue'
+export type {
+  SliderCaptchaDragPayload,
+  SliderCaptchaExpose,
+  SliderCaptchaProps,
+  SliderCaptchaSize,
+} from './types'
diff --git a/code/g3soft-libs/packages/ui/src/captcha/types.ts b/code/g3soft-libs/packages/ui/src/captcha/types.ts
new file mode 100644
index 00000000..ccb0f1e1
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/captcha/types.ts
@@ -0,0 +1,32 @@
+/** 滑块验证码尺寸，默认 medium。 */
+export type SliderCaptchaSize = 'small' | 'medium' | 'large'
+
+export interface SliderCaptchaProps {
+  /** 是否已验证通过（v-model） */
+  modelValue?: boolean
+  /** 未通过时的提示文案；不传取语言包 */
+  text?: string
+  /** 通过后的文案；不传取语言包 */
+  successText?: string
+  /** 禁用态：不响应拖拽与键盘，但样式不作整体半透明（避免通过后的绿/白被压灰） */
+  disabled?: boolean
+  /** 尺寸 */
+  size?: SliderCaptchaSize
+  /** 是否支持键盘操作（← → 微调、Home 复位、End 直达终点），默认 true */
+  keyboard?: boolean
+}
+
+/** 拖拽过程回传的载荷（仅指针拖拽触发；键盘操作不触发 move）。 */
+export interface SliderCaptchaDragPayload {
+  event: PointerEvent
+  /** 本次按下以来的位移（px，沿「行内方向」为正：LTR 向右、RTL 向左） */
+  moveDistance: number
+  /** 手柄在行内起始方向上的偏移（px），0 = 起点 */
+  offset: number
+}
+
+/** 通过 `ref` 调用的实例方法。 */
+export interface SliderCaptchaExpose {
+  /** 复位到未验证状态（校验失败、重新登录时调用） */
+  resume: () => void
+}
diff --git a/code/g3soft-libs/packages/ui/src/dropdown/Dropdown.test.ts b/code/g3soft-libs/packages/ui/src/dropdown/Dropdown.test.ts
index a11885e1..93d23868 100644
--- a/code/g3soft-libs/packages/ui/src/dropdown/Dropdown.test.ts
+++ b/code/g3soft-libs/packages/ui/src/dropdown/Dropdown.test.ts
@@ -45,6 +45,38 @@ async function openDropdown(wrapper: ReturnType<typeof mountDropdown>) {
   return lastMenu()
 }
 
+describe('Dropdown 菜单面板高度', () => {
+  /**
+   * 回归：上限原本是写死的 256px，只够放 8 个菜单项，10 项的操作菜单会在面板内部出滚动条
+   * （富文本「更多」菜单 295px 即如此）。现在默认按视口算（`--g3-dropdown-max-height`，
+   * 兜底 `calc(100vh - 48px)`），不传 prop 时不写内联样式。
+   */
+  it('不传 menuMaxHeight：不写内联上限，交给 CSS 变量（默认按视口）', async () => {
+    const wrapper = mountDropdown(DECLARATIVE)
+    const menu = await openDropdown(wrapper)
+    expect(menu!.style.maxHeight).toBe('')
+  })
+
+  it('menuMaxHeight：false 不限制、数字按 px、字符串原样', async () => {
+    // 逐个挂载：避免在 vm 上改联合类型属性（类型推断会退化成 never）
+    const menuMaxHeightOf = async (attr: string) => {
+      const wrapper = mountDropdown(`
+        <G3Dropdown ${attr}>
+          <template #trigger><button class="trigger">菜单</button></template>
+          <G3DropdownItem item-key="edit">编辑</G3DropdownItem>
+        </G3Dropdown>
+      `)
+      return (await openDropdown(wrapper))!.style.maxHeight
+    }
+
+    expect(await menuMaxHeightOf(':menu-max-height="false"')).toBe('none')
+    expect(await menuMaxHeightOf(':menu-max-height="320"')).toBe('320px')
+    expect(await menuMaxHeightOf(":menu-max-height=\"'min(480px, 70vh)'\"")).toBe(
+      'min(480px, 70vh)',
+    )
+  })
+})
+
 describe('Dropdown 声明式子项', () => {
   it('插槽文本会作为菜单文案渲染（不再出现空白项）', async () => {
     const wrapper = mountDropdown(DECLARATIVE)
diff --git a/code/g3soft-libs/packages/ui/src/dropdown/Dropdown.vue b/code/g3soft-libs/packages/ui/src/dropdown/Dropdown.vue
index 7d72e2fd..cdac0885 100644
--- a/code/g3soft-libs/packages/ui/src/dropdown/Dropdown.vue
+++ b/code/g3soft-libs/packages/ui/src/dropdown/Dropdown.vue
@@ -4,7 +4,12 @@ import { useNamespace } from '../_composables/useNamespace'
 import G3Popover from '../popover/Popover.vue'
 import G3DropdownItem from './DropdownItem.vue'
 import G3DropdownMenu from './DropdownMenu.vue'
-import { dropdownActiveIndexKey, dropdownSelectKey } from './context'
+import {
+  dropdownActiveIndexKey,
+  dropdownMenuMaxHeightKey,
+  dropdownScopeKey,
+  dropdownSelectKey,
+} from './context'
 import type { DropdownClickPayload, DropdownItemData, DropdownProps } from './types'
 
 /**
@@ -25,6 +30,12 @@ const props = withDefaults(defineProps<DropdownProps>(), {
   mouseLeaveDelay: 200,
   offset: 4,
   unwrapped: true,
+  /**
+   * 必须显式声明 default：`menuMaxHeight` 的类型里含 `boolean`，而 Vue 对「类型含 Boolean
+   * 且没声明 default」的 prop 会把缺省值转成 `false` —— 那正好是「不限制」，默认行为就被改掉了。
+   * 声明 default: undefined 后，缺省值才是 undefined（= 用 `--g3-dropdown-max-height`）。
+   */
+  menuMaxHeight: undefined,
 })
 
 const emit = defineEmits<{
@@ -249,8 +260,34 @@ function onMenuKeydown(event: KeyboardEvent) {
 }
 
 /* ---------- 注入给菜单 / 子菜单 ---------- */
+/**
+ * 浮层链标识：根面板与各级子菜单共用，让「点子菜单项」不被当成点击外部
+ * （详见 context.ts 与 useFloating 的 popupScope 注释）。
+ * 用模块级自增保证同页多个 Dropdown 之间互不串链。
+ */
+let scopeSeed = 0
+const popupScope = `g3-dropdown-${++scopeSeed}`
+
+/**
+ * 面板最大高度：prop 归一成 CSS 值（空串 = 交给 `--g3-dropdown-max-height`），根面板与子菜单共用。
+ * - `false` → `none`：不限制；
+ * - 数字 → px；字符串 → 原样。
+ */
+const menuMaxHeightValue = computed(() => {
+  const value = props.menuMaxHeight
+  if (value == null || value === true) return ''
+  if (value === false) return 'none'
+  return typeof value === 'number' ? `${value}px` : value
+})
+
+const menuStyle = computed(() =>
+  menuMaxHeightValue.value ? { maxHeight: menuMaxHeightValue.value } : undefined,
+)
+
 provide(dropdownSelectKey, selectItem)
 provide(dropdownActiveIndexKey, activeIndex)
+provide(dropdownScopeKey, popupScope)
+provide(dropdownMenuMaxHeightKey, menuMaxHeightValue)
 </script>
 
 <template>
@@ -264,6 +301,7 @@ provide(dropdownActiveIndexKey, activeIndex)
     :unwrapped="unwrapped"
     :mouse-enter-delay="mouseEnterDelay"
     :mouse-leave-delay="mouseLeaveDelay"
+    :popup-scope="popupScope"
     @update:open="onOpenChange"
   >
     <!-- 触发器：#trigger 具名插槽优先，未传时回退默认插槽 -->
@@ -275,6 +313,7 @@ provide(dropdownActiveIndexKey, activeIndex)
       <div
         ref="menuEl"
         :class="e('menu')"
+        :style="menuStyle"
         role="menu"
         tabindex="-1"
         @keydown="onMenuKeydown"
@@ -299,7 +338,14 @@ provide(dropdownActiveIndexKey, activeIndex)
   flex-direction: column;
   box-sizing: border-box;
   min-width: v('dropdown-min-width', 180px);
-  max-height: v('dropdown-max-height', 256px);
+  /**
+   * 上限按视口算，而不是写死一个魔法数。
+   *
+   * 原来兜底是 256px —— 只够放 8 个菜单项，10 项的操作菜单就会在面板内部出滚动条
+   * （富文本的「更多」菜单 295px 就是这么滚起来的）。改成「长到屏幕放不下才滚」：
+   * 短菜单不再无谓地滚，长菜单也不会顶出视口。需要按实例收紧/放开时用 `menuMaxHeight`。
+   */
+  max-height: v('dropdown-max-height', calc(100vh - 48px));
   overflow: auto;
   padding: v('space-1', 4px);
   outline: none;
diff --git a/code/g3soft-libs/packages/ui/src/dropdown/DropdownMenu.vue b/code/g3soft-libs/packages/ui/src/dropdown/DropdownMenu.vue
index 940c0fd9..b1c45779 100644
--- a/code/g3soft-libs/packages/ui/src/dropdown/DropdownMenu.vue
+++ b/code/g3soft-libs/packages/ui/src/dropdown/DropdownMenu.vue
@@ -1,9 +1,14 @@
 <script setup lang="ts">
-import { inject, isVNode, provide, ref, type Ref, type VNode } from 'vue'
+import { computed, inject, isVNode, provide, ref, type Ref, type VNode } from 'vue'
 import { ChevronRight } from '@lucide/vue'
 import { useNamespace } from '../_composables/useNamespace'
 import G3Popover from '../popover/Popover.vue'
-import { dropdownActiveIndexKey, dropdownSelectKey } from './context'
+import {
+  dropdownActiveIndexKey,
+  dropdownMenuMaxHeightKey,
+  dropdownScopeKey,
+  dropdownSelectKey,
+} from './context'
 import type { DropdownItemData } from './types'
 
 /**
@@ -25,6 +30,14 @@ const { b, e, m, is } = useNamespace('dropdown')
 
 const selectItem = inject(dropdownSelectKey, null)
 const injectedActiveIndex = inject(dropdownActiveIndexKey, null)
+/** 同一条浮层链的标识：子菜单面板要带上，否则点击子项会被父浮层当成外部点击 */
+const popupScope = inject(dropdownScopeKey, '')
+/** 根面板的最大高度：子菜单面板沿用（否则仍在 256px 处出滚动条） */
+const injectedMenuMaxHeight = inject(dropdownMenuMaxHeightKey, null)
+const submenuStyle = computed(() => {
+  const value = injectedMenuMaxHeight?.value
+  return value ? { maxHeight: value } : undefined
+})
 
 /**
  * 本层生效的高亮索引（Ref<number>）。
@@ -91,6 +104,7 @@ const VNodeRenderer = (renderProps: { node: VNode }) => renderProps.node
       :offset="0"
       :arrow="false"
       unwrapped
+      :popup-scope="popupScope || undefined"
     >
       <template #trigger>
         <span
@@ -116,7 +130,7 @@ const VNodeRenderer = (renderProps: { node: VNode }) => renderProps.node
         </span>
       </template>
       <template #content>
-        <div :class="e('menu')" role="menu" @mouseleave="clearActive">
+        <div :class="e('menu')" :style="submenuStyle" role="menu" @mouseleave="clearActive">
           <G3DropdownMenu :items="item.children" :interactive="false" />
         </div>
       </template>
diff --git a/code/g3soft-libs/packages/ui/src/dropdown/DropdownSubmenu.test.ts b/code/g3soft-libs/packages/ui/src/dropdown/DropdownSubmenu.test.ts
index 3cd4477b..bad0df86 100644
--- a/code/g3soft-libs/packages/ui/src/dropdown/DropdownSubmenu.test.ts
+++ b/code/g3soft-libs/packages/ui/src/dropdown/DropdownSubmenu.test.ts
@@ -101,6 +101,49 @@ describe('子菜单 hover 高亮', () => {
     expect(rows[1].className).toContain('is-item-active')
   })
 
+  it('点击子菜单项：执行该项并关闭整条链（不被父浮层当成外部点击）', async () => {
+    const clicked: string[] = []
+    const wrapper = mount({
+      components: { G3Dropdown },
+      data() {
+        return {
+          items: [
+            {
+              key: 'more',
+              label: '更多',
+              children: [
+                { key: 'c1', label: '子项一', onClick: () => clicked.push('c1') },
+                { key: 'c2', label: '子项二', onClick: () => clicked.push('c2') },
+              ],
+            },
+          ],
+        }
+      },
+      template: `
+        <G3Dropdown trigger="click" :items="items">
+          <template #trigger><button class="trigger">菜单</button></template>
+        </G3Dropdown>
+      `,
+    })
+
+    await wrapper.find('.trigger').trigger('click')
+    await nextTick()
+    itemsIn(menus()[0])[0].dispatchEvent(new MouseEvent('mouseenter', { bubbles: true }))
+    await settle()
+    expect(menus().length).toBe(2)
+
+    // 回归：useFloating 在 document 的 pointerdown 捕获阶段判「点在外面」，而子菜单面板
+    // Teleport 到 body、不在父面板里 —— 没有 popupScope 时父浮层会先关掉，click 永远收不到。
+    const child = itemsIn(menus()[1])[0]
+    child.dispatchEvent(new PointerEvent('pointerdown', { bubbles: true }))
+    child.dispatchEvent(new MouseEvent('click', { bubbles: true }))
+    await settle()
+
+    expect(clicked).toEqual(['c1'])
+    // 选中后整条链收起
+    expect(menus().length).toBe(0)
+  })
+
   it('根层键盘导航仍然生效（未被自持索引改坏）', async () => {
     const wrapper = mount({
       components: { G3Dropdown },
diff --git a/code/g3soft-libs/packages/ui/src/dropdown/context.ts b/code/g3soft-libs/packages/ui/src/dropdown/context.ts
index 15f0ccd2..3e2c3132 100644
--- a/code/g3soft-libs/packages/ui/src/dropdown/context.ts
+++ b/code/g3soft-libs/packages/ui/src/dropdown/context.ts
@@ -1,4 +1,4 @@
-import type { InjectionKey, Ref } from 'vue'
+import type { ComputedRef, InjectionKey, Ref } from 'vue'
 import type { DropdownItemData } from './types'
 
 /** 主 Dropdown 注入给菜单 / 子菜单的选中回调 */
@@ -20,3 +20,22 @@ export const dropdownSelectKey: InjectionKey<((item: DropdownItemData) => void)
 export const dropdownActiveIndexKey: InjectionKey<Ref<number> | null> = Symbol(
   'g3-dropdown-active',
 )
+
+/**
+ * 同一条浮层链的标识（Popover 的 popupScope）：根面板与各级子菜单共用同一个值。
+ *
+ * 没有它子菜单就用不了鼠标：子菜单面板 Teleport 到 body，useFloating 在 document 的
+ * pointerdown 捕获阶段判定「点在外面」→ 根下拉先关闭 → 子项的 click 永远不触发
+ * （键盘路径同理失效）。带上同一个 scope 后，点子菜单项不再算外部点击。
+ */
+export const dropdownScopeKey: InjectionKey<string> = Symbol('g3-dropdown-scope')
+
+/**
+ * 菜单面板的最大高度（CSS 值字符串，空串 = 用默认的 `--g3-dropdown-max-height`）。
+ *
+ * 子菜单面板同样由 `.g3-dropdown__menu` 渲染、也走同一个 256px 上限 —— 字体那类
+ * 8 项的二级菜单就正好卡在边界上，加一项就出滚动条。所以根面板与子菜单统一取这个值。
+ */
+export const dropdownMenuMaxHeightKey: InjectionKey<ComputedRef<string>> = Symbol(
+  'g3-dropdown-menu-max-height',
+)
diff --git a/code/g3soft-libs/packages/ui/src/dropdown/types.ts b/code/g3soft-libs/packages/ui/src/dropdown/types.ts
index 73a5a65f..2314e7ad 100644
--- a/code/g3soft-libs/packages/ui/src/dropdown/types.ts
+++ b/code/g3soft-libs/packages/ui/src/dropdown/types.ts
@@ -60,4 +60,17 @@ export interface DropdownProps {
   offset?: number
   /** 零包裹模式（默认开启）：把事件注入到触发器单根 vnode，不再包 span */
   unwrapped?: boolean
+  /**
+   * 菜单面板的最大高度（超出才滚动）。默认按视口算：`--g3-dropdown-max-height`，
+   * 兜底 `calc(100vh - 48px)` —— 菜单随内容长，长到屏幕放不下才滚，短菜单不会无谓地滚。
+   *
+   * - 不传 / `true`：用默认上限；
+   * - `false`：不限制（面板随内容撑开，只在确定菜单很短时用，否则会超出视口）；
+   * - `number`：按 px；
+   * - `string`：原样 CSS 值，如 `'320px'`、`'min(480px, 70vh)'`。
+   *
+   * 为什么要这个 prop：菜单面板 Teleport 到 body，不在调用方 DOM 里，调用方没法用
+   * CSS 局部覆盖那个变量。子菜单面板沿用同一个值。
+   */
+  menuMaxHeight?: boolean | number | string
 }
diff --git a/code/g3soft-libs/packages/ui/src/form/FormItem.vue b/code/g3soft-libs/packages/ui/src/form/FormItem.vue
index 6387d731..c8ff546f 100644
--- a/code/g3soft-libs/packages/ui/src/form/FormItem.vue
+++ b/code/g3soft-libs/packages/ui/src/form/FormItem.vue
@@ -245,6 +245,10 @@ onBeforeUnmount(() => {
 
 .#{m('form-item', 'vertical')} {
   flex-direction: column;
+  /* 纵向布局下 label / 控件各占一行，必须重置基础类的 align-items: flex-start ——
+     基础类是为横向布局（label 在左、控件在右）写的，纵向时不重置会让控件区按内容宽度
+     收缩，输入框只有十几个字符宽（登录页踩到过）。 */
+  align-items: stretch;
   gap: v('space-1', 4px);
 }
 
diff --git a/code/g3soft-libs/packages/ui/src/index.ts b/code/g3soft-libs/packages/ui/src/index.ts
index 377e1b67..68d92f89 100644
--- a/code/g3soft-libs/packages/ui/src/index.ts
+++ b/code/g3soft-libs/packages/ui/src/index.ts
@@ -5,8 +5,10 @@ import { setBaseZIndex } from './_utils/z-index'
 import './_styles/rtl.scss'
 
 // ---------------- 组件 ----------------
+import { G3Attachment } from './attachment'
 import { G3Button } from './button'
 import { G3ButtonGroup, G3ButtonGroupSeparator } from './button-group'
+import { G3SliderCaptcha } from './captcha'
 import { G3Checkbox } from './checkbox'
 import { G3ColorPicker } from './color-picker'
 import { G3CalendarPanel, G3DatePicker, G3RangePicker, G3TimeSelect } from './date'
@@ -21,6 +23,8 @@ import { G3NotificationContainer } from './notification'
 import { G3Pagination } from './pagination'
 import { G3Popover } from './popover'
 import { G3Radio, G3RadioGroup } from './radio'
+import { G3Result } from './result'
+import { G3RichText } from './rich-text'
 import { G3Scrollbar } from './scrollbar'
 import { G3Segmented } from './segmented'
 import { G3Select } from './select'
@@ -33,8 +37,10 @@ import { G3Tag } from './tag'
 import { G3Tooltip } from './tooltip'
 import { G3Tree } from './tree'
 
+export * from './attachment'
 export * from './button'
 export * from './button-group'
+export * from './captcha'
 export * from './checkbox'
 export * from './color-picker'
 export * from './date'
@@ -49,6 +55,8 @@ export * from './notification'
 export * from './pagination'
 export * from './popover'
 export * from './radio'
+export * from './result'
+export * from './rich-text'
 export * from './scrollbar'
 export * from './segmented'
 export * from './select'
@@ -117,6 +125,7 @@ export type { Locale } from './locale'
 export interface G3UIOptions extends GlobalConfig {}
 
 const components = {
+  G3Attachment,
   G3Button,
   G3ButtonGroup,
   G3ButtonGroupSeparator,
@@ -140,10 +149,13 @@ const components = {
   G3Radio,
   G3RadioGroup,
   G3RangePicker,
+  G3Result,
+  G3RichText,
   G3Row,
   G3Scrollbar,
   G3Segmented,
   G3Select,
+  G3SliderCaptcha,
   G3Space,
   G3Spin,
   G3Splitter,
diff --git a/code/g3soft-libs/packages/ui/src/locale/index.ts b/code/g3soft-libs/packages/ui/src/locale/index.ts
index 12c87804..a6c99b98 100644
--- a/code/g3soft-libs/packages/ui/src/locale/index.ts
+++ b/code/g3soft-libs/packages/ui/src/locale/index.ts
@@ -61,6 +61,53 @@ export interface Locale {
     max: string
     invalid: string
   }
+  /** 验证码类组件文案。 */
+  captcha: {
+    /** 滑块验证：未通过时的提示 */
+    slide: string
+    /** 滑块验证：通过后的文案 */
+    verified: string
+    /** 滑块验证：手柄的可访问名称（读屏 / 键盘聚焦时播报） */
+    sliderLabel: string
+  }
+  /**
+   * 附件管理器文案，`{count}` / `{name}` / `{size}` 为占位符。
+   */
+  attachment: {
+    allCategory: string
+    selectAll: string
+    selected: string
+    select: string
+    upload: string
+    download: string
+    remove: string
+    preview: string
+    pending: string
+    pendingCount: string
+    total: string
+    empty: string
+    emptyHint: string
+    limitAccept: string
+    limitSize: string
+    limitCount: string
+    dropHint: string
+    previewEmpty: string
+    prev: string
+    next: string
+    removeConfirm: string
+    removeConfirmSingle: string
+    invalidAccept: string
+    invalidMaxSize: string
+    invalidMaxCount: string
+  }
+  /** 结果 / 缺省页文案（403 / 404 / 500 / 离线 / 空状态）。 */
+  result: {
+    '403': { title: string; desc: string }
+    '404': { title: string; desc: string }
+    '500': { title: string; desc: string }
+    offline: { title: string; desc: string }
+    empty: { title: string; desc: string }
+  }
 }
 
 export const zhCN: Locale = {
@@ -119,6 +166,60 @@ export const zhCN: Locale = {
     max: '{label}长度不能超过 {max}',
     invalid: '{label}校验未通过',
   },
+  captcha: {
+    slide: '按住滑块拖动',
+    verified: '验证通过',
+    sliderLabel: '滑动验证',
+  },
+  attachment: {
+    allCategory: '全部',
+    selectAll: '全选',
+    selected: '已选 {count} 项',
+    select: '选择',
+    upload: '上传',
+    download: '下载',
+    remove: '删除',
+    preview: '预览',
+    pending: '待上传',
+    pendingCount: '待上传 {count} 个',
+    total: '共 {count} 个文件',
+    empty: '暂无文件',
+    emptyHint: '拖拽文件到此处，或点击选择',
+    limitAccept: '支持格式：{accept}',
+    limitSize: '单个文件不超过 {size}',
+    limitCount: '最多 {count} 个待上传',
+    dropHint: '释放文件到此处',
+    previewEmpty: '选择文件查看预览',
+    prev: '上一个',
+    next: '下一个',
+    removeConfirm: '确定删除选中的 {count} 个文件？',
+    removeConfirmSingle: '确定删除「{name}」？',
+    invalidAccept: '「{name}」类型不支持',
+    invalidMaxSize: '「{name}」超过大小限制（{size}）',
+    invalidMaxCount: '待上传文件最多 {count} 个',
+  },
+  result: {
+    '403': {
+      title: '无权访问',
+      desc: '你没有访问该页面的权限，请联系管理员',
+    },
+    '404': {
+      title: '页面不存在',
+      desc: '你访问的页面不存在或已被移除',
+    },
+    '500': {
+      title: '页面出错了',
+      desc: '服务暂时不可用，请稍后重试',
+    },
+    offline: {
+      title: '网络已断开',
+      desc: '请检查网络连接后重试',
+    },
+    empty: {
+      title: '暂无数据',
+      desc: '',
+    },
+  },
 }
 
 export const enUS: Locale = {
@@ -176,4 +277,58 @@ export const enUS: Locale = {
     max: '{label} length must be at most {max}',
     invalid: '{label} failed validation',
   },
+  captcha: {
+    slide: 'Slide to verify',
+    verified: 'Verified',
+    sliderLabel: 'Slide verification',
+  },
+  attachment: {
+    allCategory: 'All',
+    selectAll: 'Select all',
+    selected: '{count} selected',
+    select: 'Choose',
+    upload: 'Upload',
+    download: 'Download',
+    remove: 'Delete',
+    preview: 'Preview',
+    pending: 'Pending',
+    pendingCount: '{count} pending',
+    total: '{count} files',
+    empty: 'No files',
+    emptyHint: 'Drop files here, or click to choose',
+    limitAccept: 'Accepted: {accept}',
+    limitSize: 'Up to {size} per file',
+    limitCount: 'At most {count} pending',
+    dropHint: 'Drop files here',
+    previewEmpty: 'Select a file to preview',
+    prev: 'Previous',
+    next: 'Next',
+    removeConfirm: 'Delete the {count} selected files?',
+    removeConfirmSingle: 'Delete "{name}"?',
+    invalidAccept: '"{name}" is not an accepted file type',
+    invalidMaxSize: '"{name}" exceeds the size limit ({size})',
+    invalidMaxCount: 'At most {count} pending files',
+  },
+  result: {
+    '403': {
+      title: 'Access Denied',
+      desc: 'You do not have permission to view this page. Please contact an administrator.',
+    },
+    '404': {
+      title: 'Page Not Found',
+      desc: 'The page you visited does not exist or has been removed',
+    },
+    '500': {
+      title: 'Something Went Wrong',
+      desc: 'The service is temporarily unavailable. Please try again later.',
+    },
+    offline: {
+      title: 'You Are Offline',
+      desc: 'Please check your network connection and try again',
+    },
+    empty: {
+      title: 'No Data',
+      desc: '',
+    },
+  },
 }
diff --git a/code/g3soft-libs/packages/ui/src/popover/Popover.vue b/code/g3soft-libs/packages/ui/src/popover/Popover.vue
index 45257dd6..ce177423 100644
--- a/code/g3soft-libs/packages/ui/src/popover/Popover.vue
+++ b/code/g3soft-libs/packages/ui/src/popover/Popover.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import { computed, nextTick, onBeforeUnmount, ref, useSlots, watch } from 'vue'
-import { useFloating } from '../_composables/useFloating'
+import { POPUP_SCOPE_ATTR, useFloating } from '../_composables/useFloating'
 import { useNamespace } from '../_composables/useNamespace'
 import { usePopupContainer } from '../_composables/usePopupContainer'
 import { useUnwrappedTrigger } from '../_composables/useUnwrappedTrigger'
@@ -30,6 +30,7 @@ const props = withDefaults(defineProps<PopoverProps>(), {
   followTriggerWidth: false,
   unwrapped: false,
   popupContainer: undefined,
+  popupScope: undefined,
 })
 
 const emit = defineEmits<{
@@ -64,6 +65,7 @@ const { floatingRef, floatingStyle, resolvedPlacement, resolvedBase, updatePosit
   followTriggerWidth: () => props.followTriggerWidth,
   triggerRef: triggerEl,
   anchor: () => pointAnchor,
+  popupScope: () => props.popupScope,
   onClickOutside: () => setOpen(false),
   onEscape: () => setOpen(false),
 })
@@ -226,6 +228,7 @@ onBeforeUnmount(() => {
           { [is('follow-trigger-width')]: followTriggerWidth, [is('unwrapped')]: !!injectedTrigger },
         ]"
         :style="popupStyle"
+        :[POPUP_SCOPE_ATTR]="popupScope || undefined"
         role="dialog"
         @mouseenter="onMouseEnter"
         @mouseleave="onMouseLeave"
diff --git a/code/g3soft-libs/packages/ui/src/popover/types.ts b/code/g3soft-libs/packages/ui/src/popover/types.ts
index b8b9055e..b913ddf2 100644
--- a/code/g3soft-libs/packages/ui/src/popover/types.ts
+++ b/code/g3soft-libs/packages/ui/src/popover/types.ts
@@ -31,4 +31,12 @@ export interface PopoverProps {
   unwrapped?: boolean
   /** 弹层挂载容器；不传时取 ConfigProvider.popupContainer，再退回 body */
   popupContainer?: PopupContainer
+  /**
+   * 同一条浮层链的标识：链上所有浮层（父面板 + 子菜单面板）传同一个值，
+   * 点击链内任意面板都不会被当成「点击外部」。
+   *
+   * 场景：Dropdown 的子菜单面板 Teleport 到 body，不在父面板 DOM 里，
+   * 若不声明同一条链，鼠标点子菜单项时父浮层会先关闭，子项的 click 收不到。
+   */
+  popupScope?: string
 }
diff --git a/code/g3soft-libs/packages/ui/src/result/Result.vue b/code/g3soft-libs/packages/ui/src/result/Result.vue
new file mode 100644
index 00000000..b3e72121
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/result/Result.vue
@@ -0,0 +1,150 @@
+<script setup lang="ts">
+import { computed, defineAsyncComponent, type Component } from 'vue'
+import { useNamespace } from '../_composables/useNamespace'
+import { useLocale } from '../_composables/useLocale'
+import IconOffline from './icons/IconOffline.vue'
+import type { ResultProps, ResultStatus } from './types'
+
+/**
+ * Result 结果页 —— 缺省页 / 空状态的通用壳。
+ *
+ * 边界（重要）：本组件只管「图标 + 标题 + 描述 + 操作区」的**呈现**，
+ * 【不碰路由、不碰业务】。所以：
+ *   - 「返回首页 / 重新加载」这类操作由调用方通过 #extra 插槽自备，
+ *     组件不知道也不该知道首页在哪、要不要刷新。
+ *   - 403 / 404 / 500 / offline 只是「预设的插图 + 默认文案」，
+ *     文案走 locale、插图是内置资源，都不含任何应用约定。
+ *
+ * 这就是它属于组件库、而应用侧的 FallbackPage 不属于的原因：
+ * 前者是纯 UI，后者才知道自己的路由结构。
+ */
+defineOptions({ name: 'G3Result' })
+
+const props = withDefaults(defineProps<ResultProps>(), {
+  status: undefined,
+  title: undefined,
+  desc: undefined,
+  align: 'center',
+})
+
+const { b, e, m } = useNamespace('result')
+const locale = useLocale()
+
+/**
+ * 插图：按状态取用。
+ *
+ * ⚠️ 注意 offline 与其他四个的【加载方式必须不同】—— 这是踩过的坑：
+ *
+ *   403 / 404 / 500 / empty 用 defineAsyncComponent 懒加载：
+ *     四张插图合计约 50KB，而任一页面通常只用一张。静态 import 会让
+ *     任何用到 G3Result 的页面把四张全打进自己的 chunk；懒加载后各成一块，
+ *     按需下载（实测产物：Icon404 24.7KB / Icon403 9.4KB / Icon500 7.1KB）。
+ *
+ *   offline 【必须静态 import，不能懒加载】：
+ *     离线页出现的时刻，网络【已经断了】。此时再去 import 它的插图 chunk
+ *     必然失败 —— 实测表现为图标区渲染成空注释节点 <!---->，只剩文字与按钮。
+ *     所以它必须随组件本体一起加载，保证断网时立刻可显示。
+ *     代价是这 8.7KB 会进主包，值得。
+ */
+const ICONS: Record<ResultStatus, Component> = {
+  '403': defineAsyncComponent(() => import('./icons/Icon403.vue')),
+  '404': defineAsyncComponent(() => import('./icons/Icon404.vue')),
+  '500': defineAsyncComponent(() => import('./icons/Icon500.vue')),
+  offline: IconOffline,
+  empty: defineAsyncComponent(() => import('./icons/IconEmpty.vue')),
+}
+
+const icon = computed(() => (props.status ? ICONS[props.status] : null))
+
+/** 标题 / 描述：显式传入优先，否则回退到 status 对应的 locale 文案 */
+const preset = computed(() => (props.status ? locale.value.result[props.status] : undefined))
+const titleText = computed(() => props.title ?? preset.value?.title ?? '')
+const descText = computed(() => props.desc ?? preset.value?.desc ?? '')
+
+const classes = computed(() => [b(), m(props.align)])
+</script>
+
+<template>
+  <div :class="classes" data-slot="result">
+    <!-- 图标区：#icon 插槽优先（纯自定义形态），否则用 status 的内置插图 -->
+    <div :class="e('icon')">
+      <slot name="icon">
+        <component :is="icon" v-if="icon" />
+      </slot>
+    </div>
+
+    <h1 v-if="titleText" :class="e('title')">{{ titleText }}</h1>
+    <p v-if="descText" :class="e('desc')">{{ descText }}</p>
+
+    <!-- 默认插槽：描述与操作之间的自由内容（如额外的错误码、排查建议） -->
+    <div v-if="$slots.default" :class="e('content')">
+      <slot />
+    </div>
+
+    <!-- 操作区：调用方自备按钮（组件不猜「跳到哪」） -->
+    <div v-if="$slots.extra" :class="e('extra')">
+      <slot name="extra" />
+    </div>
+  </div>
+</template>
+
+<style lang="scss">
+@use '@g3soft/tokens/scss' as *;
+
+.#{b('result')} {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  min-height: 100%;
+  padding: v('space-6', 24px);
+  text-align: center;
+}
+
+/* 左对齐形态：嵌在卡片里的空状态用，避免大片居中留白 */
+.#{m('result', 'start')} {
+  align-items: flex-start;
+  text-align: left;
+}
+
+.#{e('result', 'icon')} {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+
+  /* 插图自适应：窄屏不溢出，宽屏不过分放大 */
+  svg {
+    width: clamp(200px, 30vw, 380px);
+    height: auto;
+  }
+}
+
+.#{e('result', 'title')} {
+  margin: v('space-6', 24px) 0 0;
+  font-size: v('font-size-xl', 22px);
+  font-weight: 600;
+  color: v('text-1', rgba(0, 0, 0, 0.88));
+}
+
+.#{e('result', 'desc')} {
+  margin: v('space-2', 8px) 0 v('space-5', 20px);
+  font-size: v('font-size', 14px);
+  color: v('text-3', rgba(0, 0, 0, 0.45));
+}
+
+.#{e('result', 'content')} {
+  margin-bottom: v('space-5', 20px);
+  color: v('text-2', rgba(0, 0, 0, 0.65));
+}
+
+.#{e('result', 'extra')} {
+  display: flex;
+  align-items: center;
+  gap: v('space-2', 8px);
+}
+
+/* 插图为固定浅灰系（原图无深色适配），深色下压一档透明度融入背景 */
+.dark .#{e('result', 'icon')} {
+  opacity: 0.75;
+}
+</style>
diff --git a/code/g3soft-libs/packages/ui/src/result/icons/Icon403.vue b/code/g3soft-libs/packages/ui/src/result/icons/Icon403.vue
new file mode 100644
index 00000000..4c29109a
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/result/icons/Icon403.vue
@@ -0,0 +1,133 @@
+<template>
+  <svg
+    height="659.29778"
+    viewBox="0 0 586 659.29778"
+    width="586"
+    xmlns="http://www.w3.org/2000/svg"
+    xmlns:xlink="http://www.w3.org/1999/xlink"
+  >
+    <circle cx="332.47856" cy="254" fill="#f2f2f2" r="254.00001" />
+    <path
+      d="M498.46363,113.58835H33.17063c-.99774-.02133-1.78931-.84746-1.76797-1.84521,.02069-.96771,.80026-1.74727,1.76797-1.76796H498.46363c.99774,.02133,1.78931,.84746,1.76794,1.84521-.02069,.96771-.80023,1.74727-1.76794,1.76796Z"
+      fill="#cacaca"
+    />
+    <rect
+      fill="#fff"
+      height="34.98639"
+      rx="17.49318"
+      ry="17.49318"
+      width="163.61147"
+      x="193.77441"
+      y="174.47256"
+    />
+    <path
+      d="M128.17493,244.44534H422.98542c9.66122,0,17.49316,7.83197,17.49316,17.49319h0c0,9.66122-7.83194,17.49319-17.49316,17.49319H128.17493c-9.66122,0-17.49318-7.83197-17.49318-17.49319h0c0-9.66122,7.83196-17.49319,17.49318-17.49319Z"
+      fill="#fff"
+    />
+    <path
+      d="M128.17493,314.41812H422.98542c9.66122,0,17.49316,7.83197,17.49316,17.49319h0c0,9.66122-7.83194,17.49319-17.49316,17.49319H128.17493c-9.66122,0-17.49318-7.83197-17.49318-17.49319h0c0-9.66122,7.83196-17.49319,17.49318-17.49319Z"
+      fill="#fff"
+    />
+    <path
+      d="M91.64085,657.75932l-.69385-.06793c-23.54068-2.42871-44.82135-15.08929-58.18845-34.61835-3.66138-5.44159-6.62299-11.32251-8.815-17.50409l-.21069-.58966,.62375-.05048c7.44699-.59924,15.09732-1.86292,18.49585-2.46417l-21.91473-7.42511-.1355-.65033c-1.29926-6.10406,1.24612-12.38458,6.4285-15.86176,5.19641-3.64447,12.08731-3.76111,17.40405-.29449,2.38599,1.52399,4.88162,3.03339,7.29489,4.49359,8.29321,5.01636,16.8688,10.20337,23.29828,17.30121,9.74951,10.97778,14.02298,25.76984,11.63,40.25562l4.7829,17.47595Z"
+      fill="#f2f2f2"
+    />
+    <polygon
+      fill="#a0616a"
+      points="171.30016 646.86102 182.10017 646.85999 187.23916 605.198 171.29716 605.19897 171.30016 646.86102"
+    />
+    <path
+      d="M170.9192,658.12816l33.21436-.00122v-.41998c-.00049-7.13965-5.78833-12.92737-12.92798-12.92773h-.00079l-6.06702-4.60278-11.3197,4.60345-2.89941,.00012,.00055,13.34814Z"
+      fill="#2f2e41"
+    />
+    <polygon
+      fill="#a0616a"
+      points="84.74116 616.94501 93.38016 623.42603 122.49316 593.185 109.74116 583.61902 84.74116 616.94501"
+    />
+    <path
+      d="M77.67448,625.72966l26.569,19.93188,.25208-.336c4.2843-5.71136,3.12799-13.81433-2.58279-18.09937l-.00064-.00049-2.09079-7.32275-11.81735-3.11102-2.31931-1.73993-8.01019,10.67767Z"
+      fill="#2f2e41"
+    />
+    <path
+      d="M120.64463,451.35271s.59625,16.26422,1.3483,29.30737c.12335,2.13916-4.88821,4.46301-4.75842,6.7901,.08609,1.54395,1.02808,3.04486,1.1156,4.65472,.09235,1.69897-1.20822,3.20282-1.1156,4.95984,.09052,1.71667,1.57422,3.6853,1.66373,5.44244,.96317,18.9093,4.45459,41.54633,.9584,47.87439-1.72299,3.11871-23.68533,46.32446-23.68533,46.32446,0,0,12.23666,18.35498,15.73285,12.23663,4.61771-8.08099,40.20615-45.88745,40.20615-53.10712,0-7.21088,8.23346-61.25323,8.23346-61.25323l5.74103,31.98169,2.63239,6.33655-.82715,3.71997,1.70117,5.02045,.09192,4.96838,1.65619,9.22614s-4.98199,71.88159-2.17633,73.88312c2.81439,2.01038,16.44086,5.62018,18.04901,2.01038,1.59955-3.6098,12.0108-75.01947,12.0108-75.01947,0,0,1.6781-32.72424,3.49622-63.14111,.1048-1.76556,1.34607-3.89825,1.4422-5.63763,.11365-2.01898-.67297-4.64111-.56818-6.599,.11365-2.24628,1.11005-3.82831,1.20618-5.97852,.74292-16.6156-3.42761-36.84912-4.7561-38.84192-4.01202-6.01343-7.62177-10.82074-7.62177-10.82074,0,0-54.03558-17.75403-68.47485,.28625l-3.30185,25.37585Z"
+      fill="#2f2e41"
+    />
+    <path
+      d="M174.53779,284.10378l-21.4209-4.28418-9.9964,13.56656h0c-18.65262,18.34058-18.93359,34.52753-15.60379,60.47382v36.41553l-2.41,24.41187s-8.53156,17.84521,.26788,22.00006,66.59857,3.80066,72.117,2.14209,.73517-3.69482-.71399-11.4245c-2.72211-14.51929-.90131-7.51562-.71399-12.13849,2.68585-66.31363-3.57013-93.5379-4.20544-100.69376l-10.89398-19.75858-6.42639-10.71042Z"
+      fill="#3f3d56"
+    />
+    <path
+      d="M287.43909,337.57097c-2.23248,4.23007-7.47144,5.84943-11.70148,3.61694-.45099-.23804-.88013-.51541-1.28229-.82895l-46.26044,29.37308,.13336-15.9924,44.93842-26.07846c3.20093-3.58887,8.70514-3.90332,12.29401-.70239,3.00305,2.67844,3.7796,7.0657,1.87842,10.61218Z"
+      fill="#a0616a"
+    />
+    <path
+      d="M157.62488,302.62425l-5.26666-.55807c-4.86633-.50473-9.64093,1.57941-12.57947,5.491-1.12549,1.48346-1.9339,3.18253-2.37491,4.99164l-.00317,.01447c-1.32108,5.44534,.75095,11.15201,5.25803,14.48117l18.19031,13.41101c12.76544,17.24899,36.75653,28.69272,64.89832,37.98978l43.74274-27.16666-15.47186-18.73843-30.00336,16.0798-44.59833-34.52374-.0257-.02075-16.97424-10.936-4.79169-.5152Z"
+      fill="#3f3d56"
+    />
+    <circle cx="167.29993" cy="248.60526" fill="#a0616a" r="24.9798" />
+    <path
+      d="M167.8769,273.59047c-.20135,.00662-.4032,.01108-.6048,.01657-.0863,.22388-.17938,.44583-.2868,.66357l.8916-.68015Z"
+      fill="#2f2e41"
+    />
+    <path
+      d="M174.73243,249.29823c.03918,.24612,.09912,.48846,.17914,.72449-.03302-.24731-.09308-.49026-.17914-.72449Z"
+      fill="#2f2e41"
+    />
+    <path
+      d="M192.59852,224.6942c-1.0282,3.19272-1.94586-.85715-5.32825-.12869-4.06885,.87625-8.80377,.57532-12.13586-1.91879-4.96478-3.64273-11.39874-4.62335-17.22333-2.62509-5.70154,2.01706-15.25348,3.43933-16.73907,9.30179-.51642,2.03781-.7215,4.24933-1.97321,5.9382-1.09436,1.47662-2.82166,2.31854-4.26608,3.45499-4.87726,3.83743-1.14954,14.73981,1.15881,20.50046,2.30838,5.76065,7.60355,9.95721,13.42526,12.10678,5.63281,2.07977,11.7464,2.44662,17.75531,2.28317,1.04517-2.7106,.59363-5.84137-.26874-8.65134-.93359-3.04199-2.31592-5.97791-2.70593-9.13599s.46643-6.74527,3.11444-8.50986c2.4339-1.62192,6.39465-.63388,7.32062,1.98843-.54028-3.27841,2.7807-6.4509,6.20508-7.00882,3.67651-.599,7.35291,.72833,11.01886,1.38901s2.36475-14.77301,.64209-18.98425Z"
+      fill="#2f2e41"
+    />
+    <circle
+      cx="281.3585"
+      cy="285.71051"
+      fill="var(--g3-color-primary, #165dff)"
+      r="51.12006"
+      transform="translate(-26.58509 542.54478) rotate(-85.26884)"
+    />
+    <path
+      d="M294.78675,264.41051l-13.42828,13.42828-13.42828-13.42828c-2.17371-2.17374-5.69806-2.17374-7.87177,0s-2.17371,5.69803,0,7.87177l13.42828,13.42828-13.42828,13.42828c-2.17169,2.17575-2.1684,5.70007,.00739,7.87177,2.17285,2.16879,5.69153,2.16879,7.86438-.00003l13.42828-13.42828,13.42828,13.42828c2.17578,2.17169,5.70007,2.1684,7.87177-.00735,2.16882-2.17288,2.16882-5.6915,0-7.86438l-13.42828-13.42828,13.42828-13.42828c2.17371-2.17374,2.17371-5.69803,0-7.87177s-5.69806-2.17374-7.87177,0h0Z"
+      fill="#fff"
+    />
+    <path
+      d="M261.21387,242.74385c1.5069,4.53946-.95154,9.44101-5.49097,10.94791-.48401,.16064-.9812,.27823-1.4859,.35141l-10.83051,53.71692-11.44788-11.16785,12.29266-50.48209c-.37366-4.7944,3.21008-8.98395,8.00452-9.3576,4.01166-.31265,7.71509,2.16425,8.95807,5.9913Z"
+      fill="#a0616a"
+    />
+    <path
+      d="M146.12519,312.22478l-4.04883,3.41412c-3.73322,3.16214-5.53476,8.05035-4.74649,12.87888,.29129,1.83917,.95773,3.59879,1.95786,5.16949l.00824,.0123c3.01477,4.72311,8.5672,7.17865,14.08978,6.23117l22.27075-3.84171c21.28461,2.72995,46.15155-6.65967,72.34302-20.53055l10.67969-50.37274-24.23297-1.80811-9.16821,32.78271-55.78815,8.28149-.03278,.00415-19.64294,4.67767-3.68896,3.1011Z"
+      fill="#3f3d56"
+    />
+    <path
+      d="M272.93684,658.99046l-271.75,.30731c-.65759-.00214-1.18896-.53693-1.18683-1.19452,.00211-.6546,.53223-1.18469,1.18683-1.18683l271.75-.30731c.65759,.00214,1.18896,.53693,1.18683,1.19452-.00208,.6546-.53223,1.18469-1.18683,1.18683Z"
+      fill="#cacaca"
+    />
+    <g>
+      <ellipse cx="56.77685" cy="82.05834" fill="#3f3d56" rx="8.45661" ry="8.64507" />
+      <ellipse cx="85.9906" cy="82.05834" fill="#3f3d56" rx="8.45661" ry="8.64507" />
+      <ellipse cx="115.20435" cy="82.05834" fill="#3f3d56" rx="8.45661" ry="8.64507" />
+      <path
+        d="M148.51577,88.89113c-.25977,0-.51904-.10059-.71484-.30078l-5.70605-5.83301c-.38037-.38867-.38037-1.00977,0-1.39844l5.70605-5.83252c.38721-.39453,1.021-.40088,1.41406-.01562,.39502,.38623,.40186,1.01953,.01562,1.41406l-5.02197,5.1333,5.02197,5.13379c.38623,.39453,.37939,1.02783-.01562,1.41406-.19434,.19043-.44678,.28516-.69922,.28516Z"
+        fill="#3f3d56"
+      />
+      <path
+        d="M158.10415,88.89113c-.25244,0-.50488-.09473-.69922-.28516-.39502-.38623-.40186-1.01904-.01562-1.41406l5.02148-5.13379-5.02148-5.1333c-.38623-.39453-.37939-1.02783,.01562-1.41406,.39404-.38672,1.02783-.37939,1.41406,.01562l5.70557,5.83252c.38037,.38867,.38037,1.00977,0,1.39844l-5.70557,5.83301c-.1958,.2002-.45508,.30078-.71484,.30078Z"
+        fill="#3f3d56"
+      />
+      <path
+        d="M456.61398,74.41416h-10.60999c-1.21002,0-2.19,.97998-2.19,2.19v10.62c0,1.21002,.97998,2.19,2.19,2.19h10.60999c1.21002,0,2.20001-.97998,2.20001-2.19v-10.62c0-1.21002-.98999-2.19-2.20001-2.19Z"
+        fill="#3f3d56"
+      />
+      <path
+        d="M430.61398,74.41416h-10.60999c-1.21002,0-2.19,.97998-2.19,2.19v10.62c0,1.21002,.97998,2.19,2.19,2.19h10.60999c1.21002,0,2.20001-.97998,2.20001-2.19v-10.62c0-1.21002-.98999-2.19-2.20001-2.19Z"
+        fill="#3f3d56"
+      />
+      <path
+        d="M481.11398,74.91416h-10.60999c-1.21002,0-2.19,.97998-2.19,2.19v10.62c0,1.21002,.97998,2.19,2.19,2.19h10.60999c1.21002,0,2.20001-.97998,2.20001-2.19v-10.62c0-1.21002-.98999-2.19-2.20001-2.19Z"
+        fill="#3f3d56"
+      />
+      <path
+        d="M321.19229,78.95414h-84.81c-1.48004,0-2.67004,1.20001-2.67004,2.67004s1.19,2.66998,2.67004,2.66998h84.81c1.46997,0,2.66998-1.20001,2.66998-2.66998s-1.20001-2.67004-2.66998-2.67004Z"
+        fill="#3f3d56"
+      />
+    </g>
+  </svg>
+</template>
diff --git a/code/g3soft-libs/packages/ui/src/result/icons/Icon404.vue b/code/g3soft-libs/packages/ui/src/result/icons/Icon404.vue
new file mode 100644
index 00000000..e3167f04
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/result/icons/Icon404.vue
@@ -0,0 +1,154 @@
+<template>
+  <svg
+    height="571"
+    viewBox="0 0 860 571"
+    width="860"
+    xmlns="http://www.w3.org/2000/svg"
+    xmlns:xlink="http://www.w3.org/1999/xlink"
+  >
+    <path
+      d="M605.66974,324.95306c-7.66934-12.68446-16.7572-26.22768-30.98954-30.36953-16.482-4.7965-33.4132,4.73193-47.77473,14.13453a1392.15692,1392.15692,0,0,0-123.89338,91.28311l.04331.49238q46.22556-3.1878,92.451-6.37554c22.26532-1.53546,45.29557-3.2827,64.97195-13.8156,7.46652-3.99683,14.74475-9.33579,23.20555-9.70782,10.51175-.46217,19.67733,6.87923,26.8802,14.54931,42.60731,45.371,54.937,114.75409,102.73817,154.61591A1516.99453,1516.99453,0,0,0,605.66974,324.95306Z"
+      fill="#f2f2f2"
+      transform="translate(-169.93432 -164.42601)"
+    />
+    <path
+      d="M867.57068,709.78146c-4.71167-5.94958-6.6369-7.343-11.28457-13.34761q-56.7644-73.41638-106.70791-151.79237-33.92354-53.23-64.48275-108.50439-14.54864-26.2781-28.29961-52.96872-10.67044-20.6952-20.8646-41.63793c-1.94358-3.98782-3.8321-7.99393-5.71122-12.00922-4.42788-9.44232-8.77341-18.93047-13.43943-28.24449-5.31686-10.61572-11.789-21.74485-21.55259-28.877a29.40493,29.40493,0,0,0-15.31855-5.89458c-7.948-.51336-15.28184,2.76855-22.17568,6.35295-50.43859,26.301-97.65922,59.27589-140.3696,96.79771A730.77816,730.77816,0,0,0,303.32241,496.24719c-1.008,1.43927-3.39164.06417-2.37419-1.38422q6.00933-8.49818,12.25681-16.81288A734.817,734.817,0,0,1,500.80465,303.06436q18.24824-11.82581,37.18269-22.54245c6.36206-3.60275,12.75188-7.15967,19.25136-10.49653,6.37146-3.27274,13.13683-6.21547,20.41563-6.32547,24.7701-.385,37.59539,27.66695,46.40506,46.54248q4.15283,8.9106,8.40636,17.76626,16.0748,33.62106,33.38729,66.628,10.68453,20.379,21.83683,40.51955,34.7071,62.71816,73.77854,122.897c34.5059,53.1429,68.73651,100.08874,108.04585,149.78472C870.59617,709.21309,868.662,711.17491,867.57068,709.78146Z"
+      fill="#e4e4e4"
+      transform="translate(-169.93432 -164.42601)"
+    />
+    <path
+      d="M414.91613,355.804c-1.43911-1.60428-2.86927-3.20856-4.31777-4.81284-11.42244-12.63259-23.6788-25.11847-39.3644-32.36067a57.11025,57.11025,0,0,0-23.92679-5.54622c-8.56213.02753-16.93178,2.27348-24.84306,5.41792-3.74034,1.49427-7.39831,3.1902-11.00078,4.99614-4.11634,2.07182-8.15927,4.28118-12.1834,6.50883q-11.33112,6.27044-22.36816,13.09089-21.9606,13.57221-42.54566,29.21623-10.67111,8.11311-20.90174,16.75788-9.51557,8.03054-18.64618,16.492c-1.30169,1.20091-3.24527-.74255-1.94358-1.94347,1.60428-1.49428,3.22691-2.97938,4.84955-4.44613q6.87547-6.21546,13.9712-12.19257,12.93921-10.91827,26.54851-20.99312,21.16293-15.67614,43.78288-29.22541,11.30361-6.76545,22.91829-12.96259c2.33794-1.24675,4.70318-2.466,7.09572-3.6211a113.11578,113.11578,0,0,1,16.86777-6.86632,60.0063,60.0063,0,0,1,25.476-2.50265,66.32706,66.32706,0,0,1,23.50512,8.1314c15.40091,8.60812,27.34573,21.919,38.97,34.90915C418.03337,355.17141,416.09875,357.12405,414.91613,355.804Z"
+      fill="#e4e4e4"
+      transform="translate(-169.93432 -164.42601)"
+    />
+    <path
+      d="M730.47659,486.71092l36.90462-13.498,18.32327-6.70183c5.96758-2.18267,11.92082-4.66747,18.08988-6.23036a28.53871,28.53871,0,0,1,16.37356.20862,37.73753,37.73753,0,0,1,12.771,7.91666,103.63965,103.63965,0,0,1,10.47487,11.18643c3.98932,4.79426,7.91971,9.63877,11.86772,14.46706q24.44136,29.89094,48.56307,60.04134,24.12117,30.14991,47.91981,60.556,23.85681,30.48041,47.38548,61.21573,2.88229,3.76518,5.75966,7.53415c1.0598,1.38809,3.44949.01962,2.37472-1.38808Q983.582,650.9742,959.54931,620.184q-24.09177-30.86383-48.51647-61.46586-24.42421-30.60141-49.17853-60.93743-6.16706-7.55761-12.35445-15.09858c-3.47953-4.24073-6.91983-8.52718-10.73628-12.47427-7.00539-7.24516-15.75772-13.64794-26.23437-13.82166-6.15972-.10214-12.121,1.85248-17.844,3.92287-6.16968,2.232-12.32455,4.50571-18.48633,6.75941l-37.16269,13.59243-9.29067,3.3981c-1.64875.603-.93651,3.2619.73111,2.652Z"
+      fill="#e4e4e4"
+      transform="translate(-169.93432 -164.42601)"
+    />
+    <path
+      d="M366.37741,334.52609c-18.75411-9.63866-42.77137-7.75087-60.00508,4.29119a855.84708,855.84708,0,0,1,97.37056,22.72581C390.4603,353.75916,380.07013,341.5635,366.37741,334.52609Z"
+      fill="#f2f2f2"
+      transform="translate(-169.93432 -164.42601)"
+    />
+    <path
+      d="M306.18775,338.7841l-3.61042,2.93462c1.22123-1.02713,2.4908-1.99013,3.795-2.90144C306.31073,338.80665,306.24935,338.79473,306.18775,338.7841Z"
+      fill="#f2f2f2"
+      transform="translate(-169.93432 -164.42601)"
+    />
+    <path
+      d="M831.54929,486.84576c-3.6328-4.42207-7.56046-9.05222-12.99421-10.84836l-5.07308.20008A575.436,575.436,0,0,0,966.74929,651.418Q899.14929,569.13192,831.54929,486.84576Z"
+      fill="#f2f2f2"
+      transform="translate(-169.93432 -164.42601)"
+    />
+    <path
+      d="M516.08388,450.36652A37.4811,37.4811,0,0,0,531.015,471.32518c2.82017,1.92011,6.15681,3.76209,7.12158,7.03463a8.37858,8.37858,0,0,1-.87362,6.1499,24.88351,24.88351,0,0,1-3.86126,5.04137l-.13667.512c-6.99843-4.14731-13.65641-9.3934-17.52227-16.55115s-4.40553-16.53895.34116-23.14544"
+      fill="#f2f2f2"
+      transform="translate(-169.93432 -164.42601)"
+    />
+    <path
+      d="M749.08388,653.36652A37.4811,37.4811,0,0,0,764.015,674.32518c2.82017,1.92011,6.15681,3.76209,7.12158,7.03463a8.37858,8.37858,0,0,1-.87362,6.1499,24.88351,24.88351,0,0,1-3.86126,5.04137l-.13667.512c-6.99843-4.14731-13.65641-9.3934-17.52227-16.55115s-4.40553-16.53895.34116-23.14544"
+      fill="#f2f2f2"
+      transform="translate(-169.93432 -164.42601)"
+    />
+    <path
+      d="M284.08388,639.36652A37.4811,37.4811,0,0,0,299.015,660.32518c2.82017,1.92011,6.15681,3.76209,7.12158,7.03463a8.37858,8.37858,0,0,1-.87362,6.1499,24.88351,24.88351,0,0,1-3.86126,5.04137l-.13667.512c-6.99843-4.14731-13.65641-9.3934-17.52227-16.55115s-4.40553-16.53895.34116-23.14544"
+      fill="#f2f2f2"
+      transform="translate(-169.93432 -164.42601)"
+    />
+    <circle cx="649.24878" cy="51" fill="var(--g3-color-primary, #165dff)" r="51" />
+    <path
+      d="M911.21851,176.29639c-24.7168-3.34094-52.93512,10.01868-59.34131,34.12353a21.59653,21.59653,0,0,0-41.09351,2.10871l2.82972,2.02667a372.27461,372.27461,0,0,0,160.65881-.72638C957.07935,195.76,935.93537,179.63727,911.21851,176.29639Z"
+      fill="#f0f0f0"
+      transform="translate(-169.93432 -164.42601)"
+    />
+    <path
+      d="M805.21851,244.29639c-24.7168-3.34094-52.93512,10.01868-59.34131,34.12353a21.59653,21.59653,0,0,0-41.09351,2.10871l2.82972,2.02667a372.27461,372.27461,0,0,0,160.65881-.72638C851.07935,263.76,829.93537,247.63727,805.21851,244.29639Z"
+      fill="#f0f0f0"
+      transform="translate(-169.93432 -164.42601)"
+    />
+    <path
+      d="M1020.94552,257.15423a.98189.98189,0,0,1-.30176-.04688C756.237,173.48919,523.19942,184.42376,374.26388,208.32122c-20.26856,3.251-40.59131,7.00586-60.40381,11.16113-5.05811,1.05957-10.30567,2.19532-15.59668,3.37793-6.31885,1.40723-12.55371,2.85645-18.53223,4.30567q-3.873.917-7.59472,1.84863c-3.75831.92773-7.57178,1.89453-11.65967,2.957-4.56787,1.17774-9.209,2.41309-13.79737,3.67188a.44239.44239,0,0,1-.05127.01465l.00049.001c-5.18261,1.415-10.33789,2.8711-15.32324,4.3252-2.69824.77929-5.30371,1.54785-7.79932,2.30664-.2788.07715-.52587.15136-.77636.22754l-.53614.16308c-.31054.09473-.61718.1875-.92382.27539l-.01953.00586.00048.001-.81152.252c-.96777.293-1.91211.5791-2.84082.86426-24.54492,7.56641-38.03809,12.94922-38.17139,13.00195a1,1,0,1,1-.74414-1.85644c.13428-.05274,13.69336-5.46289,38.32764-13.05762.93213-.28613,1.87891-.57226,2.84961-.86621l.7539-.23438c.02588-.00976.05176-.01757.07813-.02539.30518-.08691.60986-.17968.91943-.27343l.53711-.16309c.26758-.08105.53125-.16113.80127-.23535,2.47852-.75391,5.09278-1.52441,7.79785-2.30664,4.98731-1.45508,10.14746-2.91113,15.334-4.32813.01611-.00586.03271-.00976.04883-.01464v-.001c4.60449-1.2627,9.26269-2.50293,13.84521-3.68457,4.09424-1.06348,7.915-2.03223,11.67969-2.96192q3.73755-.93017,7.60937-1.85253c5.98536-1.45118,12.23291-2.90235,18.563-4.3125,5.29932-1.1836,10.55567-2.32227,15.62207-3.38282,19.84326-4.16211,40.19776-7.92285,60.49707-11.17871C523.09591,182.415,756.46749,171.46282,1021.2463,255.2011a.99974.99974,0,0,1-.30078,1.95313Z"
+      fill="#ccc"
+      transform="translate(-169.93432 -164.42601)"
+    />
+    <path
+      d="M432.92309,584.266a6.72948,6.72948,0,0,0-1.7-2.67,6.42983,6.42983,0,0,0-.92-.71c-2.61-1.74-6.51-2.13-8.99,0a5.81012,5.81012,0,0,0-.69.71q-1.11,1.365-2.28,2.67c-1.28,1.46-2.59,2.87-3.96,4.24-.39.38-.78.77-1.18,1.15-.23.23-.46.45-.69.67-.88.84-1.78,1.65-2.69,2.45-.48.43-.96.85-1.45,1.26-.73.61-1.46,1.22-2.2,1.81-.07.05-.14.1-.21.16-.02.01-.03.03-.05.04-.01,0-.02,0-.03.02a.17861.17861,0,0,0-.07.05c-.22.15-.37.25-.48.34.04-.01995.08-.05.12-.07-.18.14-.37.28-.55.42-1.75,1.29-3.54,2.53-5.37,3.69a99.21022,99.21022,0,0,1-14.22,7.55c-.33.13-.67.27-1.01.4a85.96993,85.96993,0,0,1-40.85,6.02q-2.13008-.165-4.26-.45c-1.64-.24-3.27-.53-4.89-.86a97.93186,97.93186,0,0,1-18.02-5.44,118.65185,118.65185,0,0,1-20.66-12.12c-1-.71-2.01-1.42-3.02-2.11,1.15-2.82,2.28-5.64,3.38-8.48.55-1.37,1.08-2.74,1.6-4.12,4.09-10.63,7.93-21.36,11.61-32.13q5.58-16.365,10.53-32.92.51-1.68.99-3.36,2.595-8.745,4.98-17.53c.15-.56994.31-1.12994.45-1.7q.68994-2.52,1.35-5.04c1-3.79-1.26-8.32-5.24-9.23a7.63441,7.63441,0,0,0-9.22,5.24c-.43,1.62-.86,3.23-1.3,4.85q-3.165,11.74494-6.66,23.41-.51,1.68-1.02,3.36-7.71,25.41-16.93,50.31-1.11,3.015-2.25,6.01c-.37.98-.74,1.96-1.12,2.94-.73,1.93-1.48,3.86-2.23,5.79-.43006,1.13-.87006,2.26-1.31,3.38-.29.71-.57,1.42-.85,2.12a41.80941,41.80941,0,0,0-8.81-2.12l-.48-.06a27.397,27.397,0,0,0-7.01.06,23.91419,23.91419,0,0,0-17.24,10.66c-4.77,7.51-4.71,18.25,1.98,24.63,6.89,6.57,17.32,6.52,25.43,2.41a28.35124,28.35124,0,0,0,10.52-9.86,50.56939,50.56939,0,0,0,2.74-4.65c.21.14.42.28.63.43.8.56,1.6,1.13,2.39,1.69a111.73777,111.73777,0,0,0,14.51,8.91,108.35887,108.35887,0,0,0,34.62,10.47c.27.03.53.07.8.1,1.33.17,2.67.3,4.01.41a103.78229,103.78229,0,0,0,55.58-11.36q2.175-1.125,4.31-2.36,3.315-1.92,6.48-4.08c1.15-.78,2.27-1.57,3.38-2.4a101.04244,101.04244,0,0,0,13.51-11.95q2.35491-2.475,4.51-5.11005a8.0612,8.0612,0,0,0,2.2-5.3A7.5644,7.5644,0,0,0,432.92309,584.266Zm-165.59,23.82c.21-.15.42-.31.62-.47C267.89312,607.766,267.60308,607.936,267.33312,608.086Zm3.21-3.23c-.23.26-.44.52-.67.78a23.36609,23.36609,0,0,1-2.25,2.2c-.11.1-.23.2-.35.29a.00976.00976,0,0,0-.01.01,3.80417,3.80417,0,0,0-.42005.22q-.645.39-1.31994.72a17.00459,17.00459,0,0,1-2.71.75,16.79925,16.79925,0,0,1-2.13.02h-.02a14.82252,14.82252,0,0,1-1.45-.4c-.24-.12-.47-.25994-.7-.4-.09-.08-.17005-.16-.22-.21a2.44015,2.44015,0,0,1-.26995-.29.0098.0098,0,0,0-.01-.01c-.11005-.2-.23005-.4-.34-.6a.031.031,0,0,1-.01-.02c-.08-.25-.15-.51-.21-.77a12.51066,12.51066,0,0,1,.01-1.37,13.4675,13.4675,0,0,1,.54-1.88,11.06776,11.06776,0,0,1,.69-1.26c.02-.04.12-.2.23-.38.01-.01.01-.01.01-.02.15-.17.3-.35.46-.51.27-.3.56-.56.85-.83a18.02212,18.02212,0,0,1,1.75-1.01,19.48061,19.48061,0,0,1,2.93-.79,24.98945,24.98945,0,0,1,4.41.04,30.30134,30.30134,0,0,1,4.1,1.01,36.94452,36.94452,0,0,1-2.77,4.54C270.6231,604.746,270.58312,604.806,270.54308,604.856Zm-11.12-3.29a2.18029,2.18029,0,0,1-.31.38995A1.40868,1.40868,0,0,1,259.42309,601.566Z"
+      fill="var(--g3-text-1, rgba(0, 0, 0, 0.88))"
+      transform="translate(-169.93432 -164.42601)"
+    />
+    <path
+      d="M402.86309,482.136q-.13494,4.71-.27,9.42-.285,10.455-.59,20.92-.315,11.775-.66,23.54-.165,6.07507-.34,12.15-.465,16.365-.92,32.72c-.03,1.13-.07,2.25-.1,3.38q-.225,8.11506-.45,16.23-.255,8.805-.5,17.61-.18,6.59994-.37,13.21-1.34994,47.895-2.7,95.79a7.64844,7.64844,0,0,1-7.5,7.5,7.56114,7.56114,0,0,1-7.5-7.5q.75-26.94,1.52-53.88.675-24.36,1.37-48.72.225-8.025.45-16.06.345-12.09.68-24.18c.03-1.13.07-2.25.1-3.38.02-.99.05-1.97.08-2.96q.66-23.475,1.32-46.96.27-9.24.52-18.49.3-10.545.6-21.08c.09-3.09.17005-6.17.26-9.26a7.64844,7.64844,0,0,1,7.5-7.5A7.56116,7.56116,0,0,1,402.86309,482.136Z"
+      fill="var(--g3-text-1, rgba(0, 0, 0, 0.88))"
+      transform="translate(-169.93432 -164.42601)"
+    />
+    <path
+      d="M814.29118,484.2172a893.23753,893.23753,0,0,1-28.16112,87.94127c-3.007,7.94641-6.08319,15.877-9.3715,23.71185l.75606-1.7916a54.58274,54.58274,0,0,1-5.58953,10.61184q-.22935.32119-.46685.63642,1.16559-1.49043.4428-.589c-.25405.30065-.5049.60219-.7676.89546a23.66436,23.66436,0,0,1-2.2489,2.20318q-.30139.25767-.61188.5043l.93783-.729c-.10884.25668-.87275.59747-1.11067.74287a18.25362,18.25362,0,0,1-2.40479,1.21853l1.7916-.75606a19.0859,19.0859,0,0,1-4.23122,1.16069l1.9938-.26791a17.02055,17.02055,0,0,1-4.29785.046l1.99379.2679a14.0022,14.0022,0,0,1-3.40493-.917l1.79159.75606a12.01175,12.01175,0,0,1-1.67882-.89614c-.27135-.17688-1.10526-.80852-.01487.02461,1.13336.86595.14562.07434-.08763-.15584-.19427-.19171-.36962-.4-.55974-.595-.88208-.90454.99637,1.55662.39689.49858a18.18179,18.18179,0,0,1-.87827-1.63672l.75606,1.7916a11.92493,11.92493,0,0,1-.728-2.65143l.26791,1.9938a13.65147,13.65147,0,0,1-.00316-3.40491l-.2679,1.9938a15.96371,15.96371,0,0,1,.99486-3.68011l-.75606,1.7916a16.72914,16.72914,0,0,1,1.17794-2.29848,6.72934,6.72934,0,0,1,.72851-1.0714c.04915.01594-1.26865,1.51278-.56937.757.1829-.19767.354-.40592.539-.602.29617-.31382.61354-.60082.92561-.89791,1.04458-.99442-1.46188.966-.25652.17907a19.0489,19.0489,0,0,1,2.74925-1.49923l-1.79159.75606a20.31136,20.31136,0,0,1,4.99523-1.33984l-1.9938.2679a25.62828,25.62828,0,0,1,6.46062.07647l-1.9938-.2679a33.21056,33.21056,0,0,1,7.89178,2.2199l-1.7916-.75606c5.38965,2.31383,10.16308,5.74926,14.928,9.118a111.94962,111.94962,0,0,0,14.50615,8.9065,108.38849,108.38849,0,0,0,34.62226,10.47371,103.93268,103.93268,0,0,0,92.58557-36.75192,8.07773,8.07773,0,0,0,2.1967-5.3033,7.63232,7.63232,0,0,0-2.1967-5.3033c-2.75154-2.52586-7.94926-3.239-10.6066,0a95.63575,95.63575,0,0,1-8.10664,8.72692q-2.01736,1.914-4.14232,3.70983-1.21364,1.02588-2.46086,2.01121c-.3934.31081-1.61863,1.13807.26309-.19744-.43135.30614-.845.64036-1.27058.95478a99.26881,99.26881,0,0,1-20.33215,11.56478l1.79159-.75606a96.8364,96.8364,0,0,1-24.17119,6.62249l1.99379-.2679a97.64308,97.64308,0,0,1-25.75362-.03807l1.99379.2679a99.79982,99.79982,0,0,1-24.857-6.77027l1.7916.75607a116.02515,116.02515,0,0,1-21.7364-12.59112,86.87725,86.87725,0,0,0-11.113-6.99417,42.8238,42.8238,0,0,0-14.43784-4.38851c-9.43884-1.11076-19.0571,2.56562-24.24624,10.72035-4.77557,7.50482-4.71394,18.24362,1.97369,24.62519,6.8877,6.5725,17.31846,6.51693,25.43556,2.40567,7.81741-3.95946,12.51288-12.18539,15.815-19.94186,7.43109-17.45514,14.01023-35.31364,20.1399-53.263q9.09651-26.63712,16.49855-53.81332.91661-3.36581,1.80683-6.73869c1.001-3.78869-1.26094-8.32-5.23829-9.22589a7.63317,7.63317,0,0,0-9.22589,5.23829Z"
+      fill="var(--g3-text-1, rgba(0, 0, 0, 0.88))"
+      transform="translate(-169.93432 -164.42601)"
+    />
+    <path
+      d="M889.12382,482.13557l-2.69954,95.79311-2.68548,95.29418-1.5185,53.88362a7.56465,7.56465,0,0,0,7.5,7.5,7.64923,7.64923,0,0,0,7.5-7.5l2.69955-95.79311,2.68548-95.29418,1.51849-53.88362a7.56465,7.56465,0,0,0-7.5-7.5,7.64923,7.64923,0,0,0-7.5,7.5Z"
+      fill="var(--g3-text-1, rgba(0, 0, 0, 0.88))"
+      transform="translate(-169.93432 -164.42601)"
+    />
+    <path
+      d="M629.52566,700.36106h2.32885V594.31942h54.32863v-2.32291H631.85451V547.25214H673.8102q-.92256-1.17339-1.89893-2.31694H631.85451V515.38231c-.7703-.32846-1.54659-.64493-2.32885-.9435V544.9352h-45.652V507.07c-.78227.03583-1.55258.08959-2.3289.15527v37.71h-36.4201V516.68409c-.78227.34636-1.55258.71061-2.31694,1.0928V544.9352h-30.6158v2.31694h30.6158v44.74437h-30.6158v2.32291h30.6158V700.36106h2.31694V594.31942a36.41283,36.41283,0,0,1,36.4201,36.42007v69.62157h2.3289V594.31942h45.652Zm-84.401-108.36455V547.25214h36.4201v44.74437Zm38.749,0V547.25214h.91362a44.74135,44.74135,0,0,1,44.73842,44.74437Z"
+      opacity="0.2"
+      transform="translate(-169.93432 -164.42601)"
+    />
+    <path
+      d="M615.30309,668.566a63.05854,63.05854,0,0,1-20.05,33.7c-.74.64-1.48,1.26-2.25,1.87q-2.805.25506-5.57.52c-1.53.14-3.04.29-4.54.43l-.27.03-.19-1.64-.76-6.64a37.623,37.623,0,0,1-3.3-32.44c2.64-7.12,7.42-13.41,12.12-19.65,6.49-8.62,12.8-17.14,13.03-27.65a60.54415,60.54415,0,0,1,7.9,13.33,16.432,16.432,0,0,0-5.12,3.76995c-.41.45-.82,1.08-.54,1.62006.24.46.84.57,1.36.62994,1.25.13,2.51.26,3.76.39,1,.11,2,.21,3,.32a63.99025,63.99025,0,0,1,2.45,12.18A61.18851,61.18851,0,0,1,615.30309,668.566Z"
+      fill="var(--g3-text-1, rgba(0, 0, 0, 0.88))"
+      transform="translate(-169.93432 -164.42601)"
+    />
+    <path
+      d="M648.50311,642.356c-5.9,4.29-9.35,10.46-12.03,17.26a16.62776,16.62776,0,0,0-7.17,4.58c-.41.45-.82,1.08-.54,1.62006.24.46.84.57,1.36.62994,1.25.13,2.51.26,3.76.39-2.68,8.04-5.14,16.36-9.88,23.15a36.98942,36.98942,0,0,1-12.03,10.91,38.49166,38.49166,0,0,1-4.02,1.99q-7.62.585-14.95,1.25-2.805.25506-5.57.52c-1.53.14-3.04.29-4.54.43q-.015-.825,0-1.65a63.30382,63.30382,0,0,1,15.25-39.86c.45-.52.91-1.03,1.38-1.54a61.7925,61.7925,0,0,1,16.81-12.7A62.65425,62.65425,0,0,1,648.50311,642.356Z"
+      fill="var(--g3-color-primary, #165dff)"
+      transform="translate(-169.93432 -164.42601)"
+    />
+    <path
+      d="M589.16308,699.526l-1.15,3.4-.58,1.73c-1.53.14-3.04.29-4.54.43l-.27.03c-1.66.17-3.31.34-4.96.51-.43-.5-.86-1.01-1.28-1.53a62.03045,62.03045,0,0,1,8.07-87.11c-1.32,6.91.22,13.53,2.75,20.1-.27.11-.53.22-.78.34a16.432,16.432,0,0,0-5.12,3.76995c-.41.45-.82,1.08-.54,1.62006.24.46.84.57,1.36.62994,1.25.13,2.51.26,3.76.39,1,.11,2,.21,3,.32q.705.075,1.41.15c.07.15.13.29.2.44,2.85,6.18,5.92,12.39,7.65,18.83a43.66591,43.66591,0,0,1,1.02,4.91A37.604,37.604,0,0,1,589.16308,699.526Z"
+      fill="var(--g3-color-primary, #165dff)"
+      transform="translate(-169.93432 -164.42601)"
+    />
+    <path
+      d="M689.82123,554.48655c-8.60876-16.79219-21.94605-30.92088-37.63219-41.30357a114.2374,114.2374,0,0,0-52.5626-18.37992q-3.69043-.33535-7.399-.39281c-2.92141-.04371-46.866,12.63176-61.58712,22.98214a114.29462,114.29462,0,0,0-35.333,39.527,102.49972,102.49972,0,0,0-12.12557,51.6334,113.56387,113.56387,0,0,0,14.70268,51.47577,110.47507,110.47507,0,0,0,36.44425,38.74592C549.66655,708.561,565.07375,734.51,583.1831,735.426c18.24576.923,39.05418-23.55495,55.6951-30.98707a104.42533,104.42533,0,0,0,41.72554-34.005,110.24964,110.24964,0,0,0,19.599-48.94777c2.57368-18.08313,1.37415-36.73271-4.80123-54.01627a111.85969,111.85969,0,0,0-5.58024-12.9833c-1.77961-3.50519-6.996-4.7959-10.26142-2.69063a7.67979,7.67979,0,0,0-2.69064,10.26142q1.56766,3.08773,2.91536,6.27758l-.75606-1.7916a101.15088,101.15088,0,0,1,6.87641,25.53816l-.26791-1.99379a109.2286,109.2286,0,0,1-.06613,28.68252l.26791-1.9938a109.73379,109.73379,0,0,1-7.55462,27.67419l.75606-1.79159a104.212,104.212,0,0,1-6.67151,13.09835q-1.92308,3.18563-4.08062,6.22159c-.63172.8881-1.28287,1.761-1.939,2.63114-.85625,1.13555,1.16691-1.48321.28228-.36941-.15068.18972-.30049.3801-.45182.5693q-.68121.85165-1.3818,1.68765a93.61337,93.61337,0,0,1-10.17647,10.38359q-1.36615,1.19232-2.77786,2.33115c-.46871.37832-.932.77269-1.42079,1.12472.01861-.0134,1.57956-1.19945.65556-.511-.2905.21644-.57851.43619-.86961.65184q-2.90994,2.1558-5.97433,4.092a103.48509,103.48509,0,0,1-14.75565,7.7131l1.7916-.75606a109.21493,109.21493,0,0,1-27.59663,7.55154l1.9938-.26791a108.15361,108.15361,0,0,1-28.58907.0506l1.99379.2679a99.835,99.835,0,0,1-25.09531-6.78448l1.79159.75607a93.64314,93.64314,0,0,1-13.41605-6.99094q-3.17437-2-6.18358-4.24743c-.2862-.21359-.56992-.43038-.855-.64549-.9155-.69088.65765.50965.67021.51787a19.16864,19.16864,0,0,1-1.535-1.22469q-1.45353-1.18358-2.86136-2.4218a101.98931,101.98931,0,0,1-10.49319-10.70945q-1.21308-1.43379-2.37407-2.91054c-.33524-.4263-.9465-1.29026.40424.5289-.17775-.23939-.36206-.47414-.54159-.71223q-.64657-.85751-1.27568-1.72793-2.203-3.048-4.18787-6.24586a109.29037,109.29037,0,0,1-7.8054-15.10831l.75606,1.7916a106.58753,106.58753,0,0,1-7.34039-26.837l.26791,1.9938a97.86589,97.86589,0,0,1-.04843-25.63587l-.2679,1.9938A94.673,94.673,0,0,1,505.27587,570.55l-.75606,1.7916a101.55725,101.55725,0,0,1,7.19519-13.85624q2.0655-3.32328,4.37767-6.4847.52528-.71832,1.06244-1.42786c.324-.4279,1.215-1.49333-.30537.38842.14906-.18449.29252-.37428.43942-.56041q1.26882-1.60756,2.59959-3.1649A107.40164,107.40164,0,0,1,530.772,536.21508q1.47408-1.29171,2.99464-2.52906.6909-.56218,1.39108-1.11284c.18664-.14673.37574-.29073.56152-.43858-1.99743,1.58953-.555.43261-.10157.09288q3.13393-2.34833,6.43534-4.46134a103.64393,103.64393,0,0,1,15.38655-8.10791l-1.7916.75606c7.76008-3.25839,42.14086-10.9492,48.394-10.10973l-1.99379-.26791A106.22471,106.22471,0,0,1,628.768,517.419l-1.7916-.75606a110.31334,110.31334,0,0,1,12.6002,6.32922q3.04344,1.78405,5.96742,3.76252,1.38351.93658,2.73809,1.915.677.48917,1.34626.98885c.24789.185.49386.37253.74135.558,1.03924.779-1.43148-1.1281-.34209-.26655a110.84261,110.84261,0,0,1,10.36783,9.2532q2.401,2.445,4.63686,5.04515,1.14659,1.33419,2.24643,2.70757c.36436.45495,1.60506,2.101.08448.08457.37165.49285.74744.98239,1.11436,1.47884a97.97718,97.97718,0,0,1,8.39161,13.53807c1.79317,3.49775,6.98675,4.80186,10.26142,2.69064A7.67666,7.67666,0,0,0,689.82123,554.48655Z"
+      fill="var(--g3-text-1, rgba(0, 0, 0, 0.88))"
+      transform="translate(-169.93432 -164.42601)"
+    />
+    <path
+      d="M602.43116,676.88167a3.77983,3.77983,0,0,1-2.73939-6.55137c.09531-.37882.16368-.65085.259-1.02968q-.05115-.12366-.1029-.24717c-3.47987-8.29769-25.685,14.83336-26.645,22.63179a30.029,30.029,0,0,0,.52714,10.32752A120.39223,120.39223,0,0,1,562.77838,652.01a116.20247,116.20247,0,0,1,.72078-12.96332q.59712-5.293,1.65679-10.51055a121.78667,121.78667,0,0,1,24.1515-51.61646c6.87378.38364,12.898-.66348,13.47967-13.98532.10346-2.36972,1.86113-4.42156,2.24841-6.756-.65621.08607-1.32321.13985-1.97941.18285-.20444.0107-.41958.02149-.624.03228l-.07709.00346a3.745,3.745,0,0,1-3.07566-6.10115q.425-.52305.85054-1.04557c.43036-.53793.87143-1.06507,1.30171-1.60292a1.865,1.865,0,0,0,.13986-.16144c.49494-.61322.98971-1.21564,1.48465-1.82885a10.82911,10.82911,0,0,0-3.55014-3.43169c-4.95941-2.90463-11.80146-.89293-15.38389,3.59313-3.59313,4.486-4.27083,10.77947-3.023,16.3843a43.39764,43.39764,0,0,0,6.003,13.3828c-.269.34429-.54872.67779-.81765,1.02209a122.57366,122.57366,0,0,0-12.79359,20.2681c1.0163-7.93863-11.41159-36.60795-16.21776-42.68052-5.773-7.29409-17.61108-4.11077-18.62815,5.13562q-.01476.13428-.02884.26849,1.07082.60411,2.0964,1.28237a5.12707,5.12707,0,0,1-2.06713,9.33031l-.10452.01613c-9.55573,13.64367,21.07745,49.1547,28.74518,41.18139a125.11045,125.11045,0,0,0-6.73449,31.69282,118.66429,118.66429,0,0,0,.08607,19.15986l-.03231-.22593C558.90163,648.154,529.674,627.51374,521.139,629.233c-4.91675.99041-9.75952.76525-9.01293,5.72484q.01788.11874.03635.2375a34.4418,34.4418,0,0,1,3.862,1.86105q1.07082.60423,2.09639,1.28237a5.12712,5.12712,0,0,1-2.06712,9.33039l-.10464.01606c-.07528.01079-.13987.02157-.21507.03237-4.34967,14.96631,27.90735,39.12,47.5177,31.43461h.01081a125.07484,125.07484,0,0,0,8.402,24.52806H601.679c.10765-.3335.20443-.67779.3013-1.01129a34.102,34.102,0,0,1-8.30521-.49477c2.22693-2.73257,4.45377-5.48664,6.6807-8.21913a1.86122,1.86122,0,0,0,.13986-.16135c1.12956-1.39849,2.26992-2.78627,3.39948-4.18476l.00061-.00173a49.95232,49.95232,0,0,0-1.46367-12.72495Zm-34.37066-67.613.0158-.02133-.0158.04282Zm-6.64832,59.93237-.25822-.58084c.01079-.41957.01079-.83914,0-1.26942,0-.11845-.0215-.23672-.0215-.35508.09678.74228.18285,1.48464.29042,2.22692Z"
+      fill="var(--g3-text-1, rgba(0, 0, 0, 0.88))"
+      transform="translate(-169.93432 -164.42601)"
+    />
+    <circle cx="95.24878" cy="439" fill="var(--g3-text-1, rgba(0, 0, 0, 0.88))" r="11" />
+    <circle cx="227.24878" cy="559" fill="var(--g3-text-1, rgba(0, 0, 0, 0.88))" r="11" />
+    <circle cx="728.24878" cy="559" fill="var(--g3-text-1, rgba(0, 0, 0, 0.88))" r="11" />
+    <circle cx="755.24878" cy="419" fill="var(--g3-text-1, rgba(0, 0, 0, 0.88))" r="11" />
+    <circle cx="723.24878" cy="317" fill="var(--g3-text-1, rgba(0, 0, 0, 0.88))" r="11" />
+    <path
+      d="M434.1831,583.426a10.949,10.949,0,1,1-.21-2.16A10.9921,10.9921,0,0,1,434.1831,583.426Z"
+      fill="var(--g3-text-1, rgba(0, 0, 0, 0.88))"
+      transform="translate(-169.93432 -164.42601)"
+    />
+    <circle cx="484.24878" cy="349" fill="var(--g3-text-1, rgba(0, 0, 0, 0.88))" r="11" />
+    <path
+      d="M545.1831,513.426a10.949,10.949,0,1,1-.21-2.16A10.9921,10.9921,0,0,1,545.1831,513.426Z"
+      fill="var(--g3-text-1, rgba(0, 0, 0, 0.88))"
+      transform="translate(-169.93432 -164.42601)"
+    />
+    <path
+      d="M403.1831,481.426a10.949,10.949,0,1,1-.21-2.16A10.9921,10.9921,0,0,1,403.1831,481.426Z"
+      fill="var(--g3-text-1, rgba(0, 0, 0, 0.88))"
+      transform="translate(-169.93432 -164.42601)"
+    />
+    <circle cx="599.24878" cy="443" fill="var(--g3-text-1, rgba(0, 0, 0, 0.88))" r="11" />
+    <circle cx="426.24878" cy="338" fill="var(--g3-text-1, rgba(0, 0, 0, 0.88))" r="16" />
+    <path
+      d="M1028.875,735.26666l-857.75.30733a1.19068,1.19068,0,1,1,0-2.38136l857.75-.30734a1.19069,1.19069,0,0,1,0,2.38137Z"
+      fill="#cacaca"
+      transform="translate(-169.93432 -164.42601)"
+    />
+  </svg>
+</template>
diff --git a/code/g3soft-libs/packages/ui/src/result/icons/Icon500.vue b/code/g3soft-libs/packages/ui/src/result/icons/Icon500.vue
new file mode 100644
index 00000000..3941f763
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/result/icons/Icon500.vue
@@ -0,0 +1,161 @@
+<template>
+  <svg
+    height="699"
+    viewBox="0 0 1119 699"
+    width="1119"
+    xmlns="http://www.w3.org/2000/svg"
+    xmlns:xlink="http://www.w3.org/1999/xlink"
+  >
+    <title>server down</title>
+    <circle cx="292.60911" cy="213" fill="#f2f2f2" r="213" />
+    <path
+      d="M31.39089,151.64237c0,77.49789,48.6181,140.20819,108.70073,140.20819"
+      fill="#2f2e41"
+      transform="translate(-31.39089 -100.5)"
+    />
+    <path
+      d="M140.09162,291.85056c0-78.36865,54.255-141.78356,121.30372-141.78356"
+      fill="var(--g3-color-primary, #165dff)"
+      transform="translate(-31.39089 -100.5)"
+    />
+    <path
+      d="M70.77521,158.66768c0,73.61476,31.00285,133.18288,69.31641,133.18288"
+      fill="var(--g3-color-primary, #165dff)"
+      transform="translate(-31.39089 -100.5)"
+    />
+    <path
+      d="M140.09162,291.85056c0-100.13772,62.7103-181.16788,140.20819-181.16788"
+      fill="#2f2e41"
+      transform="translate(-31.39089 -100.5)"
+    />
+    <path
+      d="M117.22379,292.83905s15.41555-.47479,20.06141-3.783,23.713-7.2585,24.86553-1.95278,23.16671,26.38821,5.76263,26.5286-40.43935-2.711-45.07627-5.53549S117.22379,292.83905,117.22379,292.83905Z"
+      fill="#a8a8a8"
+      transform="translate(-31.39089 -100.5)"
+    />
+    <path
+      d="M168.224,311.78489c-17.40408.14042-40.43933-2.71094-45.07626-5.53548-3.53126-2.151-4.93843-9.86945-5.40926-13.43043-.32607.014-.51463.02-.51463.02s.97638,12.43276,5.61331,15.2573,27.67217,5.67589,45.07626,5.53547c5.02386-.04052,6.7592-1.82793,6.66391-4.47526C173.87935,310.756,171.96329,311.75474,168.224,311.78489Z"
+      opacity="0.2"
+      transform="translate(-31.39089 -100.5)"
+    />
+    <ellipse cx="198.60911" cy="424.5" fill="#3f3d56" rx="187" ry="25.43993" />
+    <ellipse cx="198.60911" cy="424.5" opacity="0.1" rx="157" ry="21.35866" />
+    <ellipse cx="836.60911" cy="660.5" fill="#3f3d56" rx="283" ry="38.5" />
+    <ellipse cx="310.60911" cy="645.5" fill="#3f3d56" rx="170" ry="23.12721" />
+    <path
+      d="M494,726.5c90,23,263-30,282-90"
+      fill="none"
+      stroke="#2f2e41"
+      stroke-miterlimit="10"
+      stroke-width="2"
+      transform="translate(-31.39089 -100.5)"
+    />
+    <path
+      d="M341,359.5s130-36,138,80-107,149-17,172"
+      fill="none"
+      stroke="#2f2e41"
+      stroke-miterlimit="10"
+      stroke-width="2"
+      transform="translate(-31.39089 -100.5)"
+    />
+    <path
+      d="M215.40233,637.78332s39.0723-10.82,41.47675,24.04449-32.15951,44.78287-5.10946,51.69566"
+      fill="none"
+      stroke="#2f2e41"
+      stroke-miterlimit="10"
+      stroke-width="2"
+      transform="translate(-31.39089 -100.5)"
+    />
+    <path
+      d="M810.09554,663.73988,802.218,714.03505s-38.78182,20.60284-11.51335,21.20881,155.73324,0,155.73324,0,24.84461,0-14.54318-21.81478l-7.87756-52.719Z"
+      fill="#2f2e41"
+      transform="translate(-31.39089 -100.5)"
+    />
+    <path
+      d="M785.21906,734.69812c6.193-5.51039,16.9989-11.252,16.9989-11.252l7.87756-50.2952,113.9216.10717,7.87756,49.582c9.185,5.08711,14.8749,8.987,18.20362,11.97818,5.05882-1.15422,10.58716-5.44353-18.20362-21.38921l-7.87756-52.719-113.9216,3.02983L802.218,714.03506S769.62985,731.34968,785.21906,734.69812Z"
+      opacity="0.1"
+      transform="translate(-31.39089 -100.5)"
+    />
+    <rect
+      fill="#2f2e41"
+      height="357.51989"
+      rx="18.04568"
+      width="513.25314"
+      x="578.43291"
+      y="212.68859"
+    />
+    <rect fill="#3f3d56" height="267.83694" width="478.71308" x="595.70294" y="231.77652" />
+    <circle cx="835.05948" cy="223.29299" fill="#f2f2f2" r="3.02983" />
+    <path
+      d="M1123.07694,621.32226V652.6628a18.04341,18.04341,0,0,1-18.04568,18.04568H627.86949A18.04341,18.04341,0,0,1,609.8238,652.6628V621.32226Z"
+      fill="#2f2e41"
+      transform="translate(-31.39089 -100.5)"
+    />
+    <polygon
+      fill="#2f2e41"
+      points="968.978 667.466 968.978 673.526 642.968 673.526 642.968 668.678 643.417 667.466 651.452 645.651 962.312 645.651 968.978 667.466"
+    />
+    <path
+      d="M1125.828,762.03359c-.59383,2.539-2.83591,5.21743-7.90178,7.75032-18.179,9.08949-55.1429-2.42386-55.1429-2.42386s-28.4804-4.84773-28.4804-17.573a22.72457,22.72457,0,0,1,2.49658-1.48459c7.64294-4.04351,32.98449-14.02122,77.9177.42248a18.73921,18.73921,0,0,1,8.54106,5.59715C1125.07908,756.45353,1126.50669,759.15715,1125.828,762.03359Z"
+      fill="#2f2e41"
+      transform="translate(-31.39089 -100.5)"
+    />
+    <path
+      d="M1125.828,762.03359c-22.251,8.526-42.0843,9.1622-62.43871-4.975-10.26507-7.12617-19.59089-8.88955-26.58979-8.75618,7.64294-4.04351,32.98449-14.02122,77.9177.42248a18.73921,18.73921,0,0,1,8.54106,5.59715C1125.07908,756.45353,1126.50669,759.15715,1125.828,762.03359Z"
+      opacity="0.1"
+      transform="translate(-31.39089 -100.5)"
+    />
+    <ellipse cx="1066.53846" cy="654.13477" fill="#f2f2f2" rx="7.87756" ry="2.42386" />
+    <circle cx="835.05948" cy="545.66686" fill="#f2f2f2" r="11.51335" />
+    <polygon
+      opacity="0.1"
+      points="968.978 667.466 968.978 673.526 642.968 673.526 642.968 668.678 643.417 667.466 968.978 667.466"
+    />
+    <rect fill="#2f2e41" height="242" width="208" x="108.60911" y="159" />
+    <rect fill="#3f3d56" height="86" width="250" x="87.60911" y="135" />
+    <rect fill="#3f3d56" height="86" width="250" x="87.60911" y="237" />
+    <rect fill="#3f3d56" height="86" width="250" x="87.60911" y="339" />
+    <rect fill="#6c63ff" height="16" opacity="0.4" width="16" x="271.60911" y="150" />
+    <rect fill="#6c63ff" height="16" opacity="0.8" width="16" x="294.60911" y="150" />
+    <rect fill="#6c63ff" height="16" width="16" x="317.60911" y="150" />
+    <rect fill="#6c63ff" height="16" opacity="0.4" width="16" x="271.60911" y="251" />
+    <rect fill="#6c63ff" height="16" opacity="0.8" width="16" x="294.60911" y="251" />
+    <rect fill="#6c63ff" height="16" width="16" x="317.60911" y="251" />
+    <rect fill="#6c63ff" height="16" opacity="0.4" width="16" x="271.60911" y="352" />
+    <rect fill="#6c63ff" height="16" opacity="0.8" width="16" x="294.60911" y="352" />
+    <rect fill="#6c63ff" height="16" width="16" x="317.60911" y="352" />
+    <circle cx="316.60911" cy="538" fill="#2f2e41" r="79" />
+    <rect fill="#2f2e41" height="43" width="24" x="280.60911" y="600" />
+    <rect fill="#2f2e41" height="43" width="24" x="328.60911" y="600" />
+    <ellipse cx="300.60911" cy="643.5" fill="#2f2e41" rx="20" ry="7.5" />
+    <ellipse cx="348.60911" cy="642.5" fill="#2f2e41" rx="20" ry="7.5" />
+    <circle cx="318.60911" cy="518" fill="#fff" r="27" />
+    <circle cx="318.60911" cy="518" fill="#3f3d56" r="9" />
+    <path
+      d="M271.36733,565.03228c-6.37889-28.56758,14.01185-57.43392,45.544-64.47477s62.2651,10.41,68.644,38.9776-14.51861,39.10379-46.05075,46.14464S277.74622,593.59986,271.36733,565.03228Z"
+      fill="#6c63ff"
+      transform="translate(-31.39089 -100.5)"
+    />
+    <ellipse
+      cx="417.21511"
+      cy="611.34365"
+      fill="#2f2e41"
+      rx="39.5"
+      ry="12.40027"
+      transform="translate(-238.28665 112.98044) rotate(-23.17116)"
+    />
+    <ellipse
+      cx="269.21511"
+      cy="664.34365"
+      fill="#2f2e41"
+      rx="39.5"
+      ry="12.40027"
+      transform="translate(-271.07969 59.02084) rotate(-23.17116)"
+    />
+    <path
+      d="M394,661.5c0,7.732-19.90861,23-42,23s-43-14.268-43-22,20.90861-6,43-6S394,653.768,394,661.5Z"
+      fill="#fff"
+      transform="translate(-31.39089 -100.5)"
+    />
+  </svg>
+</template>
diff --git a/code/g3soft-libs/packages/ui/src/result/icons/IconEmpty.vue b/code/g3soft-libs/packages/ui/src/result/icons/IconEmpty.vue
new file mode 100644
index 00000000..db955b1c
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/result/icons/IconEmpty.vue
@@ -0,0 +1,46 @@
+<template>
+  <!--
+    空状态插图 —— 与其他四张缺省图同风格（浅灰底 + 主色点缀）。
+    自绘而非引入外部资源：保持四个文件的零依赖、可离线。
+  -->
+  <svg viewBox="0 0 586 400" xmlns="http://www.w3.org/2000/svg" role="img" aria-hidden="true">
+    <!-- 背景圆 -->
+    <circle cx="293" cy="176" r="150" fill="#f2f2f2" />
+
+    <!-- 纸张：向左上掀起一角 -->
+    <path
+      d="M186 96h164l50 50v158a10 10 0 0 1-10 10H186a10 10 0 0 1-10-10V106a10 10 0 0 1 10-10z"
+      fill="#fff"
+    />
+    <path d="M350 96l50 50h-40a10 10 0 0 1-10-10V96z" fill="#e6e6e6" />
+
+    <!-- 内容行：长短相间，暗示"本来是列表但为空" -->
+    <rect x="206" y="146" width="160" height="10" rx="5" fill="#e6e6e6" />
+    <rect x="206" y="176" width="120" height="10" rx="5" fill="#ececec" />
+    <rect x="206" y="206" width="140" height="10" rx="5" fill="#ececec" />
+
+    <!-- 主色放大镜：点明"没找到 / 没有数据" -->
+    <g transform="translate(342 214)">
+      <circle
+        cx="0"
+        cy="0"
+        r="30"
+        fill="#fff"
+        stroke="var(--g3-color-primary, #18181b)"
+        stroke-width="7"
+      />
+      <line
+        x1="21"
+        y1="21"
+        x2="46"
+        y2="46"
+        stroke="var(--g3-color-primary, #18181b)"
+        stroke-width="10"
+        stroke-linecap="round"
+      />
+    </g>
+
+    <!-- 地面阴影 -->
+    <ellipse cx="293" cy="346" rx="150" ry="14" fill="#ececec" />
+  </svg>
+</template>
diff --git a/code/g3soft-libs/packages/ui/src/result/icons/IconOffline.vue b/code/g3soft-libs/packages/ui/src/result/icons/IconOffline.vue
new file mode 100644
index 00000000..5e6530c3
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/result/icons/IconOffline.vue
@@ -0,0 +1,101 @@
+<template>
+  <svg
+    height="458.68642"
+    viewBox="0 0 656 458.68642"
+    width="656"
+    xmlns="http://www.w3.org/2000/svg"
+    xmlns:xlink="http://www.w3.org/1999/xlink"
+  >
+    <rect fill="#3f3d56" height="2" width="656" y="434.34322" />
+    <g>
+      <path
+        d="M471.97092,210.81397c-6.0733-36.41747-37.72842-64.16942-75.86423-64.16942H240.14931c-38.12099,0-69.76869,27.72972-75.86421,64.12497-.70358,4.16241-1.06653,8.44331-1.06653,12.80573v135.88599c0,4.36237,.36295,8.63589,1.06653,12.79831,4.85126,28.99625,25.92996,52.49686,53.58563,60.84393,7.05095,2.13306,14.53143,3.28104,22.27859,3.28104h155.9574c7.74716,0,15.22763-1.14798,22.27859-3.28104,27.66309-8.35449,48.74921-31.86993,53.58563-60.88837,.6962-4.14758,1.05911-8.40628,1.05911-12.75388V223.57525c0-4.34758-.36292-8.61369-1.05911-12.76128h-.00003Zm-62.66592,222.28954c-4.2883,.76285-8.69516,1.16281-13.19827,1.16281H240.14931c-4.50313,0-8.90997-.39999-13.19829-1.16281-35.01768-6.22885-61.60677-36.83228-61.60677-73.64224v-45.10526c0-127.45004,103.31242-165.58582,230.76244-165.58582,41.31314,0,74.80505,33.49194,74.80505,74.80505v135.88599c-100.29059,13.42047-26.58911,67.41339-61.60678,73.64224l.00003,.00003Z"
+        fill="#3f3d56"
+      />
+      <polygon
+        fill="var(--g3-color-primary, #165dff)"
+        points="349.16196 249.18644 355.16196 288.18642 443.16196 276.18642 434.66196 230.6195 349.16196 249.18644"
+      />
+      <rect fill="#2f2e41" height="37.66125" width="36.38461" x="381.84177" y="30.34218" />
+      <polygon
+        fill="#ffb6b6"
+        points="385.16196 70.18643 394.16196 43.18643 411.70447 43.18643 412.62653 70.18643 385.16196 70.18643"
+      />
+      <polygon
+        isolation="isolate"
+        opacity=".1"
+        points="385.16196 70.18643 394.16196 43.18643 411.70447 43.18643 412.62653 70.18643 385.16196 70.18643"
+      />
+      <path
+        d="M394.66196,310.68642l-1,104-1,8v11.48425l15,1.51575,1-23s16-45,12-80-2-25-2-25l-24,3Z"
+        fill="#ffb6b6"
+      />
+      <path
+        d="M404.18408,318.85363l-36.90134,97.23831-1.97873,7.81567-4.1777,10.69742-14.52368-4.04477,7.43539-21.78796s1.46619-47.7373,17.92432-78.88422,10.9574-22.5596,10.9574-22.5596l21.26434,11.52512v.00003Z"
+        fill="#ffb6b6"
+      />
+      <path
+        d="M385.16196,67.18643l-27,12,17.23959,89.01208-2.72385,127.75565-18,38s-3.01575,21.73227,27.98425,7.73227,66-18,66-18l-8.5-58.5-7.5-153.5,1-34-22-14s-26.5,3.5-26.5,3.50001Z"
+        fill="#2f2e41"
+      />
+      <path
+        d="M370.1243,335.34322l-29.96231-50.15677,34.23959-116.98792-16.23959-89.01208,28.49045-12.19685s14.74915,14.36248,14.74915,26.20894-31.27728,242.1447-31.27728,242.1447v-.00003Z"
+        fill="#e6e6e6"
+      />
+      <path
+        d="M435.1243,325.34322l-27.19693-233.62811c-.34341-2.94999,.16013-5.93678,1.45178-8.6111l7.78284-16.11441,30.5,8.69685-12.26041,95.51208,32.76041,93.98792-33.03769,60.15677Z"
+        fill="#e6e6e6"
+      />
+      <path
+        d="M410.66196,433.68642s-19-11-21-5-3,11-3,11c0,0-5,19,10,19s14-8.64172,14-8.64172v-16.35828Z"
+        fill="#2f2e41"
+      />
+      <path
+        d="M344.53574,427.60598s21.69977-3.33459,21.3801,2.9819c-.3197,6.31647-1.20709,11.33768-1.20709,11.33768,0,0-2.25433,19.51712-16.22662,14.06046s-9.89713-13.14252-9.89713-13.14252l5.95078-15.23749-.00003-.00003Z"
+        fill="#2f2e41"
+      />
+      <circle cx="404.10297" cy="33.02146" fill="#ffb6b6" r="24.85993" />
+      <path
+        d="M423.96469,10.86766c-1.15707-6.12936-7.44913-10.27514-13.66504-10.79501s-12.30453,1.82726-17.90228,4.57921c-3.79456,1.86548-7.53061,3.96811-10.60425,6.87182s-5.46063,6.69692-6.01202,10.88913c-.19507,1.48324-.1698,3.03289-.77692,4.40016-.75845,1.708-2.38654,2.86795-3.36917,4.4576-1.76227,2.85096-.95267,6.99858,1.75238,8.97753-3.40024,1.44912-6.89398,2.96069-9.48602,5.59563s-4.08878,6.70308-2.66644,10.11462c.50323,1.20699,1.33481,2.26349,1.76489,3.49843,.81668,2.34499,.03943,5.00909-1.40924,7.02585s-3.49316,3.51228-5.50174,4.97226c5.16196,1.01177,10.43097,1.80015,15.66992,1.32811s10.49707-2.30805,14.29086-5.95176c3.79379-3.64371,5.88083-9.26437,4.51974-14.34539-1.04269-3.89231-3.95898-7.30301-3.95712-11.33256,.00143-3.09747,1.7431-5.89158,3.4249-8.49271,3.67291-5.68066,7.34579-11.36132,11.01868-17.04197,.66068-1.02183,1.35739-2.07924,2.4014-2.70425,1.77606-1.06326,4.0798-.59568,5.95227,.28683,1.87244,.88252,3.58304,2.14867,5.57941,2.69585,4.07452,1.11677,8.80106-1.44789,10.08575-5.47261"
+        fill="#2f2e41"
+      />
+      <path
+        d="M409.27951,61.42523c-2.07159,2.0061-5.05701,2.65225-7.82379,3.46516s-5.70978,2.09141-6.95499,4.69243c-1.22101,2.55043-.33459,5.78793,1.68692,7.76505s4.95816,2.80999,7.78555,2.77077c2.82736-.03922,5.58282-.86796,8.24176-1.8301,7.27054-2.63087,14.15665-6.32148,20.37314-10.919-4.02679-1.11411-6.66107-5.81614-5.50836-9.83205,.93768-3.26677,3.80499-5.54528,5.75616-8.32809,3.35959-4.79151,3.91925-11.10753,2.80676-16.85277-1.11246-5.74524-3.73163-11.07097-6.32358-16.3176-.81934-1.65853-1.65805-3.34513-2.93619-4.68245-1.27814-1.33731-3.08783-2.29539-4.92776-2.10379-3.05334,.31795-5.00302,3.66989-5.02377,6.7397s1.32593,5.95491,2.34732,8.84988c1.05231,2.98259,1.78381,6.14409,1.50146,9.29425-.2366,2.63989-1.19669,5.21132-2.74811,7.36029-1.19809,1.65954-2.72479,3.05223-4.0275,4.63097-1.00714,1.22055-1.90009,2.60309-2.16486,4.16321-.48181,2.83914,1.18356,5.71186,.72714,8.55519-.48248,3.0056-3.6452,5.3067-6.65341,4.84085"
+        fill="#2f2e41"
+      />
+      <g>
+        <circle cx="333.2486" cy="323.64455" fill="var(--g3-color-primary, #165dff)" r="85" />
+        <g>
+          <path
+            d="M384.17838,316.82296h-10.56668c-1.64377-9.68713-6.7168-18.46011-14.2923-24.71729-17.43427-14.39993-43.24109-11.94022-57.64099,5.49411-.04913,.05563-.09644,.11282-.14169,.17151-1.15063,1.49146-.87427,3.63333,.61716,4.784,1.49118,1.1507,3.63306,.87448,4.78394-.61697,6.25537-7.5788,15.72369-12.40167,26.31064-12.40167,16.20853,.00195,30.17899,11.40631,33.42572,27.28629h-9.31805c-.3988,.00012-.78458,.13992-1.09082,.39502-.72375,.60281-.82175,1.6781-.21915,2.40186l13.41125,16.09894c.06577,.07889,.13855,.1517,.21759,.21747,.72324,.60327,1.79871,.50583,2.40186-.21747l13.41125-16.09894c.25504-.30624,.3949-.69223,.39514-1.09082,.00027-.94186-.763-1.70566-1.70486-1.70605v.00003Z"
+            fill="#fff"
+          />
+          <path
+            d="M364.34329,344.7337c-1.49146-1.15063-3.63333-.87433-4.78394,.6171-4.96201,6.00781-11.83066,10.13629-19.46436,11.69922-18.46167,3.77988-36.49231-8.12213-40.27225-26.58392h9.3183c.94186-.0004,1.70514-.76419,1.70486-1.70605-.00027-.39853-.14011-.78452-.39514-1.09082l-13.41125-16.09888c-.60312-.72336-1.67862-.8208-2.40186-.21753-.07904,.06577-.15182,.13855-.21759,.21753l-13.41125,16.09888c-.6026,.72375-.50461,1.7991,.21915,2.40186,.30624,.25516,.69205,.3949,1.09082,.39502h10.56641c1.64404,9.68723,6.7168,18.46011,14.29254,24.71729,17.43427,14.39999,43.24109,11.94022,57.64099-5.49405,.04913-.05569,.09619-.11295,.14142-.17163,1.15088-1.49146,.87454-3.63327-.61691-4.784h.00006Z"
+            fill="#fff"
+          />
+        </g>
+      </g>
+      <path
+        id="uuid-da16df1e-5659-4232-96f6-61e8c639a9ec-574"
+        d="M356.98148,237.19363c-1.02939,7.36621-5.66458,12.80598-10.35239,12.15012-4.68781-.65588-7.65225-7.15837-6.62149-14.52707,.37137-2.94914,1.4436-5.76646,3.12701-8.21626l4.75577-31.15587,14.57297,2.54338-6.23553,30.44414c.94736,2.81844,1.20581,5.82278,.75369,8.76157h-.00003Z"
+        fill="#ffb6b6"
+      />
+      <path
+        d="M369.66196,77.68643s-15-5-17,13-4,39.99999-4,39.99999c0,0-9,21-5,32s11,3.3307,4,12.66534-6.02478,40.04724-6.02478,40.04724l22.52478-1.13387s12.5-82.57875,12.5-84.57875-7-52-7-52v.00004Z"
+        fill="#e6e6e6"
+      />
+      <g>
+        <path
+          id="uuid-6bf35aa9-e432-4b51-af77-8f4eb19e6e42-575"
+          d="M467.16132,233.84998c.27881,7.43257-3.33017,13.60114-8.06033,13.7778s-8.78937-5.70491-9.06732-13.14017c-.15176-2.96857,.40961-5.93028,1.63712-8.63741l-.78369-31.507,14.79315-.05261-.798,31.0659c1.42709,2.60854,2.20859,5.52095,2.27905,8.49347l.00003,.00002Z"
+          fill="#ffb6b6"
+        />
+        <path
+          d="M444.06961,77.34876s15.08694-4.73121,16.76505,13.30165,3.28473,51.06508,3.28473,51.06508c0,0,8.62338,21.15744,4.42749,32.08421s-11.05774,3.13365-4.22565,12.59187c6.83212,9.45822,4.37997,36.13126,4.37997,36.13126l-22.50095-1.53612s-10.09427-78.77167-10.05853-80.77133,7.92792-62.86664,7.92792-62.86664l-.00003,.00002Z"
+          fill="#e6e6e6"
+        />
+      </g>
+    </g>
+  </svg>
+</template>
diff --git a/code/g3soft-libs/packages/ui/src/result/index.ts b/code/g3soft-libs/packages/ui/src/result/index.ts
new file mode 100644
index 00000000..1e9ec5cc
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/result/index.ts
@@ -0,0 +1,2 @@
+export { default as G3Result } from './Result.vue'
+export type { ResultAlign, ResultProps, ResultStatus } from './types'
diff --git a/code/g3soft-libs/packages/ui/src/result/types.ts b/code/g3soft-libs/packages/ui/src/result/types.ts
new file mode 100644
index 00000000..7e5117d7
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/result/types.ts
@@ -0,0 +1,19 @@
+/** 缺省状态。图标与默认文案由该值决定。 */
+export type ResultStatus = '403' | '404' | '500' | 'offline' | 'empty'
+
+/** Result 内容区的对齐方式 */
+export type ResultAlign = 'center' | 'start'
+
+export interface ResultProps {
+  /**
+   * 预设状态：决定图标与默认标题 / 描述（文案走 locale）。
+   * 不传时只有 #icon 插槽生效，即纯自定义形态。
+   */
+  status?: ResultStatus
+  /** 标题。不传时取 status 对应的默认文案（走 locale） */
+  title?: string
+  /** 描述。不传时取 status 对应的默认文案（走 locale） */
+  desc?: string
+  /** 内容对齐，默认居中（缺省页形态）；start 适合嵌在卡片里的空状态 */
+  align?: ResultAlign
+}
diff --git a/code/g3soft-libs/packages/ui/src/rich-text/RichText.vue b/code/g3soft-libs/packages/ui/src/rich-text/RichText.vue
new file mode 100644
index 00000000..98dba6e9
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/rich-text/RichText.vue
@@ -0,0 +1,593 @@
+<script setup lang="ts">
+import { computed, onBeforeUnmount, ref, watch } from 'vue'
+import { EditorContent, useEditor } from '@tiptap/vue-3'
+import { columnResizingPluginKey, TableMap } from '@tiptap/pm/tables'
+import type { Node as ProseMirrorNode } from '@tiptap/pm/model'
+import { useLocale } from '../_composables/useLocale'
+import { useNamespace } from '../_composables/useNamespace'
+import { createExtensions, DEFAULT_FONTS, DEFAULT_FONT_SIZES } from './extensions'
+import type { RichTextEmits, RichTextExpose, RichTextProps, RichTextUploadResult } from './types'
+import TableMenu from './TableMenu.vue'
+import Toolbar from './Toolbar.vue'
+import type { UploadHandlers } from './upload'
+
+/**
+ * 富文本编辑器 —— 基于 Tiptap，输出干净 HTML。
+ *
+ * - v-model 输出 HTML 字符串（邮件正文等场景直接取用）；
+ * - 图片 / 视频通过 uploadImage / uploadVideo 钩子上传，完成后 emit('upload-inline')
+ *   把内联资源元数据上报给外层（对齐邮件「inline 附件」模型，见 Email-Vue）；
+ * - 字体 / 字号 / 上标 / 下标 / 表格 / 撤销重做内置；不含代码块。
+ */
+defineOptions({ name: 'G3RichText' })
+
+const props = withDefaults(defineProps<RichTextProps>(), {
+  modelValue: '',
+  placeholder: '',
+  disabled: false,
+  readonly: false,
+  toolbar: 'top',
+  minHeight: 200,
+  maxHeight: undefined,
+  uploadImage: undefined,
+  uploadVideo: undefined,
+  fonts: () => DEFAULT_FONTS,
+  fontSizes: () => DEFAULT_FONT_SIZES,
+})
+
+const emit = defineEmits<RichTextEmits>()
+
+const { b, e, m, is } = useNamespace('rich-text')
+const locale = useLocale()
+
+const mergedFonts = computed(() => props.fonts ?? DEFAULT_FONTS)
+const mergedFontSizes = computed(() => props.fontSizes ?? DEFAULT_FONT_SIZES)
+
+/** 上传回调集：注入 Toolbar / upload 逻辑 */
+const handlers: UploadHandlers = {
+  uploadImage: props.uploadImage,
+  uploadVideo: props.uploadVideo,
+  onInline: (result: RichTextUploadResult, kind: 'image' | 'video') => {
+    emit('upload-inline', result, kind)
+  },
+  onError: (error: Error, kind: 'image' | 'video') => {
+    emit('upload-error', error, kind)
+  },
+}
+
+const editor = useEditor({
+  content: props.modelValue,
+  // 注意：这里故意恒为 true 创建，而不是直接用目标 editable 状态。
+  // Tiptap 在创建时用 isEditable 决定是否注册 columnResizing（列宽拖拽）插件，
+  // 而 setEditable 只切换 view 状态、不重建插件 —— 初始 disabled / readonly 的
+  // 编辑器即使后来恢复可编辑，列宽拖拽也永远不存在。先按可编辑创建拿到完整
+  // 插件集，再立即降级到目标状态（见下方 setEditable 调用）。
+  editable: true,
+  extensions: createExtensions({
+    placeholder: props.placeholder,
+    uploadImage: props.uploadImage,
+    uploadVideo: props.uploadVideo,
+  }),
+  onUpdate: ({ editor }) => {
+    const html = editor.getHTML()
+    emit('update:modelValue', html)
+    emit('change', html)
+  },
+  onFocus: ({ event }) => emit('focus', event),
+  onBlur: ({ event }) => emit('blur', event),
+})
+
+/* ---------- 列宽归一化：拖拽结束 / 插入表格后固化整表列宽 ---------- */
+// 背景：prosemirror-tables 的 columnResizing 在拖拽结束时只把「被拖那一列」的宽度写回
+// colwidth，其余列保持无宽度。配合 table-layout: fixed，未设宽度的列会平分剩余空间，
+// 于是拖第 2/3 列分隔线时，第 1 列（无宽度）会被动伸缩 —— 需求要求「只有相邻列变、
+// 其余列纹丝不动」。
+//
+// 解法：在「插入表格」（尚无任何 colwidth）与「拖拽结束」（dragging 从有 → 无）两个
+// 时机，读取所有列的实际渲染宽度，一次性写回整表每个单元格的 colwidth，让每列都有
+// 明确宽度。之后 fixed 布局下每次拖拽只动被拖列，其余列严格隔离。
+
+/** 记录上一次 transaction 时是否处于列宽拖拽中，用于识别「拖拽结束」沿 */
+let wasDragging = false
+
+/** 是否正在等待一次待执行的归一化（rAF 去抖，避免同帧多次调度） */
+let normalizationScheduled = false
+
+/**
+ * 把当前表格所有列的实际渲染宽度写回 colwidth。
+ * @param tablePos table 节点在文档中的内容区起点（绝对位置）
+ */
+function writeRenderedColumnWidths(tablePos: number): void {
+  const instance = editor.value
+  if (!instance) return
+  const view = instance.view
+  const tableEl = view.dom.querySelector('table')
+  if (!tableEl) return
+
+  const cols = Array.from(tableEl.querySelectorAll<HTMLTableColElement>('colgroup > col'))
+  if (cols.length === 0) return
+
+  const found = findTableAt(tablePos)
+  if (!found) return
+  const tableNode = found.node
+
+  const map = TableMap.get(tableNode as never)
+  const widths = cols.map((col) => {
+    // 优先取内联 width（拖拽时 prosemirror 写的是 style.width），否则取实测宽度
+    const inline = parseFloat(col.style.width)
+    if (!Number.isNaN(inline) && inline > 0) return Math.round(inline)
+    return Math.round(col.getBoundingClientRect().width)
+  })
+
+  const tr = view.state.tr
+  for (let row = 0; row < map.height; row++) {
+    for (let col = 0; col < map.width; col++) {
+      const cellPos = map.map[row * map.width + col]
+      if (row && cellPos === map.map[(row - 1) * map.width + col]) continue // 跨行合并跳过
+      const cellNode = tableNode.nodeAt(cellPos)
+      if (!cellNode) continue
+      const colwidth = widths.slice(col, col + cellNode.attrs.colspan)
+      tr.setNodeMarkup(tablePos + cellPos, null, { ...cellNode.attrs, colwidth })
+    }
+  }
+  if (tr.docChanged) view.dispatch(tr)
+}
+
+/** 从文档某位置向上定位所属 table 节点；找不到返回 null */
+function findTableAt(pos: number): { node: ProseMirrorNode; depth: number } | null {
+  const instance = editor.value
+  if (!instance) return null
+  const resolved = instance.view.state.doc.resolve(pos)
+  for (let depth = resolved.depth; depth > 0; depth--) {
+    if (resolved.node(depth).type.name === 'table') {
+      return { node: resolved.node(depth), depth }
+    }
+  }
+  return null
+}
+
+/** 从文档某位置向上定位所属 table 节点的内容区起点（找不到返回 -1） */
+function tablePosAround(pos: number): number {
+  const instance = editor.value
+  if (!instance) return -1
+  const resolved = instance.view.state.doc.resolve(pos)
+  for (let depth = resolved.depth; depth > 0; depth--) {
+    if (resolved.node(depth).type.name === 'table') return resolved.start(depth)
+  }
+  return -1
+}
+
+/** 检查某张表是否「任何一列都没有 colwidth」（即刚插入、从未归一化过） */
+function tableNeedsInit(tablePos: number): boolean {
+  const found = findTableAt(tablePos)
+  if (!found) return false
+  const tableNode = found.node
+  const firstRow = tableNode.firstChild
+  if (!firstRow) return false
+  for (let i = 0; i < firstRow.childCount; i++) {
+    if (firstRow.child(i).attrs.colwidth) return false
+  }
+  return true
+}
+
+function scheduleColumnWidthNormalization(): void {
+  if (normalizationScheduled) return
+  normalizationScheduled = true
+  // 等 DOM 更新（transaction 已提交、表格按新列宽重排）后再读实际宽度
+  requestAnimationFrame(() => {
+    normalizationScheduled = false
+    const instance = editor.value
+    if (!instance || instance.isDestroyed) return
+
+    // 拖拽结束时选区仍在表格内，从这里定位 table
+    const pos = instance.view.state.selection.from
+    const tablePos = tablePosAround(pos)
+    if (tablePos < 0) return
+    writeRenderedColumnWidths(tablePos)
+  })
+}
+
+function onEditorTransaction(): void {
+  const instance = editor.value
+  if (!instance) return
+
+  const pluginState = columnResizingPluginKey.getState(instance.view.state)
+  const dragging = !!(pluginState && (pluginState as { dragging?: unknown }).dragging)
+  const justFinished = wasDragging && !dragging
+  wasDragging = dragging
+
+  if (justFinished) {
+    scheduleColumnWidthNormalization()
+    return
+  }
+
+  // 插入表格（或粘贴 / setContent 进来的表）尚未归一化：首次进入时给所有列等分固化为 colwidth
+  const pos = instance.view.state.selection.from
+  const tablePos = tablePosAround(pos)
+  if (tablePos >= 0 && tableNeedsInit(tablePos)) {
+    scheduleColumnWidthNormalization()
+  }
+}
+
+watch(editor, (instance, oldInstance) => {
+  oldInstance?.off('transaction', onEditorTransaction)
+  if (!instance) return
+  instance.on('transaction', onEditorTransaction)
+})
+
+/* ---------- disabled / readonly 同步 ---------- */
+// 编辑器实例在 onMounted 才创建（@tiptap/vue-3 的 useEditor 行为），
+// 初始 editable 状态必须等实例出现后再应用。
+watch(
+  editor,
+  (instance) => {
+    if (!instance) return
+    instance.setEditable(!props.disabled && !props.readonly, false)
+  },
+  { immediate: true },
+)
+
+// 运行中切换 disabled / readonly
+watch(
+  () => [props.disabled, props.readonly],
+  ([disabled, readonly]) => {
+    editor.value?.setEditable(!disabled && !readonly)
+  },
+)
+
+/* ---------- v-model 受控同步（外部值 → 编辑器） ---------- */
+watch(
+  () => props.modelValue,
+  (value) => {
+    if (!editor.value) return
+    // 避免「编辑器内部更新 → emit → 回写 → 再次 setContent」的循环
+    if (editor.value.getHTML() === value) return
+    editor.value.commands.setContent(value, { emitUpdate: false })
+  },
+)
+
+onBeforeUnmount(() => {
+  editor.value?.destroy()
+})
+
+/* ---------- 内容区空白处聚焦 ---------- */
+/**
+ * 点内容区里「编辑器 DOM 之外」的空白也要能编辑。
+ *
+ * 布局上可编辑区已撑满内容区（见 `.g3-rich-text__editable`），正常情况下点哪儿都在
+ * `.tiptap` 里、由 ProseMirror 自己按坐标定位光标。这里兜的是剩余情形：宿主样式把
+ * 撑高改掉了、或内容区因为其它原因比可编辑区高出一块 —— 落在编辑器 DOM 之外的
+ * mousedown 手动聚焦，并把光标放到正文末尾。
+ */
+function onContentMousedown(event: MouseEvent): void {
+  const instance = editor.value
+  if (!instance || instance.isDestroyed || !instance.isEditable) return
+  const target = event.target as Node | null
+  // 编辑器内部的点击交给 ProseMirror：它要按坐标定位光标、跨块拖选、点链接等
+  if (target && instance.view.dom.contains(target)) return
+  // 不 preventDefault 的话浏览器会先在内容区起一个原生选区，聚焦时闪一下
+  event.preventDefault()
+  instance.chain().focus('end').run()
+}
+
+/* ---------- 暴露 ---------- */
+function getHTML(): string {
+  return editor.value?.getHTML() ?? ''
+}
+function getText(): string {
+  return editor.value?.getText() ?? ''
+}
+function focus(): void {
+  editor.value?.commands.focus()
+}
+function clear(): void {
+  editor.value?.commands.clearContent()
+}
+
+defineExpose<RichTextExpose>({
+  editor: editor as unknown as RichTextExpose['editor'],
+  getHTML,
+  getText,
+  focus,
+  clear,
+})
+
+const classes = computed(() => [
+  b(),
+  {
+    [m('disabled')]: props.disabled,
+    [m('readonly')]: props.readonly,
+    [m(`toolbar-${props.toolbar}`)]: props.toolbar !== false,
+  },
+])
+
+const showToolbar = computed(() => props.toolbar !== false && !!editor.value)
+
+const contentStyle = computed(() => ({
+  minHeight: typeof props.minHeight === 'number' ? `${props.minHeight}px` : props.minHeight,
+  maxHeight: props.maxHeight
+    ? typeof props.maxHeight === 'number'
+      ? `${props.maxHeight}px`
+      : props.maxHeight
+    : undefined,
+}))
+</script>
+
+<template>
+  <div :class="classes">
+    <!-- 工具条：上 / 下 -->
+    <Toolbar
+      v-if="showToolbar && toolbar === 'top'"
+      :editor="editor!"
+      :fonts="mergedFonts"
+      :font-sizes="mergedFontSizes"
+      :handlers="handlers"
+      placement="top"
+    />
+
+    <div :class="e('content')" :style="contentStyle" @mousedown="onContentMousedown">
+      <!-- 给 EditorContent 的根 div 挂类名：它夹在内容区与 .tiptap 之间，
+           不显式命名就只能靠 `> div` 这种结构选择器去撑高 -->
+      <EditorContent :editor="editor!" :class="e('editable')" />
+    </div>
+
+    <TableMenu :editor="editor" />
+
+    <Toolbar
+      v-if="showToolbar && toolbar === 'bottom'"
+      :editor="editor!"
+      :fonts="mergedFonts"
+      :font-sizes="mergedFontSizes"
+      :handlers="handlers"
+      placement="bottom"
+    />
+  </div>
+</template>
+
+<style lang="scss">
+@use '@g3soft/tokens/scss' as *;
+
+.#{b('rich-text')} {
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+  border: 1px solid v('border-color', #d9d9d9);
+  border-radius: v('radius', 6px);
+  background: v('bg-container', #fff);
+  color: v('text-1', rgba(0, 0, 0, 0.88));
+  font-size: v('font-size', 14px);
+  line-height: v('line-height', 1.5);
+
+  &.#{m('rich-text', 'disabled')} {
+    background: v('bg-disabled', rgba(0, 0, 0, 0.04));
+    color: v('text-disabled', rgba(0, 0, 0, 0.25));
+    cursor: not-allowed;
+  }
+}
+
+/**
+ * 聚焦高亮：编辑器拿到焦点时，只在正文区四周描一圈 2px 主色，工具条不参与 ——
+ * 与 TinyMCE 给 `.tox-edit-area` 做激活反馈是同一个目的（谁可编辑，谁亮）。
+ *
+ * 三个实现细节都跟直觉不同，都是有原因的：
+ * - 用 `inset` box-shadow 而不是 `border`：边框参与布局，聚焦时正文会被挤动一格；
+ * - 也不用 `::after` 覆盖层（TinyMCE 的写法）：正文区本身就是滚动容器，
+ *   绝对定位的伪元素会跟着正文一起滚走，滚一下高亮环就没了；
+ *   而滚动容器的背景 / 阴影不随内容滚动，天然钉在内容盒上；
+ * - 触发条件是根节点的 `:focus-within` 而不是内容区自己的：点工具条按钮时焦点临时
+ *   落在按钮上，挂内容区会在「按下 → 命令回焦」之间闪一下，挂根上则全程常亮。
+ */
+.#{b('rich-text')}:focus-within .#{e('rich-text', 'content')} {
+  box-shadow: inset 0 0 0 2px v('color-primary', #18181b);
+}
+
+.#{e('rich-text', 'content')} {
+  display: flex;
+  flex: 1;
+  flex-direction: column;
+  min-height: 0;
+  overflow-y: auto;
+  /* 与外框那 1px 边框同心：内描边要跟着圆角拐，半径只小 1px */
+  border-radius: calc(#{v('radius', 6px)} - 1px);
+  transition: box-shadow v('duration', 0.2s) v('ease', ease);
+
+  /**
+   * EditorContent 的根 div —— 夹在内容区与可编辑区（`.tiptap`）之间的一层包裹 DOM。
+   *
+   * 让它跟 `.tiptap` 一起撑满内容区，是为了让「内容区」与「可编辑区」重合，
+   * 而不是靠 `.tiptap` 上的 `min-height: inherit`：inherit 取的是这一层的 computed
+   * 值（恒为 0 / none，与 minHeight / maxHeight 两个 prop 无关），于是可编辑区只跟
+   * 内容一样高，空文档时内容区下方会空出一大块「点上去既不聚焦也不落光标」的死区。
+   *
+   * 两层都用 `flex: 1 0 auto`：内容短时撑满内容区（整块都是可编辑区），内容长时
+   * 按内容高度撑开、由内容区滚动 —— 不允许收缩，否则正文会被裁掉。
+   */
+  .#{e('rich-text', 'editable')} {
+    display: flex;
+    flex: 1 0 auto;
+    flex-direction: column;
+  }
+
+  .tiptap {
+    flex: 1 0 auto;
+    /* 上下也要留白：否则首个块若没有 UA 外边距（表格 / 图片 / 视频 / 分割线）就会贴顶，
+       而段落靠 UA margin 穿透撑出间距 —— 同一位置两类块表现不一致 */
+    padding: v('space-3', 12px);
+    outline: none;
+    /* 长串（URL / 无空格文本）允许在任意位置断行：
+       既避免正文被撑出横向滚动，也避免表格列被长内容撑宽（auto 布局按内容最小宽度分配） */
+    overflow-wrap: anywhere;
+
+    > * + * {
+      margin-top: 0.75em;
+    }
+
+    /* 首 / 末块去掉外边距，避免与容器内边距叠加，顶部（底部）间距统一为内边距值 */
+    > :first-child {
+      margin-top: 0;
+    }
+
+    > :last-child {
+      margin-bottom: 0;
+    }
+
+    /* 悬停 / 拖拽列宽分隔线时，prosemirror-tables 会给编辑器根节点加 .resize-cursor */
+    &.resize-cursor {
+      cursor: col-resize;
+    }
+
+    /* 基础排版，让编辑器输出与渲染一致 */
+    h1 {
+      font-size: 2em;
+      font-weight: 600;
+      line-height: 1.3;
+    }
+    h2 {
+      font-size: 1.5em;
+      font-weight: 600;
+      line-height: 1.3;
+    }
+    h3 {
+      font-size: 1.25em;
+      font-weight: 600;
+      line-height: 1.3;
+    }
+
+    ul,
+    ol {
+      padding-inline-start: 1.5em;
+    }
+
+    blockquote {
+      border-inline-start: 2px solid v('color-primary', #18181b);
+      margin: 1em 0;
+      padding-inline-start: 1em;
+      color: v('text-2', rgba(0, 0, 0, 0.65));
+    }
+
+    a {
+      color: v('color-primary', #18181b);
+      text-decoration: underline;
+    }
+
+    img {
+      max-width: 100%;
+      height: auto;
+      border-radius: v('radius-sm', 4px);
+
+      &.ProseMirror-selectednode {
+        outline: 2px solid v('color-primary', #18181b);
+      }
+    }
+
+    video {
+      max-width: 100%;
+      border-radius: v('radius-sm', 4px);
+
+      &.ProseMirror-selectednode {
+        outline: 2px solid v('color-primary', #18181b);
+      }
+    }
+
+    /* 可拖拽表格的 <table> 被 Tiptap 包在 .tableWrapper 里：
+       列数极多、各列最小宽度之和超过容器时，让它在这一层横向滚动，
+       避免把横向滚动条带进编辑器内容区 */
+    .tableWrapper {
+      max-width: 100%;
+      overflow-x: auto;
+    }
+
+    table {
+      /* 显式重置，防止宿主页面的全局 table 样式侵入（如 VitePress `.vp-doc table`）：
+         宿主常把 table 设为 display:block 以便横向滚动，那会让表格退化为块级收缩布局，
+         网格宽度不再是 100% —— 这里复位 display 并清零 margin。 */
+      display: table;
+      /* 默认铺满容器。不用 !important：Tiptap 拖拽列宽时会给 <table> 写内联 width
+         （所有列都有明确宽度时 = 各列宽之和），让内联值覆盖这里的 100% ——
+         这样拖宽某列后表格总宽超过容器时，会在这层（而非内容区）横向滚动，
+         也就是 Excel 式「拖列宽只动相邻列、表格可变宽」的语义。 */
+      width: 100%;
+      min-width: 0;
+      margin: 0;
+      border-collapse: collapse;
+      /* 用 fixed 而非 auto：fixed 布局下列宽由 <col> 的宽度硬性决定，不受单元格内容影响。
+         这带来两个好处：
+         1. 拖拽列宽时只有相邻列变化、其余列纹丝不动（auto 会把「被拖列挤出的空间」按内容
+            重新摊给其它列，表现为拖第 2/3 列线时第 1 列被动变窄）；
+         2. 拖拽过程不触发整表内容重排（auto 每次 mousemove 都要重算所有列宽，很卡）。 */
+      table-layout: fixed;
+
+      /* 宿主常见的 `tr:nth-child(2n)` 斑马纹会染到表体行，这里复位为透明 */
+      tbody tr {
+        border: 0;
+        background: transparent;
+      }
+
+      th,
+      td {
+        /* 作为列宽拖拽手柄的定位参照（手柄是绝对定位元素，见下） */
+        position: relative;
+        border: 1px solid v('border-color', #d9d9d9);
+        padding: v('space-2', 8px);
+        vertical-align: top;
+        /* fixed 布局下单元格内容超宽会溢出单元格，这里裁剪并省略（而不是把列撑宽） */
+        overflow: hidden;
+
+        /* 单元格内容默认是 <p>，其 UA 上下外边距（各 1em）会把单行行高从 ~38px 撑到 ~66px —— 归零；
+           多个块之间只补 0.5em，避免内容粘在一起 */
+        > * {
+          margin: 0;
+        }
+
+        > * + * {
+          margin-top: 0.5em;
+        }
+      }
+
+      th {
+        background: v('fill', rgba(0, 0, 0, 0.04));
+        font-weight: 500;
+        text-align: start;
+      }
+
+      .selectedCell {
+        background: v('fill-hover', rgba(0, 0, 0, 0.08));
+      }
+
+      /* 列宽拖拽手柄（prosemirror-tables 注入的 widget）：必须脱离文档流，
+         否则它会作为单元格内的块级元素把行高撑高 —— 表现为「hover 分隔线时表头行高度闪烁」。
+         透明无视觉竖线，只靠 col-resize 光标提示（需求明确不要黑色竖线）。 */
+      .column-resize-handle {
+        position: absolute;
+        inset-block: 0;
+        inset-inline-end: -2px;
+        z-index: 1;
+        width: 4px;
+        background: transparent;
+        pointer-events: none;
+        /* prosemirror-tables 会给该列的「每一行」都插一个手柄，这里只在第一行（表头行）显示，
+           否则看起来是一列断开的短虚线 */
+        display: none;
+      }
+
+      tr:first-child .column-resize-handle {
+        display: block;
+      }
+    }
+
+    hr {
+      border: 0;
+      border-top: 1px solid v('border-color', #d9d9d9);
+      margin: 1em 0;
+    }
+
+    p.is-editor-empty:first-child::before {
+      content: attr(data-placeholder);
+      float: inline-start;
+      height: 0;
+      pointer-events: none;
+      color: v('text-3', rgba(0, 0, 0, 0.45));
+    }
+  }
+}
+</style>
diff --git a/code/g3soft-libs/packages/ui/src/rich-text/TableMenu.vue b/code/g3soft-libs/packages/ui/src/rich-text/TableMenu.vue
new file mode 100644
index 00000000..dec5504c
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/rich-text/TableMenu.vue
@@ -0,0 +1,454 @@
+<script setup lang="ts">
+import { h, onBeforeUnmount, ref, watch, type Component } from 'vue'
+import type { Editor } from '@tiptap/vue-3'
+import {
+  ArrowDownToLine,
+  ArrowLeftToLine,
+  ArrowRightToLine,
+  ArrowUpToLine,
+  BetweenHorizontalStart,
+  TableCellsMerge,
+  TableCellsSplit,
+  TableProperties,
+  Trash2,
+} from '@lucide/vue'
+import { G3Button } from '../button'
+import { G3Tooltip } from '../tooltip'
+import { nextZIndex, releaseZIndex } from '../_utils/z-index'
+import { useNamespace } from '../_composables/useNamespace'
+
+/**
+ * 表格操作浮层 —— 光标在表格内时，浮在表格下方的操作栏。
+ *
+ * 不复用顶部 Toolbar：表格操作就近出现在表格上下文，避免顶部工具条在
+ * 编辑表格时突然变长、跳动。定位靠表格 DOM 的 getBoundingClientRect 计算，
+ * 操作栏 fixed 定位于表格正下方（用 rAF 对齐渲染帧，避免读到未更新的布局）。
+ *
+ * 只放结构操作：行 / 列增删、单元格合并与拆分、表头列 / 表头单元格、删表。
+ * 文字与单元格对齐交给顶部工具条（单元格内容同样是 paragraph，对齐走 textAlign）。
+ */
+defineOptions({ name: 'G3RichTextTableMenu' })
+
+const props = defineProps<{ editor?: Editor }>()
+
+const { b, e } = useNamespace('rich-text-table-menu')
+
+interface TableAction {
+  label: string
+  icon: Component
+  action: () => void
+  disabled?: () => boolean
+}
+
+/** 当前 editor（用于 actions 内的命令执行；菜单可见时必存在） */
+function editor(): Editor {
+  return props.editor as Editor
+}
+
+/**
+ * 删除行 / 删除列的图标。
+ *
+ * lucide 没有「表格 + 删除」的现成图标 —— 只有 `table-rows-split` /
+ * `table-columns-split` 这类「拆分行列」的画法，拿来当删除用看不出语义
+ * （此前正是这么用的）。这里按 lucide 的规范手绘：左上角是表格，
+ * 横线表示行、竖线表示列，右下角一只 × 角标。
+ */
+function createTableDeleteIcon(orientation: 'row' | 'column'): Component {
+  return () =>
+    h(
+      'svg',
+      {
+        xmlns: 'http://www.w3.org/2000/svg',
+        viewBox: '0 0 24 24',
+        width: 24,
+        height: 24,
+        fill: 'none',
+        stroke: 'currentColor',
+        'stroke-width': 2,
+        'stroke-linecap': 'round',
+        'stroke-linejoin': 'round',
+      },
+      [
+        h('rect', { x: 2, y: 2, width: 11, height: 11, rx: 2 }),
+        h('path', { d: orientation === 'row' ? 'M2 7.5h11' : 'M7.5 2v11' }),
+        h('path', { d: 'm14 14 7 7' }),
+        h('path', { d: 'm21 14-7 7' }),
+      ],
+    )
+}
+
+const DeleteRowIcon = createTableDeleteIcon('row')
+const DeleteColumnIcon = createTableDeleteIcon('column')
+
+/**
+ * 表格操作分组：
+ * - 行：上插 / 下插 / 删行
+ * - 列：左插 / 右插 / 删列
+ * - 单元格：合并 / 拆分（两个独立按钮，各自按 can() 置灰）
+ * - 表头：切换表头列 / 表头单元格
+ * - 危险：删除表格（与增删行列用分隔线隔开，防误点）
+ */
+const actionGroups: TableAction[][] = [
+  [
+    {
+      label: '上方插入行',
+      icon: ArrowUpToLine,
+      action: () => editor().chain().focus().addRowBefore().run(),
+      disabled: () => !props.editor?.can().addRowBefore(),
+    },
+    {
+      label: '下方插入行',
+      icon: ArrowDownToLine,
+      action: () => editor().chain().focus().addRowAfter().run(),
+      disabled: () => !props.editor?.can().addRowAfter(),
+    },
+    {
+      label: '删除行',
+      icon: DeleteRowIcon,
+      action: () => editor().chain().focus().deleteRow().run(),
+      disabled: () => !props.editor?.can().deleteRow(),
+    },
+  ],
+  [
+    {
+      label: '左侧插入列',
+      icon: ArrowLeftToLine,
+      action: () => editor().chain().focus().addColumnBefore().run(),
+      disabled: () => !props.editor?.can().addColumnBefore(),
+    },
+    {
+      label: '右侧插入列',
+      icon: ArrowRightToLine,
+      action: () => editor().chain().focus().addColumnAfter().run(),
+      disabled: () => !props.editor?.can().addColumnAfter(),
+    },
+    {
+      label: '删除列',
+      icon: DeleteColumnIcon,
+      action: () => editor().chain().focus().deleteColumn().run(),
+      disabled: () => !props.editor?.can().deleteColumn(),
+    },
+  ],
+  [
+    {
+      label: '合并单元格',
+      icon: TableCellsMerge,
+      action: () => editor().chain().focus().mergeCells().run(),
+      disabled: () => !props.editor?.can().mergeCells(),
+    },
+    {
+      label: '拆分单元格',
+      icon: TableCellsSplit,
+      action: () => editor().chain().focus().splitCell().run(),
+      disabled: () => !props.editor?.can().splitCell(),
+    },
+  ],
+  [
+    {
+      label: '切换表头列',
+      icon: BetweenHorizontalStart,
+      action: () => editor().chain().focus().toggleHeaderColumn().run(),
+      disabled: () => !props.editor?.can().toggleHeaderColumn(),
+    },
+    {
+      label: '切换表头单元格',
+      icon: TableProperties,
+      action: () => editor().chain().focus().toggleHeaderCell().run(),
+      disabled: () => !props.editor?.can().toggleHeaderCell(),
+    },
+  ],
+  [
+    {
+      label: '删除表格',
+      icon: Trash2,
+      action: () => editor().chain().focus().deleteTable().run(),
+      disabled: () => !props.editor?.can().deleteTable(),
+    },
+  ],
+]
+
+/* ---------- 显示状态 + 定位 ---------- */
+const visible = ref(false)
+const menuStyle = ref<{ top: string; left: string; zIndex?: number }>({ top: '0px', left: '0px' })
+
+/** 层级：显示时从 popup 档位领取，隐藏即归还（与 Popover / Dropdown 同一套机制） */
+let menuZIndex = 0
+
+function acquireZIndex(): void {
+  if (!menuZIndex) menuZIndex = nextZIndex('popup')
+}
+
+function releaseMenuZIndex(): void {
+  if (menuZIndex) {
+    releaseZIndex(menuZIndex)
+    menuZIndex = 0
+  }
+}
+
+/** 向上找最近的「可纵向滚动」祖先元素（overflow-y 为 auto/scroll/overlay） */
+function findScrollContainer(start: HTMLElement): HTMLElement | null {
+  let el: HTMLElement | null = start.parentElement
+  while (el && el !== document.body && el !== document.documentElement) {
+    const { overflowY } = window.getComputedStyle(el)
+    if (overflowY === 'auto' || overflowY === 'scroll' || overflowY === 'overlay') {
+      return el
+    }
+    el = el.parentElement
+  }
+  return null
+}
+
+/** 判断当前选区是否在表格内（覆盖光标与 CellSelection 整行/整列两种选区） */
+function isCursorInTable(): boolean {
+  const editor = props.editor
+  if (!editor) return false
+  const selection = editor.state.selection
+  // 整行 / 整列多选时（CellSelection）isActive('table') 会返回 false，
+  // 但选区仍落在表格内 —— 用 $anchorCell 兜底（对齐 tiptap-vue-pro 的做法）。
+  const anySel = selection as unknown as { $anchorCell?: unknown }
+  if (anySel.$anchorCell) return true
+  return editor.isActive('table')
+}
+
+/**
+ * 找到当前表格的 DOM。
+ *
+ * 两个坑的解法：
+ * 1. nodeDOM(pos) 在 resizable 模式下返回 .tableWrapper（NodeView 包装），
+ *    内部结构随拖拽参数变化 —— 不用。
+ * 2. domAtPos(from).node 在光标落在单元格「文本内」时返回的是 **文本节点**
+ *    （TextViewDesc.domFromPos 返回 { node: textDOM }），文本节点没有
+ *    closest，直接调用会抛 TypeError「closest is not a function」——
+ *    这正是「在单元格里打字时浮层位置不刷新 / 控制台报错」的根因。
+ *    解法：nodeType 归一化，文本节点取 parentElement 再 closest。
+ */
+function findTableElement(): HTMLTableElement | null {
+  const editor = props.editor
+  if (!editor) return null
+  const view = editor.view
+  if (!view) return null
+
+  const selection = view.state.selection
+  // CellSelection：从锚点单元格的 DOM 反查（选区 from 是表格起点，closest 也能命中）
+  const pos = (selection as unknown as { $anchorCell?: { pos: number } }).$anchorCell
+    ? (selection as unknown as { $anchorCell: { pos: number } }).$anchorCell.pos
+    : selection.from
+
+  const domAtPos = view.domAtPos(pos)
+  let node = domAtPos.node as (Node & { closest?: (sel: string) => Element | null }) | null
+
+  // 文本节点（nodeType 3）没有 closest / parentElement 是 Element —— 归一化成元素
+  if (node && node.nodeType === Node.TEXT_NODE) {
+    node = (node as unknown as Text).parentElement
+  }
+  // domAtPos 也可能返回 document（空编辑器）：直接放弃
+  if (!node || typeof (node as Element).closest !== 'function') return null
+
+  return (node as Element).closest('table') as HTMLTableElement | null
+}
+
+/**
+ * 刷新浮层位置（rAF 对齐渲染帧：transaction 后 DOM 已更新、但浏览器还没
+ * 重排，同帧读 getBoundingClientRect 会拿到旧布局 —— 下一帧再读才准）。
+ */
+function schedulePositionUpdate(): void {
+  requestAnimationFrame(() => {
+    // 组件可能在等待帧期间卸载
+    if (!props.editor || props.editor.isDestroyed) return
+    updatePosition()
+  })
+}
+
+/** 计算浮层定位（表格正下方、左对齐；编辑器不可编辑时隐藏） */
+function updatePosition(): void {
+  const editor = props.editor
+  if (!editor || editor.isDestroyed) return
+
+  // 只读 / 禁用态没有表格操作可言（命令全部不可执行），浮层隐藏
+  if (!editor.isEditable) {
+    hide()
+    return
+  }
+
+  if (!isCursorInTable()) {
+    hide()
+    return
+  }
+
+  const tableEl = findTableElement()
+  if (!tableEl) {
+    hide()
+    return
+  }
+
+  const tableRect = tableEl.getBoundingClientRect()
+
+  // 表格整体滚出编辑器可视区时隐藏浮层，避免浮层漂到屏幕外。
+  // 向上找最近的「可纵向滚动」祖先（编辑器内容区 overflow-y: auto），
+  // 用它而非视口判断，才能正确识别「表格还在文档里但已滚出可见区」。
+  // 不硬编码命名空间类名，避免动态 namespace 下匹配失效。
+  const scrollEl = findScrollContainer(tableEl)
+  if (scrollEl) {
+    const scrollRect = scrollEl.getBoundingClientRect()
+    if (tableRect.bottom < scrollRect.top || tableRect.top > scrollRect.bottom) {
+      hide()
+      return
+    }
+  }
+
+  // position: fixed 直接使用视口坐标：表格底部下方 + 左对齐
+  acquireZIndex()
+  menuStyle.value = {
+    top: `${tableRect.bottom + 4}px`,
+    left: `${tableRect.left}px`,
+    zIndex: menuZIndex,
+  }
+  visible.value = true
+}
+
+function hide(): void {
+  if (!visible.value && !menuZIndex) return
+  visible.value = false
+  releaseMenuZIndex()
+}
+
+/** 刷新：表格结构变化 / 选区变化后重新判断 + 重定位 */
+function refresh(): void {
+  if (!isCursorInTable()) {
+    hide()
+    return
+  }
+  schedulePositionUpdate()
+}
+
+/** 窗口滚动 / 缩放：fixed 浮层必须跟随表格重定位（此前只监听编辑器内部滚动） */
+function onWindowScroll(): void {
+  if (!visible.value) return
+  schedulePositionUpdate()
+}
+
+/* ---------- 监听编辑器事务 ---------- */
+function onTransaction(): void {
+  refresh()
+}
+
+/** 当前监听滚动事件的编辑器根 DOM（用于卸载时正确移除监听） */
+let scrollBoundDom: HTMLElement | null = null
+
+/**
+ * 编辑器内容区滚动时（无 transaction），表格浮层若不重新定位会停在旧位置。
+ * scroll 事件从内部滚动容器冒泡到编辑器根节点，这里用捕获阶段监听一次即可
+ * 覆盖所有内部滚动容器，滚动即刷新浮层位置。
+ */
+function onEditorScroll(): void {
+  refresh()
+}
+
+watch(
+  () => props.editor,
+  (editor, oldEditor) => {
+    oldEditor?.off('transaction', onTransaction)
+    oldEditor?.off('selectionUpdate', onTransaction)
+    if (scrollBoundDom) {
+      scrollBoundDom.removeEventListener('scroll', onEditorScroll, true)
+      scrollBoundDom = null
+    }
+    if (!editor) return
+    editor.on('transaction', onTransaction)
+    editor.on('selectionUpdate', onTransaction)
+    const dom = editor.view.dom
+    dom.addEventListener('scroll', onEditorScroll, true)
+    scrollBoundDom = dom
+    refresh()
+  },
+  { immediate: true },
+)
+
+// 页面级滚动（编辑器外部）：fixed 元素不会跟着动，必须显式跟随。
+// passive + 捕获：滚动高频事件，不允许 preventDefault，性能优先。
+window.addEventListener('scroll', onWindowScroll, { passive: true, capture: true })
+window.addEventListener('resize', onWindowScroll, { passive: true })
+
+onBeforeUnmount(() => {
+  props.editor?.off('transaction', onTransaction)
+  props.editor?.off('selectionUpdate', onTransaction)
+  if (scrollBoundDom) {
+    scrollBoundDom.removeEventListener('scroll', onEditorScroll, true)
+    scrollBoundDom = null
+  }
+  window.removeEventListener('scroll', onWindowScroll, { capture: true } as EventListenerOptions)
+  window.removeEventListener('resize', onWindowScroll)
+  releaseMenuZIndex()
+})
+</script>
+
+<template>
+  <Teleport to="body">
+    <div
+      v-show="visible"
+      :class="b()"
+      :style="menuStyle"
+      @mousedown.prevent
+    >
+      <template v-for="(group, gi) in actionGroups" :key="gi">
+        <span v-if="gi > 0" :class="e('divider')" />
+        <G3Tooltip v-for="act in group" :key="act.label" :content="act.label" placement="top">
+          <G3Button
+            :class="e('action')"
+            type="ghost"
+            size="small"
+            :disabled="act.disabled?.()"
+            :aria-label="act.label"
+            @click="act.action()"
+          >
+            <component :is="act.icon" />
+          </G3Button>
+        </G3Tooltip>
+      </template>
+    </div>
+  </Teleport>
+</template>
+
+<style lang="scss">
+@use '@g3soft/tokens/scss' as *;
+
+/* 表格操作浮层：fixed 定位到表格下方，带边框 + 阴影 + 圆角 */
+.#{b('rich-text-table-menu')} {
+  position: fixed;
+  display: flex;
+  align-items: center;
+  gap: v('space-1', 4px);
+  padding: v('space-1', 4px);
+  border: 1px solid v('border-color', #d9d9d9);
+  border-radius: v('radius', 6px);
+  background: v('bg-container', #fff);
+  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.08);
+
+  /* 分组分隔线：行 / 列 / 单元格 / 表头 / 对齐 / 危险操作分组，防误点 */
+  .#{e('rich-text-table-menu', 'divider')} {
+    flex-shrink: 0;
+    width: 1px;
+    height: 16px;
+    margin: 0 v('space-1', 4px);
+    background: v('border-color', #d9d9d9);
+  }
+
+  .#{e('rich-text-table-menu', 'action')} {
+    width: 28px;
+    height: 28px;
+    padding: 0;
+    /* 与工具条同一份前景色 / 描边强度（见 Toolbar.vue 的 .g3-rich-text__button） */
+    color: v('text-1', rgba(0, 0, 0, 0.88));
+
+    /* 与工具条同一份分量：16px 图标 + lucide 原生描边，只把前景提到 text-1 */
+    svg {
+      width: 16px;
+      height: 16px;
+    }
+
+    &.#{is('disabled')} {
+      opacity: 0.4;
+    }
+  }
+}
+</style>
diff --git a/code/g3soft-libs/packages/ui/src/rich-text/Toolbar.vue b/code/g3soft-libs/packages/ui/src/rich-text/Toolbar.vue
new file mode 100644
index 00000000..db8cde56
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/rich-text/Toolbar.vue
@@ -0,0 +1,911 @@
+<script setup lang="ts">
+import { computed, ref } from 'vue'
+import type { Editor } from '@tiptap/vue-3'
+import {
+  AlignCenter,
+  AlignLeft,
+  AlignRight,
+  Baseline,
+  Bold,
+  ChevronDown,
+  Ellipsis,
+  Eraser,
+  Highlighter,
+  Image,
+  Italic,
+  Link,
+  List,
+  ListOrdered,
+  Palette,
+  Quote,
+  Redo2,
+  Strikethrough,
+  Subscript,
+  Superscript,
+  Table,
+  Underline,
+  Undo2,
+  Video,
+} from '@lucide/vue'
+import { G3Button } from '../button'
+import { G3Checkbox } from '../checkbox'
+import { G3Dropdown, type DropdownItemData } from '../dropdown'
+import { G3Popover } from '../popover'
+import { G3Tooltip } from '../tooltip'
+import { useNamespace } from '../_composables/useNamespace'
+import {
+  DEFAULT_BACKGROUND_COLORS,
+  DEFAULT_FONTS,
+  DEFAULT_FONT_SIZES,
+  DEFAULT_TEXT_COLORS,
+} from './extensions'
+import { insertImage, insertVideo, type UploadHandlers } from './upload'
+
+defineOptions({ name: 'G3RichTextToolbar' })
+
+const props = withDefaults(
+  defineProps<{
+    editor: Editor
+    fonts?: { label: string; value: string }[]
+    fontSizes?: { label: string; value: string }[]
+    handlers: UploadHandlers
+    placement?: 'top' | 'bottom'
+  }>(),
+  {
+    fonts: () => DEFAULT_FONTS,
+    fontSizes: () => DEFAULT_FONT_SIZES,
+    placement: 'top',
+  },
+)
+
+const { e, em, is } = useNamespace('rich-text')
+
+/* ---------- 标题（正文 / H1 / H2 / H3）---------- */
+const headingLevels = [
+  { key: 'paragraph', label: '正文', level: null as null },
+  { key: 'h1', label: '标题 1', level: 1 as const },
+  { key: 'h2', label: '标题 2', level: 2 as const },
+  { key: 'h3', label: '标题 3', level: 3 as const },
+]
+
+const currentHeading = computed(() => {
+  if (props.editor.isActive('heading', { level: 1 })) return 'h1'
+  if (props.editor.isActive('heading', { level: 2 })) return 'h2'
+  if (props.editor.isActive('heading', { level: 3 })) return 'h3'
+  return 'paragraph'
+})
+
+const currentHeadingLabel = computed(
+  () => headingLevels.find((h) => h.key === currentHeading.value)?.label ?? '正文',
+)
+
+const headingItems = computed(() =>
+  headingLevels.map((h) => ({
+    key: h.key,
+    label: h.label,
+    onClick: () => setHeading(h),
+  })),
+)
+
+function setHeading(h: { key: string; level: 1 | 2 | 3 | null }) {
+  const chain = props.editor.chain().focus()
+  if (h.level === null) chain.setParagraph()
+  else chain.setHeading({ level: h.level })
+  chain.run()
+}
+
+/* ---------- 字体 / 字号（收在「更多」菜单的子菜单里） ---------- */
+const currentFont = computed(() => props.editor.getAttributes('textStyle').fontFamily ?? '')
+const currentFontSize = computed(() => props.editor.getAttributes('textStyle').fontSize ?? '')
+
+const fontItems = computed<DropdownItemData[]>(() =>
+  props.fonts.map((f) => ({
+    key: f.value,
+    label: f.label,
+    // 选中态跟随光标（不必再靠按钮上的「当前值」文字来体现）
+    selected: currentFont.value === f.value,
+    onClick: () => {
+      props.editor.chain().focus().setFontFamily(f.value).run()
+    },
+  })),
+)
+
+const fontSizeItems = computed<DropdownItemData[]>(() =>
+  props.fontSizes.map((s) => ({
+    key: s.value,
+    label: s.label,
+    selected: currentFontSize.value === s.value,
+    onClick: () => {
+      props.editor.chain().focus().setFontSize(s.value).run()
+    },
+  })),
+)
+
+/* ---------- 链接 ---------- */
+function toggleLink() {
+  if (props.editor.isActive('link')) {
+    props.editor.chain().focus().unsetLink().run()
+    return
+  }
+  const url = window.prompt('请输入链接地址')
+  if (url) props.editor.chain().focus().setLink({ href: url }).run()
+}
+
+/* ---------- 表格（弹窗选行列）---------- */
+const tableOpen = ref(false)
+const tableRows = ref(3)
+const tableCols = ref(3)
+const tableWithHeader = ref(true)
+
+function openTablePanel() {
+  tableRows.value = 3
+  tableCols.value = 3
+  tableWithHeader.value = true
+  tableOpen.value = true
+}
+
+/** 行 / 列数范围（与输入框 min/max 一致）：超出时在「插入」时夹回，而非静默失败 */
+const TABLE_SIZE_MIN = 1
+const TABLE_SIZE_MAX = 20
+
+function clampSize(value: number): number {
+  if (!Number.isFinite(value)) return 3
+  return Math.min(TABLE_SIZE_MAX, Math.max(TABLE_SIZE_MIN, Math.trunc(value)))
+}
+
+function insertTable() {
+  const rows = clampSize(tableRows.value)
+  const cols = clampSize(tableCols.value)
+  tableRows.value = rows
+  tableCols.value = cols
+
+  const inserted = props.editor
+    .chain()
+    .focus()
+    .insertTable({
+      rows,
+      cols,
+      withHeaderRow: tableWithHeader.value,
+    })
+    .run()
+  if (inserted) tableOpen.value = false
+}
+
+/* ---------- 工具按钮 ---------- */
+interface ToolButton {
+  label: string
+  icon: typeof Bold
+  action: () => void
+  active?: () => boolean
+  disabled?: () => boolean
+  /** 快捷键提示（只在「更多」菜单里展示）：对着 Tiptap 的真实键位写 */
+  shortcut?: string
+}
+
+/** 高频行内格式：加粗 / 斜体 / 下划线 */
+const inlineButtons: ToolButton[] = [
+  {
+    label: '加粗',
+    icon: Bold,
+    action: () => props.editor.chain().focus().toggleBold().run(),
+    active: () => props.editor.isActive('bold'),
+  },
+  {
+    label: '斜体',
+    icon: Italic,
+    action: () => props.editor.chain().focus().toggleItalic().run(),
+    active: () => props.editor.isActive('italic'),
+  },
+  {
+    label: '下划线',
+    icon: Underline,
+    action: () => props.editor.chain().focus().toggleUnderline().run(),
+    active: () => props.editor.isActive('underline'),
+  },
+]
+
+/**
+ * 低频功能：不进工具条，收进「更多」菜单。
+ *
+ * 判据是「一天里点几次」而不是「功能重不重要」：删除线 / 上下标 / 引用是排版细节，
+ * 视频在 ERP 正文里极少出现，它们平铺在工具条上只会把工具条顶到 928px 宽
+ * （560px 的弹窗里要折成两行）。`shortcut` 都对着 Tiptap 的真实键位写的，
+ * 菜单里显示出来才不是装饰。
+ */
+const moreButtons: ToolButton[] = [
+  {
+    label: '删除线',
+    icon: Strikethrough,
+    shortcut: 'Ctrl+Shift+S',
+    action: () => props.editor.chain().focus().toggleStrike().run(),
+    active: () => props.editor.isActive('strike'),
+  },
+  {
+    label: '上标',
+    icon: Superscript,
+    shortcut: 'Ctrl+.',
+    action: () => props.editor.chain().focus().toggleSuperscript().run(),
+    active: () => props.editor.isActive('superscript'),
+  },
+  {
+    label: '下标',
+    icon: Subscript,
+    shortcut: 'Ctrl+,',
+    action: () => props.editor.chain().focus().toggleSubscript().run(),
+    active: () => props.editor.isActive('subscript'),
+  },
+  {
+    label: '引用',
+    icon: Quote,
+    shortcut: 'Ctrl+Shift+B',
+    action: () => props.editor.chain().focus().toggleBlockquote().run(),
+    active: () => props.editor.isActive('blockquote'),
+  },
+]
+
+/**
+ * 「更多」菜单数据：分组标题 + 图标 + 快捷键，用 Dropdown 现成的能力拼出来。
+ *
+ * 与工具条共用同一份 ToolButton 定义（一条功能只描述一次），所以激活态 / 禁用态
+ * 在菜单里同样准确 —— 打开菜单就能看出当前光标是否在引用里。
+ *
+ * 字体 / 字号放最上（二级菜单）：它们对正文排版来说是「选一次」的操作，
+ * 常驻在工具条上白白占掉 130px，而带当前值的下拉按钮还会在切换时改宽度、把后面的按钮推走。
+ */
+const moreItems = computed<DropdownItemData[]>(() => [
+  { key: 'font', label: '字体', children: fontItems.value },
+  { key: 'fontSize', label: '字号', children: fontSizeItems.value },
+  { divider: true },
+  { type: 'label', label: '格式' },
+  ...moreButtons.map((btn) => ({
+    key: btn.label,
+    label: btn.label,
+    icon: btn.icon,
+    shortcut: btn.shortcut,
+    selected: btn.active?.(),
+    disabled: btn.disabled?.(),
+    onClick: btn.action,
+  })),
+  { divider: true },
+  { type: 'label', label: '插入' },
+  {
+    key: '视频',
+    label: '视频',
+    icon: Video,
+    onClick: () => insertVideo(props.editor, props.handlers),
+  },
+])
+
+/**
+ * 对齐：左 / 中 / 右。
+ *
+ * 用 toggleTextAlign 而非 setTextAlign —— 再点当前的档位即「取消对齐」，
+ * 省掉一个单独的「取消对齐」按钮（表格单元格的对齐也走这里，
+ * 单元格内容同样是 paragraph，无需表格操作栏单独提供）。
+ */
+const ALIGNMENTS: { key: string; label: string; icon: typeof Bold }[] = [
+  { key: 'left', label: '左对齐', icon: AlignLeft },
+  { key: 'center', label: '居中', icon: AlignCenter },
+  { key: 'right', label: '右对齐', icon: AlignRight },
+]
+
+const alignmentButtons: ToolButton[] = ALIGNMENTS.map((item) => ({
+  label: item.label,
+  icon: item.icon,
+  action: () => props.editor.chain().focus().toggleTextAlign(item.key).run(),
+  active: () => props.editor.isActive({ textAlign: item.key }),
+  // 光标选中的是图片 / 视频等非文本块时不可用
+  disabled: () => !props.editor.can().setTextAlign(item.key),
+}))
+
+/* ---------- 颜色：字体颜色 / 背景颜色 ---------- */
+interface ColorControl {
+  key: 'color' | 'background'
+  label: string
+  icon: typeof Baseline
+  /** 预设色板 */
+  palette: string[]
+  /** 选区当前颜色（未设置时为空串），用于触发器色条与面板选中环 */
+  current: () => string
+  apply: (color: string) => void
+  clear: () => void
+}
+
+const colorControls: ColorControl[] = [
+  {
+    key: 'color',
+    label: '字体颜色',
+    icon: Baseline,
+    palette: DEFAULT_TEXT_COLORS,
+    current: () => (props.editor.getAttributes('textStyle').color as string | undefined) ?? '',
+    apply: (color) => {
+      props.editor.chain().focus().setColor(color).run()
+    },
+    clear: () => {
+      props.editor.chain().focus().unsetColor().run()
+    },
+  },
+  {
+    key: 'background',
+    label: '背景颜色',
+    icon: Highlighter,
+    palette: DEFAULT_BACKGROUND_COLORS,
+    current: () =>
+      (props.editor.getAttributes('textStyle').backgroundColor as string | undefined) ?? '',
+    apply: (color) => {
+      props.editor.chain().focus().setBackgroundColor(color).run()
+    },
+    clear: () => {
+      props.editor.chain().focus().unsetBackgroundColor().run()
+    },
+  },
+]
+
+/** 同一时刻只开一个取色面板（'' = 都关着）；取完色立即收起 */
+const openColor = ref<'' | ColorControl['key']>('')
+
+function onColorOpen(key: ColorControl['key'], value: boolean): void {
+  if (value) openColor.value = key
+  else if (openColor.value === key) openColor.value = ''
+}
+
+function applyColor(control: ColorControl, color: string): void {
+  control.apply(color)
+  openColor.value = ''
+}
+
+function clearColor(control: ColorControl): void {
+  control.clear()
+  openColor.value = ''
+}
+
+/** 面板里当前色是否命中该色块（选中环）：HTML 里的 hex 大小写不固定，统一小写比对 */
+function isCurrentColor(control: ColorControl, color: string): boolean {
+  return control.current().toLowerCase() === color
+}
+
+/** 自定义颜色（原生取色器）：只接受完整 hex，避免半截输入写进文档 */
+function onCustomColor(control: ColorControl, event: Event): void {
+  const value = (event.target as HTMLInputElement).value
+  if (/^#[0-9a-f]{6}$/i.test(value)) applyColor(control, value)
+}
+
+/** 列表与插入：无序 / 有序 / 链接 / 图片（引用、视频已收进「更多」） */
+const blockButtons: ToolButton[] = [
+  {
+    label: '无序列表',
+    icon: List,
+    action: () => props.editor.chain().focus().toggleBulletList().run(),
+    active: () => props.editor.isActive('bulletList'),
+  },
+  {
+    label: '有序列表',
+    icon: ListOrdered,
+    action: () => props.editor.chain().focus().toggleOrderedList().run(),
+    active: () => props.editor.isActive('orderedList'),
+  },
+  {
+    label: '链接',
+    icon: Link,
+    action: toggleLink,
+    active: () => props.editor.isActive('link'),
+  },
+  {
+    label: '图片',
+    icon: Image,
+    action: () => insertImage(props.editor, props.handlers),
+  },
+]
+
+/** 撤销 / 重做：历史操作，放工具条末尾 */
+const historyButtons: ToolButton[] = [
+  {
+    label: '撤销',
+    icon: Undo2,
+    action: () => props.editor.chain().focus().undo().run(),
+    disabled: () => !props.editor.can().undo(),
+  },
+  {
+    label: '重做',
+    icon: Redo2,
+    action: () => props.editor.chain().focus().redo().run(),
+    disabled: () => !props.editor.can().redo(),
+  },
+]
+</script>
+
+<template>
+  <div :class="[e('toolbar'), { [em('toolbar', 'bottom')]: placement === 'bottom' }]">
+    <!-- 撤销 / 重做放最前：历史是「先于格式」的一类操作 -->
+    <G3Tooltip v-for="btn in historyButtons" :key="btn.label" :content="btn.label" placement="top">
+      <G3Button
+        :class="e('button')"
+        type="ghost"
+        size="small"
+        :disabled="btn.disabled?.()"
+        :aria-label="btn.label"
+        @click="btn.action()"
+      >
+        <component :is="btn.icon" />
+      </G3Button>
+    </G3Tooltip>
+
+    <span :class="e('divider')" />
+
+    <!-- 段落格式（紧接历史操作；字体 / 字号已收进「更多」） -->
+    <G3Dropdown :items="headingItems" trigger="click" placement="bottom-start">
+      <template #trigger>
+        <G3Button :class="e('trigger')" type="ghost" size="small">
+          <span :class="e('trigger-label')">{{ currentHeadingLabel }}</span>
+          <ChevronDown :class="e('trigger-caret')" />
+        </G3Button>
+      </template>
+    </G3Dropdown>
+
+    <span :class="e('divider')" />
+
+    <!-- 行内格式：加粗 / 斜体 / 下划线 -->
+    <G3Tooltip v-for="btn in inlineButtons" :key="btn.label" :content="btn.label" placement="top">
+      <G3Button
+        :class="[e('button'), { [is('active')]: btn.active?.() }]"
+        type="ghost"
+        size="small"
+        :disabled="btn.disabled?.()"
+        :aria-label="btn.label"
+        :aria-pressed="btn.active?.() || undefined"
+        @click="btn.action()"
+      >
+        <component :is="btn.icon" />
+      </G3Button>
+    </G3Tooltip>
+
+    <span :class="e('divider')" />
+
+    <!-- 对齐：左 / 中 / 右（再点当前档位即取消对齐） -->
+    <G3Tooltip
+      v-for="btn in alignmentButtons"
+      :key="btn.label"
+      :content="btn.label"
+      placement="top"
+    >
+      <G3Button
+        :class="[e('button'), { [is('active')]: btn.active?.() }]"
+        type="ghost"
+        size="small"
+        :disabled="btn.disabled?.()"
+        :aria-label="btn.label"
+        :aria-pressed="btn.active?.() || undefined"
+        @click="btn.action()"
+      >
+        <component :is="btn.icon" />
+      </G3Button>
+    </G3Tooltip>
+
+    <span :class="e('divider')" />
+
+    <!-- 字体颜色 / 背景颜色：图标 + 当前色条，点开启预设色板 -->
+    <G3Popover
+      v-for="control in colorControls"
+      :key="control.key"
+      :open="openColor === control.key"
+      trigger="click"
+      placement="bottom-start"
+      :arrow="false"
+      :offset="4"
+      :content-class="e('color-panel-wrap')"
+      @update:open="(value: boolean) => onColorOpen(control.key, value)"
+    >
+      <template #trigger>
+        <G3Tooltip :content="control.label" placement="top">
+          <G3Button
+            :class="[
+              e('button'),
+              e('color-button'),
+              { [is('active')]: openColor === control.key },
+            ]"
+            type="ghost"
+            size="small"
+            :aria-label="control.label"
+            :aria-pressed="!!control.current() || undefined"
+          >
+            <component :is="control.icon" />
+            <span
+              :class="e('color-bar')"
+              :style="{ background: control.current() || undefined }"
+              aria-hidden="true"
+            />
+          </G3Button>
+        </G3Tooltip>
+      </template>
+
+      <template #content>
+        <div :class="e('color-panel')">
+          <div :class="e('color-actions')">
+            <G3Button
+              :class="e('color-action')"
+              type="ghost"
+              size="small"
+              :aria-label="`清除${control.label}`"
+              @click="clearColor(control)"
+            >
+              <Eraser />
+              <span>无颜色</span>
+            </G3Button>
+
+            <!-- 自定义颜色：原生取色器（图标只是标识，真正的触发体是覆盖其上的 input） -->
+            <label :class="e('color-custom')" :title="`自定义${control.label}`">
+              <Palette />
+              <input
+                :class="e('color-native')"
+                type="color"
+                :value="control.current() || '#000000'"
+                :aria-label="`自定义${control.label}`"
+                @input="onCustomColor(control, $event)"
+              />
+            </label>
+          </div>
+
+          <div :class="e('color-grid')">
+            <button
+              v-for="color in control.palette"
+              :key="color"
+              type="button"
+              :class="[
+                e('color-swatch'),
+                { [is('active')]: isCurrentColor(control, color) },
+              ]"
+              :style="{ background: color }"
+              :aria-label="color"
+              @click="applyColor(control, color)"
+            />
+          </div>
+        </div>
+      </template>
+    </G3Popover>
+
+    <span :class="e('divider')" />
+
+    <!-- 列表与插入：无序 / 有序 / 链接 / 图片（表格在后面，同组不分隔） -->
+    <G3Tooltip v-for="btn in blockButtons" :key="btn.label" :content="btn.label" placement="top">
+      <G3Button
+        :class="[e('button'), { [is('active')]: btn.active?.() }]"
+        type="ghost"
+        size="small"
+        :disabled="btn.disabled?.()"
+        :aria-label="btn.label"
+        :aria-pressed="btn.active?.() || undefined"
+        @click="btn.action()"
+      >
+        <component :is="btn.icon" />
+      </G3Button>
+    </G3Tooltip>
+
+    <!-- 表格按钮 + 行列选择面板（需要选行列，所以留在工具条而不是收进「更多」） -->
+    <G3Popover
+      v-model:open="tableOpen"
+      trigger="click"
+      placement="bottom-start"
+      :arrow="false"
+      :offset="4"
+      :content-class="e('table-panel')"
+    >
+      <template #trigger>
+        <G3Tooltip content="插入表格" placement="top">
+          <G3Button :class="e('button')" type="ghost" size="small" aria-label="插入表格">
+            <Table />
+          </G3Button>
+        </G3Tooltip>
+      </template>
+
+      <template #content>
+        <div :class="e('table-form')" @keydown.enter.prevent="insertTable">
+          <div :class="e('table-field')">
+            <label :class="e('table-label')">行数</label>
+            <input
+              v-model.number="tableRows"
+              :class="e('table-input')"
+              type="number"
+              :min="TABLE_SIZE_MIN"
+              :max="TABLE_SIZE_MAX"
+            />
+          </div>
+          <div :class="e('table-field')">
+            <label :class="e('table-label')">列数</label>
+            <input
+              v-model.number="tableCols"
+              :class="e('table-input')"
+              type="number"
+              :min="TABLE_SIZE_MIN"
+              :max="TABLE_SIZE_MAX"
+            />
+          </div>
+          <div :class="e('table-field')">
+            <label :class="e('table-label')">包含表头行</label>
+            <G3Checkbox v-model="tableWithHeader" :class="e('table-checkbox')" />
+          </div>
+          <G3Button type="primary" size="small" block @click="insertTable">插入</G3Button>
+        </div>
+      </template>
+    </G3Popover>
+
+    <span :class="e('divider')" />
+
+    <!-- 更多：低频功能按组收进菜单，工具条保持一行。
+         菜单内容约 295px，Dropdown 的上限默认按视口算（calc(100vh - 48px)），
+         所以面板内部不会出滚动条 —— 不需要在这里传 menuMaxHeight。 -->
+    <G3Dropdown :items="moreItems" trigger="click" placement="bottom-end" :offset="4">
+      <template #trigger>
+        <G3Button :class="e('button')" type="ghost" size="small" aria-label="更多">
+          <Ellipsis />
+        </G3Button>
+      </template>
+    </G3Dropdown>
+  </div>
+</template>
+
+<style lang="scss">
+@use '@g3soft/tokens/scss' as *;
+
+.#{e('rich-text', 'toolbar')} {
+  /* 抬一层：正文滚动时内容会走到工具条下沿，投影不能被正文盖住 */
+  position: relative;
+  z-index: 1;
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  /* 组内 4px：图标回到 16px 后，16px 图形落在 24px 按钮正中（左右各 4px 空），
+     再给 4px 间隙，两个图标的墨迹之间就有 12px，不会再显得挤 */
+  gap: v('space-1', 4px);
+  /**
+   * 上下 8px / 左右 10px：图标 24px 之后，原来的 4px / 8px 会让图标几乎贴住上边框与左边框。
+   * 左右取 10px 而不是 12px：图标在 24px 按钮里自己还留了 2px，10 + 2 = 12px 正好和正文的
+   * 12px 内边距对齐（首列视觉齐平）。
+   */
+  padding: v('space-2', 8px) 10px;
+  background: v('bg-container', #fff);
+
+  /**
+   * 双层柔和投影（观感对齐 TinyMCE 的工具条）：近处一道 2px 的硬边交代边界，
+   * 远处一道 8px 弥散托出层次 —— 单层做不到「贴边但不脏」。
+   *
+   * 不用 border-bottom 画分隔线：一层 1px 线 + 一层投影会互相打架（线把投影的
+   * 起笔压死），TinyMCE 同款也是纯投影。颜色抽成局部变量，宿主想整体调深浅只覆盖
+   * 这两个值即可（无需碰组件代码）；左右两侧的溢出由容器 overflow: hidden 裁掉，
+   * 视觉上只剩向下这一道。
+   */
+  #{css-var('rich-text-toolbar-shadow-near')}: rgba(34, 47, 62, 0.1);
+  #{css-var('rich-text-toolbar-shadow-far')}: rgba(34, 47, 62, 0.07);
+  box-shadow:
+    0 2px 2px -2px v('rich-text-toolbar-shadow-near', rgba(34, 47, 62, 0.1)),
+    0 8px 8px -4px v('rich-text-toolbar-shadow-far', rgba(34, 47, 62, 0.07));
+
+  /* 下置工具条：同样的两层，方向翻到上方 */
+  &.#{em('rich-text', 'toolbar', 'bottom')} {
+    box-shadow:
+      0 -2px 2px -2px v('rich-text-toolbar-shadow-near', rgba(34, 47, 62, 0.1)),
+      0 -8px 8px -4px v('rich-text-toolbar-shadow-far', rgba(34, 47, 62, 0.07));
+  }
+}
+
+/* 下拉触发器：ghost 按钮承载「当前值 + 箭头」 */
+.#{e('rich-text', 'trigger')} {
+  gap: v('space-1', 4px);
+  padding: 0 v('space-2', 8px);
+  /* 与图标按钮同一份前景色（见 .g3-rich-text__button） */
+  color: v('text-1', rgba(0, 0, 0, 0.88));
+}
+
+.#{e('rich-text', 'trigger-label')} {
+  /* 图标 24px 之后，12px 的按钮文字会显得偏小，提到正文档位 */
+  font-size: v('font-size', 14px);
+}
+
+.#{e('rich-text', 'trigger-caret')} {
+  width: 14px;
+  height: 14px;
+  /* 箭头是二级信息：比文字浅一档，描边也不加重 */
+  color: v('text-2', rgba(0, 0, 0, 0.65));
+}
+
+/* 分隔线 */
+.#{e('rich-text', 'divider')} {
+  flex-shrink: 0;
+  width: 1px;
+  height: 16px;
+  margin: 0 v('space-1', 4px);
+  background: v('border-color', #d9d9d9);
+}
+
+/* 图标按钮：ghost，激活态主色底；图标 16px，hit 区 32px（等于 --g3-control-height） */
+.#{e('rich-text', 'button')} {
+  flex-shrink: 0;
+  width: 32px;
+  height: 32px;
+  padding: 0;
+  /**
+   * 图标分量取「深色 + 标准描边」的组合：前景从 ghost 默认的 text-2（65% 黑）提到
+   * text-1（88%），描边保持 lucide 原生的 2（16px 显示 ≈ 1.33px）。
+   *
+   * 之前试过把描边加到 2.5、甚至把图标放大到 24px，都会偏重；实测「发虚」的主因是
+   * 浅灰前景而不是线宽，所以只动颜色这一项最稳。
+   */
+  color: v('text-1', rgba(0, 0, 0, 0.88));
+
+  svg {
+    width: 16px;
+    height: 16px;
+  }
+
+  &.#{is('active')} {
+    background: v('color-primary-soft', rgba(0, 0, 0, 0.12));
+    color: v('color-primary', #18181b);
+  }
+}
+
+/* 取色按钮：图标在上（16px）、当前色条在下（3px），竖排后 20px，24px 按钮里居中 */
+.#{e('rich-text', 'color-button')} {
+  .#{e('button', 'content')} {
+    flex-direction: column;
+    gap: 1px;
+  }
+
+  svg {
+    width: 16px;
+    height: 16px;
+  }
+}
+
+/* 当前色条：未设色时是「斜线 + 描边」的空位，设色后由内联 background 覆盖 */
+.#{e('rich-text', 'color-bar')} {
+  display: block;
+  box-sizing: border-box;
+  width: 16px;
+  height: 3px;
+  border-radius: 1px;
+  background-image: linear-gradient(
+    135deg,
+    transparent 42%,
+    v('border-color', #d9d9d9) 42%,
+    v('border-color', #d9d9d9) 58%,
+    transparent 58%
+  );
+  box-shadow: inset 0 0 0 1px v('border-color', #d9d9d9);
+}
+
+/* 取色面板：10 列色块 + 顶部「无颜色 / 自定义」一行 */
+.#{e('rich-text', 'color-panel')} {
+  display: flex;
+  flex-direction: column;
+  gap: v('space-2', 8px);
+}
+
+.#{e('rich-text', 'color-actions')} {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: v('space-2', 8px);
+}
+
+/* 「无颜色」用 ghost 按钮，与色块区拉开距离，避免误点成某个色块 */
+.#{e('rich-text', 'color-action')} {
+  gap: v('space-1', 4px);
+  height: 24px;
+  padding: 0 v('space-1', 4px);
+  font-size: v('font-size-sm', 12px);
+
+  svg {
+    width: 14px;
+    height: 14px;
+  }
+}
+
+/* 自定义颜色：彩虹底 + 覆盖其上的原生取色器 */
+.#{e('rich-text', 'color-custom')} {
+  position: relative;
+  display: inline-flex;
+  flex-shrink: 0;
+  align-items: center;
+  justify-content: center;
+  box-sizing: border-box;
+  width: 28px;
+  height: 24px;
+  border-radius: v('radius-sm', 4px);
+  background: conic-gradient(
+    from 0deg,
+    #f5222d,
+    #fa8c16,
+    #fadb14,
+    #52c41a,
+    #13c2c2,
+    #1677ff,
+    #722ed1,
+    #f5222d
+  );
+  box-shadow: inset 0 0 0 1px v('border-color', #d9d9d9);
+  cursor: pointer;
+
+  svg {
+    position: relative;
+    width: 12px;
+    height: 12px;
+    color: #fff;
+    filter: drop-shadow(0 0 1px rgb(0 0 0 / 60%));
+  }
+}
+
+.#{e('rich-text', 'color-native')} {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  padding: 0;
+  border: 0;
+  opacity: 0;
+  cursor: pointer;
+}
+
+/* 色块：白/浅色也要看得见边界，所以每个都加内描边；选中态用 outline，避免与内描边打架 */
+.#{e('rich-text', 'color-grid')} {
+  display: grid;
+  grid-template-columns: repeat(10, 20px);
+  gap: v('space-1', 4px);
+}
+
+.#{e('rich-text', 'color-swatch')} {
+  box-sizing: border-box;
+  width: 20px;
+  height: 20px;
+  padding: 0;
+  border: 0;
+  border-radius: v('radius-sm', 4px);
+  box-shadow: inset 0 0 0 1px rgb(0 0 0 / 8%);
+  cursor: pointer;
+
+  &:hover {
+    transform: scale(1.1);
+  }
+
+  &.#{is('active')} {
+    outline: 2px solid v('color-primary', #18181b);
+    outline-offset: 1px;
+  }
+}
+
+/* 表格选择面板 */
+.#{e('rich-text', 'table-form')} {
+  display: flex;
+  flex-direction: column;
+  gap: v('space-2', 8px);
+  padding: v('space-3', 12px);
+}
+
+/* 行 / 列数：label 与输入框上下排列 */
+.#{e('rich-text', 'table-field')} {
+  display: flex;
+  flex-direction: column;
+  gap: v('space-1', 4px);
+}
+
+.#{e('rich-text', 'table-label')} {
+  color: v('text-2', rgba(0, 0, 0, 0.65));
+  font-size: v('font-size-sm', 12px);
+}
+
+.#{e('rich-text', 'table-input')} {
+  box-sizing: border-box;
+  width: 100%;
+  height: v('control-height-sm', 24px);
+  padding: 0 v('space-2', 8px);
+  border: 1px solid v('border-color', #d9d9d9);
+  border-radius: v('radius-sm', 4px);
+  background: v('bg-container', #fff);
+  color: v('text-1', rgba(0, 0, 0, 0.88));
+  font-size: v('font-size', 14px);
+  outline: none;
+
+  &:focus {
+    border-color: v('color-primary', #18181b);
+    box-shadow: 0 0 0 2px v('color-primary-ring', rgba(24, 24, 27, 0.2));
+  }
+}
+</style>
diff --git a/code/g3soft-libs/packages/ui/src/rich-text/VideoNode.ts b/code/g3soft-libs/packages/ui/src/rich-text/VideoNode.ts
new file mode 100644
index 00000000..4c0f1699
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/rich-text/VideoNode.ts
@@ -0,0 +1,91 @@
+import { Node, mergeAttributes } from '@tiptap/core'
+
+/**
+ * 自写视频 node —— Tiptap 官方无视频扩展，这里定义一个轻量 block node。
+ *
+ * 设计要点：
+ * - attrs：src（必填）、poster（封面，可选）、width / height（可选）；
+ * - 编辑态渲染 `<video controls>` 可直接预览；
+ * - HTML 解析：兼容 `<video>` 与 `<div data-type="video">` 两种形态；
+ * - 序列化输出保留 `<video>` 标签，邮件场景由业务层决定是否转成附件 /
+ *   封面图降级（编辑器不绑定邮件语义，见 README 实现说明）。
+ */
+export interface VideoAttributes {
+  src: string
+  poster?: string
+  width?: string
+  height?: string
+}
+
+declare module '@tiptap/core' {
+  interface Commands<ReturnType> {
+    video: {
+      /** 插入 / 更新一个视频 node */
+      setVideo: (attrs: VideoAttributes) => ReturnType
+    }
+  }
+}
+
+export const Video = Node.create({
+  name: 'video',
+
+  group: 'block',
+  atom: true,
+  draggable: true,
+
+  addAttributes() {
+    return {
+      src: {
+        default: null,
+        parseHTML: (el) => el.getAttribute('src'),
+        renderHTML: (attrs) => ({ src: attrs.src }),
+      },
+      poster: {
+        default: null,
+        parseHTML: (el) => el.getAttribute('poster'),
+        renderHTML: (attrs) => (attrs.poster ? { poster: attrs.poster } : {}),
+      },
+      width: {
+        default: null,
+        parseHTML: (el) => el.getAttribute('width'),
+        renderHTML: (attrs) => (attrs.width ? { width: attrs.width } : {}),
+      },
+      height: {
+        default: null,
+        parseHTML: (el) => el.getAttribute('height'),
+        renderHTML: (attrs) => (attrs.height ? { height: attrs.height } : {}),
+      },
+    }
+  },
+
+  parseHTML() {
+    return [
+      {
+        tag: 'video[src]',
+      },
+      {
+        tag: 'div[data-type="video"]',
+        getAttrs: (el) => {
+          const video = el.querySelector('video')
+          return {
+            src: video?.getAttribute('src') ?? el.getAttribute('data-src'),
+            poster: video?.getAttribute('poster') ?? el.getAttribute('data-poster') ?? null,
+          }
+        },
+      },
+    ]
+  },
+
+  renderHTML({ HTMLAttributes }) {
+    return ['video', mergeAttributes(HTMLAttributes, { controls: 'controls' })]
+  },
+
+  addCommands() {
+    return {
+      setVideo:
+        (attrs: VideoAttributes) =>
+        ({ commands }) =>
+          commands.insertContent({ type: this.name, attrs }),
+    }
+  },
+})
diff --git a/code/g3soft-libs/packages/ui/src/rich-text/extensions.ts b/code/g3soft-libs/packages/ui/src/rich-text/extensions.ts
new file mode 100644
index 00000000..e415071d
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/rich-text/extensions.ts
@@ -0,0 +1,140 @@
+import type { Extensions } from '@tiptap/core'
+import StarterKit from '@tiptap/starter-kit'
+import Image from '@tiptap/extension-image'
+import Link from '@tiptap/extension-link'
+import Placeholder from '@tiptap/extension-placeholder'
+import Subscript from '@tiptap/extension-subscript'
+import Superscript from '@tiptap/extension-superscript'
+import { Table, TableCell, TableHeader, TableRow } from '@tiptap/extension-table'
+import TextAlign from '@tiptap/extension-text-align'
+import { TextStyleKit } from '@tiptap/extension-text-style'
+import { Video } from './VideoNode'
+import type { RichTextProps } from './types'
+
+/**
+ * 组装 G3RichText 用到的全部 Tiptap 扩展。
+ *
+ * 设计原则：
+ * - 从 starter-kit 剔除 Code / CodeBlock（ERP 场景不需要代码块）；
+ * - 字体 / 字号 / 颜色 / 背景色用 TextStyleKit（官方封装，内置 setFontFamily /
+ *   setFontSize / setColor / setBackgroundColor 命令），行高保持关闭；
+ * - 对齐用 TextAlign，只作用于块级文本节点（heading / paragraph）；
+ * - 链接 openOnClick: false，避免编辑时误跳转（点击跳转交给业务层）；
+ * - 图片强制走上传（allowBase64: false），由 uploadImage 钩子注入 URL。
+ */
+export function createExtensions(props: Pick<RichTextProps, 'placeholder' | 'uploadImage' | 'uploadVideo'>): Extensions {
+  return [
+    StarterKit.configure({
+      code: false,
+      codeBlock: false,
+      // 链接已在下方单独配置 openOnClick，这里关闭 starter-kit 内置的默认 link
+      link: false,
+    }),
+    Link.configure({
+      openOnClick: false,
+      autolink: true,
+      linkOnPaste: true,
+    }),
+    TextStyleKit.configure({
+      fontFamily: {},
+      fontSize: {},
+      // 字体颜色 / 背景颜色：工具栏「A」「荧光笔」两个按钮取色后写入 textStyle 记号
+      color: {},
+      backgroundColor: {},
+      // 行高不在需求内，关闭以精简命令与工具条
+      lineHeight: false,
+    }),
+    TextAlign.configure({
+      // 只作用于块级文本节点：表格单元格里的内容也是 paragraph，
+      // 所以「单元格左中右」由这两个按钮统一承担（表格操作栏不再单列对齐）
+      types: ['heading', 'paragraph'],
+      // 左中右三档；用 toggleTextAlign，点当前档位即取消对齐
+      alignments: ['left', 'center', 'right'],
+    }),
+    // 上标 / 下标：化学式、脚注编号、商标等场景
+    Superscript,
+    Subscript,
+    Image.configure({
+      allowBase64: false,
+      inline: false,
+    }),
+    Table.configure({
+      resizable: true,
+      // 最后一列不参与拖拽，避免把表格拖出容器
+      lastColumnResizable: false,
+      // 列最小宽度：拖拽时的夹取下限（需求要求 10px）
+      cellMinWidth: 10,
+      // 悬停判定宽度（距单元格右边缘多少 px 内算「悬停在分隔线上」）：默认 5px 太难瞄准
+      handleWidth: 8,
+    }),
+    TableRow,
+    TableHeader,
+    TableCell,
+    Placeholder.configure({
+      placeholder: props.placeholder ?? '请输入内容…',
+    }),
+    Video,
+  ]
+}
+
+/** 预设字体列表（供 Toolbar 下拉使用） */
+export const DEFAULT_FONTS = [
+  { label: '默认', value: '' },
+  { label: '宋体', value: 'SimSun, serif' },
+  { label: '黑体', value: 'SimHei, sans-serif' },
+  { label: '微软雅黑', value: 'Microsoft YaHei, sans-serif' },
+  { label: '楷体', value: 'KaiTi, serif' },
+  { label: '仿宋', value: 'FangSong, serif' },
+  { label: 'Arial', value: 'Arial, sans-serif' },
+  { label: 'Times New Roman', value: 'Times New Roman, serif' },
+] satisfies { label: string; value: string }[]
+
+/** 预设字号列表 */
+export const DEFAULT_FONT_SIZES = [
+  { label: '12px', value: '12px' },
+  { label: '14px', value: '14px' },
+  { label: '16px', value: '16px' },
+  { label: '18px', value: '18px' },
+  { label: '20px', value: '20px' },
+  { label: '24px', value: '24px' },
+  { label: '28px', value: '28px' },
+  { label: '32px', value: '32px' },
+] satisfies { label: string; value: string }[]
+
+/**
+ * 字体颜色预设色板：黑 / 灰两档中性色 + 常用彩色（取 Ant Design 的 6 号色）。
+ *
+ * 只放一屏能看全的量（10 个 = 面板一行），需要其它颜色时用面板里的「自定义」取色器。
+ */
+export const DEFAULT_TEXT_COLORS = [
+  '#000000',
+  '#434343',
+  '#8c8c8c',
+  '#bfbfbf',
+  '#f5222d',
+  '#fa8c16',
+  '#52c41a',
+  '#1677ff',
+  '#722ed1',
+  '#eb2f96',
+] satisfies string[]
+
+/**
+ * 背景颜色预设色板：全部取浅色档（Ant Design 的 1 号色），
+ * 深底会把正文文字盖掉 —— 背景色是「标记重点」而非「反色」。
+ */
+export const DEFAULT_BACKGROUND_COLORS = [
+  '#f5f5f5',
+  '#fff1f0',
+  '#fff7e6',
+  '#feffe6',
+  '#f6ffed',
+  '#e6fffb',
+  '#e6f4ff',
+  '#f0f5ff',
+  '#f9f0ff',
+  '#fff0f6',
+] satisfies string[]
+
+// 供 Toolbar 直接引用的字体类型（与 types.ts 保持一致）
+export type { RichTextFontOption, RichTextFontSizeOption } from './types'
diff --git a/code/g3soft-libs/packages/ui/src/rich-text/index.ts b/code/g3soft-libs/packages/ui/src/rich-text/index.ts
new file mode 100644
index 00000000..71bc7127
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/rich-text/index.ts
@@ -0,0 +1,9 @@
+export { default as G3RichText } from './RichText.vue'
+export type {
+  RichTextProps,
+  RichTextEmits,
+  RichTextExpose,
+  RichTextUploadResult,
+  RichTextFontOption,
+  RichTextFontSizeOption,
+} from './types'
diff --git a/code/g3soft-libs/packages/ui/src/rich-text/types.ts b/code/g3soft-libs/packages/ui/src/rich-text/types.ts
new file mode 100644
index 00000000..b530a1a4
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/rich-text/types.ts
@@ -0,0 +1,78 @@
+import type { Editor } from '@tiptap/vue-3'
+
+/** 上传结果：对齐邮件体系的「内联资源」模型，返回完整元数据而非仅 URL */
+export interface RichTextUploadResult {
+  /** 文件可访问 URL（正文 img / video 的 src） */
+  fileUrl: string
+  /** 后端返回的文件 id（用于删除 / 关联） */
+  fileId?: string
+  /** 内联资源 cid（邮件场景由后端生成，正文引用 cid:xxx） */
+  cid?: string
+  /** 原始文件名 */
+  fileName?: string
+  /** 文件大小（字节） */
+  fileSize?: number
+  /** 允许业务透传额外字段（如 emailId / fileType 等） */
+  [key: string]: unknown
+}
+
+/** 字体选项 */
+export interface RichTextFontOption {
+  label: string
+  value: string
+}
+
+/** 字号选项（value 为 CSS 长度，如 '14px'） */
+export interface RichTextFontSizeOption {
+  label: string
+  value: string
+}
+
+export interface RichTextProps {
+  /** v-model：HTML 字符串 */
+  modelValue?: string
+  /** 占位文案 */
+  placeholder?: string
+  /** 是否禁用 */
+  disabled?: boolean
+  /** 是否只读 */
+  readonly?: boolean
+  /** 工具条位置：'top' | 'bottom' | false（不显示） */
+  toolbar?: 'top' | 'bottom' | false
+  /** 编辑区最小高度 */
+  minHeight?: number | string
+  /** 编辑区最大高度（超出滚动） */
+  maxHeight?: number | string
+  /** 图片上传函数：接收 File，返回完整元数据 */
+  uploadImage?: (file: File) => Promise<RichTextUploadResult>
+  /** 视频上传函数：接收 File，返回完整元数据 */
+  uploadVideo?: (file: File) => Promise<RichTextUploadResult>
+  /** 预设字体列表（toolbar 下拉） */
+  fonts?: RichTextFontOption[]
+  /** 预设字号列表（toolbar 下拉） */
+  fontSizes?: RichTextFontSizeOption[]
+}
+
+export interface RichTextEmits {
+  (e: 'update:modelValue', html: string): void
+  (e: 'change', html: string): void
+  (e: 'focus', ev: FocusEvent): void
+  (e: 'blur', ev: FocusEvent): void
+  /** 内联资源上传完成：外层收集进 inlines（对齐邮件附件模型） */
+  (e: 'upload-inline', result: RichTextUploadResult, kind: 'image' | 'video'): void
+  /** 上传失败 */
+  (e: 'upload-error', error: Error, kind: 'image' | 'video'): void
+}
+
+export interface RichTextExpose {
+  /** Tiptap Editor 实例 */
+  editor: Editor | undefined
+  /** 当前 HTML */
+  getHTML: () => string
+  /** 纯文本（邮件 text/plain） */
+  getText: () => string
+  /** 聚焦编辑器 */
+  focus: () => void
+  /** 清空内容 */
+  clear: () => void
+}
diff --git a/code/g3soft-libs/packages/ui/src/rich-text/upload.ts b/code/g3soft-libs/packages/ui/src/rich-text/upload.ts
new file mode 100644
index 00000000..051d3caf
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/rich-text/upload.ts
@@ -0,0 +1,102 @@
+import type { Editor } from '@tiptap/vue-3'
+import type { RichTextProps, RichTextUploadResult } from './types'
+
+/** 上传回调集：由 RichText.vue 注入，供 Toolbar 与内部逻辑复用 */
+export interface UploadHandlers {
+  uploadImage?: (file: File) => Promise<RichTextUploadResult>
+  uploadVideo?: (file: File) => Promise<RichTextUploadResult>
+  onInline: (result: RichTextUploadResult, kind: 'image' | 'video') => void
+  onError: (error: Error, kind: 'image' | 'video') => void
+}
+
+/** 可接受的文件类型校验 */
+const IMAGE_TYPES = ['image/jpeg', 'image/png', 'image/gif', 'image/webp', 'image/svg+xml']
+const VIDEO_TYPES = ['video/mp4', 'video/webm', 'video/ogg']
+
+function pickFile(accept: string, multiple = false): Promise<File | null> {
+  return new Promise((resolve) => {
+    const input = document.createElement('input')
+    input.type = 'file'
+    input.accept = accept
+    input.multiple = multiple
+    input.style.display = 'none'
+    document.body.appendChild(input)
+
+    let settled = false
+    const cleanup = () => {
+      if (settled) return
+      settled = true
+      window.removeEventListener('focus', onFocus)
+      input.remove()
+    }
+
+    input.onchange = () => {
+      const file = input.files?.[0] ?? null
+      cleanup()
+      resolve(file)
+    }
+
+    // 用户取消选择时多数浏览器不触发 change，input 会泄漏在 DOM 里。
+    // oncancel 在 Firefox/Safari 不支持 —— 用「窗口重新聚焦」兜底：
+    // 文件对话框关闭后焦点必然回到 window，此时若无 change 即视为取消。
+    const onFocus = () => {
+      // 延迟到下一帧，确保 change（若发生）先于 focus 处理完
+      window.setTimeout(() => {
+        cleanup()
+        resolve(null)
+      }, 300)
+    }
+    window.addEventListener('focus', onFocus)
+
+    input.click()
+  })
+}
+
+function validateType(file: File, kind: 'image' | 'video'): void {
+  const accepted = kind === 'image' ? IMAGE_TYPES : VIDEO_TYPES
+  if (!accepted.includes(file.type)) {
+    throw new Error(`不支持的文件类型：${file.type}`)
+  }
+}
+
+/** 触发图片选择 → 上传 → 插入编辑器，并上报内联资源 */
+export async function insertImage(editor: Editor, handlers: UploadHandlers): Promise<void> {
+  if (!handlers.uploadImage) {
+    handlers.onError(new Error('未提供 uploadImage 上传函数'), 'image')
+    return
+  }
+  const file = await pickFile('image/*')
+  if (!file) return
+
+  try {
+    validateType(file, 'image')
+    const result = await handlers.uploadImage(file)
+    editor.chain().focus().setImage({ src: result.fileUrl }).run()
+    handlers.onInline(result, 'image')
+  } catch (err) {
+    handlers.onError(err instanceof Error ? err : new Error(String(err)), 'image')
+  }
+}
+
+/** 触发视频选择 → 上传 → 插入编辑器，并上报内联资源 */
+export async function insertVideo(editor: Editor, handlers: UploadHandlers): Promise<void> {
+  if (!handlers.uploadVideo) {
+    handlers.onError(new Error('未提供 uploadVideo 上传函数'), 'video')
+    return
+  }
+  const file = await pickFile('video/*')
+  if (!file) return
+
+  try {
+    validateType(file, 'video')
+    const result = await handlers.uploadVideo(file)
+    editor
+      .chain()
+      .focus()
+      .setVideo({ src: result.fileUrl })
+      .run()
+    handlers.onInline(result, 'video')
+  } catch (err) {
+    handlers.onError(err instanceof Error ? err : new Error(String(err)), 'video')
+  }
+}
diff --git a/code/g3soft-libs/pnpm-lock.yaml b/code/g3soft-libs/pnpm-lock.yaml
index d0cdd178..31b50c0d 100644
--- a/code/g3soft-libs/pnpm-lock.yaml
+++ b/code/g3soft-libs/pnpm-lock.yaml
@@ -69,10 +69,55 @@ importers:
       '@lucide/vue':
         specifier: ^1.31.0
         version: 1.52.0(vue@3.5.43(typescript@5.9.3))
+      '@tiptap/extension-image':
+        specifier: ^3.31.4
+        version: 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))
+      '@tiptap/extension-link':
+        specifier: ^3.31.4
+        version: 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)
+      '@tiptap/extension-placeholder':
+        specifier: ^3.31.4
+        version: 3.31.4(@tiptap/extensions@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4))
+      '@tiptap/extension-subscript':
+        specifier: ^3.31.4
+        version: 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)
+      '@tiptap/extension-superscript':
+        specifier: ^3.31.4
+        version: 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)
+      '@tiptap/extension-table':
+        specifier: ^3.31.4
+        version: 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)
+      '@tiptap/extension-table-cell':
+        specifier: ^3.31.4
+        version: 3.31.4(@tiptap/extension-table@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4))
+      '@tiptap/extension-table-header':
+        specifier: ^3.31.4
+        version: 3.31.4(@tiptap/extension-table@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4))
+      '@tiptap/extension-table-row':
+        specifier: ^3.31.4
+        version: 3.31.4(@tiptap/extension-table@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4))
+      '@tiptap/extension-text-align':
+        specifier: ^3.31.4
+        version: 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))
+      '@tiptap/extension-text-style':
+        specifier: ^3.31.4
+        version: 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))
+      '@tiptap/starter-kit':
+        specifier: ^3.31.4
+        version: 3.31.4
     devDependencies:
       '@playwright/test':
         specifier: ^1.63.0
         version: 1.63.0
+      '@tiptap/core':
+        specifier: ^3.31.4
+        version: 3.31.4(@tiptap/pm@3.31.4)
+      '@tiptap/pm':
+        specifier: ^3.31.4
+        version: 3.31.4
+      '@tiptap/vue-3':
+        specifier: ^3.31.4
+        version: 3.31.4(@floating-ui/dom@1.8.0)(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)(vue@3.5.43(typescript@5.9.3))
       '@vitejs/plugin-vue':
         specifier: ^6.0.0
         version: 6.0.9(vite@8.3.3(@types/node@26.6.4)(sass@1.105.1))(vue@3.5.43(typescript@5.9.3))
@@ -423,6 +468,15 @@ packages:
     cpu: [x64]
     os: [win32]
 
+  '@floating-ui/core@1.8.0':
+    resolution: {integrity: sha512-0CIZ5itps/8x7BG8dEIhs53BvCUH2PCoogtakwRTut+Arm58sJooJ0AuZhLw2HJYIR5cMLNPBSS728sPho2khQ==}
+
+  '@floating-ui/dom@1.8.0':
+    resolution: {integrity: sha512-yXSrzeHZBTZadLOlfyhCkJHNeLJnHRnRInwdZ40L7ZiaAtrBwoYlsDrX3v5zB1Utk7CLfzcOVnVVWoXEky7Ceg==}
+
+  '@floating-ui/utils@0.2.12':
+    resolution: {integrity: sha512-HpCo8tmWzLVad5s2d19EhAz5zqrrQ6s69qd6moPMQvkOuSwDT1YgRfWSVuc4ennqrgv3OHppiOGMQ7oC13yIww==}
+
   '@iconify-json/simple-icons@1.2.99':
     resolution: {integrity: sha512-kouZhqvUoNdxEe+lZksbJJZMCZv4b4Ob62O1GW3fcpz/I0mVPzM+9/Qf/DUuv5ns8l6c46D8M/ubhJjjbLp9HQ==}
 
@@ -856,6 +910,207 @@ packages:
   '@shikijs/vscode-textmate@10.0.2':
     resolution: {integrity: sha512-83yeghZ2xxin3Nj8z1NMd/NCuca+gsYXswywDy5bHvwlWL8tpTQmzGeUuHd9FC3E/SBEMvzJRwWEOz5gGes9Qg==}
 
+  '@tiptap/core@3.31.4':
+    resolution: {integrity: sha512-cIVUQYBycighzsk6GbmCef8ZiEDVxoT5EuAe4xg2q9dNkDqCXVqI4YGr9aavCQEiAS4uHiRwqvcsPqJHipFDfg==}
+    peerDependencies:
+      '@tiptap/pm': 3.31.4
+
+  '@tiptap/extension-blockquote@3.31.4':
+    resolution: {integrity: sha512-FHnbvCIW0eDKgUUFjmvEB0ax9YUBW7/Unm+38qpuQROvU872yRqhnDtycKT9IKk46jNdjM4A4fAGUbge10CrAA==}
+    peerDependencies:
+      '@tiptap/core': 3.31.4
+      '@tiptap/pm': 3.31.4
+
+  '@tiptap/extension-bold@3.31.4':
+    resolution: {integrity: sha512-QX1xoXvO0gz6uVsoLegumqQ4MJXL7lcUDQZ4J7la7LBqiIh4efrCmp2EXbhpr37M/YQL7w8q3g7H/VovSh7xIg==}
+    peerDependencies:
+      '@tiptap/core': 3.31.4
+
+  '@tiptap/extension-bubble-menu@3.31.4':
+    resolution: {integrity: sha512-Ml/yswuys+3QkOMajfXyAGlUKCxEbT3dMyF8vHwQ5mDk9MDm+dqp10It5CrDBkUT/KkVTa6AJI3kb0TXZJZiAA==}
+    peerDependencies:
+      '@tiptap/core': 3.31.4
+      '@tiptap/pm': 3.31.4
+
+  '@tiptap/extension-bullet-list@3.31.4':
+    resolution: {integrity: sha512-gHn1RDR4olCnmKpH+G9x+f8R+iKPNVdLlvbFkIpR/stjabZi7fB4Rr5GiHWsulbtxAjdQrNjnVeNdGM4rBxApw==}
+    peerDependencies:
+      '@tiptap/extension-list': 3.31.4
+
+  '@tiptap/extension-code-block@3.31.4':
+    resolution: {integrity: sha512-su/B/cfQ1HpiHl6JfJ6wa+RVEptiYsV4dCntE8XQNj2dUcII4y6w6PQbbswOoDrU79uXHsAvpy44215rghG4LA==}
+    peerDependencies:
+      '@tiptap/core': 3.31.4
+      '@tiptap/pm': 3.31.4
+
+  '@tiptap/extension-code@3.31.4':
+    resolution: {integrity: sha512-pzi8GNDs5J1DEoO1HNYiJ5WZpgOZzlc/2VIa77mMpEuD4hZxuK0BQzlF/O6Ps/O5P1lGJT4xS0Yowpzb9mD9RA==}
+    peerDependencies:
+      '@tiptap/core': 3.31.4
+
+  '@tiptap/extension-document@3.31.4':
+    resolution: {integrity: sha512-vT20u62RWR+BLIyNJ54e24MPUY4zm8VF7tcgJnxQXi7BgVJWcNMtMWWDIkPJ4JNXwfoIznKh3jzYsaYmbCJgQQ==}
+    peerDependencies:
+      '@tiptap/core': 3.31.4
+
+  '@tiptap/extension-dropcursor@3.31.4':
+    resolution: {integrity: sha512-5TbCPCC4RL+QT1NYHjXCYDBHBtVqYOFvFEnk3v98lvXCM2PNL13ofXUfJPuykAVy1OdTAx4DlZOQAD9WKy/IdQ==}
+    peerDependencies:
+      '@tiptap/extensions': 3.31.4
+
+  '@tiptap/extension-floating-menu@3.31.4':
+    resolution: {integrity: sha512-pKzulkDmolpVt7IP9FSPsC5pKbXQ5pyeqkaAYr8cyOVW+KUObpPRIzAuXvEso8PCjWgwJ1f2qyishOEMw8MbfQ==}
+    peerDependencies:
+      '@floating-ui/dom': ^1.0.0
+      '@tiptap/core': 3.31.4
+      '@tiptap/pm': 3.31.4
+
+  '@tiptap/extension-gapcursor@3.31.4':
+    resolution: {integrity: sha512-hBogUAepQH6IQUhaePhPWzQ1Oeu+yqlJVMKO06Eue5m36uRy1PZZAQ780pCGT0SC4R5MH2td1N8EUQ7bupQdDA==}
+    peerDependencies:
+      '@tiptap/extensions': 3.31.4
+
+  '@tiptap/extension-hard-break@3.31.4':
+    resolution: {integrity: sha512-oLNajLyUvRMg1qtzFgKGduygTlpaHFB9PU+M+pUWdA4sa1bRnxS2Y++Ao4lHYopJ7nxatLndrYoCIHkotqkPDQ==}
+    peerDependencies:
+      '@tiptap/core': 3.31.4
+
+  '@tiptap/extension-heading@3.31.4':
+    resolution: {integrity: sha512-KqlSeLathpdxCc3kVHBCA/RkHvb+V7u5vgiSEu1Cv3L70r7F19COMGODav/k1AGYBgEXKL6lM9cy8cloE5/28g==}
+    peerDependencies:
+      '@tiptap/core': 3.31.4
+
+  '@tiptap/extension-horizontal-rule@3.31.4':
+    resolution: {integrity: sha512-ws0Kh8kfHL7ESILSXj0HJAXs8G10ewlW1sedXKm8dm0op9L8il+xl8bEJVoqG/jMf77900Fc2CaQldcCGRpF1g==}
+    peerDependencies:
+      '@tiptap/core': 3.31.4
+      '@tiptap/pm': 3.31.4
+
+  '@tiptap/extension-image@3.31.4':
+    resolution: {integrity: sha512-vtD+rK73abJnPRKOjU37sQTCa5Auyg451yhqZD/3lZKiFJDBHAZKI7lQARkXBQYK289hBhK6yMIwofoqCBvi3g==}
+    peerDependencies:
+      '@tiptap/core': 3.31.4
+
+  '@tiptap/extension-italic@3.31.4':
+    resolution: {integrity: sha512-pftTQBPYZocNDAj/u6OyDIp7YxmN0+N895cQPogJQ6qMHdLiRhzgawiEewJkniyN1w8k3Wx/Etp8pTKrxaOOBQ==}
+    peerDependencies:
+      '@tiptap/core': 3.31.4
+
+  '@tiptap/extension-link@3.31.4':
+    resolution: {integrity: sha512-LLxW3qfeL9gvDdMPVdxYFYZ0zZSjsoIDhOqjJ5U2UfaK3U2iwkKTBgV2qT+FWf3uUHmBRjBZ08q3dRPmWBAD5g==}
+    peerDependencies:
+      '@tiptap/core': 3.31.4
+      '@tiptap/pm': 3.31.4
+
+  '@tiptap/extension-list-item@3.31.4':
+    resolution: {integrity: sha512-ao8XAPvhOrtGFILs+fKtOM91omDSpUC8X19m44gbaq5xJDVpIMZ0rP+NAVUS72G7LskhcHa0bu/Pm022bUVjVw==}
+    peerDependencies:
+      '@tiptap/extension-list': 3.31.4
+
+  '@tiptap/extension-list-keymap@3.31.4':
+    resolution: {integrity: sha512-etdkl/YnYfwtALDxecJ+4WYgJAez1fn1vzzZqJklZBpgqiZtny3NxpvWS7/JhsltNG84Wo/oovpfJgVmzhddrw==}
+    peerDependencies:
+      '@tiptap/extension-list': 3.31.4
+
+  '@tiptap/extension-list@3.31.4':
+    resolution: {integrity: sha512-Wd4YRYxOdf+TtF33/QsRo1RK1CecVxjYGjUBIKNGHAywfh8tghgV4YOUCiV1iJqYt2IBs+RWlIqTmdIPzBrd4A==}
+    peerDependencies:
+      '@tiptap/core': 3.31.4
+      '@tiptap/pm': 3.31.4
+
+  '@tiptap/extension-ordered-list@3.31.4':
+    resolution: {integrity: sha512-UNWyF+Dhm08znszIMnT8Y2kJ1lvtiCvUGs1aG7m9cPHxDa7VycWnOqdtXWkc+6xRLNiC0zgWCFWgLLHduV8pRQ==}
+    peerDependencies:
+      '@tiptap/extension-list': 3.31.4
+
+  '@tiptap/extension-paragraph@3.31.4':
+    resolution: {integrity: sha512-WZlBgw+XVKXerRlmEsoQ7x1PwSU+dh3X+b70+ViZsLebdfsmmYBIaNDrvIGwG9UQr5eLnddJnZplMSTI2YKs+g==}
+    peerDependencies:
+      '@tiptap/core': 3.31.4
+
+  '@tiptap/extension-placeholder@3.31.4':
+    resolution: {integrity: sha512-3SoJopaOzaA9IZHSk9ZXHiO6ib8ErPh7ssRh3bIaxfD+BqRyXcm4hV4yfFXTqrDCnl5FE+DbBRGmeVAVkDko3g==}
+    peerDependencies:
+      '@tiptap/extensions': 3.31.4
+
+  '@tiptap/extension-strike@3.31.4':
+    resolution: {integrity: sha512-4MBr63TJIMqxCjE+gAPdlY1IdELgvbAP516K3Ntn/BkcpEbEoPMEYVz+XTxULyHQEuARDO6jsXPPxRXpA74jaw==}
+    peerDependencies:
+      '@tiptap/core': 3.31.4
+
+  '@tiptap/extension-subscript@3.31.4':
+    resolution: {integrity: sha512-90gg5+av98JxdVTIR7PcZWIJj/fMI+3SJlIXIYBhpU6I7ZE02rUPz4DWluSlzNB04TFy+f4++CyB0wBiCwxpQQ==}
+    peerDependencies:
+      '@tiptap/core': 3.31.4
+      '@tiptap/pm': 3.31.4
+
+  '@tiptap/extension-superscript@3.31.4':
+    resolution: {integrity: sha512-fN2sVrfYfFHXUSWOnAplHfOBbVhYi9SRuESAvwlNqq/8Em0U7NSNmGG3MipOZaPwWZ2/N4GtkViuk22gYrCdQA==}
+    peerDependencies:
+      '@tiptap/core': 3.31.4
+      '@tiptap/pm': 3.31.4
+
+  '@tiptap/extension-table-cell@3.31.4':
+    resolution: {integrity: sha512-jM5siWIALv7AIRGgWmiLxEaVnyQ26VqAPaF5E8TM2Z/u9AWZ8UfPCzJnHeWQxYMyFdZzYZJQXbA+5VfNLl36zg==}
+    peerDependencies:
+      '@tiptap/extension-table': 3.31.4
+
+  '@tiptap/extension-table-header@3.31.4':
+    resolution: {integrity: sha512-6DARj2c/fbGq46PbtMaJrxSn8HPWeC45xOV/nDeK5gxsvvBllGx7g2HQjj/WNY74H0HazBfJLlRDPUV4WQkFAA==}
+    peerDependencies:
+      '@tiptap/extension-table': 3.31.4
+
+  '@tiptap/extension-table-row@3.31.4':
+    resolution: {integrity: sha512-JZhKD6gA4up6xkEiQA6mKPCvj0ZWh5uUyZNvi/RyOzSjyiQdibOxuovVDiOSQwn9Bs4VpmM3KVcriuxnP2nYSA==}
+    peerDependencies:
+      '@tiptap/extension-table': 3.31.4
+
+  '@tiptap/extension-table@3.31.4':
+    resolution: {integrity: sha512-ai7DLwg/xmhlUas3LgWaPQdPlZ8StliY6Dn+iUH6eyZ/TQqRDY/oeIsKWaHpXq22T5M5dMlZPTg172ZdtwKswQ==}
+    peerDependencies:
+      '@tiptap/core': 3.31.4
+      '@tiptap/pm': 3.31.4
+
+  '@tiptap/extension-text-align@3.31.4':
+    resolution: {integrity: sha512-Z8x/x2N4BiFwu7+UfJABT/OQbwZPUHbmvAH6Fo5lefgeIlTwAXFBzz4x7Eeed7iJAcXUzOnyd6bmkhK36gYJ2g==}
+    peerDependencies:
+      '@tiptap/core': 3.31.4
+
+  '@tiptap/extension-text-style@3.31.4':
+    resolution: {integrity: sha512-djeemliEWmqs3cJrUyMG+17HbjHyf6D/0NkIHl/RkVHYOCX1AYMZ7r+XLefApSNBCAx/aFh1hJzaMlnGbnTaAw==}
+    peerDependencies:
+      '@tiptap/core': 3.31.4
+
+  '@tiptap/extension-text@3.31.4':
+    resolution: {integrity: sha512-WL2ZRpFksgQcXJN05/UQH09YCH9LlhdLrSEcviASvEH/aAfsKiJlDrouN8PET+YAWK/F5xFc5/Q1z0xj+I23jw==}
+    peerDependencies:
+      '@tiptap/core': 3.31.4
+
+  '@tiptap/extension-underline@3.31.4':
+    resolution: {integrity: sha512-0iFGPIqmqGkCrOFh1OPo7Dzv5s86dVN3bZaugsz0jK04otkb8bn04ZDKP2/6Wq+lcK0M9DfJ0QqfW5hC2nBZxQ==}
+    peerDependencies:
+      '@tiptap/core': 3.31.4
+
+  '@tiptap/extensions@3.31.4':
+    resolution: {integrity: sha512-nIupIne/sHpV2Kw1M4MOmr4+G454KI8BXM5+LWKOU2EpzfALZWVSy7koF9lVRna4Zp5Gv8hfg5Z8kvmrYQvhkw==}
+    peerDependencies:
+      '@tiptap/core': 3.31.4
+      '@tiptap/pm': 3.31.4
+
+  '@tiptap/pm@3.31.4':
+    resolution: {integrity: sha512-x7dwth79cQp4QGae66/RJqMDJQv0+n7b7dD7cyFQBWqzPFLJxN/4paHY4qbWedZjNLhRyIOAD9a5q4AYM1zmPA==}
+
+  '@tiptap/starter-kit@3.31.4':
+    resolution: {integrity: sha512-u7HIJ9vK6kFe4S4J2CIcDLrhRZzoTMSyU0XxjQ6lUNF7pWW3rMi//pvi8RcsZmxGjyb8CpXAqYgNl7f9WyaUeA==}
+
+  '@tiptap/vue-3@3.31.4':
+    resolution: {integrity: sha512-xi/t4EfSX9QEbOSC0RhkzhT78GJSeJ2Jmz0EBV860lcxDdNd+Xw1pfOjFseNz2E+r3zhTcKDBsLblhCao7eF5Q==}
+    peerDependencies:
+      '@floating-ui/dom': ^1.0.0
+      '@tiptap/core': 3.31.4
+      '@tiptap/pm': 3.31.4
+      vue: ^3.0.0
+
   '@types/chai@5.2.3':
     resolution: {integrity: sha512-Mw558oeA9fFbv65/y4mHtXDs9bPnFMZAL/jxdPFUpOHHIXX91mcgEHbS5Lahr+pwZFR8A7GQleRWeI6cGFC2UA==}
 
@@ -1514,6 +1769,9 @@ packages:
   linkify-it@5.0.2:
     resolution: {integrity: sha512-ONTm2jCMAVZjgQa/Fy1kScXsuOoF5NPTsoFBdE1KVIZ2vAh/r9+Bqo+0jINCBYnavTPQZz38QzFTme79ENoN3Q==}
 
+  linkifyjs@4.3.3:
+    resolution: {integrity: sha512-P8aEP5U/D1/IlTY2OeYsErdwh9bGuLE30NcXtKEjgdHcahveQoQwM2yZNsioQHsWFz0P7KKudisbrzCgR0sDHg==}
+
   local-pkg@1.2.1:
     resolution: {integrity: sha512-++gUqRDEvcnN6Zhqrr+y/CkVEHhlrR96vZn3nZZPYzMcBUyBtTKzB9NadClFIsIVSsu+3i9tfk/erqy9kAmt7Q==}
     engines: {node: '>=14'}
@@ -1698,6 +1956,9 @@ packages:
   oniguruma-to-es@2.3.0:
     resolution: {integrity: sha512-bwALDxriqfKGfUufKGGepCzu9x7nJQuoRoAFp4AnwehhC2crqrDIAP/uN2qdlsAvSMpeRC3+Yzhqc7hLmle5+g==}
 
+  orderedmap@2.1.1:
+    resolution: {integrity: sha512-TvAWxi0nDe1j/rtMcWcIj94+Ffe6n7zhow33h40SKxmsmozs6dz/e+EajymfoFcHd7sxNn8yHM8839uixMOV6g==}
+
   outdent@0.5.0:
     resolution: {integrity: sha512-/jHxFIzoMXdqPzTaCpFzAAWhpkSjZPF4Vsn6jAfNpmbH/ymsmd7Qc6VE9BGn0L6YMj6uwpQLxCECpus4ukKS9Q==}
 
@@ -1810,6 +2071,45 @@ packages:
   property-information@7.2.0:
     resolution: {integrity: sha512-IAtzIB6sUiWaJYrX9smp3V46pBGbBeLFRGdh25kg1334VcBlD8HzhPeNIWQH9zhGmo2itIe25EHt9dQP7G5hmg==}
 
+  prosemirror-changeset@2.4.4:
+    resolution: {integrity: sha512-Gyuz9jYdrAeA9I7AholyOes9KUmv/lEwsC5O9s5xF5VB3EgTPsXMGUxz4+H1B+wKVPdZbvRcg1Cp3x8qX+8ofA==}
+
+  prosemirror-commands@1.7.2:
+    resolution: {integrity: sha512-q6Q6szxqdu9Xd6EcdKsqXghu5nQdZTpB4Q9yd04WRc7/jt763e/rT60Owh0L1GYY+T46o5rD+9lEN36dZS43tw==}
+
+  prosemirror-dropcursor@1.8.4:
+    resolution: {integrity: sha512-VmKxhcA6a+h5oPSYmfF1ZNeQqPbyYaIxqZsKqeYCyTlPtrjUgNaHL3P8vVaO19oqAV0zuaM/axkowZHrB1P3Tg==}
+
+  prosemirror-gapcursor@1.4.1:
+    resolution: {integrity: sha512-pMdYaEnjNMSwl11yjEGtgTmLkR08m/Vl+Jj443167p9eB3HVQKhYCc4gmHVDsLPODfZfjr/MmirsdyZziXbQKw==}
+
+  prosemirror-history@1.5.1:
+    resolution: {integrity: sha512-onlwnqKvgtFg6srZOmDOAhlAy1FIHQpOExORybX0S+DvJepE5tPALrB9iGet/2sqqqrelSnB10OoiOJqAvu2DA==}
+
+  prosemirror-inputrules@1.5.1:
+    resolution: {integrity: sha512-7wj4uMjKaXWAQ1CDgxNzNtR9AlsuwzHfdFH1ygEHA2KHF2DOEaXl1CJfNPAKCg9qNEh4rum975QLaCiQPyY6Fw==}
+
+  prosemirror-keymap@1.2.3:
+    resolution: {integrity: sha512-4HucRlpiLd1IPQQXNqeo81BGtkY8Ai5smHhKW9jjPKRc2wQIxksg7Hl1tTI2IfT2B/LgX6bfYvXxEpJl7aKYKw==}
+
+  prosemirror-model@1.25.12:
+    resolution: {integrity: sha512-Ue2gTmXMa7EhpLNhC7J+h4+ykD8ha12K6rrZFFKKJHBForfIStw5gJ6Zrf1mqqAa9NmpmEB4wp9bKmA4eUVjWg==}
+
+  prosemirror-schema-list@1.5.1:
+    resolution: {integrity: sha512-927lFx/uwyQaGwJxLWCZRkjXG0p48KpMj6ueoYiu4JX05GGuGcgzAy62dfiV8eFZftgyBUvLx76RsMe20fJl+Q==}
+
+  prosemirror-state@1.4.4:
+    resolution: {integrity: sha512-6jiYHH2CIGbCfnxdHbXZ12gySFY/fz/ulZE333G6bPqIZ4F+TXo9ifiR86nAHpWnfoNjOb3o5ESi7J8Uz1jXHw==}
+
+  prosemirror-tables@1.8.5:
+    resolution: {integrity: sha512-V/0cDCsHKHe/tfWkeCmthNUcEp1IVO3p6vwN8XtwE9PZQLAZJigbw3QoraAdfJPir4NKJtNvOB8oYGKRl+t0Dw==}
+
+  prosemirror-transform@1.12.2:
+    resolution: {integrity: sha512-PE/aY0HEY4zczvmqrilgkUK/WautF0chvMqkmM/iN5/aPHvwrCWaQZjS6CIZp+K84YrvPFqrL+YArrfJX8xX7g==}
+
+  prosemirror-view@1.42.6:
+    resolution: {integrity: sha512-3g25f6hKV2bBxo3puH3EcYWmmVNSH0iWmNsMVT7sugDSpA025jgpOLarcDWr39SdzPjYMaiYtRdNtXialPSjEQ==}
+
   proto-list@1.2.4:
     resolution: {integrity: sha512-vtK/94akxsTMhe0/cbfpR+syPuszcuwhqVjJq26CuNDgFGj682oRBXOP5MJpv2r7JtE8MsiepGIqvvOTBwn2vA==}
 
@@ -1882,6 +2182,9 @@ packages:
     engines: {node: '>=18.0.0', npm: '>=8.0.0'}
     hasBin: true
 
+  rope-sequence@1.3.4:
+    resolution: {integrity: sha512-UT5EDe2cu2E/6O4igUr5PSFs23nvvukicWHx6GnOPlHAiiYbzNuCRQCuiUdHJQcqKalLKlrYJnjY0ySGsXNQXQ==}
+
   run-parallel@1.2.0:
     resolution: {integrity: sha512-5l4VyZR86LZ/lDxZTR6jqL8AFE2S0IFLMP26AbjsLVADxHdhB/c0GUsH+y39UfCi3dzz8OlQuPmnaJOMoDHQBA==}
 
@@ -2250,6 +2553,9 @@ packages:
       typescript:
         optional: true
 
+  w3c-keyname@2.2.8:
+    resolution: {integrity: sha512-dpojBhNsCNN7T82Tm7k26A6G9ML3NkhDsnw9n/eoxSRlVBB4CEtIQ/KTCLI2Fwf3ataSXRhYFkQi3SlnFwPvPQ==}
+
   webpack-virtual-modules@0.6.2:
     resolution: {integrity: sha512-66/V2i5hQanC51vBQKPH4aI8NMAcBW59FVBs+rC7eGHupMyfn34q7rZIE+ETlJ+XTevqfUhVVBgSUNSW2flEUQ==}
 
@@ -2669,6 +2975,17 @@ snapshots:
   '@esbuild/win32-x64@0.21.3':
     optional: true
 
+  '@floating-ui/core@1.8.0':
+    dependencies:
+      '@floating-ui/utils': 0.2.12
+
+  '@floating-ui/dom@1.8.0':
+    dependencies:
+      '@floating-ui/core': 1.8.0
+      '@floating-ui/utils': 0.2.12
+
+  '@floating-ui/utils@0.2.12': {}
+
   '@iconify-json/simple-icons@1.2.99':
     dependencies:
       '@iconify/types': 2.0.0
@@ -2979,6 +3296,215 @@ snapshots:
 
   '@shikijs/vscode-textmate@10.0.2': {}
 
+  '@tiptap/core@3.31.4(@tiptap/pm@3.31.4)':
+    dependencies:
+      '@tiptap/pm': 3.31.4
+
+  '@tiptap/extension-blockquote@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)':
+    dependencies:
+      '@tiptap/core': 3.31.4(@tiptap/pm@3.31.4)
+      '@tiptap/pm': 3.31.4
+
+  '@tiptap/extension-bold@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))':
+    dependencies:
+      '@tiptap/core': 3.31.4(@tiptap/pm@3.31.4)
+
+  '@tiptap/extension-bubble-menu@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)':
+    dependencies:
+      '@floating-ui/dom': 1.8.0
+      '@tiptap/core': 3.31.4(@tiptap/pm@3.31.4)
+      '@tiptap/pm': 3.31.4
+    optional: true
+
+  '@tiptap/extension-bullet-list@3.31.4(@tiptap/extension-list@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4))':
+    dependencies:
+      '@tiptap/extension-list': 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)
+
+  '@tiptap/extension-code-block@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)':
+    dependencies:
+      '@tiptap/core': 3.31.4(@tiptap/pm@3.31.4)
+      '@tiptap/pm': 3.31.4
+
+  '@tiptap/extension-code@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))':
+    dependencies:
+      '@tiptap/core': 3.31.4(@tiptap/pm@3.31.4)
+
+  '@tiptap/extension-document@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))':
+    dependencies:
+      '@tiptap/core': 3.31.4(@tiptap/pm@3.31.4)
+
+  '@tiptap/extension-dropcursor@3.31.4(@tiptap/extensions@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4))':
+    dependencies:
+      '@tiptap/extensions': 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)
+
+  '@tiptap/extension-floating-menu@3.31.4(@floating-ui/dom@1.8.0)(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)':
+    dependencies:
+      '@floating-ui/dom': 1.8.0
+      '@tiptap/core': 3.31.4(@tiptap/pm@3.31.4)
+      '@tiptap/pm': 3.31.4
+    optional: true
+
+  '@tiptap/extension-gapcursor@3.31.4(@tiptap/extensions@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4))':
+    dependencies:
+      '@tiptap/extensions': 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)
+
+  '@tiptap/extension-hard-break@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))':
+    dependencies:
+      '@tiptap/core': 3.31.4(@tiptap/pm@3.31.4)
+
+  '@tiptap/extension-heading@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))':
+    dependencies:
+      '@tiptap/core': 3.31.4(@tiptap/pm@3.31.4)
+
+  '@tiptap/extension-horizontal-rule@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)':
+    dependencies:
+      '@tiptap/core': 3.31.4(@tiptap/pm@3.31.4)
+      '@tiptap/pm': 3.31.4
+
+  '@tiptap/extension-image@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))':
+    dependencies:
+      '@tiptap/core': 3.31.4(@tiptap/pm@3.31.4)
+
+  '@tiptap/extension-italic@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))':
+    dependencies:
+      '@tiptap/core': 3.31.4(@tiptap/pm@3.31.4)
+
+  '@tiptap/extension-link@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)':
+    dependencies:
+      '@tiptap/core': 3.31.4(@tiptap/pm@3.31.4)
+      '@tiptap/pm': 3.31.4
+      linkifyjs: 4.3.3
+
+  '@tiptap/extension-list-item@3.31.4(@tiptap/extension-list@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4))':
+    dependencies:
+      '@tiptap/extension-list': 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)
+
+  '@tiptap/extension-list-keymap@3.31.4(@tiptap/extension-list@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4))':
+    dependencies:
+      '@tiptap/extension-list': 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)
+
+  '@tiptap/extension-list@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)':
+    dependencies:
+      '@tiptap/core': 3.31.4(@tiptap/pm@3.31.4)
+      '@tiptap/pm': 3.31.4
+
+  '@tiptap/extension-ordered-list@3.31.4(@tiptap/extension-list@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4))':
+    dependencies:
+      '@tiptap/extension-list': 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)
+
+  '@tiptap/extension-paragraph@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))':
+    dependencies:
+      '@tiptap/core': 3.31.4(@tiptap/pm@3.31.4)
+
+  '@tiptap/extension-placeholder@3.31.4(@tiptap/extensions@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4))':
+    dependencies:
+      '@tiptap/extensions': 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)
+
+  '@tiptap/extension-strike@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))':
+    dependencies:
+      '@tiptap/core': 3.31.4(@tiptap/pm@3.31.4)
+
+  '@tiptap/extension-subscript@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)':
+    dependencies:
+      '@tiptap/core': 3.31.4(@tiptap/pm@3.31.4)
+      '@tiptap/pm': 3.31.4
+
+  '@tiptap/extension-superscript@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)':
+    dependencies:
+      '@tiptap/core': 3.31.4(@tiptap/pm@3.31.4)
+      '@tiptap/pm': 3.31.4
+
+  '@tiptap/extension-table-cell@3.31.4(@tiptap/extension-table@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4))':
+    dependencies:
+      '@tiptap/extension-table': 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)
+
+  '@tiptap/extension-table-header@3.31.4(@tiptap/extension-table@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4))':
+    dependencies:
+      '@tiptap/extension-table': 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)
+
+  '@tiptap/extension-table-row@3.31.4(@tiptap/extension-table@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4))':
+    dependencies:
+      '@tiptap/extension-table': 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)
+
+  '@tiptap/extension-table@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)':
+    dependencies:
+      '@tiptap/core': 3.31.4(@tiptap/pm@3.31.4)
+      '@tiptap/pm': 3.31.4
+
+  '@tiptap/extension-text-align@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))':
+    dependencies:
+      '@tiptap/core': 3.31.4(@tiptap/pm@3.31.4)
+
+  '@tiptap/extension-text-style@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))':
+    dependencies:
+      '@tiptap/core': 3.31.4(@tiptap/pm@3.31.4)
+
+  '@tiptap/extension-text@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))':
+    dependencies:
+      '@tiptap/core': 3.31.4(@tiptap/pm@3.31.4)
+
+  '@tiptap/extension-underline@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))':
+    dependencies:
+      '@tiptap/core': 3.31.4(@tiptap/pm@3.31.4)
+
+  '@tiptap/extensions@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)':
+    dependencies:
+      '@tiptap/core': 3.31.4(@tiptap/pm@3.31.4)
+      '@tiptap/pm': 3.31.4
+
+  '@tiptap/pm@3.31.4':
+    dependencies:
+      prosemirror-changeset: 2.4.4
+      prosemirror-commands: 1.7.2
+      prosemirror-dropcursor: 1.8.4
+      prosemirror-gapcursor: 1.4.1
+      prosemirror-history: 1.5.1
+      prosemirror-inputrules: 1.5.1
+      prosemirror-keymap: 1.2.3
+      prosemirror-model: 1.25.12
+      prosemirror-schema-list: 1.5.1
+      prosemirror-state: 1.4.4
+      prosemirror-tables: 1.8.5
+      prosemirror-transform: 1.12.2
+      prosemirror-view: 1.42.6
+
+  '@tiptap/starter-kit@3.31.4':
+    dependencies:
+      '@tiptap/core': 3.31.4(@tiptap/pm@3.31.4)
+      '@tiptap/extension-blockquote': 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)
+      '@tiptap/extension-bold': 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))
+      '@tiptap/extension-bullet-list': 3.31.4(@tiptap/extension-list@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4))
+      '@tiptap/extension-code': 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))
+      '@tiptap/extension-code-block': 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)
+      '@tiptap/extension-document': 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))
+      '@tiptap/extension-dropcursor': 3.31.4(@tiptap/extensions@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4))
+      '@tiptap/extension-gapcursor': 3.31.4(@tiptap/extensions@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4))
+      '@tiptap/extension-hard-break': 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))
+      '@tiptap/extension-heading': 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))
+      '@tiptap/extension-horizontal-rule': 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)
+      '@tiptap/extension-italic': 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))
+      '@tiptap/extension-link': 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)
+      '@tiptap/extension-list': 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)
+      '@tiptap/extension-list-item': 3.31.4(@tiptap/extension-list@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4))
+      '@tiptap/extension-list-keymap': 3.31.4(@tiptap/extension-list@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4))
+      '@tiptap/extension-ordered-list': 3.31.4(@tiptap/extension-list@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4))
+      '@tiptap/extension-paragraph': 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))
+      '@tiptap/extension-strike': 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))
+      '@tiptap/extension-text': 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))
+      '@tiptap/extension-underline': 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))
+      '@tiptap/extensions': 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)
+      '@tiptap/pm': 3.31.4
+
+  '@tiptap/vue-3@3.31.4(@floating-ui/dom@1.8.0)(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)(vue@3.5.43(typescript@5.9.3))':
+    dependencies:
+      '@floating-ui/dom': 1.8.0
+      '@tiptap/core': 3.31.4(@tiptap/pm@3.31.4)
+      '@tiptap/pm': 3.31.4
+      vue: 3.5.43(typescript@5.9.3)
+    optionalDependencies:
+      '@tiptap/extension-bubble-menu': 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)
+      '@tiptap/extension-floating-menu': 3.31.4(@floating-ui/dom@1.8.0)(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)
+
   '@types/chai@5.2.3':
     dependencies:
       '@types/deep-eql': 4.0.2
@@ -3615,6 +4141,8 @@ snapshots:
     dependencies:
       uc.micro: 2.1.0
 
+  linkifyjs@4.3.3: {}
+
   local-pkg@1.2.1:
     dependencies:
       mlly: 1.8.2
@@ -3914,6 +4442,8 @@ snapshots:
       regex: 5.1.1
       regex-recursion: 5.1.1
 
+  orderedmap@2.1.1: {}
+
   outdent@0.5.0: {}
 
   p-filter@2.1.0:
@@ -3997,6 +4527,80 @@ snapshots:
 
   property-information@7.2.0: {}
 
+  prosemirror-changeset@2.4.4:
+    dependencies:
+      prosemirror-transform: 1.12.2
+
+  prosemirror-commands@1.7.2:
+    dependencies:
+      prosemirror-model: 1.25.12
+      prosemirror-state: 1.4.4
+      prosemirror-transform: 1.12.2
+
+  prosemirror-dropcursor@1.8.4:
+    dependencies:
+      prosemirror-state: 1.4.4
+      prosemirror-transform: 1.12.2
+      prosemirror-view: 1.42.6
+
+  prosemirror-gapcursor@1.4.1:
+    dependencies:
+      prosemirror-keymap: 1.2.3
+      prosemirror-model: 1.25.12
+      prosemirror-state: 1.4.4
+      prosemirror-view: 1.42.6
+
+  prosemirror-history@1.5.1:
+    dependencies:
+      prosemirror-state: 1.4.4
+      prosemirror-transform: 1.12.2
+      prosemirror-view: 1.42.6
+      rope-sequence: 1.3.4
+
+  prosemirror-inputrules@1.5.1:
+    dependencies:
+      prosemirror-state: 1.4.4
+      prosemirror-transform: 1.12.2
+
+  prosemirror-keymap@1.2.3:
+    dependencies:
+      prosemirror-state: 1.4.4
+      w3c-keyname: 2.2.8
+
+  prosemirror-model@1.25.12:
+    dependencies:
+      orderedmap: 2.1.1
+
+  prosemirror-schema-list@1.5.1:
+    dependencies:
+      prosemirror-model: 1.25.12
+      prosemirror-state: 1.4.4
+      prosemirror-transform: 1.12.2
+
+  prosemirror-state@1.4.4:
+    dependencies:
+      prosemirror-model: 1.25.12
+      prosemirror-transform: 1.12.2
+      prosemirror-view: 1.42.6
+
+  prosemirror-tables@1.8.5:
+    dependencies:
+      prosemirror-keymap: 1.2.3
+      prosemirror-model: 1.25.12
+      prosemirror-state: 1.4.4
+      prosemirror-transform: 1.12.2
+      prosemirror-view: 1.42.6
+
+  prosemirror-transform@1.12.2:
+    dependencies:
+      prosemirror-model: 1.25.12
+
+  prosemirror-view@1.42.6:
+    dependencies:
+      prosemirror-model: 1.25.12
+      prosemirror-state: 1.4.4
+      prosemirror-transform: 1.12.2
+
   proto-list@1.2.4: {}
 
   publint@0.3.25:
@@ -4126,6 +4730,8 @@ snapshots:
       '@rollup/rollup-win32-x64-msvc': 4.64.0
       fsevents: 2.3.3
 
+  rope-sequence@1.3.4: {}
+
   run-parallel@1.2.0:
     dependencies:
       queue-microtask: 1.2.3
@@ -4474,6 +5080,8 @@ snapshots:
     optionalDependencies:
       typescript: 5.9.3
 
+  w3c-keyname@2.2.8: {}
+
   webpack-virtual-modules@0.6.2: {}
 
   whatwg-mimetype@3.0.0: {}