校园服务台助手技能 是做什么的？
本技能定义了开发、增强和维护 Campus Helpdesk Web 应用程序的技术标准、工作流和最佳实践。在添加功能、重构组件、更新状态工作流或修改该项目中的数据模型时，请使用本指南。
1. 编写简洁、可复用的 React 组件
保持模块化、解耦的组件架构：
- 单一职责原则：每个组件应专注于做好一件事。
- 表单逻辑和输入字段属于
IssueForm.jsx。 - 公共搜索、筛选和工单卡片显示属于
TicketList.jsx。 - 分析指标、可视化进度条和管理表格属于
AdminDashboard.jsx。 - 模态框检查和历史时间线属于
TicketModal.jsx。 - 通知属于
Toast.jsx。
- 表单逻辑和输入字段属于
- Props 与 State 设计：
- 尽可能保持 state 局部化。仅在跨不同视图（例如全局
tickets、activeTab、toasts）共享时，才将 state 提升到App.jsx。 - 尽可能使用纯展示型子组件，并清晰地向下传递回调函数（如
onSelectTicket、onUpdateStatus、onDeleteTicket）。 - 避免重复的 state；使用
useMemo计算派生值（例如筛选后的工单、KPI 统计）。
- 尽可能保持 state 局部化。仅在跨不同视图（例如全局
- 命名规范与整洁代码：
- 组件文件使用 PascalCase（
AdminDashboard.jsx、IssueForm.jsx）。 - 工具和常量文件使用 camelCase（
storage.js、constants.js）。 - 事件处理程序应遵循
handle[Action]模式（例如handleSubmit、handleStatusChange）。 - 保留注释和文档字符串。编写自解释的代码，使用清晰描述性的变量名称。
- 组件文件使用 PascalCase（
- 零重量级外部依赖：
- 保持轻量级架构：使用原生 React 钩子、纯内联 SVG 作为图标，以及作用域 CSS 类，避免引入庞大的第三方组件库。
2. 创建响应式且可访问的 UI
Campus Helpdesk 门户必须在所有设备（手机、平板、笔记本电脑、大显示器）上提供无摩擦的用户体验：
- 流畅布局与断点：
- 采用移动优先或桌面向下设计，使用一致的断点：
- 桌面端：最大容器宽度
1240px，多列网格（5 个指标卡片、2 列分析、2 列表单）。 - 平板端（
<= 1024px）：将 5 列指标网格折叠为 3 或 2 列；将分析图表堆叠为单列。 - 移动端（
<= 768px）：将头部导航、表单输入堆叠为 1 列；在数据表上启用水平滚动。 - 小屏幕（
<= 480px）：全宽指标卡片，堆叠操作按钮，并固定底部 Toast 通知。
- 桌面端：最大容器宽度
- 采用移动优先或桌面向下设计，使用一致的断点：
- 可访问性（a11y）：
- 所有交互元素必须使用适当的语义化 HTML（
<button>、<input>、<select>、<textarea>）。 - 表单控件必须有关联的
<label htmlFor="...">元素，并匹配id属性。 - 模态对话框必须有
role="dialog"、aria-modal="true"，并支持通过点击背景和按 Escape 键关闭。 - 交互式图标或纯图标按钮必须包含描述性的
aria-label或title属性。 - 保持状态徽章和优先级标签上文本的可访问颜色对比度。
- 所有交互元素必须使用适当的语义化 HTML（
- 视觉反馈与过渡：
- 交互元素必须显示清晰的
:hover、:focus和:active状态。 - 聚焦的表单字段必须显示高对比度的聚焦环（
var(--primary-ring)）。 - 使用微动画（Toast 滑入、模态框放大、按钮旋转器）向用户反馈后台操作，同时避免布局偏移。
- 交互元素必须显示清晰的
3. 验证学生问题表单
所有通过 IssueForm.jsx 提交的问题都必须遵循严格的客户端验证规则，然后才能进行状态变更或存储：
验证规则矩阵
| 字段 | 规则 | 错误消息 |
|---|---|---|
| 全名 | 必填，去除首尾空格，非空 | “请提供您的全名。” |
| 校园邮箱 | 必填，有效正则模式 /^[^\s@]+@[^\s@]+\.[^\s@]+$/ | “请输入有效的电子邮件地址。” |
| 位置/房间 | 必填，去除首尾空格，非空 | “请指定建筑、大厅或校园位置。” |
| 类别 | 必填，必须匹配 CATEGORIES 列表 | 默认自动选择 |
| 优先级 | 必填，必须匹配 PRIORITIES（低、中、高、紧急） | 默认为 '中' |
| 问题主题/标题 | 必填，去除首尾空格，最小长度 $\ge 5$ 个字符 | “标题至少需要 5 个字符。” |
| 详细描述 | 必填，去除首尾空格，最小长度 $\ge 15$ 个字符 | “描述至少需要 15 个字符。” |
验证实现步骤
- 维护一个
errors状态对象，将字段名称映射到错误字符串。 - 当用户修改其输入时（
handleChange），清除该特定字段的错误。 - 在
handleSubmit时检查所有规则。如果存在错误，阻止提交并使用.input-error和.field-error高亮无效字段。 - 成功时：
- 生成唯一 ID（例如
TCK-XXXX）。 - 分配初始状态
待处理。 - 记录初始提交时间戳和历史节点。
- 重置表单字段和错误状态。
- 触发成功 Toast 并导航到工单跟踪器视图。
- 生成唯一 ID（例如
4. 管理待处理、进行中和已解决状态
Campus Helpdesk 遵循严格定义的 3 阶段生命周期：
[ 待处理 ] ───► [ 进行中 ] ───► [ 已解决 ]
▲ ▲ │
└──────────────────────┴─────────────────────┘ （可按需重新打开）
状态定义与视觉设计系统
待处理：- 含义：学生/教职员工提交的新问题，等待分诊或分配。
- 颜色主题：琥珀色（
#d97706），背景#fef3c7，边框#fde68a。 - 进度阶段：步骤 1 激活。
进行中：- 含义：技术人员或校园部门已认领工单，正在积极调查或维修。
- 颜色主题：皇家蓝（
#2563eb），背景#dbeafe，边框#bfdbfe。 - 进度阶段：步骤 1 和 2 激活。
已解决：- 含义：修复完成，设备已更换，或服务已恢复。
- 颜色主题：翡翠绿（
#059669），背景#d1fae5，边框#a7f3d0。 - 进度阶段：步骤 1、2 和 3 激活。
生命周期规则与审计历史
- 每个状态转换必须向工单的
history数组追加一条事件：{ status: newStatus, timestamp: new Date().toISOString(), note: `状态已更新为 ${newStatus}` } - 更新内部工作人员注释必须更新
adminNote和updatedAt，且不重置工单原始的createdAt。 - 更新必须立即同步到
localStorage（campus_helpdesk_tickets_v1）。
5. 保持仪表板统计准确
管理仪表板提供实时操作可见性。所有 KPI 指标和图表计算必须从数据源 tickets 数组动态派生：
指标计算
- 总工单数： $$\text{总数} = \text{tickets.length}$$
- 待处理计数： $$\text{待处理} = \text{tickets.filter}(t \Rightarrow t.\text{status} === \text{STATUSES.PENDING}).\text{length}$$
- 进行中计数： $$\text{进行中} = \text{tickets.filter}(t \Rightarrow t.\text{status} === \text{STATUSES.IN_PROGRESS}).\text{length}$$
- 已解决计数： $$\text{已解决} = \text{tickets.filter}(t \Rightarrow t.\text{status} === \text{STATUSES.RESOLVED}).\text{length}$$
- 解决率（%）： $$\text{解决率} = \begin{cases} \text{Math.round}\left(\frac{\text{已解决}}{\text{总数}} \times 100\right), & \text{如果总数} > 0 \ 0, & \text{否则} \end{cases}$$
- 高优先级与紧急优先级队列： $$\text{紧急/高} = \text{tickets.filter}(t \Rightarrow t.\text{priority} === '紧急' \lor t.\text{priority} === '高').\text{length}$$
- 类别与优先级分布：
- 即使计数为 0，也要计算所有预定义类别和优先级的计数，以防止 UI 闪烁或除零错误。
- 确保进度条宽度百分比总和始终 $\le 100%$。
将所有统计计算包装在 React 的 useMemo 钩子中，并将 [tickets] 作为依赖项，以保持性能。
6. 测试更改并运行构建
在提交任何代码更改或将任务标记为完成之前，通过静态分析和生产构建步骤验证应用程序：
验证协议
-
导航到项目目录：
cd "campus-helpdesk" -
运行静态代码检查：
npm run lint- 必须以退出码
0结束。 - 确保没有未使用的导入、变量或未转义的 JSX 实体。
- 必须以退出码
-
运行生产构建：
npm run build- 验证 Vite 完成生产资产捆绑，且无错误或警告。
- 验证
dist/index.html、dist/assets/*.css和dist/assets/*.js是否已成功创建。
-
验证 localStorage 持久化：
- 测试提交工单是否会更新
localStorage.getItem('campus_helpdesk_tickets_v1')。 - 测试更新工单状态是否在页面刷新后保留。
- 测试“重置示例数据”和“全部清除”功能。
- 测试提交工单是否会更新
7. 诚实报告错误
在报告系统状态或错误时，正直和诚实至关重要：
- 不要掩盖失败：如果发生构建错误、语法错误或 lint 失败，请报告确切的错误消息、文件名和行号。
- 根本原因解释：解释为什么发生错误（例如缺少导入、存储解析器中未处理的 null 情况、损坏的 prop 契约）。
- 仅已验证修复：在未重新运行验证命令（
npm run lint/npm run build）并确认退出码0的情况下，不要声称问题已修复。 - 用户透明度：如果发生意外浏览器限制或 localStorage 配额问题，请主动向用户解释限制，并提供清晰的技术选项。