# 前端二次开发手册

> 本文面向需要自定义UI的企业开发者  
> **仅涉及前端表层**，不包含任务调度规则、工时阈值等内核逻辑

---

## 页面结构

```
frontend/
├── index.html     主页面（仪表盘）
├── app_v2.js      核心JS逻辑 + 页面渲染
├── app.js         兼容副本
└── *.css          样式文件
```

### 主要页面（通过CSS class切换）

| 页面 | class | 说明 |
|------|-------|------|
| 仪表盘 | `page-dashboard` | Agent状态、任务概览 |
| 任务面板 | `page-tasks` | 任务看板、时序流水 |
| 督查台账 | `page-inspector` | 督查巡检结果 |
| 系统监控 | `page-monitor` | 端口/服务健康状态 |
| 技能库 | `page-skills` | 公开技能模板列表 |

---

## 自定义品牌

### 更换Logo
1. 准备PNG/SVG格式Logo文件
2. 放入 `assets/` 目录
3. 在 `frontend/index.html` 中修改Logo引用路径

### 修改标题
在 `frontend/index.html` 中搜索 "城丰星际" 替换为自定义名称

### 自定义配色
在 `frontend/app_v2.js` 中搜索CSS变量区域，修改颜色值

---

## 自定义图表

### 任务看板
看板数据来自 `/api/tasks/board` API（只读），前端仅做渲染。  
可自定义看板布局、卡片样式、筛选条件。

### 时序大盘
时序数据来自 `/api/tasks/{id}/timeline` API。  
可自定义时间轴样式、筛选条件、导出格式。

---

## 导出报表模板

### Excel导出
使用 SheetJS CDN 导出任务数据为 Excel：
```html
<script src="https://cdn.sheetjs.com/xlsx-0.20.0/package/dist/xlsx.full.min.js"></script>
<script>
async function exportTasks() {
  const board = await fetch('/api/tasks/board').then(r => r.json());
  const rows = [];
  for (const col of Object.values(board.columns || {})) {
    for (const t of col.tasks || []) {
      rows.push({ 任务ID: t.task_id, 类型: t.task_type, 状态: t.status, 负责人: t.assigned_to, 工时: t.effective_hours });
    }
  }
  const ws = XLSX.utils.json_to_sheet(rows);
  const wb = XLSX.utils.book_new();
  XLSX.utils.book_append_sheet(wb, ws, '任务列表');
  XLSX.writeFile(wb, 'tasks_export.xlsx');
}
</script>
```

### PDF导出
使用浏览器 `window.print()` 或 jsPDF 库导出当前页面

---

## 技能模板自定义

在 `skills/` 目录下创建 `.md` 文件：
```markdown
name: my-custom-skill
description: 自定义任务处理模板
tags: [custom, export]

## 提示词
请根据以下要求处理导出任务...
```

标签系统支持自定义分类，前端会自动扫描 `skills/` 目录。

---

## 重要约束

- 前端**不可直连数据库**，所有数据通过 `/api/` 获取
- 写操作需 `X-Core-Key` 密钥（前端无内置密钥）
- 前端修改不改变底层调度规则（内核硬编码管控）
- `role` 字段由内核校验，前端传值无效