# ticket

**Repository Path**: sh_huahui/ticket

## Basic Information

- **Project Name**: ticket
- **Description**: No description available
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: develop
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-04
- **Last Updated**: 2026-09-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ServiceHub 工单系统

面向集团多业务系统的 IT 服务台与运维管理系统。以“业务系统 → 工单服务”为入口，让普通用户提报问题、查询处理进度和知识，让运维人员按负责系统受理、处理和协作，让管理员集中维护系统、服务目录、人员权限及服务配置。

当前使用**本地账号密码登录**，无需先接入 IAM。已有 IAM/OIDC 能力保留为可选适配；零信任、外部客户端身份对接不属于本批交付。

> 本项目仍在功能完善阶段，不是整本 ITSupport 操作手册的一比一复刻。自定义 BPMN 与多表单设计目前为 `DRAFT_ONLY`：可以设计、保存草稿，但不能作为任意自定义流程发布执行；实际工单运行使用已有受控生命周期。

## 功能概览

| 模块 | 当前能力 |
| --- | --- |
| 账号与权限 | 账号密码登录/退出、账号管理、角色与负责系统配置、服务端对象权限校验 |
| 工作台 | 我的待办、逾期待办、当日需完成、我的已办、我的创建、我的待阅，以及系统服务入口、公告和知识入口 |
| 系统与服务配置 | 系统/模块/工单服务管理，查询、表格、操作列、新增编辑；从系统与服务进入表单和流程配置 |
| 工单发起 | 选择系统与服务、动态表单、富文本、附件、流程预览、个人草稿暂存与恢复 |
| 受理与处理 | 分派/共享队列抢单、受理、处理信息持久化、转办、协办、提交验证、未解决返回、确认解决和关闭 |
| 我的流程 | 分类队列、筛选/重置、个人列设置、分页、按筛选导出 CSV |
| 知识管理 | 仓库检索、个人收藏、知识草稿创建/版本编辑、提交审核、审核发布、正文/来源/历史、工单处理引用 |
| 运营与治理 | 已有 SLA、审批策略、通知、审计、报表和运行治理能力 |

几个重要规则：

- 运维人员的操作权限取决于账号角色、负责系统及当前流程关系，不只是前端是否显示按钮。
- 共享抢单场景在领取前展示实际候选人，领取后只展示实际主办人；自动分派场景直接展示被分派人员，不虚构候选名单。
- “当日需完成”是今天到期的未完成待办，不是“今天已完成”。业务日默认按 `Asia/Shanghai` 计算。
- 工单草稿按账号隔离，暂存不创建正式流程；草稿附件需要重新选择。版本冲突时保留输入，支持另存新草稿。
- 处理表单的“保存”只保存信息，不推进流程。匹配已发布审批策略的动作仍需审批；已有待审批请求不会因策略退役而被绕过。

## 技术栈

| 层次 | 技术 |
| --- | --- |
| 前端 | Vue 3、TypeScript、Vite、Element Plus、Pinia、Vue Router |
| 编辑与流程展示 | Tiptap 富文本、bpmn-js |
| 后端 | Java 21、Spring Boot 3.5.5、Spring Security，模块化单体结构 |
| 流程引擎 | Flowable 7.2.0 |
| 数据库 | MySQL 8、Flyway；无 MySQL 的开发预览使用 H2 与内存业务仓储 |
| 部署 | Docker / Compose、Nginx、外部 MySQL；正式环境使用 HTTPS 与附件扫描服务 |

精确依赖版本以 [后端依赖](backend/pom.xml)、[前端依赖](frontend/package.json) 和锁文件为准。

日常巡检、账号/系统管理、工单与知识操作、故障处理和发布交接见[运维手册](运维手册.md)。外部操作手册和项目资料统一通过[附件引用清单](附件引用清单.md)管理，原始 Word 手册及截图不复制进仓库。

## 仓库结构

```text
backend/                 Spring Boot 后端、流程定义、数据库迁移及测试
frontend/                Vue 管理端与服务门户、组件及前端测试
contracts/openapi/       OpenAPI 接口契约
docs/                    需求、架构、功能设计及验收记录
devops/                  容器部署、数据库基线、备份恢复与 CI 脚本
prototype/               历史页面原型，非当前运行入口
离线部署手册.md          离线验收与正式部署说明
运维手册.md              日常运维、业务管理、故障排查和发布交接
附件引用清单.md          附件稳定编号、入口及版本维护
```

## 本地启动

### 环境准备

- JDK 21、Maven 3.9。
- Node.js 24 与 npm。
- 持久化验收需要 MySQL 8；无数据库时可先使用下面的内存预览模式。
- 首次安装依赖需要网络，或提前准备 Maven/npm 缓存；无网络部署请直接使用[离线部署手册](离线部署手册.md)。

### 方式一：快速预览（不保存重启后的数据）

从仓库根目录打开两个 PowerShell 终端。

终端一启动后端：

```powershell
cd backend
$env:SPRING_PROFILES_ACTIVE = "local-dev"
$env:SERVICEHUB_LOCAL_AUTH_ENABLED = "true"
$env:SERVER_ADDRESS = "127.0.0.1"
$env:SERVER_PORT = "8080"
mvn spring-boot:run
```

终端二启动前端：

```powershell
cd frontend
npm ci --ignore-scripts
npm run dev
```

浏览器访问 **[http://127.0.0.1:1525](http://127.0.0.1:1525)**。

此模式使用 H2 和内存业务仓储，不执行 MySQL Flyway 迁移，重启后业务记录不保留。它用于快速预览和开发，不替代 MySQL 下的完整功能、持久化和并发验收。`local-dev` 还使用仅开发环境的附件扫描适配，禁止对外提供正式服务。

### 本地测试账号

以下账号仅在启用 `local-dev` 和本地认证时由开发初始化器创建：

| 账号 | 用途 |
| --- | --- |
| `requester` | 普通用户：发起工单、查看本人事项、使用知识库 |
| `ops01` ～ `ops05` | 运维人员：按已配置系统范围受理与处理 |
| `admin` | 平台管理员：系统、服务、账号与后台配置 |

开发默认密码为 `LocalDev-Only!2026`，可通过 `SERVICEHUB_LOCAL_AUTH_LOCAL_DEV_PASSWORD` 配置开发初始化密码。已有账号的密码变更应通过账号管理完成，不能把修改环境变量当成密码重置操作。

开发夹具会为运维账号分配初始化时的系统范围；正式人员负责范围须由管理员明确配置。**正式环境没有上述默认密码，不得启用 `local-dev` 或复用开发账号。**

### 方式二：MySQL 持久化验收

建议实际功能验收使用此模式。

1. 按[离线部署手册](离线部署手册.md)准备数据库及 Flowable 结构。新库初始化与已有库升级是两种不同流程，不要混用。
2. 使用 [backend/.env.example](backend/.env.example) 了解配置项，把真实值注入启动后端的进程环境。
3. 在后端启动终端设置以下变量，再运行 `mvn spring-boot:run`：

```powershell
$env:SPRING_PROFILES_ACTIVE = "mysql,local-dev"
$env:SERVICEHUB_LOCAL_AUTH_ENABLED = "true"
$env:SERVER_ADDRESS = "127.0.0.1"
$env:SERVER_PORT = "8080"
$env:SERVICEHUB_DB_URL = "jdbc:mysql://127.0.0.1:3306/servicehub?useUnicode=true&characterEncoding=utf8&connectionTimeZone=UTC"
$env:SERVICEHUB_DB_USERNAME = "servicehub_app"

# 使用临时凭据输入，避免把真实密码写进脚本或命令历史。
$serviceHubDbCredential = Get-Credential -UserName $env:SERVICEHUB_DB_USERNAME -Message "输入本地 ServiceHub 数据库凭据"
$env:SERVICEHUB_DB_PASSWORD = $serviceHubDbCredential.GetNetworkCredential().Password
mvn spring-boot:run
```

以上命令应在 `backend` 目录执行；前端启动与方式一相同。若数据库使用独立迁移账号，还需注入 `SERVICEHUB_FLYWAY_DB_URL`、`SERVICEHUB_FLYWAY_DB_USERNAME`、`SERVICEHUB_FLYWAY_DB_PASSWORD`。

注意：Spring Boot 不会因为目录里存在 `.env.local` 就自动加载它；必须通过启动脚本、终端或部署系统注入变量。示例中的占位密码不可直接使用，真实配置不得提交 Git。普通内存预览或已有 `local-dev` 验收不需要照搬 `.env.example` 中的生产管理员引导变量。

### 端口与代理

| 入口 | 仓库默认值 |
| --- | --- |
| 前端开发服务 | `127.0.0.1:1525` |
| 后端开发服务 | `127.0.0.1:8080` |
| 前端 API 代理 | `/api` → `http://127.0.0.1:8080` |
| 业务接口前缀 | `/api/v1` |

代理配置在 [frontend/vite.config.ts](frontend/vite.config.ts)。如果后端换成 `18080` 等端口，必须同时调整代理目标或使用配套的本地 Vite 配置，不能只改后端端口。前端端口被占用时会明确启动失败，不会自动换端口。

## 推荐验收顺序

1. 使用管理员登录，在“服务配置”中建立系统、模块及对应工单服务，配置并发布可使用的服务。
2. 在账号管理中给运维人员配置角色和负责系统。
3. 使用普通用户登录，从工作台选择系统与工单服务，填写表单；先暂存、从草稿箱恢复，再正式发起。
4. 使用有权运维账号登录，按目录配置领取或受理；确认主办人显示、保存处理说明并刷新核对。
5. 提交用户验证；申请人确认已解决，或选择未解决退回处理；最后完成关闭。
6. 创建知识草稿，编辑新版本并提交审核；管理员审核发布后，普通用户查询正文、收藏知识。

不同目录的自动分派、共享队列与审批配置会影响具体步骤，不应为了复现按钮而直接修改数据库中的工单状态。

## 数据库与离线部署

**v0.1.0 数据库目标迁移版本：V58。** 审计 UPDATE/DELETE 保护采用独立 DBA 加固步骤，不通过给应用账号增加超级权限安装。

| 迁移 | 内容 |
| --- | --- |
| V46 | 本地账号认证 |
| V47 | 个人工单草稿 |
| V48 | 工单处理明细及旧版默认受理/解决/关闭审批兜底策略退役 |
| V49 | 知识收藏及草稿状态 |
| V50 | 同一工单、动作、来源版本的活动审批唯一约束 |
| V51 | 本地账号首次、重置及周期改密状态 |
| V53 | SLA 不可变策略修订、历史运行快照及扫描进度 |
| V54 | 管理员并发保底锁、通用持久命令幂等台账 |
| V55 | 日报待刷新分区/原子刷新证据、附件写入与清理补偿台账 |
| V56 | 服务目录公开／用户／组织提单授权及发布快照 |
| V57 | 补齐已发布管理目录的基础引用记录 |
| V58 | 兼容受理审批冻结后续处理人，保留其他动作目标约束 |

- 新库：采用 V34 业务结构基线与 Flowable 7.2.0 结构，按手册完成一次性基线登记，再前向迁移到 V58。
- 已有库：先备份并在隔离恢复库演练，再执行尚未应用的前向迁移；不要重新导入基线。
- V50 升级前检查重复活动审批。若查到重复，不得删审计或修改迁移历史来强行跳过。
- 已执行迁移不要修改、删除或重命名；后续数据库变更新增迁移文件。
- V53–V55 需停写维护窗，禁止旧应用混合写新表语义；核对历史 SLA 治理态和持久 HMAC 密钥环。详见[整改接口与部署兼容说明](docs/36-整改接口与部署兼容说明.md)。自定义 BPMN 运行平台仍不能因本轮修复而视为已交付。
- 正式环境使用一次性管理员引导配置，成功创建后移除引导密码；身份接入、HTTPS、附件扫描及备份按部署手册配置。

完整步骤、镜像制作、离线验收、数据库准备、备份与恢复见 **[离线部署手册](离线部署手册.md)**。数据库基线文件见 [devops/database-baseline](devops/database-baseline/)。

## pigx 联调测试用户

以下账号仅用于本机隔离联调环境，在 **pigx 统一认证页**输入账号和密码：

- [工单统一登录入口](http://localhost:11525/oauth2/authorization/pigx)
- [工单联调首页](http://localhost:11525) · [pigx 测试系统](http://localhost:18888)

| 测试账号 | 工单角色 | 用途 | 工单 IAM 用户 ID |
| --- | --- | --- | --- |
| `flow_admin` | 平台管理员 | 配置服务目录、系统、审批策略及外部人员授权 | `pigx:pigx:1:910001` |
| `flow_requester` | 普通提单人 | 发起工单、确认解决、申请关闭 | `pigx:pigx:1:910002` |
| `flow_handler` | 一线支持 | 抢单、申请受理、处理并提交用户验证 | `pigx:pigx:1:910003` |
| `flow_manager_a` | 服务经理／审批人 A | 批准受理、解决会签第一票、关闭审批 | `pigx:pigx:1:910004` |
| `flow_manager_b` | 服务经理／审批人 B | 解决会签第二票、关闭及并发审批验证 | `pigx:pigx:1:910005` |
| `flow_outsider` | 范围外普通用户 | 验证公开服务、用户／组织授权及越权拒绝 | `pigx:pigx:1:910006` |
| `catalog_reviewer` | 平台管理员 | 公开服务目录的第二人发布复核 | `pigx:pigx:1:910007` |
| `admin` | 普通提单人（工单侧） | 最初的显式绑定联调账号；在 pigx 是管理员，不自动取得工单管理员权限 | `iam-pigx-lab-1` |

**测试密码位置：** `flow_*` 账号及 `catalog_reviewer` 共用本次独立测试密码，见本机忽略文件 [approval-manual-access.local](tmp/approval-manual-access.local)；`admin` 的测试密码见 [pigx-lab-access.local](tmp/pigx-lab-access.local)。这些凭据文件不随 Git 分发，其他机器需要重新准备测试环境。

除 `flow_outsider` 主组织为 `pigx:pigx:1:dept:2` 外，其余 `flow_*` 账号及 `catalog_reviewer` 主组织为 `pigx:pigx:1:dept:1`。后台角色和范围是本机测试配置，普通 pigx 用户首次登录仍只获得提单身份。

**推荐测试顺序：** `flow_requester` 提单 → `flow_handler` 抢单并申请受理 → `flow_manager_a` 同意 → 主办人提交验证、提单人申请解决 → A、B 分别会签 → 提单人申请关闭、经理同意。选择“多环节审批测试系统 → 多环节审批测试服务”。

不同账号使用独立浏览器配置文件或不同浏览器；普通多标签页会共享登录会话。已关闭参考单 `TKT-20260907-000007`、`TKT-20260907-000008` 可查看记录，练习时请新建工单。

详细步骤见 [多审批节点测试手册](docs/42-多审批节点测试操作手册.md) 和 [公开提单与协同人员配置手册](docs/43-公开提单与协同人员配置操作手册.md)。

## 测试与构建

在仓库根目录分别执行：

```powershell
cd backend
mvn -B test
mvn -B -DskipTests package
```

```powershell
cd frontend
npm ci --ignore-scripts
npm test
npm run build
```

后端构建产物位于 `backend/target/`，前端位于 `frontend/dist/`。生产不使用 Vite 开发服务器，具体容器构建步骤见部署手册。

截至 2026-09-05，功能提交 `92a7a8a` 的本地验证记录为：后端 44 个测试套件、156 项通过；前端 51 项通过；生产构建通过；真实 MySQL 前向迁移至 V50，并完成工单闭环与知识工作区验收。此记录不是后续提交或生产环境的自动验收证明。

GitHub 的 `production-readiness` 工作流依赖带 `servicehub-secure` 标签的自托管运行器、镜像摘要配置及安全扫描工具；等待运行器或尚未执行的 CI 不代表检查通过。

本批安全整改新增密码更新入口及强制改密会话限制；生产默认密码周期 90 天、无 HTTP 请求会话超时 15 分钟，数值为项目基线而非等保统一要求。整改验证、证据和未关闭项见[等保二级控制与证据说明](等保二级控制与证据说明.md)，不能把本地测试或 npm 零已知漏洞当作已经通过等保测评。

继续整改已补齐知识/附件数据库变更与审计的事务一致性、未知提交时的保守文件补偿、受控跨实例两阶段恢复及退出结果判断。最新本地验证为后端167项、前端57项和构建通过；记录见[证据登记](docs/evidence/mlps2/README.md)。

需要重新生成执行证据时，在仓库根目录的**独立干净 PowerShell 终端**运行（不携带 `SERVICEHUB_*`、`SPRING_*` 或 Java/Maven 参数注入环境变量）：

```powershell
& ./devops/ci/run-mlps-local-verification.ps1 -Targets Backend,Frontend
```

执行器会实际运行测试/构建，拒绝旧报告、运行中源码变化及原始日志与共享证据混放；不是生产扫描或部署程序。

## 当前边界

- 自定义 BPMN / 多表单设计仍为草稿能力，实际执行使用已有受控工单生命周期。
- 暂未实现代他人提单、事件转问题后的自动挂起/恢复、任意跨节点退回、真正传阅和满意度评价。
- “我的待阅”当前表示未读工单消息；列表导出为最多 5000 条 CSV，不是 Excel 或后台异步导出。
- 知识暂未实现驳回/撤回、作废审批、专题、分享、纠错和积分排行；也未覆盖参考手册的全部报表口径。
- 零信任、企业移动客户端及外部客户端模式接入后续单独设计。

更详细的完成项、差异和验收记录见[功能与页面对齐清单](docs/17-ITSupport操作手册功能与页面对齐.md)。

## 文档导航

| 文档 | 内容 |
| --- | --- |
| [需求规格说明书](docs/01-需求规格说明书.md) | 业务需求基线 |
| [总体架构与技术规格](docs/03-总体架构与技术规格说明书.md) | 系统架构与技术边界 |
| [BPMN 与多表单设计方案](docs/13-BPMN与多表单设计平台方案.md) | 设计器、表单及流程方案 |
| [系统服务目录与首页门户](docs/14-系统服务目录与首页门户设计.md) | 系统优先的服务入口 |
| [系统配置入口整合](docs/15-系统配置入口整合设计.md) | 管理配置路径 |
| [本地账号、抢单与后台重构](docs/16-本地账号抢单候选与管理后台重构设计.md) | 本地身份、系统权限与管理表格 |
| [功能与页面对齐清单](docs/17-ITSupport操作手册功能与页面对齐.md) | 本批实现、未实现差异与验收记录 |
| [知识草稿编辑设计](docs/18-知识草稿编辑设计.md) | 草稿编辑、版本和冲突规则 |
| [OpenAPI 接口契约](contracts/openapi/servicehub-v1.yaml) | 接口路径、请求及响应模型 |
| [离线部署手册](离线部署手册.md) | 离线制品、部署、数据库与备份恢复 |
| [运维手册](运维手册.md) | 巡检、业务管理、排障、升级回退与交接 |
| [附件引用清单](附件引用清单.md) | 原手册及项目资料引用，附件更新统一维护 |
| [全站业务优先设计规范](docs/20-全站业务优先与辅助信息设计规范.md) | 业务信息、风险提示、帮助与次要详情的统一呈现规则 |
| [等保二级控制与证据说明](等保二级控制与证据说明.md) | 应用整改、真实验证、证据索引和生产补证 |

早期文档保留项目演进记录；涉及本地账号与本批功能时，以当前实现及文档 16–18 的明确交付边界为准。后续开发继续遵循“先补需求与设计文档，再开发和验收”的顺序。