refactor(pc): 从 Gi Admin Pro + Arco 重搭为纯 Vue 3 + Naive UI
旧模板的 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
This commit is contained in:
+42
-24
@@ -1,6 +1,10 @@
|
||||
# AGENTS.md
|
||||
|
||||
面向 AI 编码助手的项目指南。规范以 `.agents/` 为唯一来源。
|
||||
面向 AI 编码助手的项目指南（PC 管理端）。规范以 `.agents/` 为唯一来源。
|
||||
|
||||
> ⚠️ **2026-10 已重搭**：从 **Gi Admin Pro + Arco Design Vue** 换成 **纯 Vue 3 + Naive UI 2.42**。
|
||||
> 上一版基于 Gi/Arco 的 skills 已全部重写 —— **不要再按 Arco 的组件名（`a-table` / `a-form`）、
|
||||
> `v-hasPerm`、auto-import、Stylelint 去写代码**。
|
||||
|
||||
## 常驻规则（Agent 行为准则）
|
||||
|
||||
@@ -19,36 +23,50 @@
|
||||
| 写/改 `.vue` | `.agents/skills/code-vue/SKILL.md` |
|
||||
| 写/改样式 | `.agents/skills/code-css/SKILL.md` |
|
||||
| 写/改 `.ts` / composable | `.agents/skills/code-ts/SKILL.md` |
|
||||
| 项目约定、Gi 组件 | `.agents/skills/project-guide/SKILL.md` |
|
||||
| 项目约定、Naive UI 组件与目录 | `.agents/skills/project-guide/SKILL.md` |
|
||||
| CRUD 列表/表单 | `.agents/skills/project-crud/SKILL.md` |
|
||||
| API / Mock | `.agents/skills/project-api/SKILL.md` |
|
||||
| 接口调用（`src/apis/xt/`） | `.agents/skills/project-api/SKILL.md` |
|
||||
| 提交代码（git commit） | `.agents/skills/git-commit/SKILL.md` |
|
||||
|
||||
## 按需技能（`.agents/skills/`）
|
||||
|
||||
| 场景 | 文件 |
|
||||
|------|------|
|
||||
| TS 命名、导入、Lint | `code-ts/SKILL.md` |
|
||||
| Vue SFC、Emits、Ref | `code-vue/SKILL.md` |
|
||||
| 样式、BEM、Stylelint | `code-css/SKILL.md` |
|
||||
| 项目总览、技术栈、Gi 约定 | `project-guide/SKILL.md` |
|
||||
| CRUD 列表/表单 | `project-crud/SKILL.md` |
|
||||
| API 与 Mock | `project-api/SKILL.md` |
|
||||
| Git 提交 | `git-commit/SKILL.md` |
|
||||
|
||||
## 快速入口
|
||||
|
||||
```bash
|
||||
pnpm dev # 开发（/api 代理到 http://localhost:8080，没有 Mock）
|
||||
pnpm build # 生产构建
|
||||
pnpm typecheck # vue-tsc
|
||||
pnpm lint # ESLint
|
||||
pnpm lint:style # Stylelint
|
||||
pnpm typecheck # vue-tsc（**当前 0 错**，有报错就是新引入的）
|
||||
pnpm lint # ESLint（@antfu/eslint-config）
|
||||
```
|
||||
|
||||
- 路径别名：`@` → `src/`，`~` → 项目根目录
|
||||
- **开发没有 Mock**：`mock/` 目录与 `vite-plugin-mock` 都已删除，`pnpm dev` 把 `/api`
|
||||
代理到 `http://localhost:8080`（见 `vite.config.ts` 的 `server.proxy` 与
|
||||
`.env.development` 的 `VITE_API_BASE_URL`）→ **后端不起着就没有数据**。
|
||||
我们的接口模块在 `src/apis/xt/`（`apis/system|user|…` 是 Gi 模板自带的）
|
||||
- 登录演示账号见 `README.md`（如 admin / 123456）
|
||||
- 路径别名：`@` → `src/`
|
||||
- **开发没有 Mock**：`pnpm dev` 把 `/api` 代理到 `http://localhost:8080`
|
||||
（见 `vite.config.ts` 的 `server.proxy`）→ **后端不起着就没有数据**
|
||||
- 接口模块在 `src/apis/xt/`（按业务域分文件），统一从 `@/apis/xt` 或 `@/apis/xt/<域>` 引
|
||||
- 演示账号：`admin / Admin@123` + 租户码 `demo`（⚠️ **不是** Gi 模板 README 里的 `admin/123456`）
|
||||
|
||||
## 七条最容易写错的约定
|
||||
|
||||
1. **没有 auto-import**：naive-ui 组件、Vue API、工具函数**全部显式 `import`**，
|
||||
标签统一写 **PascalCase**（`<NButton>`）。
|
||||
⚠️ 漏 import 是**静默故障**：写小写 `<n-button>` 而没 import 时，Vue 把它当未知自定义元素渲染，
|
||||
**不报错、typecheck/lint 全绿，只是样式整块丢掉**（2026-10 实测踩到 4 个文件 6 处）。
|
||||
`python scripts/check-wiring.py` 第 ⑧ 项会静态核对这件事。
|
||||
2. **权限判断**：`useUserStore().has('码')` / `hasAny(...)`（**没有 `v-hasPerm` 指令**）；
|
||||
权限码字符串必须与后端 `PermissionDef` **逐字一致**（`progress:viewAll` 是驼峰）。
|
||||
3. **状态色**：`n-tag` 的 `type` 必须过 **`@/utils/tag.ts`** 的 `tagOf()` ——
|
||||
`apis/xt/*.ts` 里的展示映射仍是 Arco 色词（`green`/`arcoblue`/`gold`），
|
||||
直接透传给 `n-tag` 会**静默变灰**且不报错。
|
||||
4. **图标**：用 `@/icons/AppIcon.vue` + 图标名；图标数据由
|
||||
`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` 灰底浮起来；卡片外观（描边/阴影/圆角/卡片头色带）
|
||||
由 `src/styles/index.scss` 的 `.n-card.n-card` 统一给，**页面不要再自己写**；
|
||||
卡片内部分区用 `.section-title` + 浅灰小格子，**不要卡里套卡**。
|
||||
工具条控件同一行尺寸要一致（统一默认尺寸，别混 `size="small"`）。
|
||||
7. **品牌标**：几何标在 `src/assets/images/logo.svg`（**不要换回文字字形标** —— 形状的出处与
|
||||
构造参数写在该文件注释里）；页签用 `public/favicon.svg`（加粗版），改一个要同步另一个，
|
||||
外加侧栏/登录页的引用尺寸与 `docs/prototype/admin-web.html` 的 `.mark`。
|
||||
⚠️ **SVG 的注释里不能出现连续两个减号**（XML 规范禁止）：会让整个文件 not well-formed，
|
||||
表现是图片裂开、**控制台一句话都不报**，typecheck/lint 也全绿。
|
||||
`python scripts/check-wiring.py` 第 ⑨ 项会核对这件事。
|
||||
|
||||
Reference in New Issue
Block a user