公共办事大厅前端（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》。

本地启动

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/公共端上线与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）。