docs: 补充规格文档（specs 01-15）

2026-09-08 13:39:10 +08:00
parent 4ac8f8b472
commit b12acf7793
16 changed files with 1462 additions and 0 deletions
@@ -0,0 +1,90 @@
+# 13 AdminHtml 观感与交互对齐（蓝白浅色）Spec
+
+> **状态（task-283）**：对齐工作已全部完成，本 spec 所引用的基线文件（`backend/web_source/admin.html`、`backend/static/admin.js`、`admin-interactions.js` 及 Java 侧 static 副本）已按 spec 11 阶段 5 删除；历史内容保留于 git 中（`git log -- backend/web_source/admin.html` 可查），本 spec 作为过程记录不再可逐行对照。
+
+## 模块职责
+
+让 `admin-frontend-vue`（Vue3 + Element Plus 后台 SPA）的**壳层与 15 个业务页面**在观感与交互上对齐旧 Flask 后台 `backend/web_source/admin.html` 的**现行「蓝白浅色」皮肤**与 `backend/static/admin.js` / `admin-interactions.js` 的交互文案，实现从旧后台切换到新后台时用户无感。**DuplicateCheckPage（店铺撞款监控，menuKey `admin_shop_data_duplicate_check`）为例外页：保留其自身设计，本次不比对、不修改。**
+
+## 依赖关系
+
+- **上游（冻结参照，禁止改动）**：
+  - `backend/web_source/admin.html` —— 面板 markup + CSS（4 代主题纵向堆叠，**最终生效 = 末层 L4477-4830「蓝白色调」亮色皮肤**）
+  - `backend/static/admin.js`（7206 行）—— 各面板交互与用户可见文案
+  - `backend/static/admin-interactions.js`（333 行）—— 全局确认框/Toast/按钮 title 语义
+  - Java 侧镜像副本 `backend-java/src/main/resources/static/admin.html` + `static/static/admin.*`
+- **下游**：`admin-frontend-vue`（src/layout、src/styles、src/pages/*、src/components/*、src/api 适配、tests/task-NNN.test.ts、e2e/）。
+- **例外页**：`src/pages/tasks/DuplicateCheckPage.vue` 不改。
+
+## 基线：admin.html 蓝白浅色皮肤（对齐目标值）
+
+最终生效 token（admin.html L4478 :root）：
+- 主色 `#4f78a5`，主色强 `#2f5d8b`，主色浅 `#e7f0f8`，按钮渐变 `#5f85ad→#4f78a5`
+- 内容底 `#f4f7fb`（body 叠加两团淡蓝 radial 晕染），卡片白、卡片抬升 `#f9fbfd`
+- **浅色侧栏** `#f8fbfe→#edf3f9`（渐变），侧栏文字 `#536a81`
+- 边框 `#d8e3ee`（强 `#b7c9db`）、文字 `#24384d` / 次 `#5b6f83` / 弱 `#8293a5`
+- danger `#b35f6a`（渐变 `#c06d77→#b35f6a`）、success `#4e806d`、warning `#a8793e`
+- radius 14px（卡片/按钮），9px（控件）；卡片阴影 `0 1px 2px rgba(39,67,94,.04),0 14px 30px -24px rgba(39,67,94,.28)`
+
+壳层密度：侧栏 252px（折叠 64px）、顶栏 76px（sticky 半透明白 blur8）、菜单项 min-height 42px、品牌 mark 36px、内容 padding `30px 32px 56px`、kicker 10px/700 + 面包屑 + 页题 18px/650、角色胶囊（#2f5d8b/#e6f0f8/#bfd1e2）。
+
+组件观感基线（详见 plan/任务 241-248 展开）：
+- 按钮 `.btn`（渐变蓝、min-height42、shadow）、`.btn-secondary`、`.btn-danger`、`.btn-sm`（行内 36px）
+- 表单 `.form-group label` 上置、控件 min-height42、focus 蓝 ring `0 0 0 3px rgba(95,133,173,.16)`
+- 表格 `.table-scroll`：外框 1px `#dbe5ee` radius10、th `#edf4fa` 12.5px/600、td 13.5px、hover `#f1f7fb`、无斑马
+- 分页：非数字页码「共 N 条 · 上一页 · 第 x / y 页 · 下一页 · 跳至[ ] 跳转」
+- 弹窗 `.modal`（radius14、width min(920px,…)）、右侧 `.drawer`（min(460px,…)）三段式；撞款锚点抽屉除外
+- Toast 右上角（成功绿/错误红/信息蓝前徽）；二次确认（遮罩 blur + 橙底感叹图标 + [取消][确认删除]）；顶部 3px 进度条 + 右上「请求处理中...」
+- 空态 `.empty-tip`、行内 `暂无 X`；面板头统一「h3 与操作按钮同行」
+
+## 面板 ↔ Vue 页面映射（权威，以 Vue menuKey 为准）
+
+| admin.html panel | admin 菜单名 | Vue menuKey | Vue 页面文件 | 业务命名差异/备注 |
+|---|---|---|---|---|
+| panel-users | 用户管理 | admin_users | account/UsersPage.vue | — |
+| panel-columns | 菜单权限配置 | admin_columns | account/MenusPage.vue | 列/交互以 admin 为准 |
+| panel-group-manage | 分组管理 | admin_group_manage | account/GroupsPage.vue | 需补编辑器+选人 |
+| panel-dedupe-total-data | 去重数据汇总 | admin_dedupe_total_data | asin/DedupeRegistryPage.vue | 需补导入/导出/筛选 |
+| panel-invalid-asin-data | 品牌数据库 | admin_invalid_asin_data | asin/AsinInvalidPage.vue | 同一 API /invalid-asin-data；Vue 用业务名「不符合ASIN数据」，保留 |
+| panel-query-asin | 查询ASIN | admin_query_asin | asin/QueryAsinPage.vue | 需补配置抽屉/导入 |
+| panel-product-categories | 商品类目 | admin_product_categories | asin/ProductCategoryPage.vue | 需补懒加载/导出/删除 |
+| panel-skip-price-asin | 最低价ASIN设置 | admin_skip_price_asin | asin/SkipPricePage.vue | 需补配置抽屉/导入 |
+| panel-shop-keys | 店铺密钥管理 | admin_shop_keys | shop/ShopKeysPage.vue | 白名单药丸/令牌语义 |
+| panel-shop-manage | 店铺管理 | admin_shop_manage | shop/ShopManagePage.vue | 凭证明文/眼睛实时读 |
+| panel-image-video-tasks | 视频任务记录 | admin_image_video_tasks | tasks/ImageVideoTasksPage.vue | 需改卡片网格+播放 |
+| panel-shop-data-crawl-tasks | 店铺数据记录 | admin_shop_data_crawl_tasks | tasks/ShopDataTasksPage.vue | 需改每店卡片网格 |
+| panel-shop-data-duplicate-check | 店铺数据重复检查 | admin_shop_data_duplicate_check | tasks/DuplicateCheckPage.vue | **例外页，不动** |
+| panel-history | 生成记录 | admin_history | records/RecordsHistoryPage.vue | 缩略图预览布局 |
+| panel-version | 软件版本管理 | admin_version | records/RecordsSoftwareVersionPage.vue | — |
+| panel-digital-human-version | 数字人版本管理 | digital_human_version | records/RecordsDigitalHumanVersionPage.vue | 状态色/操作矩阵 |
+
+## 对齐契约类别（每个任务按此过一遍）
+
+1. **观感**：色板/尺寸/圆角/阴影 = 上节基线；页面结构 = 「面板头(h3+按钮同行) + 筛选条 + 表格/卡片 + 分页脚」。
+2. **交互逻辑**：筛选字段与提交方式、行内操作按钮集、弹窗/抽屉表单字段与校验、导入/导出/轮询/等待态、空/错/loading 态 —— 与 admin.js 对应段一致。
+3. **用户可见文案**：页头描述、按钮名、确认框文案（删除“X”…）、成功/错误提示 —— 对齐 admin。
+4. **复用优先**：优先接线已存在但未进 UI 的孤儿 TS 模块（如 user-create/user-edit/user-menu-auth、dedupe-total-export/import、query-asin-*/skip-price-*、product-category-export、history-*/version-*/digitalhuman-*、shop-*、image-video-*/shop-data-*），再补缺口，避免重复造。
+5. **已知容忍项**：业务命名差异（品牌数据库→不符合ASIN数据）、admin 分页无页码为历史不一致（Vue 保留跳页但观感统一）、登录页独立设计不纳入。
+
+## 实现顺序
+
+1. A 换皮与共享基线（241-249）——先做，供后续页面直接受益。
+2. B account（250-253）→ C asin（254-258）→ D records（259-261）→ E shop（262-263）→ F tasks（264-267）。
+3. G 收尾（268-272）。
+
+## 迁移边界
+
+- **改**：admin-frontend-vue 内样式/布局/页面/共享组件/测试/e2e；主题单测随 token 翻转更新。
+- **不改**：`backend/web_source/admin.html`、`backend/static/admin.js`、`admin-interactions.js`、Java 侧 static 副本；DuplicateCheckPage；Java 后端 API 契约（如遇后端缺口另开 Java 任务，不夹带）。
+- 每任务仅 stage 本任务改动文件；不覆盖工作树他人未提交改动。
+
+## 风险与验收标准
+
+| 级别 | 验收点 | 证据 |
+|---|---|---|
+| P0 | 壳层与 15 页为蓝白浅色；颜色/尺寸对齐基线 | 截图对照 admin.html；tests 断言 token 与 CSS 变量 |
+| P0 | 页面交互与文案对齐（含补齐缺失交互）；无误导/死按钮 | 每页测试 + 真实交互 |
+| P1 | 换皮不引入对比度/无障碍回归（WCAG AA） | theme 不变量测试 |
+| P1 | 响应式/折叠/空错态/loading 语义一致 | e2e + 清单 |
+| P2 | DuplicateCheckPage 与其余回归不受影响；全部旧提交不破坏 | git diff 校验例外页不变；全量 test+build |
+| P2 | check_progress 闭合、总任务数 272 | check_progress.py 退出 0 |