足迹 Footprints

个人成长档案馆 —— 面向大学生的留痕、检索、量化与多端同步系统。

平时随手留痕，需要时秒级检索：大二上学期做过什么？拿过哪些省级奖？志愿时长总共多少？ 评奖评优、综测、简历、入党材料的素材库，也是一台记录成长的时光机。

功能特性

• 留痕本体 —— 自定义记录类型 + 动态表单模板；竞赛、志愿、学生工作、荣誉、证书、科研、实习皆可配；正面/负面、进行中、草稿全留痕
• 秒级检索 —— FTS5 trigram 中文全文搜索 + 多条件筛选 + 保存视图（同一查询一键复用）
• 时间线 —— 按学年/月分组的完整回顾，玻璃质感粘性年份头
• 学业成绩 —— 学期 GPA/排名、课程成绩、可自定义绩点梯度（grade band）与趋势图；综测学业分直接取学期卡同源口径
• 成长量化 —— 自定义维度与指标（如志愿时长），统计总览与年度对比
• 简历 —— 可视化编辑模板（基本信息/学业/经历区块增删排序）+ 一键导出规范排版的 Word 文档
• 综合测评 —— 五大素质自动计分（活动/竞赛/学生工作/奖惩，逐项证据画廊）、中文 FTS 三角分词检索佐证、可编辑评分细则与手动修正、学年九格信息表、导出带页码页脚与附件矩阵附录的 Word 档案
• 附件佐证 —— 图片/文档/PDF 上传，SHA-256 内容寻址去重，客户端缩略图 + 灯箱预览，docx/xlsx 在线预览（已 HTML 加固）
• 多用户云优先 —— 所有数据存服务器，按用户独立 SQLite 档案库；浏览器 / PWA / Windows 桌面三端同源同步
• 管理后台 —— 邀请码全生命周期管理（自定义码、备注、启用/停用、删除、批量生成）、用户列表、注册配额、账号删除级联清理（图床/档案库/附件/会话）
• 演示模式 —— 内置演示账号 demo / demo1234，自动播种 25 条足迹 + 4 学期成绩 + 7 份佐证附件，开箱即看
• PWA + 桌面 —— 可安装到桌面/手机；Windows Tauri 安装包；亮/暗双主题

架构

  浏览器 PWA ─┐
  Windows 桌面 ─┤   HTTPS + Bearer Token（365 天，可服务端吊销）
  移动端 PWA ─┘
        │
        ▼
┌────────────────────────────────┐
│ sync-server（零依赖 Node ≥ 22.5）│
│ node:http + node:sqlite         │
│ scrypt 认证 · 邀请码 · LWW 同步   │
│ 登录限速 · 会话吊销 · 附件加固    │
└───────────────┬────────────────┘
                ▼
   data/users/<uid>.db   每用户独立 SQLite 档案库（WAL + 索引齐全）
   data/attachments/     按用户隔离的内容寻址附件

设计取向：

• 服务器零 npm 依赖：仅用 Node 内置模块（node:http / node:sqlite / node:crypto），攻击面与供应链风险极小
• 命令层同源：Web、桌面、数据播种共用同一份 app/server/db.mjs 命令层（44 个命令），同一业务逻辑多处不漂移
• 同步元数据内建：所有表带 uuid/hlc/origin 列 + oplog，为多端增量同步而生
• 性能基线（3000 条记录实测）：列表/时间线 ≤23ms、单条写 ≈0.3ms（WAL + synchronous=NORMAL + 8MB 页缓存）

快速开始（Docker 部署）

git clone https://gitea.linyux.cn/root/FootPrint.git footprints
cd footprints/sync-server

# 构建 + 启动（数据持久化在 ./data）
docker compose -f docker-compose.caddy.yml up -d --build

# 国内拉取 node:24-alpine 超时时，换镜像源构建：
docker compose -f docker-compose.caddy.yml build \
  --build-arg NODE_IMAGE=docker.1ms.run/library/node:24-alpine

反向代理（Caddy 示例，容器网络需与 Caddy 同网）：

footprints.example.com {
    encode zstd gzip
    reverse_proxy footprints-sync:8788
}

compose 默认加入名为 mynet 的外部网络；没有就先 docker network create mynet，或把 compose 里的 networks 段改成你自己的。 详细部署与拓扑说明见 sync-server/README.md。

首次使用：

1. 打开站点 → 注册 —— 第一个注册的账号自动成为管理员（内置 demo 账号不占管理员席位）
2. 管理员登录 → 侧边栏「管理」→ 新建/批量生成邀请码，发给需要注册的用户
3. 人齐之后建议收紧注册：compose 里 REGISTER_ENABLED=false，并把 INVITE_CODE 从示例默认值 please-change-me 换成强随机值或留空（改用管理页动态码）
4. 想先看看界面？用演示账号 demo / demo1234 登录，数据管够

本地开发

# 1) 启动同步服务器（Node ≥ 22.5，推荐 24；零依赖，无需 npm install）
cd sync-server
PORT=8788 DATA_DIR=./data node src/index.mjs

# 2) 前端开发服务
npm install --prefix app        # 或 pnpm -C app install
npm run dev --prefix app

# 3) 让网页版指向本地服务器（浏览器控制台执行一次）
localStorage.setItem('fp-server-url', 'http://127.0.0.1:8788')

# 4) Windows 桌面安装包（需 Rust + MSVC）
pnpm -C app install && pnpm -C app tauri build

测试与质量

node scripts/check.mjs              # 语法 + 类型 + 构建 + 关键标记 tripwire
node scripts/test-integration.mjs   # 61 条集成断言（播种/登录/邀请码全矩阵/角色规则/幂等/级联删除）
node scripts/smoke.mjs <url> <user> <pass>   # 部署后冒烟
git config core.hooksPath .githooks # 启用 pre-push 钩子：工作区不干净或测试红，push 直接拒绝

项目结构

├─ app/                    # 前端 + 桌面端
│  ├─ src/                 #   React 19 + Vite + Tailwind v4 UI（三端共用）
│  │  ├─ pages/            #   时间线/记录/成绩/统计/类型/字典/个人信息/简历/综合测评/管理
│  │  ├─ lib/zongce.ts     #   综测计分引擎（五大素质聚合 + 学业口径对齐）
│  │  └─ styles/theme.css  #   亮/暗主题令牌 + MHTML Word 导出样式基座
│  ├─ public/              #   PWA：sw.js（接口绝不缓存）/ manifest / icons
│  ├─ server/              #   ★ 命令层 db.mjs：零依赖数据层（44 个命令）
│  ├─ schema.sql           #   数据库 schema（Rust 与 Node 共用）
│  └─ src-tauri/           #   Tauri 2 桌面壳
├─ sync-server/            # 自建同步服务器
│  ├─ src/                 #   index/auth/db/sync/attachments（零依赖）
│  ├─ www/                 #   构建产物（部署时以卷挂载，git pull 即更新）
│  └─ docker-compose.caddy.yml
├─ docs/                   # api.md · DESIGN.md · SECURITY.md · zongce-rules（测评细则示例）
├─ scripts/                # check / test-integration / smoke
├─ tools/                  # pnpm.cjs + 图标生成器
├─ .gitea/                 # Issue/PR 模板
├─ .githooks/              # pre-push 质量门禁（check + 61 条集成断言）
└─ .editorconfig

环境变量（sync-server）

变量	默认	说明
PORT	8788	监听端口
DATA_DIR	./data	数据目录（用户库/附件/同步账本）
REGISTER_ENABLED	true	是否开放注册（注册完毕后建议关闭）
INVITE_CODE	空	静态兜底邀请码（动态码由管理员在管理页生成；务必改默认值）
MAX_USERS	0	用户数上限，0 = 不限
WWW_DIR	../www	前端静态目录
LSKY_API / LSKY_TOKEN	空	可选：附件自动迁入自建图床（Lsky Pro）

文档

文档	内容
HTTP API 参考	全部 HTTP 端点与 44 个业务命令
安全模型	威胁模型、已加固项、漏洞报告渠道
设计方案（v0.5 底稿）	项目的原始设计思想；现产品已演进为云优先多用户架构
综合测评细则示例	「评分细则参考」默认值的来源（纯文本，可自行修改）

Roadmap

• 大文件分片上传
• 附件缩略图 / 上传前压缩（客户端 canvas 生成 480px WebP）
• 评奖评优材料包一键导出（简历 / 综测 Word 档案）
• 对象存储（S3）适配
• 端到端加密存储
• 移动端体验优化（手势、离线编辑队列）
• 英文界面

License

MIT