Files
funjia-admin-template-vue/README.md
T
funjia a640389095 重构: 修复致命缺陷、清理死代码并打通类型检查与构建
本次优化在不改变业务行为的前提下,修复了多处会导致数据丢失或
功能失效的缺陷,并把此前从未跑过的类型检查与生产构建接通。

== 修复的严重缺陷 ==

服务端:
- dynamic/notice 路由在目标表缺失时用 `db.data = { dynamic: [] }`
  整体替换数据库对象后落盘,会把 employee/Notice/qa 等全部业务表清空。
  改为只创建缺失的那一张表。
- 列表接口在空表时访问 undefined.length 直接 500,统一补默认空数组。
- /api/employee/list 与 /login 明文返回 pwd 字段,且把含密码的
  请求体写进日志。改为统一剔除敏感字段、移除参数日志。
- upd 允许请求体覆盖主键 id / createTime;改为服务端维护。
- upload 未限制扩展名与大小,且用原始扩展名拼路径。

前端:
- src/common/axios.ts 的拦截器注册在全局默认 axios 实例上,而业务
  走 funjia-axios,导致拦截器全程失效;同时 funjia-axios 内部
  `axios.prototype.error = () => {}` + `axios.prototype(msg)` 会抛
  TypeError,使所有接口错误(含 401)被静默吞掉。现在本文件是唯一
  的拦截器注册点。
- 修改密码功能形同虚设: PwdForm.onUpdate 只做 setTimeout 后 emit
  成功,从不调接口;PwdDialog 又用已被拦截器解包掉的 status 判断
  成败,无论结果都提示失败。
- Notice/Plugin 新增时 userId 静默丢失 (UmByClassEnhance 的
  otherParams 只进 getList,不传 onAdd/onEdit),改用会话级
  setCurrentUserId/getCurrentUserId。
- 修复 Login 模板绑定了从未定义的 loading、跳转到路由表里不存在
  的路径;DynamicTable 里每次路由切换都触发的 debugger。
- 修复 Record/RecordUser 引用不存在的 marsLib/*、@/components/UmTable;
  CodeMirror 使用 ref 却未 import; ImageCell 调用不存在的
  getObjectTypeName。

== 结构优化 ==

- 新增 src/common/response.ts 与 BaseViewModel,收敛 7 个 viewModel
  中重复 20+ 次的响应码判断与 CRUD 样板。
- 新增 server/routers/helpers.mjs,统一服务端取表/过滤/分页/脱敏。
- 新增 server/smoke-test.mjs,16 个用例覆盖上述修复(含整库清空回归)。
- 删除 0 引用的死文件: ImageList.vue、autoresponsive.vue、
  animation.js、PwdDialog/PwdForm.vue。

== 工程配置 ==

- 修复阻塞安装与构建的三处错误:
  funjiaui 指向不存在的仓库 FunjiaUI_Vue(#v1.1.3),实为
  FunJiaUI_Vue_Package(#v1.3.1); pinia 锁 ~2.0.36 (vue 固定 3.2.33,
  2.1+ 要求 vue ^3.3.0); App.vue 引用不存在的 funjiaui/dist/style.css,
  实为包根目录 style.css。
- 新增 build/typecheck/build:only 脚本; 此前项目没有类型检查步骤。
- 移除 8 个未使用依赖,补齐 terser 与缺失的类型包。
- vite.config.ts 代理目标改由 .env 配置,移除硬编码内网地址;
  增加 manualChunks 拆包。
- 服务端数据库改为不进版本库,提供 *.example.json 初始化模板。

== 验证 ==

- npx vue-tsc --noEmit          : 0 错误
- npm run build                 : 成功 (1759 模块)
- cd server && npm run smoke    : 16/16 通过

优化前的代码保留在 legacy 分支。
2026-09-24 15:39:59 +08:00

76 lines
3.0 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# funjia-admin-template-vue
基于 Vue 3 + TypeScript + Vite 的后台管理模板,配套 Koa + lowdb 的轻量服务端。
- 前端:Vue 3.2 `<script setup>` + Element Plus 2.1 + Pinia + vue-router(hash 模式)
- 表格/表单:内部组件库 `funjiaui` 的 **装饰器驱动** 模式(`@tcpd` / `@tfcpd` / `@tcmd` / `@tsfpd`)
- 请求层:内部封装 `funjia-axios`(响应拦截器会直接解包 `response.data`)
- 服务端:`funjia-server` + Koa,数据落在 `server/db/*.json`(lowdb)
## 快速开始
```bash
# 前端
npm install
npm run dev # http://localhost:4444
# 服务端(另开一个终端)
cd server
npm install
node index.mjs # 监听 4873
```
开发环境默认把 `/api`、`/static` 等前缀代理到 `http://localhost:4873/`。
如需改动,复制 `.env.example` 为 `.env.local` 并修改 `VITE_API_TARGET`。
## 校验命令
```bash
npm run typecheck # vue-tsc 类型检查
npm run build # 类型检查 + 生产构建(vite build)
npm run build:only # 仅构建,跳过类型检查
cd server && npm run smoke # 服务端路由烟雾测试(16 个用例)
```
## 依赖说明(重要)
三个内部包通过 git 依赖引入。**它们的地址必须与 Gitea 上的仓库名完全一致**:
| 包名 | 仓库 | 说明 |
| --- | --- | --- |
| `funjiaui` | `funjia/FunJiaUI_Vue_Package` | 组件库,样式在包根目录 `style.css`(**不是** `dist/style.css`) |
| `funjia-axios` | `funjia/funjia-axios` | 请求封装。`main` 直接指向未编译的 `index.ts` |
| `funjialib` | `funjia/FunJiaLib_Package` | 工具库。按子路径引用,如 `funjialib/date` |
需要注意的坑:
1. **仓库名大小写敏感**。历史配置里写成 `FunjiaUI_Vue`(且引用 `#v1.1.3`),
该仓库与 tag 均不存在,`npm install` 会在 git 认证环节长时间静默卡住而不报错。
2. **`pinia` 需锁定 `~2.0.36`**。`vue` 固定在 `3.2.33`,而 `pinia >= 2.1.7`
要求 `vue ^3.3.0`,升级会触发 ERESOLVE。
3. `funjia-axios` 的类型由本项目 `src/type/funjia-axios.d.ts` 提供
(上游源码存在 TS7006 且无法解析自身依赖,详见该文件注释)。
## 服务端数据库
`server/db/` 下的真实数据文件(`db.json` 等)**不进版本库**,已加入 `.gitignore`。
首次部署时用示例库初始化:
```bash
cd server
cp db/db.example.json db/db.json
cp db/logDB.example.json db/logDB.json
cp db/resourceDB.example.json db/resourceDB.json
cp db/backupDB.example.json db/backupDB.json
```
服务端配置同理,从 `config.example.yml` 复制为 `config.yml`。
## 推荐的 IDE 配置
- [VS Code](https://code.visualstudio.com/) + [Volar](https://marketplace.visualstudio.com/items?itemName=Vue.volar)
`.vue` 文件在 TS 中默认只能拿到通用组件类型。若需要真实的 props 类型推断,
可按 Volar 的文档启用 Take Over 模式。