101 lines
6.0 KiB
Markdown
101 lines
6.0 KiB
Markdown
# 公共办事大厅前端（svc-hall-hall）
|
||
|
||
云海平台「办事大厅」的**用户面**前端：给学生 / 教师 / 访客提供**在线办理**入口——
|
||
事项大厅 → 在线办理（填表提交）→ 我的办件 → 办件详情（审批进度、流程图、撤回/重提）。
|
||
|
||
它是**独立前端项目**，与 `svc-hall/front`（后台管理端：事项库/字典/表单/办件记录）互不引用：
|
||
|
||
| | 本项目 `hall` | 兄弟项目 `front` |
|
||
| --- | --- | --- |
|
||
| 面向 | 学生 / 教师 / 访客 | 管理员（站点管理面） |
|
||
| 入口 | 门户指南页「我要办理」按钮 / 直接访问 | 平台工作台菜单（app_module） |
|
||
| 页面 | 事项大厅、在线办理、我的办件、办件详情 | 办事事项、服务字典、表单管理（设计器）、办件记录 |
|
||
| Projman | 应用 `svc-hall` 的前端目标 **`hall`** → `/svc-hall/hall/` | 前端目标 `front` → `/svc-hall/front/` |
|
||
| 开发端口 | **8089** | 8087 |
|
||
|
||
> 用户面为什么单独一个前端：管理端走平台后台布局（模块菜单 + 表格 CRUD），用户面要的是
|
||
> "大厅 + 表单 + 进度"的对外观感与更低的使用门槛；混在一个 SPA 里会让门户访客落进后台壳子
|
||
> （菜单/权限模型也完全不同）。参见《办事大厅独立应用与对接方案V2.0.md》。
|
||
|
||
## 本地启动
|
||
|
||
```bash
|
||
npm install
|
||
npm run dev # http://localhost:8089
|
||
```
|
||
|
||
`dev` 模式 `serviceHost` 留空，接口走同源相对路径 `/api/...`，由 vite proxy 转发到本地后端
|
||
`http://localhost:8086`（后端 CAS 过滤器对 `/api/*` 不回 CORS 头，浏览器直连会被拦，必须同源代理）。
|
||
|
||
本项目**不直连流程中心**：撤回 / 审批进度 / 流程图都由办事大厅后端中转（后端用平台 SDK
|
||
`YschFlowOpenApi` 出站），所以本地只需起 svc-hall 后端 + 流程中心后端（8085），
|
||
不需要为 flow-center 前端配 CORS。
|
||
|
||
## 脚本
|
||
|
||
| 命令 | 说明 |
|
||
| --- | --- |
|
||
| `npm run dev` | 本地联调（读 `.env.dev`：`VITE_SITE_CODE` 指定站点、`VITE_THEME` 指定皮肤） |
|
||
| `npm run dev:mock` | 纯前端模式（`.env.mock`） |
|
||
| `npm run build` | 构建产物直出 `dist/`（CI 打 zip 要求 zip 根直接有 `index.html`） |
|
||
|
||
## 运行期配置（`window.__APP_CONFIG__`）
|
||
|
||
优先级见 `src/assets/config/host.config.ts`：线上由 `index.html` 引导脚本同步拉
|
||
`/{contextPath}/api/env-config?target=hall`（projman 配置管理维护 `env-config-hall.json`）；
|
||
本地走 `.env.dev` 的 `VITE_*`。
|
||
|
||
用户面特有的两个键：
|
||
|
||
| 键 | 作用 | 缺省行为 |
|
||
| --- | --- | --- |
|
||
| `siteCode` | 本部署对应的 CMS 站点标识（大厅/发起页定位用） | 退回 URL query 与 localStorage，再没有则页面提示"未配置站点" |
|
||
| `theme` / `themeParams` | 皮肤包名与颜色覆盖 | `default`；未注册的皮肤名**整页回退** default |
|
||
|
||
## 页面与路由（`src/router/routes.ts`，hash 路由）
|
||
|
||
| 路径 | 页面 | 说明 |
|
||
| --- | --- | --- |
|
||
| `/hall` | 事项大厅 | 已发布事项卡片列表 + 关键词/服务对象/分类/部门筛选（`/api/hall/*`） |
|
||
| `/apply` | 在线办理 | `?siteCode=&itemCode=`（与 CMS 指南页按钮同一深链形态） |
|
||
| `/my` | 我的办件 | 镜像状态列表 + 撤回 / 重试 / 重提 |
|
||
| `/apply-detail` | 办件详情 | `?id=`，快照回显 + 审批轨迹时间线 + 流程图 + 撤回/重提 |
|
||
| `/` | → `/hall` | 入口默认页 |
|
||
| 其他 | → `/hall` | 外部深链兜底，避免 no-match 白屏 |
|
||
|
||
## 皮肤包（`src/themes/`，参照 CMS 皮肤包方向）
|
||
|
||
SPA 版的皮肤机制，复刻 CMS《10-皮肤包契约.md》里**可移植的四条纪律**（模板绑定体不可移植，
|
||
见《CMS事项库与办事大厅方案V1.1.md》§3.1）：
|
||
|
||
1. **包 = 目录 + 清单**：`src/themes/{name}/theme.json` + `theme.css`，`name` 必须等于目录名；
|
||
新增皮肤 = 新增目录，宿主零改动（Vite `import.meta.glob` 构建期收集）。
|
||
2. **能力声明式**：`params[]` 声明能调什么（`color` 可带 `cssVar`；`select`/`text` 落 `data-sh-*` 钩子）；
|
||
运行时覆盖值按声明过滤（颜色查格式、select 查选项），非法值丢默然回落默认。
|
||
3. **令牌单一出口**：主题色只走 `var(--sh-*)`（底座在 `src/assets/styles/theme-base.css`），
|
||
换皮只改变量；列表布局这类结构变体由皮肤 CSS 命中 `data-sh-*`，宿主不判断皮肤名。
|
||
4. **默认包强制 + 整页回退**：`default` 缺失直接抛错；未注册的名字回退 `default`，
|
||
绝不出现"自己的 HTML 配别人的 CSS"。
|
||
|
||
内置两套：`default`（校园蓝）、`campus-green`（校园青绿，附带 `listLayout` 布局变体开关）。
|
||
坏包（`specVersion`/命名/参数不合规）整包丢弃并告警，不做部分加载。
|
||
|
||
## 构建与发布
|
||
|
||
push 到 `main` → gitea CI（`.gitea/workflows/build.yml`）：`npm run build` → 打包
|
||
`svc-hall-hall-<sha8>.zip` → 推 Nexus raw → 通知 projman 建档（`app=svc-hall, front=hall`）。
|
||
线上部署由运维/管理员在 projman「前端发布」手动触发，push 不会自动上线。
|
||
|
||
**首次上线前**需在 projman 应用 `svc-hall` 下新增前端目标 `hall`（路径片段 `hall`），
|
||
并在配置管理里补 `env-config-hall.json`（`siteCode`、`theme`、`baseHost`、`ssoHost`），
|
||
再把 CMS 站点的 `svc_hall_base` 指向新前端（`https://<域名>/svc-hall/hall`）。详见
|
||
`../docs/用户面(hall)上线与projman接入说明.md`。
|
||
|
||
## 契约纪律
|
||
|
||
- 前端**不得**直接调用流程中心（无 `flowHost`、无外部 `/api/flow/**`）：撤回/进度/流程图一律走
|
||
本应用后端 `/api/apply/{id}/withdraw|progress|diagram.png`。票据、CORS、授权点都在后端一侧。
|
||
- 提交响应必须按 `flowEnabled` + `flowStatus` 分流（`src/views/Apply.vue` 有详细注释）：
|
||
代发起是异步的，"提交成功那一刻 flowStatus 恒为 0"，不能当成失败。
|
||
- 表单 schema 契约同后台前端（后端 `FormValidator` 强校验：属性白名单、`key` 命名、`maxSize` 单位 MB）。
|