# 个人留痕系统（Footprints）设计方案

> 版本 v0.5 · 足迹本体是核心；分类、表单、统计、导出、评分全部用户可自定义
> 形态：单人使用 · Windows 桌面应用（MVP 已实现）· 预留多端同步

## 0. 设计原则

1. 足迹本体覆盖一个学生全部值得留痕的事，不局限于任何评分公式
2. **配置即数据**：所有枚举、分类轴、表单字段、统计口径、导出格式都是数据库里的配置，
   程序只提供渲染与计算引擎；换学校、换习惯、换关注点 = 改配置，不改代码
3. 时间线完整：正面/负面记录、进行中、草稿都留痕
4. 单机桌面、数据全本地、附件与描述分离存储

## 1. 产品定位

个人成长档案馆：平时随手留痕，需要时按任意维度检索、聚合、量化、导出。

- 检索盘点："大二上学期做过什么""拿过哪些省级奖""在宣传部做过哪些事" —— 秒级检索
- 材料输出：评奖评优/综测/简历/入党材料 → 选条目、汇总表、佐证包
- 成长量化：自定义维度与指标统计
- 时间线复盘：完整回顾

## 2. 足迹本体模型

```sql
footprint (
  id            INTEGER PRIMARY KEY,
  type_id       INTEGER NOT NULL,   -- → footprint_type（含自定义类型）
  title         TEXT NOT NULL,
  role          TEXT,               -- 来自 taxonomy(kind='role')，可自定义
  level         TEXT,               -- 来自 taxonomy(kind='level')，可自定义
  polarity      TEXT,               -- positive/negative
  award_grade   TEXT, rank INTEGER, -- 可选
  organizer     TEXT,
  start_date    DATE, end_date DATE,
  status        TEXT,               -- draft/ongoing/submitted/finished
  description   TEXT, result TEXT,
  metrics       TEXT,               -- JSON {"志愿时长":8} 任意键 → metric_def 注册后可统计
  extras        TEXT,               -- JSON 按类型表单模板的动态字段
  group_id      TEXT,               -- 事件归组
  parent_id     INTEGER,            -- 晋升链/隶属
  tags          TEXT,               -- JSON 自由标签
  weight        INTEGER,
  created_at    DATETIME, updated_at DATETIME
);

footprint_type (
  id, name, icon, color, sort,
  form_template JSON,             -- 动态字段模板（见 §3.2）
  is_builtin BOOL, closed BOOL    -- 内置类型可改名/停用，不可删除
);

dimension (id, name, color, sort);          -- 成长维度（自定义分类轴）
footprint_dimension (footprint_id, dimension_id);

attachment (id, owner_type, owner_id, kind, file_path, file_name, mime, size, taken_at);
semester (id, term UNIQUE, gpa, rank, total_students);
course_grade (id, semester_id, course_name, credit, score, grade_point);
footprint_fts: FTS5(title, description, result, tags, extras_text);
```

## 3. 用户自定义体系（本版重点）

### 3.1 十个可自定义层（从记录到输出）

| # | 对象 | 自定义内容 | 存储 |
|---|---|---|---|
| 1 | 足迹类型 | 新建类型（名称/图标/颜色）；内置类型改名、停用 | footprint_type |
| 2 | 表单字段 | 每个类型的动态字段：增删改、必填、默认值、单位 | form_template JSON |
| 3 | 分类轴（维度） | 自定义正交分类（如 学业深造/职业发展/兴趣生活），一条足迹可挂多轴 | dimension + 多对多 |
| 4 | 标签 | 自由打标 + 标签管理（重命名/合并/用量统计） | tags JSON |
| 5 | 枚举字典 | 级别、角色等枚举可增改排序（如加"企业级""国际级"） | taxonomy |
| 6 | 统计指标 | 把 metrics 的键注册为指标：求和/计数/去重计数 + 单位 | metric_def |
| 7 | 视图 | 保存筛选条件为一键视图（评优视图/学年视图/任一组合），可设默认 | saved_view |
| 8 | 导出模板 | 列选择、分组方式、文件命名规则 | export_template |
| 9 | 评分适配器 | 学校综测/加分类规则：预设 JSON 导入 + 界面微调分值 | scoring_preset |
| 10 | 外观 | 主题色/深浅模式/首页默认视图/时间线密度 | app_config |

### 3.2 动态表单模板（form_template）

每个类型一个字段数组，驱动录入表单、详情页、检索列三处渲染：

```json
[
  { "key": "team_members", "label": "队伍成员", "widget": "multiselect", "options": "从联系人选" },
  { "key": "my_work", "label": "我的分工", "widget": "text", "required": true },
  { "key": "deliverable", "label": "最终产品", "widget": "text" },
  { "key": "cert_level", "label": "证书等级", "widget": "select",
    "options": ["从业资格", "初级", "中级", "高级"] },
  { "key": "hours", "label": "志愿时长", "widget": "number", "unit": "小时",
    "metric": "volunteer_hours" }
]
```

- widget 类型：text / textarea / number / date / select / multiselect / link(关联其他足迹) / contact(联系人)
- 数据存 footprint.extras JSON；schema 永不因新字段而改
- widget=number 且声明 metric 时，录入即累计进统计

### 3.3 枚举字典（taxonomy）

```sql
taxonomy (id, kind TEXT, value TEXT, color TEXT, sort INT, is_builtin BOOL, UNIQUE(kind, value));
-- kind: level(级别) / role(角色) / attachment_kind / polarity ...
-- 预置: level = 国家级/省市级/区县级/校级/院级/none；
--       role  = 主导/核心/参加 —— 均可增改，例如加"企业实习级"
```

### 3.4 统计指标与视图

```sql
metric_def (id, key TEXT UNIQUE, label TEXT, unit TEXT,
            agg TEXT /*sum|count|distinct*/, section TEXT);
saved_view (id, name, filter JSON, sort JSON, is_default BOOL, updated_at);
export_template (id, name, columns JSON, group_by TEXT, filename_rule TEXT);
```

- 指标卡：看板上的"自定义指标卡"由 metric_def 驱动（例：volunteer_hours 求和=志愿总时长；
  证书类型 distinct 计数；省级以上获奖 count）
- 视图：筛选器(类型×级别×角色×维度×学年×状态×标签×关键词)任意组合另存，
  例："综测佐证视图" = level∈{国家级,省市级} + polarity=positive + 有附件

### 3.5 评分适配器（第 9 层，V3）

预设 JSON 定义分类映射 + 查表/矩阵/公式 + 去重 + 封顶，对足迹投影综测得分单。
示例：rules/重庆城市科技学院-计网学院-2026-2027.json（参考实现，非系统依赖）。

## 4. 技术选型

Tauri 2 + React 18 + TypeScript + Vite + Tailwind + shadcn/ui + SQLite(rusqlite, FTS5) + ECharts

- 配置驱动 UI：动态表单/动态筛选器/动态看板全部由上述配置表渲染
- 备选：Electron + better-sqlite3（数据层一致可互换）

## 5. 输出

- 任意视图/筛选结果 → xlsx 汇总表（列与分组来自 export_template）
- 勾选条目 → 佐证材料包 zip（编号命名规则可配）
- 适配器激活时 → 综测得分单 + 加分明细对账单
- V3：评优事迹 Word、简历段生成

## 6. 迭代路线

- MVP：类型管理 + 动态表单 + footprint CRUD + 时间线 + FTS 检索 + 附件 + taxonomy + 标签
- V2：维度/指标/视图/导出模板、事件归组聚合、成绩导入、xlsx/佐证包
- V3：评分适配器、AI 字段抽取、评优 Word、同步备份

## 9. 账号系统与多端互通（v0.5 新增）

### 9.1 定位

单人系统中账号 = 同步身份（多端识别 + 云备份 + 未来协作扩展点），不是数据前提。
未登录 = 纯本地模式（现状完全不变），登录后多端打通。

### 9.2 路线选型

| | A 整库文件同步 | B 云优先 | C 本地优先+同步引擎（选定） |
|---|---|---|---|
| 离线 | 可用 | 差 | 完全可用 |
| 冲突 | 整库覆盖丢数据 | 服务端事务 | 行级合并可控 |
| 改造 | 极低 | 高 | 中（数据层+同步模块） |
| 附件 | 易碎 | 对象存储 | 内容寻址+对象存储 |

### 9.3 数据层改造（P1）

```sql
-- 业务表统一增加同步元数据
uuid TEXT;          -- uuid v7（时间有序），替代自增 ID 的跨端身份
deleted_at TEXT;    -- 软删除墓碑，删除也要同步
hlc TEXT;           -- 混合逻辑时钟 "毫秒:计数:设备号"，冲突仲裁依据
origin TEXT;        -- 创建设备

-- 本地变更日志（推送队列）
CREATE TABLE sync_oplog (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  table_name TEXT NOT NULL,
  row_uuid TEXT NOT NULL,
  op TEXT NOT NULL,            -- upsert / delete
  hlc TEXT NOT NULL,
  synced_at TEXT               -- NULL = 待推送
);
```

- 自增 ID 换 UUID（v7）：两台设备各自自增必然冲突
- HLC 而非本地时间：时钟回拨免疫，跨设备可比较、同设备单调
- 删除走墓碑：硬删除无法向其他设备传播

### 9.4 同步协议（P2）

- push：本地 oplog 未同步变更 → 服务端按 hlc LWW 仲裁 upsert
- pull：GET /sync?cursor=服务端hlc → 应用比自己新的行 → 推进游标
- 附件：SHA-256 内容寻址；上传前查重；本地按需缓存（同一佐证多处引用只存一份）

### 9.4.1 附件与图片存储布局

本地（桌面端）：
```
应用数据目录/
├─ footprints.db                  ← 元数据（rel_path/sha256/size/mime + 同步元数据）
└─ attachments/{记录id}/{uuid}_{原文件名}   ← 图片实体原样保存（EXIF 保留）
```

服务器（sync-server）：
```
data/
├─ sync.db                        ← attachments 表 (user_id, sha256) 主键
└─ blobs/{user_id}/{sha256}       ← 内容寻址，跨记录/跨设备去重
```

生命周期：添加 → 本地落盘+元数据入 oplog → push 元数据 → 服务器缺 blob 则补传（哈希校验）
→ 其他端 pull 元数据 → 按需下载。删除 → 元数据墓碑同步，文件延迟 GC（全端确认后回收）。

演进方向：缩略图（256px WebP，网格用缩略图）、大文件分片、可选上传压缩、对象存储适配、E2E 加密。
- 触发：启动 + 写操作后 debounce 3s + 手动同步
- 冲突：按行 LWW（单人多端最优）；不做 CRDT

### 9.5 身份层

- 登录：邮箱魔法链接或手机验证码；本地设备 ID 注册
- 凭据：Tauri keyring（Windows Credential Manager）
- 设备管理：device_id ↔ 设备名，可远程下线
- 未登录：同步模块整体旁路，界面显示"本地模式"

### 9.6 服务端选型

| | BaaS（火山引擎 Supabase 版） | 自建轻量服务 |
|---|---|---|
| Auth/DB/存储/Realtime | 全部现成 + RLS 行级权限 | 自管 Postgres + MinIO/OSS |
| 同步实现 | 客户端直连表 + hlc 游标 | 单 /sync 模块 |
| 运维 | 免运维，起步免费 | 一台服务器 |
| 适用 | 快速落地（推荐） | 数据完全自持 |

### 9.7 安全分层

1. 基线：TLS + 服务端账号隔离（RLS）
2. 进阶：本地库 SQLCipher
3. 可选端到端：客户端加密后再上云（代价是服务端不可检索）

### 9.8 分阶段落地

| 阶段 | 内容 | 产出 | 状态 |
|---|---|---|---|
| P1 | UUID/软删除/HLC/oplog + 存量迁移（纯本地） | 同步地基，功能不变 | **已实现**（Node 与 Rust 双端一致） |
| P1.5 | 导出加密同步包手动导入合并 | 无后端的手动多端 | 待做（可选） |
| P2 | 自建同步服务：登录 + push/pull + 附件 hash 上传 | 真正多端互通 | **服务端已实现**（sync-server/，Docker 部署）；客户端引擎待接 |
| P3 | Web 端复用 React 前端；移动端 PWA | 随时随地 | **前端响应式 + PWA 改造完成**（manifest/SW/抽屉导航），待服务部署后直连 |
| P4 | 端到端加密；多人协作（复用审核流设计） | 班级/学院版 | 待做 |

### 9.9 自建同步服务实现（sync-server/，v0.2 新增）

- 零 npm 依赖：node:http + node:sqlite，Docker 镜像 node:24-alpine，构建无供应链风险
- 存储模型：`current`（每行最新态，user+table+row_uuid 唯一）+ `changes`（全量历史，seq 全局单调即拉取游标）
- push：按 HLC 三元组（毫秒:计数:设备）逐级比较 LWW；旧推送计入 stale；服务端不解释业务字段（data 为不透明 JSON，业务表间引用由客户端以 uuid 表达）
- pull：`updated_seq > cursor` 增量，游标由服务端 seq 保证单调
- 附件：(user, sha256) 内容寻址去重，上传校验实际哈希，跨设备仅存一份
- 认证：scrypt 口令散列 + Bearer token（365 天）+ 设备登记（同名设备复用 device_id）；REGISTER_ENABLED 环境变量控制注册开关
- 多用户：天然按 user_id 隔离（变更/附件/设备）；INVITE_CODE 邀请码注册 + MAX_USERS 名额上限 + ADMIN_TOKEN 保护的 /admin/users 管理视图（仅元数据，档案内容管理员不可见）
- 客户端多账号（P2）：登录/切换账号，本地档案按账号建独立 SQLite profile
- 部署：`cd sync-server && docker compose up -d --build`，数据落 ./data/；必须经 HTTPS 反代（Caddy 示例见 sync-server/README.md）

### 9.10 验证状态（诚实边界）

已验证（自动化测试）：
- 服务端协议：注册/登录/多用户/邀请码/名额/管理视图/push(LWW)/pull(游标)/附件去重/账号隔离 —— 全链路通过
- Node 数据层：53 项回归（CRUD/守卫/FTS/墓碑/级联/oplog）—— 通过
- Rust 后端：9 项运行时测试（uuid v7/HLC 单调/时钟回拨/老库迁移/命令层往返/墓碑/级联/重名守卫/加权计算）—— 通过

测试曾抓出并已修复的关键缺陷：
- Rust exec() 返回"受影响行数"而非 lastInsertRowid，导致桌面端所有创建操作拿到 id=1（关键级）
- Rust footprint_list 的 BASE_SELECT 与 build_where 双 WHERE 拼接导致检索 SQL 报错
- 学期删除未级联墓碑课程，孤儿课程污染总览

尚未闭环（诚实声明）：
- 客户端同步引擎（P2）未实现：桌面/手机目前均为纯本地，尚无数据真正流向服务器
- FK 的 uuid 映射约定已定稿（载荷中业务表间引用以 uuid 表达），代码随 P2 实现
- 真实双设备并发、附件 GC、备份恢复等长尾场景待真机验证

P1 实现说明（v0.2）：
- schema v2：9 张业务表统一 uuid/deleted_at/origin/hlc 列 + sync_state + sync_oplog + uuid 唯一索引
- 老库迁移幂等：pre_migrate（补列，先于 schema 执行）→ schema → backfill（uuid/hlc/origin）
- 所有写路径接 oplog（Node 与 Rust 26 命令一致）：变更先进本地队列，P2 推送直接消费
- 删除统一软删除（墓碑）；FTS 内容表在删除时同步清理
- 附件新增 sha256 内容寻址列，为 P2 去重上传就绪
- 新增 sync_status 命令与侧边栏同步状态显示（本地模式 · 待同步 N）