docs: initialize harness coding docs

docs/routes.md

@@ -0,0 +1,86 @@
+# 路由与页面结构
+
+> 本文约定原生前端页面路由、页面职责和组件归属。
+
+## 页面路由
+
+MVP 不使用前端路由框架。Gin 对以下路径都返回同一个 `web/index.html`，页面 JS 根据 `location.pathname` 渲染对应视图。
+
+| 路由 | 页面 | MVP 说明 |
+| --- | --- | --- |
+| `/` | 仪表盘 | 展示站点概览、同步状态和快速入口 |
+| `/sites` | 站点配置 | 管理站点 app_key / app_secret |
+| `/departments` | 部门浏览 | 站点切换、部门树、部门成员 |
+| `/users` | 人员搜索 | 搜索筛选、分页表格、导出 |
+| `/logs` | 同步日志 | 查看同步记录和错误信息 |
+
+## 页面职责
+
+### 仪表盘
+
+- 展示每个站点的部门数、人员数、最后同步时间和状态。
+- 提供同步按钮。
+- 提供进入部门浏览、人员搜索、站点配置的入口。
+
+### 站点配置
+
+- 展示站点列表。
+- 新增、编辑、删除站点。
+- app_secret 输入后保存，但列表不明文展示。
+
+### 部门浏览
+
+- 左侧展示部门树。
+- 右侧展示当前部门下人员。
+- 支持站点切换。
+- 空部门、加载失败、未同步状态需要有明确提示。
+
+### 人员搜索
+
+- 支持站点切换。
+- 支持关键词、部门、状态筛选。
+- 支持分页。
+- 支持导出当前筛选结果。
+
+### 同步日志
+
+- 按站点和状态筛选日志。
+- 展示开始时间、结束时间、类型、状态、错误信息。
+
+## 前端文件建议
+
+```text
+web/
+├── index.html
+└── assets/
+    ├── style.css
+    ├── app.js
+    ├── api.js
+    ├── state.js
+    ├── dashboard.js
+    ├── sites.js
+    ├── departments.js
+    ├── users.js
+    └── logs.js
+```
+
+## 组件建议
+
+这里的组件是 JS 函数或小模块，不是框架组件。
+
+| 模块 | 归属 | 说明 |
+| --- | --- | --- |
+| `renderShell` | 全局 | 页面框架、导航、站点选择入口 |
+| `apiFetch` | 全局 | 封装 fetch、JSON 解析和错误展示 |
+| `renderDashboard` | 仪表盘 | 渲染站点统计和同步按钮 |
+| `renderSiteForm` | 站点配置 | 新增 / 编辑站点 |
+| `renderDeptTree` | 部门浏览 | 将平铺部门列表组装为树 |
+| `renderUserTable` | 部门 / 人员页 | 渲染分页人员表格 |
+| `renderLogs` | 同步日志 | 渲染日志列表 |
+
+## 导航规则
+
+- 顶部导航固定展示：仪表盘、站点配置、部门浏览、人员搜索、同步日志。
+- 站点选择应尽量保留在 URL 查询参数中，例如 `?site_id=1`。
+- 人员页筛选条件应保留在 URL 查询参数中，方便刷新后恢复。
+- API 失败时在页面内展示错误，不静默失败。