Files
crawler-plugin/admin-frontend-vue/src/layout/operation-guides.ts
T
huangzd1997 16583f578d feat(公司tab): 批次 2/3/4 再接 8 页,注册表收到 16 页——用户页回流 company_id 按新边界改写反向钉
「切 tab 数据还一样」的根因一直是分母小于现实:批次 1 只登记 8 页,本轮按控制方
三次点名扩到 16 页(company-scope.ts 是唯一清单,routes.ts 的 companyScoped 逐页对平)。

批次 2(五页 ASIN 中心):去重总数据 / 不符合ASIN / 查询ASIN / 最低价ASIN / 商品类目。
批次 3(两页店铺中心):撞款监控、店铺数据记录。这两页没有归属列可筛,归属口径是
「本公司账号名下的店铺」——后端由 DataReadScope 推公司 → 成员账号 → biz_shop_manage.
created_by_id,前端只把 activeId 当 company_id 送下去。空成员集必须交空集合,绝不能
退化成 null(null 在这里=全量,那样第二家会看到全部数据)。
批次 4(用户管理):后端早就认 company_id(只对站点超管生效,公司超管恒锁本公司),
断的是前端——UserListQuery 里连这个字段都没有,三家 tab 看的是同一份全量列表。

三处口径改动,逐条说明:
1)company-user-list.test.ts 的反向钉被改写。2026-10-04 定案把公司维度从用户页整体摘掉,
   那条钉的原文是「列表查询/筛选/行渲染不允许出现公司维度」。控制方 2026-10-05 明确要
   用户管理区分公司 tab,所以钉的边界收窄成两半:渲染层(行级公司列、「所属公司」标签、
   筛选状态、顶栏公司名)仍不得回流;请求层的 company_id 是这次加回来的,尺子换成
   「取值口唯一」——页面每处 companyId 都必须等于 companyTab.requestCompanyId,且
   normalizeUserPageParams/toUserListQuery 两只白名单构造器体内不许出现公司值。
   新增一支行为钉:往归一化里传 companyId 必须被丢掉,这是 users.ts 读原始入参的全部理由
   (写成 normalized.companyId 时 TS 照样绿、运行时恒 undefined)。
2)align-dup-console 那条 watch 看守的 token 扩到含 reload。变异自证里「删掉 void
   loadConsole()」当场全绿:体里的清筛选项守住了,重新取数那半没人守。批次 3/4 三对
   token 一起写到 reload 为止(批次 1/2 的老条目不动)。
3)公司管理页补正/反向两把尺子:company-config-entry-super-only 新增「吃公司 tab 的页面
   集合恰好等于 COMPANY_SCOPED_PAGES 的 pageFiles」——按代码真值比,不按清单比,所以
   清单不改一字而往 CompaniesPage.vue 里塞 store 也会红。谓词带括号,否则 import 行也算消费者。

菜单权限(admin_columns)本轮不动:MenusPage 只消费 /api/admin/permission-menus 这一份全局
菜单字典,切 tab 一样是数据本身全局,不是筛选坏了。真问题在写侧——PermissionMenuService
create/update/delete 只有 ensureAdminOperatorIfPresent(isAdmin 即放行),公司管理员改的是
全平台的菜单行。收窄为仅站点超管 vs 给 permission_menu 加归属列,两种改法代价差一个量级,
留给控制方定档。

护栏:G1 发送口 22 个 / 页面分组 17、watch 体看守 10 对、operation-guide 的 tab 文案 15 页
(撞款监控是显式豁免,另有一条自检盯「豁免落空」)。
变异自证 12/12 全杀(前端 10 + 公司管理反向钉 2),分母钉死在 27 例。
门禁:后端全量 3823 例 / 0 失败 / 0 错误 / 7 skipped,BUILD SUCCESS;admin-frontend-vue
1741 例 / 0 红;vue-tsc rc=0。首轮后端 4 红是另一路 task_partial 改动与本轮编译抢跑,
单跑 13 例已绿,本笔不含他们的任何文件。

未上线:jar 与 admin-vue 都没出包,V147 未在生产执行。
2026-10-06 02:32:59 +08:00

156 lines
9.9 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/**
* 每菜单页的操作提示(guides)文案,对齐旧版 backend/static/admin-interactions.js 的 guides 表原文
* (duplicate-check 为例外页不展示)。key = 路由 meta.menuKey。
* 2026-10-05 公司 tab 起有**两处故意偏离**「原文」:group-manage 由通用 fallback 改为自带文案,
* 参与 tab 的 8 页与不参与 tab 的 C 类 2 页在原文之后各追加一句——见下方三个 *_NOTE 常量。
*/
export interface OperationGuideData {
text: string
steps: string[]
}
export const OPERATION_GUIDE_FALLBACK: OperationGuideData = {
text: '先使用筛选定位记录,再进行新增、编辑、导出等操作。涉及删除的数据会要求二次确认。',
steps: ['选择筛选条件', '处理记录', '核对反馈'],
}
/** 折叠状态 localStorage key(沿用旧版 shufuAdminGuideCollapsed 语义)。 */
export const OPERATION_GUIDE_STORAGE_KEY = 'shufuAdminGuideCollapsed'
/** §9.3 的承载:公司 tab 改的是「行数观感」,只写进既有引导文案,不做页头控件/提示条
* (§12 第 5 条把那种提示条算未批的界面暴露;当前哪一家由 is-active 的 tab 表达,一处事实不留两处)。
* 这句必须以「超级管理员」开头、不能写成祈使式的「由上方 tab 决定」:引导文案按 menuKey 取、
* 不分支角色,而非超管根本看不到 tab 条(company-tab store 的 visibleForOperator 里有 isSuperAdmin)。
* 这一句由参与 tab 的 13 页共用、不各抄一遍——文案差一个字,护栏就只盯得住其中一页。
* 由 tests/align-operation-guide.test.ts 的 guide_copy_carries_company_tab_note_for_every_scoped_page
* 按 COMPANY_SCOPED_PAGES 逐页盯着(分母取注册表,加一页忘了补文案会当场红)。 */
const COMPANY_TAB_GUIDE_NOTE = ' 超级管理员可用页面上方的公司 tab 切换公司,切换后行数会变化——行数变少不是数据丢了。'
/** §5 的承载:注册表里显式 companyScoped:false 的 C 类页要的是**另一句**——"这页不参与",
* 不是"会随 tab 变"。同一支护栏反向钉它(不得带 COMPANY_TAB_GUIDE_NOTE)。 */
const COMPANY_SCOPE_NOT_APPLIED_NOTE = ' 本页全平台共享,不按公司区分:超级管理员切换上方公司 tab 时它不会变,这不是筛选坏了。'
/** §6.3 归属口径:店铺落哪家由「负责人」决定,与 tab 无关——这条与直觉相反,不写在界面上就会被报成 bug。 */
const SHOP_OWNER_COMPANY_NOTE = ' 店铺归哪家公司由「负责人」决定,不由公司 tab 决定:负责人选自己,店铺就落在你自己那家。'
export const OPERATION_GUIDES: Record<string, OperationGuideData> = {
admin_users: {
// 2026-10-05 批次 4:与 group-manage 同型偏离——参与公司 tab 的页必须在原文之后带上那句 §9.3,
// 所以这一条不再与旧版 guides 逐字相等(护栏改为 match 原句子串,见 align_guide_users_matches_reference_text)。
text: '先用筛选定位账号,再编辑角色和菜单权限;删除账号会要求二次确认。'
+ COMPANY_TAB_GUIDE_NOTE,
steps: ['筛选账号', '编辑权限', '确认保存'],
},
admin_columns: {
text: '菜单会影响后台和软件端的可见范围。先填写名称并选择对应页面,再设置上级菜单;顺序直接拖动列表左侧手柄调整。',
steps: ['新增或调整菜单', '设置层级', '拖动排序'],
},
admin_group_manage: {
// 2026-10-05 公司 tab(spec §9.3):这页改为**自带文案**,故意偏离文件头「沿用旧版原文」的约定——
// tab 那句不能塞进 OPERATION_GUIDE_FALLBACK(fallback 会被没进 tab 的页共用,等于把 tab 端给它们)。
// 也不写「跨公司的分组彼此看不见」:那是 Task 11 Step 3 明确没做的半边(附B 记了这条部分强度)。
text: '数据权限分组决定"哪些账号能看到哪些店铺",分组按负责人和归属账号聚拢。超级管理员切换上方公司 tab 后,列表只保留当前公司账号相关的分组。'
+ COMPANY_TAB_GUIDE_NOTE,
steps: ['选择分组', '维护负责人与归属账号', '核对店铺可见范围'],
},
admin_user_secrets: {
text: '用户密钥按账号绑定,列表只展示脱敏值。可对单条立即检测连通性;清空后该用户需要重新配置密钥。'
+ COMPANY_TAB_GUIDE_NOTE,
steps: ['筛选用户或状态', '立即检测连通性', '必要时清空'],
},
admin_companies: {
text: '公司决定账号归属:新建普通账号/管理员自动落在操作者自己所在的公司,页面上不出现公司选项——要给别的公司建号,请用那个公司自己的管理员登录。唯一例外是「公司超级管理员」:由站点超管开设、需在建号弹窗中显式选择所属公司。公司只做启用/停用,不提供删除。',
steps: ['查看公司列表', '新建公司', '改名或启停'],
},
admin_dedupe_total_data: {
text: '支持按关键词、用户、分组和国家筛选;导入前先确认所选分组,导出会按日期范围生成文件。'
+ COMPANY_TAB_GUIDE_NOTE,
steps: ['选择分组', '筛选或导入', '核对并导出'],
},
admin_invalid_asin_data: {
text: '维护不符合规则的 ASIN 或品牌。添加后可使用上方筛选快速回查。'
+ COMPANY_TAB_GUIDE_NOTE,
steps: ['填写 ASIN/品牌', '选择分组', '保存并回查'],
},
admin_query_asin: {
text: '查询 ASIN 以店铺为单位维护。列表里点击 ASIN 即可复制,点右侧「配置」可一次维护该店铺所有站点的 ASIN。'
+ COMPANY_TAB_GUIDE_NOTE,
steps: ['筛选店铺', '打开配置抽屉', '保存或导出'],
},
admin_product_categories: {
text: '类目树支持展开查看层级。搜索、编辑和删除都在同一列表中完成。'
+ COMPANY_TAB_GUIDE_NOTE,
steps: ['搜索类目', '展开层级', '新增或编辑'],
},
admin_skip_price_asin: {
text: '最低价 ASIN 以店铺为单位维护。列表里点击 ASIN 即可复制,点右侧「配置」可一次维护该店铺所有站点的 ASIN 与最低价。'
+ COMPANY_TAB_GUIDE_NOTE,
steps: ['筛选店铺', '打开配置抽屉', '保存或批量导入'],
},
admin_shop_keys: {
text: '紫鸟令牌属于敏感配置。白名单状态可悬停查看检测详情,编辑前请先核对账号名称。'
+ COMPANY_SCOPE_NOT_APPLIED_NOTE,
steps: ['新增或筛选密钥', '查看白名单状态', '编辑或删除'],
},
admin_shop_manage: {
text: '店铺信息按分组管理。长商城名会自动缩略,悬停即可查看完整内容。'
+ COMPANY_TAB_GUIDE_NOTE
+ SHOP_OWNER_COMPANY_NOTE,
steps: ['选择分组', '维护店铺信息', '筛选核对结果'],
},
admin_shop_data_crawl_tasks: {
text: '店铺数据任务按状态和时间筛选。批量操作前请核对已选任务。'
+ COMPANY_TAB_GUIDE_NOTE,
steps: ['筛选任务', '检查状态', '执行批量操作'],
},
// admin_shop_data_duplicate_check(店铺撞款监控)为例外页:不展示全局提示条,不参与对齐。
// 它进了公司 tab 范围(COMPANY_SCOPED_PAGES)却没有文案可挂,所以那句 §9.3 的看守在这一页由
// tests/align-operation-guide.test.ts 显式豁免;这一页的「切 tab 行数会变」写在页面自身的说明里。
admin_image_video_tasks: {
text: '可先使用筛选缩小任务范围,再查看任务状态、结果和权限范围。'
+ COMPANY_TAB_GUIDE_NOTE,
steps: ['设置筛选', '查看任务结果', '按需处理任务'],
},
admin_history: {
text: '生成记录可按用户和时间范围回溯,用于核对结果文件和执行时间。'
+ COMPANY_TAB_GUIDE_NOTE,
steps: ['设置时间范围', '筛选记录', '查看结果预览'],
},
admin_version: {
text: '上传版本后请核对版本号和下载链接,再通知用户更新。',
steps: ['上传压缩包', '检查版本记录', '维护历史版本'],
},
admin_tutorial: {
text: '上传新的教程压缩包后即刻生效:工具台首页「立即下载教程」以下载最新上传的包为准。确认旧包不再需要后再删除。',
steps: ['上传教程压缩包', '到工具台核对下载', '清理历史包'],
},
digital_human_version: {
text: '数字人版本需先上传草稿,再发布并标记最新版本。',
steps: ['上传草稿', '确认更新日志', '发布或设为最新'],
},
admin_device_logs: {
text: '桌面客户端与麦象采集机上报的日志按来源、日期和关键字筛选;可查看日志尾部、下载完整文件或删除云端记录,云端日志按保留期自动清理。'
+ COMPANY_TAB_GUIDE_NOTE,
steps: ['选择来源与日期', '查看或下载日志', '必要时删除'],
},
admin_user_secret_usage: {
text: '按日期范围统计各用户的密钥调用次数(货源查询与外观专利按 LLM 请求次数、代理按提取次数),用于评估用户资源损耗。'
+ COMPANY_TAB_GUIDE_NOTE,
steps: ['选择日期范围', '筛选用户或分组', '核对各模块次数'],
},
admin_task_center: {
text: '按账号、业务、状态、店铺和创建时间筛出客户端任务,点任务查看明细与分组结果;顶部汇总卡给当前在跑与疑似卡住的总量。'
+ COMPANY_TAB_GUIDE_NOTE,
steps: ['按条件筛任务', '查看任务明细', '核对汇总卡'],
},
}
/** 全部有独立/兜底提示的后台业务菜单 key。 */
export const OPERATION_GUIDE_MENU_KEYS = Object.keys(OPERATION_GUIDES)
/** 返回指定菜单 key 的提示数据;menuKey 不在已知集合时返回 null(登录/404 等页面不展示)。 */
export function operationGuideFor(menuKey: unknown): OperationGuideData | null {
if (typeof menuKey !== 'string' || !menuKey) return null
return OPERATION_GUIDES[menuKey] ?? null
}