94 lines
5.6 KiB
Markdown
94 lines
5.6 KiB
Markdown
# 办事大厅后台管理端前端（svc-hall-front）
|
||
|
||
云海平台子应用「办事大厅」的**管理端**：事项库 + 服务字典 + 自定义表单（设计器）+ 办件记录。
|
||
Vue 3 + Vite + view-ui-plus + alova。
|
||
|
||
> **用户面已迁出本前端**（2026-09-16，BP-R4-3）：在线办理 / 我的办件 / 办件详情在学生与教师
|
||
> 办理入口的独立前端 **`svc-hall/app/public`（部署于 `/svc-hall/public/`）**，本前端只保留后台管理。
|
||
> 两个前端互不引用；管理端的办件详情是「办件记录」里的只读抽屉，不做提交人动作（撤回/重提）。
|
||
|
||
> 说明：本文件此前误为本仓 Notice（通知公告）前端的副本（描述 `/notice/*` 路由、
|
||
> `src/assets/mock/noticeapi.ts`、`NoticeUpload.vue` 等本仓不存在的文件），2026-09-16
|
||
> 依据本仓实际代码重写。
|
||
|
||
## 本地启动
|
||
|
||
```bash
|
||
npm install
|
||
npm run dev # http://localhost:8087
|
||
```
|
||
|
||
`dev` 模式下 `serviceHost` 留空，接口走同源相对路径 `/api/...`，由 vite proxy 转发到本地后端
|
||
`http://localhost:8086`（后端 CAS 过滤器对 `/api/*` 不回 CORS 头，浏览器直连会被拦，必须同源代理）。
|
||
|
||
本地完整链路还需：UserBase（base/sso 鉴权）、流程中心后端 `http://localhost:8085`
|
||
（流程选择器与流程图；本前端**不直连** flow-center，一律经 svc-hall 后端中转）。
|
||
另有 `npm run dev:mock`（`.env.mock`）用于后端不可达时的纯前端联调。
|
||
|
||
## 脚本
|
||
|
||
| 命令 | 说明 |
|
||
|---|---|
|
||
| `npm run dev` | 本地联调（读 `.env.dev`） |
|
||
| `npm run dev:mock` | 纯前端模式（读 `.env.mock`；mock 中间件仅在 `--mode mock` 启用） |
|
||
| `npm run build` / `build:base` / `build:ld` / `build:prod` | 构建产物恒为 `dist` 根（CI 打包要求 zip 根直接有 `index.html`，见 `vite.config.ts` 头注） |
|
||
| `npm run api:gen` | alova 接口代码生成 |
|
||
|
||
## 运行期配置
|
||
|
||
优先级见 `src/assets/config/host.config.ts`：① 线上 `window.__APP_CONFIG__`（`index.html` 引导脚本同步拉
|
||
`/<contextPath>/api/env-config?target=front`，projman 配置管理维护）→ ② 本地 `import.meta.env.VITE_*`
|
||
（build 产物不读任何 `.env.*`）→ ③ 同域推导兜底。
|
||
|
||
## 页面与路由（`src/router/routes.ts`）
|
||
|
||
| 路径 | 页面 | modId |
|
||
|---|---|---|
|
||
| `/svc/item` | 办事事项（管理面） | 23 |
|
||
| `/svc/item/edit` | 编辑事项 | 28（parentId 23） |
|
||
| `/svc/dict` | 服务字典 | 24 |
|
||
| `/svc/form` | 表单管理 | 25 |
|
||
| `/svc/form/designer` | 表单设计器（拖拽三栏，`?id=` 回填） | 25（parentId 25） |
|
||
| `/svc/apply` | 办件记录（管理面，含只读详情抽屉 + 流程图） | 26 |
|
||
| `/` | → `/svc/item` | — |
|
||
| 其他 | → `/svc/item`（旧用户面深链兜底，避免白屏） | — |
|
||
|
||
`modId` 是菜单 ↔ 路由的稳定契约（UserBase `app_module` 按本应用 appKey 配置）。用户面路由
|
||
（原 `/my`、`/apply`、`/apply-detail`，modId 27）已随用户面迁出，`app_module` 里的对应菜单应删除
|
||
或改指 `/svc-hall/public/`。
|
||
|
||
## 目录要点
|
||
|
||
- `src/api/module/svc.ts`：接口封装（alova；`siteApi`/`svcItemApi`/`svcDictApi`/`svcFormApi`/`svcFlowApi`/`applyApi`/`fileApi`）。
|
||
**纪律：本文件不得出现 flow-center 地址**——流程能力（列表 `/api/svc/flow/list`、流程图
|
||
`/api/svc/flow/diagram.png`）一律经 svc-hall 后端中转（后端用 SDK `YschFlowOpenApi` 出站）
|
||
- `src/utils/site.ts`：当前站点上下文（`localStorage.svchall.site` 持久化，管理页共用）
|
||
- `src/components/DynamicForm.vue`：表单 schema 渲染器（`{groups:[{title,fields:[…]}]}`，一期 11 类控件；
|
||
多选类值为 `string[]`，附件/图片为上传返回体数组 `[{id,fileName,fileUrl,fileSize,mimeType}]`）
|
||
- `src/views/svc/FormDesigner.vue` + `src/components/designer/*`：拖拽设计器（左组件库/中多分组画布/右属性面板，保存前可预览）
|
||
- `src/types/designer.ts`、`src/utils/designer/schema.ts`：设计器类型、控件字典与 schema 序列化
|
||
|
||
## 契约纪律（改表单相关代码前必读）
|
||
|
||
- 前端**不得**直接调用流程中心（无 `flowHost`）：撤回/进度/流程图走 svc-hall 后端
|
||
`/api/apply/{id}/withdraw|progress|diagram.png`，事项的流程图为 `/api/svc/flow/diagram.png`。
|
||
原因是浏览器直调外部应用需要跨应用 CAS 票据与 CORS，且授权点会落到前端（BP-R4-2）。
|
||
|
||
- schema 由后端 `FormValidator` 强校验：属性白名单 16 项（无 `precision`）、`key` 限
|
||
`^[A-Za-z0-9_]{1,64}$` 且表单内唯一、`select/radio/checkbox/multiselect` 必须有非空 `options`、
|
||
`maxSize` 单位 **MB**、`maxFiles` 缺省或 0=不限。设计器序列化只输出白名单键（剔除内部 `_uid` 与空串）。
|
||
- 表单行不可变：已发布版本改结构 = 后端按 `code` 克隆出新草稿版本。设计器装载到已发布版本时**保存不传 `id`**
|
||
（传了会被后端直接拒「该版本已发布不可修改」），装载到草稿才带 `id` 就地更新。
|
||
|
||
## 构建与发布
|
||
|
||
push 到 `main` → gitea CI（`.gitea/workflows/build.yml`）：`npm run build` → 打包
|
||
`svc-hall-front-<sha8>.zip` → 推 Nexus raw → 通知 projman 建档（`status=pending`）。
|
||
线上部署由运维/管理员在 projman「前端发布」手动触发，push 不会自动上线。
|
||
|
||
## 验收口径
|
||
|
||
`npm run build` 退出 0 且 `dist/static/js/<页面>-<hash>.js` 正常产出。
|
||
注意：仓库自带 `vue-tsc@1.8.27` 与 `typescript@5.9.3` 不兼容，`npx vue-tsc --noEmit` 会直接抛
|
||
`Search string not found: "/supportedTSExtensions…"`（工具链问题，非代码错误），当前**无类型门禁**。
|