feat: 办事大厅用户面前端（hall）首版入库——由 app/public 改名去 app 层；build.yml 修并发撞名容exit137

README.md

@@ -1,3 +1,100 @@
-# svc-hall-hall
+# 公共办事大厅前端（svc-hall-hall）
 
-managed by projman
+云海平台「办事大厅」的**用户面**前端：给学生 / 教师 / 访客提供**在线办理**入口——
+事项大厅 → 在线办理（填表提交）→ 我的办件 → 办件详情（审批进度、流程图、撤回/重提）。
+
+它是**独立前端项目**，与 `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/公共端上线与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）。