# 贡献指南

欢迎 Issue 与 PR！开始之前：

## 环境要求

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

## 开发流程

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

```bash
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`](docs/SECURITY.md) 的渠道，勿在公开 Issue 贴 PoC 细节

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

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

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

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