docs: add OA app icon pastel + Element Plus design and demo.

Capture the approved encoding (ep:Icon|#bg), 8-color palette, picker UX, and interactive HTML demo for implementation planning. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-06 12:54:27 +08:00
1 parent 01d4fcf12f
commit 0853777fdf
@@ -0,0 +1,125 @@
+# OA 审批应用图标：淡色底 + Element Plus 图标
+
+**日期：** 2026-08-06  
+**范围：** `web-admin` 审批管理 / 发起审批 / 设计器基础设置中的应用图标  
+**Demo：** `docs/demos/oa-app-icon-picker-demo.html`  
+**关联：** 取代 `2026-07-14-oa-apps-card-layout-design.md` 中「固定三条杠 SVG + 随机饱和底色」的默认图标策略；后端 `icon_url` / API `iconUrl` 字段不变。
+
+## 目标
+
+1. 新增审批应用时：从固定色盘**随机淡色底**，并从精选 Element Plus 图标中**随机图标**。
+2. 图标描边色 = 该底色的**同色系深色**（禁止白图标、禁止灰色底）。
+3. 用户可从图标库点选、换底色；也可上传自定义图片。
+4. 编辑时仍可修改图标（组合图标或上传图）。
+5. 卡片展示图标尺寸小于现状：列表 **32×32**，弹窗预览 **56×56**。
+
+## 编码（仅用现有 `iconUrl`）
+
+不新增数据库字段。`iconUrl` 支持三种形态：
+
+| 形态 | 示例 | 展示 |
+|------|------|------|
+| 组合约定串 | `ep:Document|#d1fae5`（图标名与底色之间为竖线 `\|`） | 淡色底 + EP 图标（同色系深色描边） |
+| 图片 URL | `/oa-app-icons/doc-orange.svg`、MinIO 相对路径、`http(s)://…` | `<img>`（兼容旧数据与上传） |
+| 空 | `""` / null | 兜底为合法 `ep:…` 组合 |
+
+约定串格式（SHALL）：
+
+- 前缀 `ep:`
+- 图标名：Element Plus Icons Vue 的导出组件名（PascalCase），如 `Document`、`Calendar`
+- 分隔符：单个 `|`
+- 底色：`#` + 6 位小写十六进制，且必须属于下方色盘 `bg` 集合
+
+解析失败（未知图标名、非法底色、残缺串）时：图标回退 `Document`，底色回退 mint（`#d1fae5` / `#059669`）。
+
+上传成功后 `iconUrl` 存 MinIO（或接口返回的）路径；之后若用户再选 EP 图标或换底色，则**覆盖**为新的 `ep:` 串。
+
+## 色盘（仅 8 组，禁止灰）
+
+随机、换底色、色盘点选均只能使用下列配对。SHALL NOT 使用 slate/灰等中性底色。
+
+| bg（底） | fg（图标描边） |
+|----------|----------------|
+| `#d1fae5` | `#059669` |
+| `#cffafe` | `#0891b2` |
+| `#dbeafe` | `#2563eb` |
+| `#e0e7ff` | `#4f46e5` |
+| `#ede9fe` | `#7c3aed` |
+| `#fce7f3` | `#db2777` |
+| `#ffedd5` | `#ea580c` |
+| `#fef3c7` | `#d97706` |
+
+## 尺寸
+
+| 场景 | 容器 | 圆角 |
+|------|------|------|
+| 审批管理卡片、发起审批卡片 | 32×32 | 8px |
+| 新增/编辑弹窗、设计器预览 | 56×56 | 12px |
+
+## 交互
+
+### 审批管理 · 新增 / 编辑基础
+
+1. 打开**新增**：`pickRandomOaAppIconSpec()` 生成 `ep:{Icon}|{bg}` 预填。
+2. 预览区展示组合图标或上传图。
+3. 操作按钮：
+   - **从图标库选择**：主弹窗内**展开面板**（非二级弹窗），展示精选 EP 图标网格 + 8 色色盘。
+   - **换底色**：在 8 色中换一色（保留当前图标名；若当前为上传图则先切回组合模式并随机/保留上次图标名）。
+   - **随机图标+底色**：同时随机。
+   - **上传图片**：走现有附件上传；成功后预览切 `<img>`。
+4. 确定：把当前 `iconUrl`（`ep:` 串或图片路径）提交后端，行为与现网一致。
+5. **编辑**：回显；可改图标/底色/重新上传。
+
+### 展示落点
+
+以下页面用同一展示组件，按 `iconUrl` 形态渲染：
+
+- `views/oa-approval/apps/index.vue`（卡片）
+- `views/oa-approval/start/index.vue`（卡片）
+- `views/oa-approval/designer/index.vue`（基础设置）
+
+### 旧数据
+
+已有 `/oa-app-icons/*.svg` 等图片 URL **继续按图片显示**；不做批量迁移。用户编辑并保存为 `ep:` 或新上传后自然替换。
+
+## 前端模块
+
+| 模块 | 职责 |
+|------|------|
+| `web-admin/src/utils/oa-app-icons.ts` | 色盘、fg 映射、精选图标名列表、随机、`buildEpIconUrl` / `parseEpIconUrl` / `resolveOaAppIcon`（兼容旧 `resolveOaAppIconUrl` 图片路径） |
+| `web-admin/src/components/oa-approval/OaAppIcon.vue` | 展示：`ep:` → 底色块 + `<el-icon>`；否则 → `<img>` |
+| `web-admin/src/components/oa-approval/OaAppIconPicker.vue` | 预览 + 展开面板 + 换色/随机/上传；`v-model` 绑定 `iconUrl` 字符串 |
+
+精选图标列表：从 `@element-plus/icons-vue` 选取业务常用子集（约 16～24 个，含 Document、Calendar、Clock、Wallet、User、Tickets、Briefcase、Money、Van、OfficeBuilding、Message、Setting、CollectionTag、Checked、Present 等），实现时以代码常量为准；不要求全量 EP 图标搜索（范围外，后续可加）。
+
+## 异常与边界
+
+- 未知 icon 名 → `Document`
+- 非法 bg → mint 对
+- 残缺 `ep:` 串 → 兜底组合
+- 上传失败 → ElMessage 提示，不修改当前 `iconUrl`
+- 换底色时若当前为图片 URL：切回组合模式（图标名用上次 ep 或 `Document`）再换色
+
+## 后端
+
+无 API / 表结构变更。`icon_url` 仍为 `VARCHAR(512)`；约定串长度远小于限制。
+
+## 测试
+
+1. **纯函数校验**：对 `parseEpIconUrl` / `buildEpIconUrl` / 色盘常量做最小自动化测试（可放 `web-admin` 侧若已有测框架；否则在实现计划中用可执行断言脚本或后端无关的轻量测）。覆盖：往返、色盘不含灰、随机合法、非法串兜底。
+2. **手工**：新增随机 → 选图标 → 换底色 → 上传 → 再选 ep；编辑旧 SVG 应用；发起页与设计器同步显示。
+
+## 范围外
+
+- 不改后端接口与库表
+- 不做旧 `/oa-app-icons/*` 批量迁移
+- 不做全量 Element Plus 图标搜索
+- 不改小程序端（若暂无对应展示）
+
+## 验收标准
+
+1. 新增打开时预填为 `ep:` 串，底色仅属 8 色盘，图标为精选 EP 之一，描边为对应 fg。
+2. 卡片图标视觉尺寸为 32×32；弹窗预览 56×56。
+3. 展开面板可选图标与底色；上传与 ep 模式可互相覆盖。
+4. 旧图片 `iconUrl` 仍能显示；发起页、设计器与审批管理一致。
+5. Demo `docs/demos/oa-app-icon-picker-demo.html` 与实现视觉策略一致（色盘、同色系深色、尺寸）。