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
73 lines
4.1 KiB
Markdown
73 lines
4.1 KiB
Markdown
---
|
||
name: project-guide
|
||
description: 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`）；
|
||
不选就不发请求，否则会把各租户数据混在一起且看起来正常。
|
||
|
||
## 七条最容易写错的约定
|
||
|
||
1. **没有 auto-import**：组件与 API 全显式 import，标签写 **PascalCase**。
|
||
漏 import 是**静默故障**（未知自定义元素 → 样式整块丢掉，typecheck/lint 全绿）；
|
||
`python scripts/check-wiring.py` 第 ⑧ 项会核对。
|
||
2. **没有 `v-hasPerm`**：权限判断写 `user.has('码')`。
|
||
3. **`n-tag` 的 `type` 必须过 `@/utils/tag.ts`**（Arco 色词直接透传会静默变灰）。
|
||
4. **图标要重跑脚本**：`scripts/extract-pc-icons.py` → `src/icons/icon-data.ts`（37 个）；
|
||
缺图标是空占位、不报错 → 图标集升级后必须重跑。
|
||
5. **`n-tab-pane` 的标签用 `#tab` 插槽**，不要用 `tab="文字"` 属性 ——
|
||
naive-ui 2.45.3 的属性写法只渲染出空注释节点，整排 tab 一个字都不显示（不报错）。
|
||
6. **卡片式版面**：白卡片靠全局 `--xt-bg` 灰底浮起来；卡片外观由 `styles/index.scss` 统一给，
|
||
页面不要再自己写；卡片内部分区用 `.section-title` + 浅灰小格子，不要卡里套卡。
|
||
详见 [code-css](../code-css/SKILL.md) 的「设计基线」一节。
|
||
7. **品牌标是几何标**：`src/assets/images/logo.svg`（方 = 卷宗，环 = 在线）。
|
||
**不要换回文字字形标**；页签用 `public/favicon.svg`（加粗版），改一个要同步另一个。
|
||
⚠️ SVG 注释里**不能出现连续两个减号**（XML 规范禁止）→ 整个文件 not well-formed，
|
||
图片裂开而控制台一句话都不报；`python scripts/check-wiring.py` 第 ⑨ 项会核对。
|
||
|
||
## 开发
|
||
|
||
```bash
|
||
pnpm install
|
||
pnpm dev # → http://localhost:5173，/api 代理到 8080（后端不起着就没有数据）
|
||
pnpm typecheck && pnpm lint
|
||
```
|
||
|
||
演示账号：`admin / Admin@123` + 租户码 `demo`（**不是** Gi README 里的 `admin/123456`）。
|