lovife
5b877451eb
旧模板的 193 个文件整体删除，换成纯 Vue 3.5 + Naive UI 2.42 的树。
- 去掉 auto-import（组件与 API 全显式 import）、v-hasPerm（改 user.has('码')，全库 8 处）、
Stylelint；n-tag 的 type 统一过 utils/tag.ts 转换（Arco 色词直接透传会静默变灰）
- 图标改为构建期抽取：scripts/extract-pc-icons.py -> icons/icon-data.ts（37 个），
内网离线部署不会白屏
- 重搭后修掉 6 类"编译 / lint / typecheck 全绿、界面上就是坏的"故障：
① NGrid 的 cols 写成像素值（不是断点名 -> 永远只 1 列，工作台因此错乱）
② n-tab-pane 用 tab 属性（只渲染空注释节点，整排 tab 一个字都不显示）
③ 漏 import 被当未知自定义元素（样式整块丢） ④ .n-card__content 类名不存在
（高度链第一环失效，表格行在 DOM 里但屏幕上没有） ⑤ 填报单状态映射错位一格
⑥ 有标题的卡片没有上内边距（naive 的 padding-top 只给"内容区是长子"的卡片）
- 卡片式版面提成全局基线：styles/index.scss 的 xt-* 令牌 + .page-card / .toolbar /
.section-title，页面只引用、不再各写一套
- 品牌：改名「深学在线」，文字标换成几何标（方 = 卷宗 / 环 = 在线，不用文字字形）；
index.html 的页签图标从 404 的 /favicon.ico 改指真实存在的 /favicon.svg
4.1 KiB
4.1 KiB
name, description
| name | description |
|---|---|
| project-guide | PC 管理端的技术栈、目录结构、菜单与权限模型，以及七条最容易写错的约定。开始任何 PC 端改动前加载本技能。 |
项目总览（PC 管理端）
技术栈
| 项 | 值 |
|---|---|
| 框架 | Vue 3.5 + TypeScript + Vite 7 |
| UI | Naive UI 2.42（2026-10 从 Gi Admin Pro + Arco 重搭，已无 Arco/Gi 依赖） |
| 状态 | Pinia（pinia-plugin-persistedstate） |
| 请求 | axios（src/utils/http.ts 统一封装） |
| 样式 | SCSS（无 Stylelint） |
| 检查 | pnpm typecheck（vue-tsc，当前 0 错）、pnpm lint（@antfu/eslint-config） |
目录
src/
├── apis/xt/ 接口模块（按业务域分文件）+ types.ts（通用类型）
├── composables/ pagination.ts（列表页分页器统一参数）
├── config/ xt-routes.ts（**业务菜单表：菜单 + 路由 + 分组**）
├── icons/ AppIcon.vue + icon-data.ts（由 scripts/extract-pc-icons.py 生成）
├── layout/ AppSider / AppHeader / index.vue
├── router/ index.ts（本地菜单表按后端 menuKeys 过滤后注册）
├── stores/ user.ts（登录态/权限/菜单）、acting-tenant.ts（平台代管学校）、app.ts
├── styles/ index.scss（只放跨页面样式）
├── utils/ http.ts / naive.ts / tag.ts / format.ts / auth.ts / rsa.ts
└── views/ 页面（每个菜单一个目录，行内抽屉与弹窗同目录）
菜单与权限模型（后端决定可见性）
- 前端
config/xt-routes.ts是唯一菜单表：key（菜单键）↔ 路由 ↔ 视图 ↔ 分组。 - 能不能看由后端决定：
/auth/me返回menus: string[]，前端只按它过滤； 绕过前端也只会拿到40301。 - 能不能做看权限码：
useUserStore().has('码')，字符串必须与后端PermissionDef逐字一致 （progress:viewAll是驼峰，不是progress:view:all—— 写错只会恒为 false，不报错）。 - 平台运营要先选学校（
stores/acting-tenant.ts→ 请求头X-Tenant-Id）； 不选就不发请求，否则会把各租户数据混在一起且看起来正常。
七条最容易写错的约定
- 没有 auto-import：组件与 API 全显式 import，标签写 PascalCase。
漏 import 是静默故障（未知自定义元素 → 样式整块丢掉，typecheck/lint 全绿）；
python scripts/check-wiring.py第 ⑧ 项会核对。 - 没有
v-hasPerm：权限判断写user.has('码')。 n-tag的type必须过@/utils/tag.ts（Arco 色词直接透传会静默变灰）。- 图标要重跑脚本：
scripts/extract-pc-icons.py→src/icons/icon-data.ts（37 个）； 缺图标是空占位、不报错 → 图标集升级后必须重跑。 n-tab-pane的标签用#tab插槽，不要用tab="文字"属性 —— naive-ui 2.45.3 的属性写法只渲染出空注释节点，整排 tab 一个字都不显示（不报错）。- 卡片式版面：白卡片靠全局
--xt-bg灰底浮起来；卡片外观由styles/index.scss统一给， 页面不要再自己写；卡片内部分区用.section-title+ 浅灰小格子，不要卡里套卡。 详见 code-css 的「设计基线」一节。 - 品牌标是几何标：
src/assets/images/logo.svg（方 = 卷宗，环 = 在线）。 不要换回文字字形标；页签用public/favicon.svg（加粗版），改一个要同步另一个。 ⚠️ SVG 注释里不能出现连续两个减号（XML 规范禁止）→ 整个文件 not well-formed， 图片裂开而控制台一句话都不报；python scripts/check-wiring.py第 ⑨ 项会核对。
开发
pnpm install
pnpm dev # → http://localhost:5173，/api 代理到 8080（后端不起着就没有数据）
pnpm typecheck && pnpm lint
演示账号：admin / Admin@123 + 租户码 demo（不是 Gi README 里的 admin/123456）。