Skip to content
SiteEnglish10Public

About

小工具站,文档、音、视频格式转换等

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

6 Commits

Folders and files

Repository files navigation

便利工具站(Party2Web)

一个前后端分离的公益向生活工具聚合站。工具以「盒子」呈现,点击即用;名称/位置由管理员自定义。左侧可伸缩导航含三个页面:工具合集、分享与建议、赞助。


一、原始需求要点

  • 便利服务网站,提供各种生活简易工具,每个工具是一个盒子模型,点击即用。
  • 后端 Python,前端 React。左侧可伸缩导航:工具合集 / 分享与建议 / 赞助。
  • 首页=工具合集:顶部搜索框;下方推荐栏展示最常用 Top10(可切换 全部/7天/一月/一年);再下方按功能类型分类展示工具。
  • 工具盒子:图标、标题、简介、使用次数(每次成功使用 +1,Top10 进推荐)。
  • 分享与建议:上部左=公告栏(可点开详情),右=互动表单(收集信息);下部=留言区(富文本、图片、点赞,按赞降序)。
  • 赞助页:感谢文字 + 本月流量(已用/剩余,共 300GB/月)+ 赞助二维码。
  • 管理员模式:导航底部「设置」→ 滑块开启 → 输入账号密码(凭据通过环境变量配置,见 backend/.env.example)。可维护三页内容。

二、已确认的设计决策

项 决定
后端框架 FastAPI(uv 管理依赖)
数据库 SQLite(SQLModel/SQLAlchemy)
前端 Vite + React + TypeScript + Ant Design
国际化 中 / 英 双语(i18next)
管理员形态 就地切换管理模式(同一前端内编辑,非独立后台);凭据存 sessionStorage,关掉页面即退出
工具架构 混合:PDF/音频/视频 → 浏览器 WASM(0 流量);Office→PDF → 后端 LibreOffice
后端任务 Office→PDF 走异步任务 + 轮询进度
使用次数 成功使用才 +1,前端上报
推荐时间段 记录每次点击时间戳,按 全部/7天/一月/一年 聚合 Top10
留言媒体 富文本 + 图片(≤5MB);视频用外链嵌入
留言删除/点赞 本期删除仅管理员;点赞不去重
流量数字 后端真实统计(本地 WASM 工具天然不计入)
互动表单 管理员自定义字段(单行/多行/单选/多选)+ 结果导出 CSV
工具打开方式 弹窗(Modal);重型工具(简历编辑器)在弹窗里给入口,新标签页打开
站点名称/位置 管理员在设置中填写,全站生效(含浏览器标签页标题)
标签页图标 管理员可选内置 emoji 图标(data URI,不占存储)或上传 .ico/.png/.svg(≤256KB)
ICP备案号 开启管理员模式后,在「赞助 → 网站信息」填写或修改完整备案号;保存后各主页面底部立即显示,点击在新标签页打开工信部备案网站,留空则隐藏。已有数据库会在后端启动时自动补充字段。
简历编辑器 自包含静态页 + localStorage,内容不出浏览器;默认恢复上次草稿,另有隐私模式/清除草稿
部署 Linux VPS 手动部署(uv + systemd + nginx;系统装 LibreOffice + ffmpeg)

前端线稿(低保真,11 屏)已确认。


三、目录结构

Party2Web/
├── README.md
├── backend/                # FastAPI + uv
│   ├── pyproject.toml
│   ├── app/
│   │   ├── main.py         # 应用入口、CORS、静态、流量中间件
│   │   ├── db.py           # SQLite 引擎/会话
│   │   ├── models.py       # SQLModel 数据模型
│   │   ├── schemas.py      # Pydantic I/O 模型
│   │   ├── auth.py         # 管理员登录/会话校验
│   │   ├── seed.py         # 初始分类/工具/站点信息
│   │   ├── deps.py         # 依赖注入
│   │   ├── traffic.py      # 流量统计中间件
│   │   ├── conversions.py  # Office→PDF 异步任务 (LibreOffice)
│   │   └── routers/
│   │       ├── tools.py        # 工具/分类 CRUD、使用上报、推荐
│   │       ├── announcements.py
│   │       ├── forms.py        # 表单定义 + 提交 + 导出
│   │       ├── comments.py     # 留言 + 点赞 + 图片上传
│   │       ├── sponsor.py      # 赞助内容 + 流量
│   │       ├── site.py         # 站点信息
│   │       └── convert.py      # 后端转换任务提交/轮询/下载
│   ├── data/               # SQLite 文件、上传目录(运行时生成)
│   └── .env.example        # 管理员密码/密钥模板(复制为 .env)
├── nginx.conf.example      # 服务器 nginx 站点配置参考
├── update.sh.example       # 服务器一键更新脚本模板(服务器上复制为 update.sh 并改路径)
└── frontend/               # Vite + React + TS + AntD
    ├── package.json
    ├── vite.config.ts
    ├── index.html
    ├── public/
    │   ├── ffmpeg/         # 自托管的 ffmpeg.wasm 核心(构建时拷贝,不入库)
    │   └── resume/
    │       └── editor.html # 简历编辑器:自包含单文件,新标签页打开
    └── src/
        ├── main.tsx / App.tsx
        ├── api/            # axios 客户端 + 各资源接口
        ├── i18n/           # zh.json / en.json
        ├── store/          # 管理员会话、站点信息 (zustand)
        ├── layout/         # 可伸缩侧栏 + 顶栏
        ├── components/     # ToolCard、AdminBar、RichEditor 等
        ├── tools/          # 前端 WASM 工具实现(pdf/audio/video)
        └── pages/
            ├── Tools/      # 工具合集(首页) + 工具弹窗
            ├── Share/      # 公告 + 表单 + 留言
            ├── Sponsor/
            └── admin/      # 就地编辑组件

四、数据模型(SQLite)

  • Category:id, name_zh, name_en, icon, sort_order
  • Tool:id, key, name_zh, name_en, desc_zh, desc_en, icon, runtime(front|backend), tool_type(pdf-merge/word-to-pdf/...), config(JSON)
  • ToolCategory(多对多 + 排序):tool_id, category_id, sort_order —— 支持一个工具属于多个分类(复制移动)
  • UsageEvent:id, tool_id, created_at —— 每次成功使用一条,用于时间段 Top10
  • Announcement:id, title_zh, title_en, body_zh, body_en(富文本), image_url, created_at, sort_order
  • FormDef:id, title_zh, title_en, active
  • FormField:id, form_id, label_zh, label_en, field_type(text/textarea/radio/checkbox), options(JSON), required, sort_order
  • FormSubmission:id, form_id, data(JSON), created_at
  • Comment:id, author_token, author_name, body(富文本HTML), likes, created_at
  • SiteConfig(单行):site_name, location, favicon_url, sponsor_text_zh/en, sponsor_qr_url, traffic_limit_gb(默认300)

SQLite 没有迁移框架:后加的列登记在 app/db.py 的 _ADDED_COLUMNS,每次启动 ALTER TABLE 补一次,已有的 data/app.db 直接就能升级。

  • ReferenceStyle:id, key, name_zh, name_en, config(JSON 文本), active, sort_order —— 管理员自定义的参考文献输出样式(内置样式在前端代码里,不入库)
  • TrafficStat:按月累计 year_month, bytes_used

五、后端 API(前缀 /api)

站点/认证

  • GET /site 站点信息 · PUT /site(管理员)
  • POST /auth/login {username,password} → 会话 token · POST /auth/logout · GET /auth/me

工具 & 分类

  • GET /categories(含各分类下工具,按排序)
  • GET /tools/recommended?range=all|7d|30d|365d → Top10
  • GET /tools/search?q=
  • POST /tools/{id}/use 使用次数 +1(写 UsageEvent)
  • 管理员:POST/PUT/DELETE /categories、POST/PUT/DELETE /tools、POST /tools/{id}/assign(移动/复制到分类)、PUT /categories/reorder、PUT /categories/{id}/tools/reorder

分享页

  • GET/POST/PUT/DELETE /announcements
  • GET /forms/active(访客)· 管理员 GET/POST/PUT/DELETE /forms + 字段
  • POST /forms/{id}/submit · 管理员 GET /forms/{id}/submissions、GET /forms/{id}/export.csv
  • GET /comments(按赞降序)· POST /comments · POST /comments/{id}/like · 管理员 DELETE /comments/{id}
  • POST /uploads/image(留言/公告配图,≤5MB,存 data/uploads/)

赞助

  • GET /sponsor(文字+二维码+流量已用/剩余)· 管理员 PUT /sponsor、POST /uploads/qr
  • 管理员 POST /uploads/favicon(.ico/.png/.svg,≤256KB,存 data/uploads/ 并写回 SiteConfig.favicon_url)

参考文献样式

  • GET /reference-styles(访客,仅启用的)· 管理员 GET /reference-styles/all、POST/PUT/DELETE /reference-styles

后端转换(Office→PDF)

  • POST /convert/{tool_type} 上传文件 → 返回 job_id
  • GET /convert/jobs/{job_id} 轮询状态/进度
  • GET /convert/jobs/{job_id}/download 下载结果(结果定时清理)

流量:中间件累加请求/响应字节到当月 TrafficStat,供赞助页展示。


六、前端工具(混合架构)

  • 浏览器 WASM(0 流量)
    • PDF 合并 / 插入 / 删除页:pdf-lib
    • 音频转换(MP3 等常见格式):@ffmpeg/ffmpeg(ffmpeg.wasm)
    • 视频:MP4→GIF、MP4→MP3:@ffmpeg/ffmpeg
    • 进度本地实时显示,完成直接下载,随后调 /tools/{id}/use。
    • 简历编辑器(tool_type: resume-editor):静态页 public/resume/editor.html,弹窗内点按钮新开标签页。
    • 参考文献格式转换(tool_type: reference-convert):解析 → IR → 样式渲染,全部本地字符串处理。
    • LaTeX 公式转 Word(tool_type: latex-to-word):MathJax 自托管懒加载,导出 PNG/SVG/docx。
  • 后端(走流量)
    • PPT / Word / Excel → PDF:上传 → 轮询 job → 下载。

每个工具在数据库以 runtime + tool_type 标识,前端据此渲染对应弹窗组件。

简历编辑器:示例与双语界面

  • 三套起始示例(顶栏「示例」下拉):general 职场通用 / fresh 应届生 · 校招 / research 科研 · 研究岗。三套是同一个虚构人物「李明,2000-05-06 生」的三种人生假设,公司、学校、期刊、电话邮箱均为虚构或占位;要点按 STAR 组织(现状与问题 → 我做了什么 → 可量化的结果)。每套都自带中英两份内容,实测 6 种组合都是一页(占用 68%–80%)。默认 general,「重置」回到当前所选示例。
  • 顶栏有两个语言开关,别混:界面 换 UI 文案(复用主站的 localStorage["lang"],两边同一个偏好);简历版本 切的是中/英两份简历内容(版面参数也各存一套)。
  • UI 文案集中在脚本开头的 UI = { zh, en };静态元素挂 data-t / data-t-html / data-t-title,动态文案走 T(key),切换时由 applyUI() 统一重铺。新增文案两边都要加。

简历编辑器的隐私与存档

单文件自包含(内联 CSS/JS,零网络请求、零外链 CDN),照片也是本地 canvas 压缩后转 dataURL,因此简历内容任何时候都不会离开浏览器;服务器上只有一次 POST /tools/{id}/use(仅工具 id,不含内容)。

  • 存档:写 localStorage["p2w.resume.v1"](含 sample 字段,记住内容来自哪套示例)。localStorage 按「浏览器 profile + 域名」隔离,不同访客彼此不可见。
  • 再次打开:默认恢复上次编辑的内容(不回到模板)。顶栏右侧显示「草稿已保存在本机 · HH:MM」;写入失败(配额满/浏览器禁用存储)会明确报错,提示用「导出 JSON」备份。
  • 隐私模式(localStorage["p2w.resume.privacy"],只存开关不存内容):勾选后清除已有草稿且本次编辑不落盘,关闭网页即消失,适合公用电脑。
  • 清除本机草稿:删除存档并回到模板初始内容。
  • 唯一的真实泄露路径是同一台电脑同一浏览器的下一个使用者 —— 上面两个出口就是为它准备的。相应地,该域名下不要接入任何第三方脚本(统计/广告 SDK 能读同源 localStorage)。

不做成 React 组件是有意的:该页自带全局 CSS(连裸 button/select 都改了),进 React 树会污染 AntD;左右分栏 + A4 预览也需要整屏。

参考文献格式转换

  • 架构:N 个解析器 → 统一 IR(tools/reference/types.ts,对齐 CSL-JSON 子集)→ M 个样式渲染器,避免 N×M 的两两映射。
  • 输入:Web of Science savedrecs.txt、RIS、BibTeX、PubMed nbib(以上标签化,可靠性高);ScienceDirect 文本引用(中高);PubMed「Cite」弹窗的成品引文串(AMA/NLM/APA/MLA,中低)。自动识别来源,也可手动指定。
  • 成品引文串是反向解析,天然不可能 100%:每条都带置信度,界面上有「解析明细」表;同一篇的多个版本按 DOI 去重,并把各版本的字段互相补全(例如 AMA 版有期刊缩写、MLA 版有期刊全称,合并后两者都有)。
  • 样式系统:不用 CSL/citeproc-js(500KB,且管理员得手写 CSL XML)。自研模板引擎:{{field}} 取值、{{#field}}…{{/field}} 有值才输出这一段(缺卷期页时不吐残缺标点),外加一遍标点清洗。
  • 内置 5 套:GB/T 7714-2015 顺序编码制 / 著者-出版年制、APA 7、Vancouver·AMA、IEEE,随代码走不入库。管理员自定义的存 ReferenceStyle 表,支持表单编辑、从内置样式复制、JSON 导入导出、实时预览、停用。
  • 导出:txt / md / docx / ris / bib,全部本地生成。

LaTeX 公式转 Word

  • MathJax v3(不是 KaTeX —— 只有 MathJax 能给出干净的 SVG,导图才不糊),自托管在 public/mathjax/,懒加载,首次约 2MB 后进浏览器缓存。
  • 切分:一行里写多个 $x$ $y$ 也能各自认出;支持 $$…$$、\[…\]、\begin{equation|align|cases|…};没加定界符的裸公式按行识别;公式之外的文字默认保留为普通段落(可关)。
  • Word 里是可编辑公式:LaTeX → MathJax → MathML → mathml2omml → OMML,导出后在 Word 里双击可编辑。OMML 表达不了的结构自动降级为图片并提示,不会默默出错。
  • 关掉了 MathJax 的 noundefined 包 —— 否则未知命令会被画成红字当作「渲染成功」,用户看不出自己写错了。
  • 导出:PNG(1x/2x/4x、透明/白底)、SVG、docx(可编辑公式 / 图片两种模式)、复制 MathML。

新增一个工具的步骤

  1. backend/app/seed.py:往 _TOOLS 加一行(key, 中英名, 中英简介, icon, runtime, tool_type),并在 _TOOL_CATEGORY 指定分类(新分类加进 _CATEGORIES)。重启后端即自动补齐,不影响已有数据。
  2. 图标:frontend/src/icons.tsx 的 MAP 里补一个 AntD 图标。
  3. 前端实现:frontend/src/tools/<Name>.tsx 实现 RunnerProps(tool + onSuccess),在 tools/runners.tsx 的 RUNNERS 里按 tool_type 注册。
  4. 文案:src/i18n/zh.json / en.json 补键。

七、国际化

  • i18next + react-i18next,语言包 zh.json / en.json。
  • 内容型数据(工具名、简介、公告、表单字段、赞助文字)在数据库存 _zh/_en 双字段,按当前语言返回。
  • 顶栏语言切换,持久化到 localStorage;<html lang> 跟随切换。
  • 浏览器标签页标题 = 页面名 · 站点名(如「工具合集 · 便利工具站」)。站点名来自 GET /site,管理员在赞助页改完即时生效、无需刷新;同时缓存到 localStorage["site_name"],首屏与静态工具页(简历编辑器)直接读缓存,避免默认标题闪一下。
  • 标签页图标同一条路径:SiteConfig.favicon_url → localStorage["site_favicon"] → <link rel="icon">,由 src/lib/favicon.ts 统一管理。内置图标是把 emoji 画进 SVG 的 data URI(零存储、零流量),自定义图标走 POST /uploads/favicon;管理员留空即恢复默认 🧰。

八、开发 & 运行

后端

cd backend
uv sync                       # 安装依赖
uv run uvicorn app.main:app --reload --port 8000
  • 首次启动自动建库并 seed 初始分类/工具/站点信息。
  • Office→PDF 需系统安装 LibreOffice(soffice 在 PATH);缺失时该类工具返回明确错误,不影响其余功能。

前端

cd frontend
npm install
npm run dev                   # 默认 http://localhost:5173,代理 /api → :8000

管理员:任意页 → 侧栏底部「设置」→ 开启管理员模式 → 输入账号密码。凭据由环境变量配置:复制 backend/.env.example 为 backend/.env 并填入 ADMIN_USERNAME / ADMIN_PASSWORD / SECRET_KEY(未配置时本地默认 root / admin)。

登录后服务端签发一个 itsdangerous 签名 token(无服务端会话,有效期 12 小时),前端存在 sessionStorage 里:

  • 只在当前标签页有效,关掉页面就退出——公用电脑上不会把后台一直开着;新开的标签页也不是管理员态。
  • 开页时会调 GET /auth/me 跟服务端核对一次。以前只看本地有没有 token 字符串,token 过期后界面照样显示管理员模式、每次保存却静默 401 失败;现在过期会直接退出管理模式。
  • 真正的鉴权始终在服务端验签,前端这套只决定「浏览器把凭据留多久」。

部署(Linux VPS):采用手动部署(后端 uv + systemd,前端构建产物由 nginx 托管并反代 /api、/uploads)。完整分步指南见 DEPLOYMENT.md,含域名 DNS、HTTPS、nginx 配置(.mjs MIME 与 COOP/COEP 已处理)、以及一键更新脚本 update.sh。ffmpeg.wasm 核心与 pdf.js 均自托管/同源,不依赖国外 CDN。


九、实现路线

  1. ✅ 需求确认 + 前端线稿
  2. 后端脚手架(uv、FastAPI、SQLite、模型、seed)
  3. 后端核心 API(站点/认证/分类/工具/使用统计/推荐)
  4. 后端 分享/赞助/流量/上传/转换任务
  5. 前端脚手架(Vite/AntD/i18n/布局/路由/侧栏)
  6. 前端 工具合集页 + 工具弹窗(WASM + 后端)
  7. 前端 分享页(公告/表单/留言)+ 赞助页
  8. 前端 设置 + 管理员就地编辑态
  9. 联调、双语校对、README 补充部署细节

About

小工具站,文档、音、视频格式转换等

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages