Files

T

root 8cdf8b44fa docs: refresh public docs for current codebase, add SECURITY.md

- README: real counts (44 commands, 61 integration asserts, demo=25 records
  + 4 semesters + 7 attachments), add resume/assessment module features,
  env vars incl. LSKY, doc navigation table, done-roadmap items checked
- docs/api.md: /auth/logout, admin users/demo-rebuild/sync-lsky routes,
  attachment thumb/download channels, profile_upsert top-key merge
  semantics, full footprint_list query reference, 44-command table
- sync-server/README: replace stale ADMIN_TOKEN/X-Admin-Token admin section
  (actual is_admin Bearer model), add go-live checklist, backup note for WAL
- CHANGELOG: add Unreleased section (resume/assessment modules, security
  fixes, perf tuning)
- CONTRIBUTING: 61 asserts, security-sensitive-change guidance, perf baseline
  table, security issue routing
- docs/SECURITY.md: new - report channel, threat model table, hardening
  summary, known tradeoffs
- LICENSE: ensure MIT file matches README badge

2026-10-17 22:27:56 +08:00

2.3 KiB

Raw Blame History

贡献指南

欢迎 Issue 与 PR！开始之前：

环境要求

Node.js ≥ 22.5（推荐 24，node:sqlite 依赖）
前端构建：npm 或 pnpm
桌面端构建（可选）：Rust stable + MSVC Build Tools（Windows）

开发流程

Fork / 建分支：git checkout -b feat/your-feature
提交信息用约定式前缀：feat: / fix: / docs: / chore: / ci: / refactor: / security: / perf:
本地跑绿再推：

git config core.hooksPath .githooks   # 每个克隆只需一次
node scripts/check.mjs
node scripts/test-integration.mjs     # 61 条集成断言

启用钩子后，push 会自动跑同一套检查；工作区有未提交变更或测试失败时 push 会被拒绝。

约定

服务端保持零 npm 依赖（只用 Node 内置模块）；确需引入依赖请先开 Issue 讨论
改动 app/server/db.mjs（命令层）时注意：Web / 桌面 / 播种三处共用它，测试必须全绿；新增命令顺手在 docs/api.md 补一行
涉及 schema 变更：保证老库能平滑迁移（参考 schema.sql IF NOT EXISTS / preMigrateColumns 的加列模式），并在 scripts/test-integration.mjs 补断言
涉及 Service Worker：接口类请求（/api /auth /admin /sync）永远不得缓存
UI 改动请同时适配亮/暗两套主题（令牌见 app/src/styles/theme.css），并兼顾移动端（390px 宽）与浏览器打印样式
安全敏感路径（认证/上传/管理/导出）请说明改动思路；过滤、白名单优先于黑名单；欢迎补 PoC 级测试（参考 docs/SECURITY.md 的字段表）

Issue

Bug 报告请附：复现步骤、期望/实际行为、服务端日志（docker logs footprints-sync）
功能建议请说明使用场景，最好附上你期望的记录/检索形态
安全问题请走 docs/SECURITY.md 的渠道，勿在公开 Issue 贴 PoC 细节

性能基线（改数据层请起压测）

命令层基准（3000 条记录、PC 单机）：

命令	耗时
footprint_list（2000 条一页）	≤23ms
timeline	≤22ms
单条 footprint_upsert	≈0.3ms

回归手动基准：node .tmp-perf/bench.mjs 模式（见 git 历史样例）；引入 >2× 的回退需要说明必要性（一般值得换改造思路）。

2.3 KiB Raw Blame History Unescape Escape