# OneOS V2 Complex Ledger Column Customization Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Add complete, discoverable OneOS V2 design-system rules for PC/Web complex-ledger column resizing, column visibility, column ordering, persistence, recovery, and accessibility.

**Architecture:** Keep the complete normative rules in the existing Table component section, then add narrow scope and accessibility references in the Layout and Accessibility chapters. Add only a concise mandatory summary to the top-level design-system document so the overview stays readable while all implementation details remain in one authoritative section.

**Tech Stack:** Markdown design-system documentation, OneOS V2 design tokens, existing React vehicle-assets table as the standard example.

---

## File Map

- Modify `src/resources/design-system/chapters/03-components.md`: authoritative component, interaction, persistence, recovery, and acceptance rules.
- Modify `src/resources/design-system/chapters/02-layout.md`: PC/Web scope, H5 exclusion, and horizontal-overflow boundary.
- Modify `src/resources/design-system/chapters/06-accessibility.md`: keyboard, focus, live-region, and drag-alternative requirements.
- Modify `src/resources/design-system/DESIGN.md`: mandatory overview summary and links to the authoritative chapter rules.
- Reference only `src/prototypes/vehicle-management/components/ListView.tsx`: existing standard example; do not change its business behavior in this plan.

The workspace is not a Git repository, so this plan intentionally contains no commit commands. Each task ends with a file-level verification checkpoint instead.

### Task 1: Add the authoritative Table column-personalization rules

**Files:**
- Modify: `src/resources/design-system/chapters/03-components.md`, immediately after the current `### 3.1 Table（Web）` base bullets and before `### 3.2 List / Description / KPI / Card`
- Reference: `docs/superpowers/specs/2026-07-26-complex-ledger-column-customization-design.md`

- [ ] **Step 1: Capture the expected section contract before editing**

Run:

```bash
rg -n "复杂台账列个性化|列宽调整|列设置|userId.*ledgerId.*schemaVersion" \
  src/resources/design-system/chapters/03-components.md
```

Expected: no matches, proving the normative section is currently absent.

- [ ] **Step 2: Add the complete normative section**

Insert this Markdown:

```markdown
#### 3.1.1 复杂台账列个性化（PC / Web 强制）

适用于字段较多、需要横向浏览或用户角色关注字段不同的复杂台账。车辆资产页
`src/prototypes/vehicle-management/components/ListView.tsx` 为标准交互示例。

**能力与入口**

- 表头列分隔线提供列宽调节把手；拖动时实时预览，释放后保存。
- 台账工具栏提供“列设置”图标按钮，弹层集中处理列显隐、列顺序和恢复默认。
- 弹层内修改先暂存；“确认”后一次应用并保存，“取消”不改变当前列表。

**列宽**

- 调节把手命中区约 `12px`；默认显示细分隔线，Hover、Focus 和拖动时使用主题主色增强。
- 普通业务列限制为 `90–480px`；首个核心识别列建议限制为 `120–360px`。
- 达到边界后停止变化，不允许无限缩小或撑宽。
- 双击把手只恢复当前列默认宽度。
- 表格继续在自身滚动容器内横向滚动，不得造成整页横向滚动。

**固定列与业务列**

- 首个核心识别列：必须显示、不可换序、允许在限制范围内调宽。
- 末尾操作列：必须显示、不可换序、不可调宽，宽度依据 `OperationActions` 规范固定。
- 其他业务列：允许显隐、换序和调宽；排序不得越过两端固定列。
- “全选/全不选”只影响可选业务列。固定列必须展示“固定”标识及限制说明。

**保存与恢复**

- 配置按“用户 + 台账页面”自动保存；建议保存键包含
  `userId + ledgerId + schemaVersion`。
- 配置至少包含 `columnWidths`、`visibleColumns`、`columnOrder`。
- 列宽在拖动结束后保存；列显隐与顺序在弹层确认后保存。
- 再次进入同一台账时恢复配置；不同用户和不同台账之间隔离。
- “恢复默认”在弹层内预览默认列宽、显隐和顺序，用户确认后应用并保存，不使用危险确认弹窗。
- 新增字段按设计默认显隐状态和默认位置合并；已删除字段自动忽略，历史配置不得整体失效。
- 配置损坏、版本不兼容或加载失败时回退默认配置，不阻塞台账数据加载。
- 保存失败时保留当前会话配置并轻提示：
  “当前设置暂未同步，下次进入可能恢复默认”。

**主题与反馈**

- 把手、焦点、选中和拖拽目标状态必须消费 OneOS V2 主题 Token，不得硬编码品牌色。
- 固定和禁用状态必须有文字或图标加文字说明，不能只依赖颜色。
- 保存过程不得阻塞台账浏览和操作。
```

- [ ] **Step 3: Verify the authoritative section is complete and unique**

Run:

```bash
rg -n "复杂台账列个性化|90–480px|120–360px|columnWidths|当前设置暂未同步" \
  src/resources/design-system/chapters/03-components.md
```

Expected: each required phrase appears once inside section `3.1.1`.

### Task 2: Define platform and overflow boundaries

**Files:**
- Modify: `src/resources/design-system/chapters/02-layout.md`, in `### 4.1 Web 列表页`
- Reference: `src/resources/design-system/DESIGN.md`, existing H5 table-to-card rule

- [ ] **Step 1: Verify the platform boundary is missing**

Run:

```bash
rg -n "H5.*忽略.*列配置|列个性化.*PC|整页横向滚动.*列宽" \
  src/resources/design-system/chapters/02-layout.md
```

Expected: no complete rule matching all three concerns.

- [ ] **Step 2: Add the PC/Web and H5 layout rule**

Append this block within `### 4.1 Web 列表页`:

```markdown
#### 4.1.1 复杂台账列个性化的端侧边界

- 列宽、列显隐和列顺序仅适用于 PC / Web 表格。
- H5（≤767px）按本规范转换为单列卡片，不显示列设置入口，也不提供表头拖拽。
- H5 忽略但不得删除同一用户已经保存的 PC 列配置。
- 用户扩大业务列后，只允许表格自身滚动容器横向滚动；页面壳层不得产生横向滚动。
- 完整交互和保存规则见 [03-components §3.1.1](./03-components.md#311-复杂台账列个性化pc--web-强制)。
```

- [ ] **Step 3: Verify the layout chapter contains the boundary and link**

Run:

```bash
rg -n "4\\.1\\.1 复杂台账列个性化的端侧边界|H5 忽略但不得删除|03-components §3\\.1\\.1" \
  src/resources/design-system/chapters/02-layout.md
```

Expected: three matches in the new subsection.

### Task 3: Add keyboard and screen-reader equivalence

**Files:**
- Modify: `src/resources/design-system/chapters/06-accessibility.md`, under `## 2. 焦点与键盘（Web）`

- [ ] **Step 1: Capture the current accessibility gap**

Run:

```bash
rg -n "Shift.*24px|Home.*默认宽度|上移/下移|aria-live.*列" \
  src/resources/design-system/chapters/06-accessibility.md
```

Expected: no matches; the current chapter only states the general requirement that drag sorting needs an alternative.

- [ ] **Step 2: Add the complex-ledger accessibility rules**

Append these bullets under `## 2. 焦点与键盘（Web）`:

```markdown

### 2.1 复杂台账列控制

- “列设置”按钮必须提供 `aria-label`、`aria-expanded` 和弹层关联；打开后焦点进入弹层，关闭后回到触发按钮，`Esc` 可关闭。
- 列宽调节把手必须可聚焦：方向键每次调整 `8px`，`Shift + 方向键` 每次调整 `24px`，`Home` 恢复当前列默认宽度。
- 读屏必须播报当前列名和调整后的像素宽度。
- 列排序除拖拽外必须提供“上移/下移”按钮；达到边界或属于固定列时禁用并说明原因。
- 显隐复选框必须与列名关联；固定列控件禁用并以文字说明“固定列不可隐藏”。
- 调宽、排序、恢复默认、保存成功和保存失败使用 `aria-live="polite"` 播报，不能只依赖颜色。
- 视觉分隔线可以为 `2–3px`，但鼠标命中区保持约 `12px`；所有可聚焦控件使用主题 Focus Token。
```

- [ ] **Step 3: Verify all keyboard operations and announcements are present**

Run:

```bash
rg -n "aria-expanded|方向键每次调整 `8px`|Shift \\+ 方向键|Home.*默认宽度|上移/下移|aria-live=\"polite\"" \
  src/resources/design-system/chapters/06-accessibility.md
```

Expected: all six patterns match inside `2.1 复杂台账列控制`.

### Task 4: Add the mandatory overview summary

**Files:**
- Modify: `src/resources/design-system/DESIGN.md`, under `## 1. 设计原则`
- Modify: `src/resources/design-system/DESIGN.md`, frontmatter version and document-version row

- [ ] **Step 1: Verify the overview principle is absent**

Run:

```bash
rg -n "复杂台账列个性化|列宽、列显隐、列顺序" src/resources/design-system/DESIGN.md
```

Expected: no matches.

- [ ] **Step 2: Add the seventh design principle**

Append this item after the current sixth principle:

```markdown
7. **复杂台账列个性化（PC / Web 强制）**：字段较多的复杂台账必须支持列宽调整、可选业务列显隐、可选业务列顺序调整及恢复默认；配置按“用户 + 台账页面”保存。首个核心识别列与末尾操作列遵守固定列限制，H5 卡片列表不提供列操作。完整规则见 [03-components §3.1.1](./chapters/03-components.md#311-复杂台账列个性化pc--web-强制)、[02-layout §4.1.1](./chapters/02-layout.md#411-复杂台账列个性化的端侧边界) 与 [06-accessibility §2.1](./chapters/06-accessibility.md#21-复杂台账列控制)。
```

- [ ] **Step 3: Update both version declarations**

Replace the frontmatter version and version-row content with:

```markdown
version: "2.6"
| 文档版本 | **v2.6 复杂台账列个性化规范**（2026-07-26） |
```

- [ ] **Step 4: Verify the overview stays concise and links all rule owners**

Run:

```bash
rg -n '^version: "2\\.6"|v2\\.6 复杂台账列个性化规范|03-components §3\\.1\\.1|02-layout §4\\.1\\.1|06-accessibility §2\\.1' \
  src/resources/design-system/DESIGN.md
```

Expected: both version declarations match and the seventh principle links all three chapters.

### Task 5: Cross-document verification

**Files:**
- Verify: `src/resources/design-system/DESIGN.md`
- Verify: `src/resources/design-system/chapters/02-layout.md`
- Verify: `src/resources/design-system/chapters/03-components.md`
- Verify: `src/resources/design-system/chapters/06-accessibility.md`

- [ ] **Step 1: Check the confirmed requirements are represented**

Run:

```bash
rg -n \
  "列宽|列显隐|列顺序|恢复默认|用户 \\+ 台账页面|固定列|H5|方向键|上移/下移|保存失败" \
  src/resources/design-system/DESIGN.md \
  src/resources/design-system/chapters/02-layout.md \
  src/resources/design-system/chapters/03-components.md \
  src/resources/design-system/chapters/06-accessibility.md
```

Expected: every requirement category appears in its designated owner document, with the complete behavior in `03-components.md`.

- [ ] **Step 2: Check for unfinished or ambiguous markers**

Run:

```bash
rg -n "TB""D|TO""DO|待""定|待""确认|FIX""ME|酌情|视情况" \
  src/resources/design-system/DESIGN.md \
  src/resources/design-system/chapters/02-layout.md \
  src/resources/design-system/chapters/03-components.md \
  src/resources/design-system/chapters/06-accessibility.md
```

Expected: no new matches in the edited sections.

- [ ] **Step 3: Confirm the standard example still resolves**

Run:

```bash
test -f src/prototypes/vehicle-management/components/ListView.tsx
rg -n "DEFAULT_COLUMN_WIDTHS|列表设置（自定义显隐与列顺序）|va-th-resizer" \
  src/prototypes/vehicle-management/components/ListView.tsx
```

Expected: the file exists and all three reference patterns match.

- [ ] **Step 4: Review the final diff manually**

Because this workspace has no Git metadata, run:

```bash
sed -n '1,220p' src/resources/design-system/chapters/03-components.md
sed -n '55,125p' src/resources/design-system/chapters/02-layout.md
sed -n '15,75p' src/resources/design-system/chapters/06-accessibility.md
sed -n '1,55p' src/resources/design-system/DESIGN.md
```

Expected: headings are correctly nested, cross-links use existing relative paths, detailed rules are not duplicated in the overview, and no unrelated content changed.