一个前后端分离的公益向生活工具聚合站。工具以「盒子」呈现,点击即用;名称/位置由管理员自定义。左侧可伸缩导航含三个页面:工具合集、分享与建议、赞助。
- 便利服务网站,提供各种生活简易工具,每个工具是一个盒子模型,点击即用。
- 后端 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/ # 就地编辑组件
- 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
站点/认证
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→ Top10GET /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 /announcementsGET /forms/active(访客)· 管理员GET/POST/PUT/DELETE /forms+ 字段POST /forms/{id}/submit· 管理员GET /forms/{id}/submissions、GET /forms/{id}/export.csvGET /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_idGET /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。
- PDF 合并 / 插入 / 删除页:
- 后端(走流量)
- 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,全部本地生成。
- 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。
backend/app/seed.py:往_TOOLS加一行(key, 中英名, 中英简介, icon, runtime, tool_type),并在_TOOL_CATEGORY指定分类(新分类加进_CATEGORIES)。重启后端即自动补齐,不影响已有数据。- 图标:
frontend/src/icons.tsx的MAP里补一个 AntD 图标。 - 前端实现:
frontend/src/tools/<Name>.tsx实现RunnerProps(tool+onSuccess),在tools/runners.tsx的RUNNERS里按tool_type注册。 - 文案:
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。
- ✅ 需求确认 + 前端线稿
- 后端脚手架(uv、FastAPI、SQLite、模型、seed)
- 后端核心 API(站点/认证/分类/工具/使用统计/推荐)
- 后端 分享/赞助/流量/上传/转换任务
- 前端脚手架(Vite/AntD/i18n/布局/路由/侧栏)
- 前端 工具合集页 + 工具弹窗(WASM + 后端)
- 前端 分享页(公告/表单/留言)+ 赞助页
- 前端 设置 + 管理员就地编辑态
- 联调、双语校对、README 补充部署细节