# tsq_sfj

**Repository Path**: gekilyar/tsq_s

## Basic Information

- **Project Name**: tsq_sfj
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-30
- **Last Updated**: 2026-08-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 政策文件检索系统

一个**纯静态**的政策文件检索与预览系统（MVP）。零后端依赖、单目录部署、同源访问，可直接放入现有 Nginx 服务器的 `/var/www/policy/` 目录，通过子路径 `/policy/` 访问。

## ✨ 特性

- **目录首页**：参考 mulu.png 的落地页，16 个彩色圆圈图标宫格导览（fenlei.png 分类），点击进入对应分类
- **分类导航**：16 个政策分类，桌面端侧边栏 / 移动端横向滑动自适应
- **前端检索**：基于本地 `data/files.json` 的内存搜索，标题 + 摘要模糊匹配，关键词高亮
- **PDF 预览**：基于 `pdf.js` 的流式渲染（**不下载后预览**），支持翻页、自适应宽度、移动端缩放
- **文件下载**：`<a download>` 触发浏览器原生下载
- **极致轻量**：首屏仅加载应用本体（gzip ≈ 50KB），`pdf.js` 按需加载
- **移动端适配**：完美支持手机浏览器（扫码访问场景）、刘海屏安全区
- **无障碍**：键盘导航、屏幕阅读器友好、可见焦点环、跳转链接

## 🧱 技术栈

| 能力 | 选型 |
| --- | --- |
| 框架 | Vue 3 + `<script setup>` + TypeScript |
| 构建 | Vite 5（`base` 子路径） |
| 样式 | Tailwind CSS 3 |
| 路由 | Vue Router 4（**Hash 模式**，免 Nginx 回退配置） |
| PDF | pdf.js（`pdfjs-dist`，随构建产物捆绑，**同源**，不使用 CDN） |
| 数据 | 本地 `data/files.json`，前端 `fetch` 读取 |

> 严格遵守：无 Node.js 后端、无外部 API、无跨域请求、`pdf.js` 经 npm 安装随包发布（不引入 CDN 以满足同源要求）。

## 📁 目录结构

```
.
├─ public/
│  ├─ data/files.json        # 数据源（构建后复制到 dist/data/）
│  └─ files/*.pdf            # 政策 PDF（构建后复制到 dist/files/）
├─ src/
│  ├─ components/            # SearchBar / CategoryNav / FileList / PdfPreviewModal / Icon
│  ├─ composables/useFiles.ts# 数据层：单次 fetch + 内存缓存
│  ├─ data/categories.ts     # 16 个分类定义（fenlei.png）
│  ├─ types/policy.ts        # TypeScript 接口
│  ├─ views/Catalog.vue      # 目录首页（落地页，16 分类宫格）
│  ├─ views/Browser.vue      # 文件列表页（检索 / 预览 / 下载）
│  ├─ router/index.ts        # Hash 路由：/#/ 目录、/#/browse/<分类>
│  └─ main.ts
├─ scripts/gen-sample-pdf.mjs# 示例 PDF 生成器（开发工具，非运行时依赖）
├─ vite.config.ts            # base: '/policy/'
├─ nginx.conf                # Nginx 子路径部署配置片段
└─ package.json
```

## 🚀 本地开发

环境要求：Node.js ≥ 18。

```bash
# 1. 安装依赖
npm install

# 2. 启动开发服务器（默认 http://localhost:5173/policy/）
npm run dev

# 3. 类型检查（可选）
npm run type-check
```

> 开发模式下也通过 `/policy/` 子路径访问，与生产环境一致。

## 📦 构建与部署

```bash
# 构建产物到 dist/
npm run build

# 本地预览构建产物
npm run preview
```

**部署步骤：**

1. 执行 `npm run build`，得到 `dist/` 目录。
2. 将 `dist/` 目录内的**全部内容**上传到服务器 `/var/www/policy/`：

   ```
   /var/www/policy/
   ├─ index.html
   ├─ assets/        (js / css / pdf.js worker)
   ├─ data/files.json
   └─ files/*.pdf
   ```
3. 在 Nginx 的 `server { ... }` 中加入 [nginx.conf](./nginx.conf) 的 `location /policy/` 配置块。
4. 访问 `https://your-domain.com/policy/`。

## 🗂️ 文件上传与数据维护

### 添加政策 PDF

把 PDF 文件放到服务器的 `/var/www/policy/files/` 目录（源码中对应 `public/files/`）。

### 维护 `data/files.json`

每条记录结构如下（接口定义见 [src/types/policy.ts](./src/types/policy.ts)）：

```jsonc
{
  "id": "gw-2024-003",                       // 唯一标识
  "title": "关于印发2024年全市政务公开工作要点的通知",
  "category": "comprehensive",               // 必须为 16 个分类 key 之一
  "summary": "围绕年度政务公开重点任务……",      // 用于检索匹配
  "publishDate": "2024-03-15",               // YYYY-MM-DD，按此倒序排列
  "fileSize": "1.8 MB",
  "path": "/policy/files/xxx.pdf"            // 同源路径，必须以 /policy/ 开头
}
```

16 个分类 `key`（对应 fenlei.png）：`free-trade` `agriculture` `land` `industry` `talent`
`project-quality` `culture-tourism` `education` `finance` `commerce` `urban-rural` `sci-tech`
`industry-support` `fiscal` `public-policy` `startup`
（中文名：自由贸易 / 农业发展 / 用地保障 / 工业强基 / 人才支持 / 项目提质 / 文旅融合 /
教育强国 / 金融服务 / 商贸流通 / 城乡建设 / 科技创新 / 产业扶持 / 财税政策 / 公共政策 / 创业护航，
详见 [src/data/categories.ts](./src/data/categories.ts)）。

> 页面与路由：`/#/` 为目录首页（16 分类宫格），点击任一分类跳转到 `/#/browse/<分类key>` 文件列表页。

更新数据后：

- 若直接修改服务器上的 `dist/data/files.json`，刷新页面即可生效（无需重新构建）。
- 若修改源码 `public/data/files.json`，需重新 `npm run build` 并部署。

> 提示：可在不重新构建的情况下，仅替换服务器端的 `data/files.json` 与 `files/` 目录实现内容更新——这正是纯静态方案的核心优势。

## 🔧 修改部署子路径

默认子路径为 `/policy/`。如需改为其它路径（如 `/wjtj/`）：

1. 修改 [vite.config.ts](./vite.config.ts) 的 `base: '/policy/'` 为目标子路径；
2. 修改 `public/data/files.json` 中每个记录的 `path` 前缀；
3. 修改 [nginx.conf](./nginx.conf) 中的 `location` 名称；
4. 重新 `npm run build` 并部署。

## 📊 性能与体积指标

| 指标 | 实测 |
| --- | --- |
| 首屏资源（gzip） | index.js ≈ 44KB + css ≈ 5KB + files.json ≈ 4KB ≈ **53KB** |
| 首屏加载（3G 模拟） | < 2s ✅ |
| `pdf.js` | 按需加载，仅在点击预览时请求 |
| `dist/` 总大小（不含 PDF） | ≈ 1.87MB ✅（< 5MB） |

## ♿ 无障碍

- 顶部「跳到主要内容」跳转链接
- 全键盘可操作：分类/预览/翻页/关闭（`Enter` `Space` `←` `→` `Esc`）
- 语义化标签（`nav` / `main` / `dialog` / `time`）与 `aria-*` 属性
- 可见焦点环（`:focus-visible`）

## ❓ 常见问题

**Q：预览点击后提示「文件预览失败」？**
A：请确认 PDF 已上传到 `/var/www/policy/files/`，且 `files.json` 中的 `path` 与实际文件名、子路径一致。本仓库内置了 6 个示例 PDF 用于演示。

**Q：为什么用 Hash 路由而不是 History 路由？**
A：Hash 路由（`/#/`）不需要 Nginx 配置 history fallback，真正做到「拷贝即用」，降低部署门槛。

**Q：数据可以热更新吗？**
A：可以。`files.json` 是普通静态文件，直接替换服务器上的该文件并刷新即可，无需重新构建应用。

## 📝 许可

内部使用，按需修改。