106 lines
8.1 KiB
Markdown
106 lines
8.1 KiB
Markdown
# 命名与注释审计(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 工具项阈值提示)暂未实现,保留为人工审阅。
|