Files
youlai-app/docs/naming-audit-2026-10-16.md
T

106 lines
8.1 KiB
Markdown
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.
# 命名与注释审计(2026-10-16)
对未提交改动文件的命名、类型与注释核查,标准依据 `mobile-ui-code-review-2026-10-04.md` 与 Vue 官方风格指南。
全部修复后 `pnpm check`(type-check / templates / eslint+prettier / stylelint)通过,旧名残留扫描为 0。
## 1. 方法命名(已修复)
| 文件 | 原名 | 现名 | 依据 |
| --- | --- | --- | --- |
| work/config/index.vue | `showConfigActions` | `openConfigActions` | 打开弹窗用 open |
| work/dict/index.vue | `showDictActions` | `openDictActions` | 同上 |
| work/dict/item/index.vue | `showItemActions` | `openItemActions` | 同上 |
| work/notice/index.vue | `showNoticeActions` | `openNoticeActions` | 同上 |
| work/role/index.vue | `showRoleActions` | `openRoleActions` | 同上 |
| work/user/index.vue | `showUserActions` | `openUserActions` | 同上 |
| work/dict/index.vue | `openDictItemPage` | `navigateToDictItem` | 页面导航不用 open |
| work/role/index.vue | `handleAssignPerm` | `navigateToAssignPerm` | 导航伪装 + handle 滥用 |
| work/dept/index.vue | `handleAddChild` | `openChildDeptDialog` | 打开弹窗,与 `openDeptDialog` 对齐 |
| work/menu/index.vue | `handleAddChild` | `openChildMenuDialog` | 同上 |
| pages/login/index.vue | `handleWechatSilentLogin` | `doWechatSilentLogin` | 与 `doFormLogin` / `doWechatPhoneLogin` 统一 |
| work/user/index.vue | `handleUserSubmit` | `submitUserForm` | 与其余 7 页 `submitXxxForm` 统一 |
| subPages/mine/about/index.vue | `openUrl` | `openExternalUrl` | 非 H5 端实际是复制链接,补行为注释 |
| subPages/mine/settings/theme/index.vue | `showCustomInput` | `openCustomColorInput` | 打开弹窗用 open,与 ref 名区分 |
| subPages/mine/account/index.vue | `handleOpenDialog` | `handleOpenPopup` | 打开的是 wd-popup,术语修正 |
| subPages/mine/profile/index.vue | `openDialog` | `openProfilePopup` | 同上 |
## 2. 变量与类型(已修复)
| 文件 | 原名 | 现名 | 依据 |
| --- | --- | --- | --- |
| subPages/mine/profile/complete-profile/index.vue | `cropperVisible` | `isCropperVisible` | 与 profile 页同名概念统一 |
| subPages/mine/settings/theme/index.vue | `showCustomColorInput` | `customColorInputVisible` | 布尔 ref 谓语风格 |
| subPages/mine/profile/index.vue | `dialogState` | `popup` | 与 account 页弹层状态统一 |
| pages/work/index.vue | 本地 `hasPermission` | `isMenuAllowed` | 与 utils 同名但空 perm 语义相反(本地视为公开入口),import 恢复 `hasPermission` 原名 |
| api/notice.ts | `level: string \| number` | `level: string` | 后端 NoticePageVO 为 String;`getLevelText` 参数同步收窄 |
## 3. api/notice.ts 类型与注释(已修复)
- 删除 `NoticeItem.priority`:后端 `NoticePageVO` 无此字段,前端零消费。
- 删除 `NoticeItem.content`:同上,详情内容来自 `NoticeDetail`。
- `targetType` 注释 `0-全体 1-指定` 改为 `1-全体 2-指定`,对齐 `NoticeTargetEnum`。
- `publishStatus` 注释 `2已撤回` 改为 `-1-已撤回`,对齐 `NoticePublishStatusEnum` 与页面判断逻辑。
## 4. 注释与死代码(已修复)
- subPages/mine/profile/index.vue:3 条复述变量名的行尾注释(`//用户信息` 等)删除。
- subPages/mine/profile/index.vue:`profile-last-cell-wrap` 死类名及包裹 view 删除。
- utils/storage.ts:挂在 `set` 上且不准确的 `/** localStorage 存储 */` 删除。
- subPages/mine/settings/theme/index.vue:`// 使用主题组合函数` 复述 import 的注释删除。
## 5. 保持原样(审计判定不改)
- `useTheme()` 转发层:是否保留属架构决策,命名本身合规。
- `usePagedList.fetchPage`:写多处状态但为模块私有实现,注释完备。
- `OfficialAccountCard` 的 `@open` 事件:注释已声明目标地址由父级决定,事件表达用户意图。
- `.is-active` / `.is-checked` 状态类:常见实践,与 BEM 并存。
- 头像选择三处命名(`chooseAvatar` / `handleChooseAvatar` / `handleAvatarUpload`):choose 与 upload 语义有别。
- account 页 catch 静默取消与解绑失败:行为缺口,非注释错误。
- 两处文件私有 `interface NavItem`:同名不同构,均为局部类型。
- `sendVerificationCode` 的 `contactType`:可收窄为 `"MOBILE" | "EMAIL"`,影响小。
- mine 页 `router.push` 与 `uni.navigateTo` 并存:API 选择,非命名问题。
- menu 页 `@search` 直绑 `loadMenuList`:规范未强制事件回调必须 handle。
- dict/item 的 `tagComponentType`:可加 get 前缀,影响小。
## 6. 已确认合规的类别
- 谓词查询无副作用:`hasPermission`、`isValidMobile`、`isValidCapsuleRect`、`isExpanded` 等。
- `ensure`:`ensureAuthenticated`、`ensureUserInfoLoaded`。
- 导航:`navigateToProfile` / `navigateToAccountSecurity` / `navigateToOfficialAccount` 等。
- 弹窗 open/close:`openXxxDialog` / `closeXxxDialog` / `openResetPwdDialog` / `BindMobilePopup.open`。
- sync / reset / load / fetch / get / build / format 系列动词与行为一致。
- `handle` 全部用于模板事件绑定。
- API 层 `getXxx` 与业务动词(`publish` / `revoke` / `bindMobile` / `unbindSocial` 等)与行为一致。
- 布尔 ref 谓语风格、单位后缀(`contentHeightPx` 等)、枚举名词化、接口无 I 前缀。
- BEM 紧凑规则:`app-navbar__content--fixed`、`profile-card__login`、`quick-card__icon--primary`、`permissions__header` 等。
- 高价值注释保留:usePagedList 迟到响应策略、storage PRESERVED_KEYS 边界、useScanLogin 失败分类等。
## 7. 遗留问题(youlai-boot,未改)
- `NoticeDetailVO.java:36` 注释写「2已撤回」,与 `NoticePublishStatusEnum` 的 `-1` 及实体、查询对象注释矛盾。按约定不动 youlai-boot,需要修复时单独提交。
## 8. 评审文档 R1–R12 验收核对(2026-10-16)
| 编号 | 问题 | 结论 | 证据 |
| --- | --- | --- | --- |
| R1 | 扫码平台能力及错误被吞 | 已关闭 | `useScanLogin.ts` 按平台判断能力并提示,失败区分取消/权限/能力/其他 |
| R2 | 确认与取消并发 | 已关闭 | `scan-confirm` 单一 status 状态机,非 ready 直接返回,finished 后不再接受提交 |
| R3 | Button 旧参数 | 已关闭 | 全量扫描无裸 `plain`、无 `type="error"`,均为 `variant="plain"` |
| R4 | 模板检查关闭、shim 过宽 | 已关闭 | `tsconfig.templates.json` + `scripts/check-templates.mjs` 只统计 src;`wot-ui-component-shims.d.ts` 已删除 |
| R5 | 玻璃卡片降级与层级 | 已关闭 | ProfileCard 恒定玻璃底、`@supports` 内叠加模糊;theme.scss 标注层级表,普通内容 5 / 导航 15 / 全局遮罩 90 |
| R6 | 退出无过程反馈 | 已关闭 | `useLogout` 的 `isLoggingOut` 防重入 + `toast.loading` 过程反馈 |
| R7 | 重复 gutter、navbar 责任 | 已关闭 | 网络页去除重复 `px-32rpx`;`NavbarMetrics` 收缩为实际被消费的 6 项 |
| R8 | 登录与无权限混判 | 已关闭 | 首页未登录展示入口引导、已登录按权限过滤;工作台 `isMenuAllowed` 保留公开入口语义 |
| R9 | 网络检测文案与行为 | 已关闭 | 探测指向接口服务地址,不可达显示「不可访问」,耗时与失败状态分开 |
| R10 | ActionSheet label 兼作 ID | 已关闭 | 命令模型 `id / label / execute`,按索引分发(本轮重构为 `ActionSheet` 组件) |
| R11 | font-bold 重定义、主色衍生、warning 错配 | 已关闭 | `unocss.config.ts` 无 font-bold shortcut;主色衍生由 AppProvider 按所选主色注入;MenuSection 的 tone 映射 `--color-warning` |
| R12 | 命名与注释缺统一约定 | 已关闭 | 本文档 1–4 节;文件名检查落地为 `scripts/check-naming.mjs` |
## 9. 已接入的自动检查
- `scripts/check-templates.mjs`:模板类型检查,只统计 src 下的错误。
- `scripts/check-naming.mjs`:自有 Vue 文件 PascalCase;路由 `index.vue`、`App.vue`、`layouts`、第三方 `qiun-*` 除外。
- 两者已加入 `pnpm check`。
评审 13 节其余可自动检查项(BEM 选择器格式、旧 Wot 参数、宽泛全局选择器、UnoCSS 工具项阈值提示)暂未实现,保留为人工审阅。