155 lines
6.6 KiB
Markdown
155 lines
6.6 KiB
Markdown
# 足迹 Footprints
|
||
|
||
> 个人成长档案馆 —— 面向大学生的留痕、检索、量化与多端同步系统。
|
||
|
||
|
||
|
||
|
||
|
||
平时随手留痕，需要时秒级检索：**大二上学期做过什么？拿过哪些省级奖？志愿时长总共多少？**
|
||
评奖评优、综测、简历、入党材料的素材库，也是一台记录成长的时光机。
|
||
|
||
## 功能特性
|
||
|
||
- **留痕本体** —— 自定义记录类型 + 动态表单模板；竞赛、志愿、学生工作、荣誉、证书、科研、实习皆可配；正面/负面、进行中、草稿全留痕
|
||
- **秒级检索** —— FTS5 trigram 中文全文搜索 + 多条件筛选 + 保存视图（同一查询一键复用）
|
||
- **时间线** —— 按学年/月分组的完整回顾
|
||
- **学业成绩** —— 学期 GPA/排名、课程成绩、可自定义绩点梯度（grade band）与趋势图
|
||
- **成长量化** —— 自定义维度与指标（如志愿时长），统计总览与年度对比
|
||
- **附件佐证** —— 图片/文档上传，SHA-256 内容寻址去重
|
||
- **多用户云优先** —— 所有数据存服务器，按用户独立 SQLite 档案库；浏览器 / PWA / Windows 桌面三端同源同步
|
||
- **管理后台** —— 邀请码全生命周期管理（自定义码、备注、启用/停用、删除、批量生成）、用户列表、注册配额
|
||
- **演示模式** —— 内置演示账号 `demo / demo1234`，自动播种 16 条足迹 + 4 学期成绩，开箱即看
|
||
- **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 档案库
|
||
data/blobs/<uid>/ 内容寻址附件存储
|
||
```
|
||
|
||
设计取向：
|
||
|
||
- **服务器零 npm 依赖**：仅用 Node 内置模块（`node:http` / `node:sqlite` / `node:crypto`），攻击面与供应链风险极小
|
||
- **命令层同源**：Web、桌面、数据播种共用同一份 `app/server/db.mjs` 命令层，同一业务逻辑多处不漂移
|
||
- **同步元数据内建**：所有表带 uuid/hlc/origin 列 + oplog，为多端增量同步而生
|
||
|
||
## 快速开始（Docker 部署）
|
||
|
||
```bash
|
||
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 同网）：
|
||
|
||
```caddyfile
|
||
footprints.example.com {
|
||
reverse_proxy footprints-sync:8788
|
||
}
|
||
```
|
||
|
||
> compose 默认加入名为 `mynet` 的外部网络；没有就先 `docker network create mynet`，或把 compose 里的 networks 段改成你自己的。
|
||
|
||
首次使用：
|
||
|
||
1. 打开站点 → 注册 —— **第一个注册的账号自动成为管理员**
|
||
2. 管理员登录 → 侧边栏「管理」→ 新建/批量生成邀请码，发给需要注册的用户
|
||
3. 人齐之后建议收紧注册：compose 里 `REGISTER_ENABLED=false`（或改掉 `INVITE_CODE` 默认值）再 `up -d`
|
||
4. 想先看看界面？用演示账号 **demo / demo1234** 登录，数据管够
|
||
|
||
## 本地开发
|
||
|
||
```bash
|
||
# 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
|
||
```
|
||
|
||
## 测试与质量
|
||
|
||
```bash
|
||
node scripts/check.mjs # 语法 + 类型 + 构建 + 关键标记 tripwire
|
||
node scripts/test-integration.mjs # 35 条集成断言（播种/登录/邀请码全矩阵/角色规则/幂等）
|
||
node scripts/smoke.mjs <url> <user> <pass> # 部署后冒烟
|
||
git config core.hooksPath .githooks # 启用 pre-push 钩子：工作区不干净或测试红，push 直接拒绝
|
||
```
|
||
|
||
CI：push 自动跑 check + 集成测试（见 `.gitea/workflows/ci.yml`，需在 Gitea 配置 act_runner）。
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
├─ app/ # 前端 + 桌面端
|
||
│ ├─ src/ # React 19 + Vite + Tailwind v4 UI（三端共用）
|
||
│ ├─ public/ # PWA：sw.js v3（接口绝不缓存）/ manifest / icons
|
||
│ ├─ server/ # ★ 命令层 db.mjs：零依赖数据层（37 个命令）
|
||
│ └─ src-tauri/ # Tauri 2 桌面壳
|
||
├─ sync-server/ # 自建同步服务器
|
||
│ ├─ src/ # index/auth/db/sync/attachments（零依赖）
|
||
│ ├─ www/ # 构建产物（部署时以卷挂载，git pull 即更新）
|
||
│ └─ docker-compose.caddy.yml
|
||
├─ scripts/ # check / test-integration / smoke
|
||
├─ .gitea/workflows/ # CI
|
||
├─ .githooks/ # pre-push 钩子
|
||
└─ docs/api.md # HTTP API 参考
|
||
```
|
||
|
||
## 环境变量（sync-server）
|
||
|
||
| 变量 | 默认 | 说明 |
|
||
|---|---|---|
|
||
| `PORT` | `8788` | 监听端口 |
|
||
| `DATA_DIR` | `./data` | 数据目录（用户库/附件/同步账本） |
|
||
| `REGISTER_ENABLED` | `true` | 是否开放注册 |
|
||
| `INVITE_CODE` | 空 | 静态兜底邀请码（动态码由管理员在管理页生成） |
|
||
| `MAX_USERS` | `0` | 用户数上限，0 = 不限 |
|
||
| `WWW_DIR` | `../www` | 前端静态目录 |
|
||
|
||
## 文档
|
||
|
||
- [HTTP API 参考](docs/api.md)
|
||
- [设计方案（v0.5 底稿）](DESIGN.md) —— 项目的原始设计思想；现产品已演进为云优先多用户架构
|
||
|
||
## Roadmap
|
||
|
||
- [ ] 附件缩略图 / 上传前压缩 / 大文件分片
|
||
- [ ] 评奖评优材料包一键导出
|
||
- [ ] 对象存储（S3）适配
|
||
- [ ] 端到端加密存储
|
||
- [ ] 移动端体验优化（手势、离线编辑队列）
|
||
- [ ] 英文界面
|
||
|
||
## License
|
||
|
||
[MIT](LICENSE)
|