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
This commit is contained in:
root
2026-10-17 22:27:56 +08:00
parent 88525a3f9f
commit 8cdf8b44fa
8 changed files with 207 additions and 73 deletions
+21 -7
View File
@@ -11,27 +11,41 @@
## 开发流程
1. Fork / 建分支:`git checkout -b feat/your-feature`
2. 提交信息用约定式前缀:`feat: / fix: / docs: / chore: / ci: / refactor:`
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
node scripts/test-integration.mjs # 61 条集成断言
```
启用钩子后,push 会自动跑同一套检查;工作区有未提交变更或测试失败时 push 会被拒绝。
## 约定
- 服务端保持**零 npm 依赖**(只用 Node 内置模块);确需引入依赖请先开 Issue 讨论
- 改动 `app/server/db.mjs`(命令层)时注意:Web / 桌面 / 播种三处共用它,测试必须全绿
- 涉及 schema 变更:保证老库能平滑迁移(参考 `preMigrateColumns` 的加列模式),并在
`scripts/test-integration.mjs` 补断言
- **服务端保持零 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`)
- 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× 的回退需要说明必要性(一般值得换改造思路)。