kd-aiot-frontend-hr/.codebuddy/memory/2026-09-14.md

2026-09-14

首页改接口：移除旧接口，对接「查询人力资源总览」

• 接口文档：http://192.168.1.147:18086/doc.html（Springfox Swagger2，18 个分组）。抓文档的可用姿势：/swagger-resources 拿分组 → /v2/api-docs?group=hr 拉全量 JSON（约 1MB，web_fetch 会截断，建议 Invoke-WebRequest -OutFile 后用 node 解析）。
• 目标接口：GET /hr/overview/data-center（summary「查询人力资源总览」，tag 人力资源-人力资源总览 / Hr Overview Controller）。
• 入参：organizationId(int64，不传=全部授权组织)、departmentId(int64)、year+month(必须同时传，不传=当前自然月)、trendMonthCount(1-12，默认 6，流动趋势月份数)。
• 返回 data：dataStatus(AVAILABLE/PARTIAL/DATA_UNAVAILABLE)、reportMonth(yyyy-MM)、statisticsDate、message；topCards[](cardCode：ON_JOB_TOTAL / MONTH_ONBOARD / ATTENDANCE_ABNORMAL_DEPT / CONTRACT_EXPIRE；value 可为空、unit、dataStatus、message、drillDownPath)；turnoverTrends[](month/onboardCount/leaveCount/onJobCount/netChangeCount/onboardRate/leaveRate) + turnoverOnboardRate/turnoverLeaveRate；departmentHeadcountRatios[](departmentId/Name、actualCount、plannedCount、headcountRatio、usageRate、vacancyCount、overstaffedCount、status：VACANCY/FULL/OVERSTAFFED/NO_PLAN) + headcountPlannedTotal/headcountActualTotal/headcountUsageRate/headcountVacancyTotal/headcountOverstaffedTotal/headcountMessage；urgentTodos[](todoType：CONTRACT_EXPIRE/ATTENDANCE_ABNORMAL/OVERSTAFFED、title、count、unit、message、drillDownPath)。
• 代码改动：新增 src/api/hr/overview.js（getHrOverviewDataCenter）；src/views/homeView/index.vue 去掉 getHrCockpit（@/api/hr/analytics）与 getCertificateWarningDashboard（@/api/hr/skillMatrix）调用，删除 src/views/homeView/mock.js 及所有 matchText/前缀猜测映射，改为按 cardCode/todoType 直接映射。
• 口径变化：「部门编制占比」由原来的「在职率/离职率/正编率/入职率」四率环形图改为按部门的实际占编占比环形图（Top6 + 其他），面板加了「计划编制/实际占编/编制使用率」汇总条 + 可滚动部门明细列表；「人员流动率」改为「人员流动趋势」（入职/离职分组合柱，不再堆叠，tooltip 补在职/净增）。
• 空值处理：接口允许 value 为 null（权威事实缺失），前端一律显示 -- 并用 title 提示 message，不再回退本地 mock。
• 保留：listOrganizations（/main/group/getGroupList）用于「所属机构」下拉，映射到新接口的 organizationId（用户未明确要求去掉）；analytics.js/skillMatrix.js 里的旧封装函数保留未删。

附件组件（fileMain，src/components/addDoc）

• 公共组件 index.vue 的「查看」逻辑：handleUpload → main.vue open()。main.vue 内置「查看 + 单附件自动预览」，会与文件列表弹框叠两层。
• 改动 main.vue：open() 里判定 previewOnly = type==='view' && ids.length===1，单附件时直接开预览、不再打开文件列表弹框；多附件/失败仍走列表弹框（showListModal()）。
• 模板结构：外层多包一层 <div class="add-doc-main">，<browse ref="browseRef"> 从列表弹框插槽内移到外层（Element el-dialog 未显示时不渲染插槽内容，移出后才能不打开列表弹框直接预览）。
• browse.vue 的 open() 返回 true/false，预览不可用时回退显示文件列表。
• 角标被裁：.el-table .cell{overflow:hidden} + el-badge 默认 translateY(-50%) 会溢出容器上边缘。已在 index.vue 的 scoped 样式里覆盖为 top:0; transform: translateX(100%)，并给 .file-main 加 padding-right:12px。

员工档案详情（EmployeeArchiveDetail.vue）

• 对照 EmployeeArchiveForm.vue（新增/编辑）补齐展示：身份信息（补性别/专业/毕业日期/户籍地址/工作地址）、组织与任职（补用户账号/所属机构/所属工厂/入职时间/转正日期/关键工序/是否启用，岗位类型→岗位层级）、联系方式（补微信号，紧急联系人拆三个字段）、新增教育经历区块、合同与薪酬（合同分类/编号/签订时间/生效状态/备注 + 薪酬银行多账户列表 + 社保公积金记录列表，去掉 adaptEmployee 不返回的 payrollType/insuredCity/housingFundAccount 等空行）、新增「资质与技能」tab（工种/证照/技能/档案附件/档案备注）。
• 数据模型来自 @/api/organization 的 adaptEmployeeProfile / adaptEmployee；注意 familyMembers、awards、files 目前恒为空数组。

人员结构看板 UI 优化（src/views/hrAnalysis/personnelStructureDashboard + src/styles/views/personnelStructureDashboard/index.scss）

• 页面是暗色科技风大屏（靠 src/styles/config/setting.js 里的 SYSTEM_NAME 布局），整页 height: calc(100vh - 72px) + overflow: auto，grid-template-rows: auto auto minmax(330px,1fr) minmax(350px,1fr)，面板高度不足时内容会被裁切（原先是 minmax(0,1fr)，字号又小又挤）。
• 「整体人员分布」原来 3 列小卡片（图标+标签+数字），卡片被压到 overflow:hidden 里，人数经常看不见；改成 2 列 × 3 行：图标 + 标签/占比条形 + 右侧醒目人数（.summary-value 22px），条形宽度由新增的 summaryMax 计算属性 + summaryBarStyle() 方法给出。
• 统一放大字号：正文 11~13px → 13~15px，指标数字 28 → 30px，图表 axisLabel 12 → 13、legend/tooltip 13 → 14、柱状图 label 12 → 13、环形中心字号 16 → 19；同时放大间距（gap 12 → 14、卡片 min-height 108 → 126、panel padding 12/14 → 14/16）。

看板 UI 二次调整（同上两个文件 + 页面脚本）

• 「人员素质分析」中心总人数原先用 ECharts graphic 文本，位于 zlevel 0 的 z=0 层、可能被饼图盖住/画布尺寸不同步导致偏移；改为饼图 series 的 label.position: 'center'（只对 dataIndex===0 输出总数，其余空串），并设 avoidLabelOverlap: false、radius: ["46%","66%"]，标签天然在扇区之上且随 resize 自动居中。
• observeResize() 现在除了 this.$el，还把每个图表容器 refs 都纳入 ResizeObserver，避免面板内部尺寸变化后画布比容器大、图表内容被裁。
• 用户要求看板一屏展示不要滚动条：.dashboard-page 恢复 grid-template-rows: auto auto minmax(0,1fr) minmax(0,1fr) 且 overflow: hidden（≤1150px 媒体查询里恢复滚动）；新增 @media (max-height: 880px) 收敛指标卡/面板/分布行尺寸，@media (max-height: 700px) 兜底允许滚动。分布行压缩为 icon 28、标签 13px、人数 20px、条形 3px、grid-auto-rows: minmax(0,1fr)。

看板第三次调整：查看明细挪右上 + 彻底解决滚动条

• 根因1：全局 main[class*='-page']{min-height:calc(100vh - 100px);display:flex;flex-direction:column} 优先级高于 .dashboard-page，导致页面的 display:grid/min-height:0 全部失效（一直是 flex 列布局，图表高度靠画布自身撑，才会出现中心数字被裁）。把根 class dashboard-page 改名为 psd-screen（不再命中 [class*='-page']）后 grid 生效。
• 根因2：.ele-admin-content 在 fixed-body + card 页签下高度固定为 100vh - 104px 且 overflow-y:auto，页面写 calc(100vh - 72px) 就高出 32px → 外层出现滚动条。改为 height: calc(100vh - 104px); max-height: 100%; overflow: hidden。
• 「查看明细」由卡片右下角（bottom:11px、hover 才显示）移到右上角（top:12px/right:13px，常显 opacity .75），因此卡片去掉底部预留 padding，min-height 126→104（≤1500px 96，矮屏 94），并给标题 padding-right:58px 避免被链接压住。
• 媒体查询同步：≤1150px 与 max-height:700px 恢复 height:auto/max-height:none/overflow:visible 允许滚动。

人员结构分析看板（personnelStructureAnalysisBoard）同款优化

• 与上一个看板同样的问题：根 class .personnel-board-page 命中全局 main[class*='-page']，且 height: calc(100vh - 72px) 比内容区（100vh-104）高 32px。改名为 .psa-board，高度改 calc(100vh - 104px); max-height: 100%，@media (max-width: 1180px) 恢复 height:auto; max-height:none; min-height:calc(100vh - 104px)。
• 字号整体上调 1~2px：tag 10→11、筛选/按钮 11→12、指标标题 12→13、指标数字 30→31、同比环比 10→11、面板标题 13→14、面板单位 9→11、序列名 12→13、序列占比 9→11、地图数值 12→13 / 地点 9→11、页脚 9→11、明细弹框 11~12→12~13、ECharts 轴/标签/图例 10~11→11~12、环形中心 18→20。
• 该页是一屏栅格布局：.personnel-board 行高 46→54（表头）、minmax(92px,.46fr)→minmax(106px,.46fr)（指标行）、页脚 16→20，gap 12→14，面板标题高 42→46（.chart/.sequence-list 的 calc(100% - 42px)、.location-map 的 top 同步改成 46）；打印块行高也同步调整。

首页（homeView）UI 优化 + 彻底去掉滚动条

• 根因：src/styles/views/HomeView.scss 的根类 .hr-overview 写的是 min-height: calc(100vh - 56px)，比固定主体 + card 页签下的内容区（100vh - 104px：顶栏56 + 页签40 + 卡片间距8）高 48px → .ele-admin-content（overflow-y:auto）出现滚动条。
• 改法：.hr-overview 改为 display:grid; grid-template-rows: auto auto minmax(0,1fr); height: calc(100vh - 104px); max-height: 100%; overflow: hidden（max-height:100% 兜底，门户 chrome 高度不同时也不会溢出）。根类名不含 -page，不会命中全局 main[class*='-page'] 规则。
• 关键坑：.panel-grid 必须显式写 grid-template-rows: minmax(0, 1fr)，否则内部 auto 行按内容高度撑（图表 flex 收缩到 0），面板会塌成只有标题栏高。
• 图表高度由固定 height: 390px 改为跟随面板：.flow-chart{flex:1 1 auto}、.staffing-chart{height:100%}（.staffing-stage 是 flex:1 的定高容器）；.metric-grid/.overview-title 去掉 margin-bottom 改用 grid gap；.panel/.panel-grid 的 min-height: 470px 改 0。
• 统计月份由「占一行」改为 .overview-title__meta 绝对定位到标题行右侧的小胶囊（≤960px 恢复静态居中）；.metric-card 118→108（矮屏 92）、数值 36→34。
• 部门编制占比：原来四个比率用 ECharts graphic 百分比定位（容器被拉高后标签会漂离圆环/被裁），改为 HTML <ul class="staffing-legend"> 四角 2×2 网格定位于 .staffing-stage，环形 radius 52/72→58/84、center 统一 50%。同时流图 grid.top 40→52 避开右上角入/离职率胶囊。
• 响应式：≤1400 收紧三列列宽；max-height:880 整体压缩（标题/指标卡/面板/todo）；≤1024 与 max-height:700 恢复 height:auto; overflow:visible 允许滚动兜底；≤960 指标卡单列、隐藏标题翅膀。
• 「考勤异常」指标卡：badge 仅在 value > 0 时显示，避免出现空心 0 角标。

修复报错 TypeError: Cannot read properties of null (reading 'userId')

• 原因：src/components/addDoc/file-edit.vue created() 直接读 this.user.info.userId（vuex user.info 初始为 null，只有门户调用 user/setInfo 后才有值）。
• 改法：新增 currentUserId 计算属性（this.user?.info?.userId ?? ''），created() 改为调用 loadFolderList() 并 try/catch；doc_template.vue 的 query(type) 同样做空值兜底。user.info 为空时不再传 currentUserId 参数。