文档

README.md

命令清单与 Makefile 里的目标一一对应；端口与变量名与 .env.example 一致。把字数控制在 80 行以内。

# 笔记服务

一句话说明这个服务做什么、给谁用。

## 环境要求

- Go 1.22 或更高（以 go.mod 为准）
- Docker 与 Docker Compose

## 启动

1. cp .env.example .env
2. 生成会话密钥并填进 .env：openssl rand -base64 32
3. docker compose up --build -d

端口默认 8080，改 .env 里的 WEB_PORT。
打开 http://localhost:8080/healthz 应返回 200。

## 常用命令

- make check              本地与持续集成跑同一条检查
- make fmt                排版，会改文件
- make layout             顶层目录白名单检查
- make migrations         迁移文件命名与成对检查
- make migrate-roundtrip  迁移上、全部下、再上（只对测试库跑）

## 文档在哪

- 决议：docs/decisions/
- 验收：docs/notes-check.md
- 接口：docs/api-notes.md

目录结构不在这里重复，见 docs/decisions/0035-layout.md。

docs/notes-check.md

读者是不认识这个项目的人，他只使用仓库和本篇，不依赖口头补充。状态码与日志字段与接口、日志两页保持一致。

# 笔记读取验收

读者：核对接口和页面的人。只使用仓库和本篇，不依赖口头补充。

前置：
- 已按 README 启动。
- 所属范围 A、B 各有一个账号，各有一条标题不同的笔记。
- 无依据的页面原句以本篇「没有依据」一节为准。

## 本范围可以读到

1. 用所属范围 A 的账号登录。
2. 打开该范围的一条笔记。
3. 期望：状态码 200，响应或页面中有这条标题。

## 其他范围读不到

1. 保持所属范围 A 的登录。
2. 请求一条已知属于所属范围 B 的 id。
3. 期望：状态码 404，正文与「id 不存在」相同，不出现所属范围 B 的标题。
4. 日志中有 cross-scope access denied，并带有两个不同的 scope_id。

## 没有依据

1. 用一段材料中不存在的问题做检索。
2. 期望：结果为无依据的原句，不出现材料里没有的讲解，
   本轮不调用对话模型。

## 留档

命令、退出码、端口、字符集记在本节下方，与本次验收的日期一起提交。

助手交出来的样子

## 验收标准
- 登录体验良好
- 数据安全
- 性能满足要求

scripts/check-doc-sync.sh

前五行自动检查。它在合并请求的检出目录里运行，BASE 默认 main。规则写成「触及左边就必须出现右边」，所以要放宽时改的是这个文件，评审会看到。

#!/bin/sh
# 文档同步检查：改动触及左边的路径时，右边必须出现在同一次改动里。
changed=$(git diff --name-only "origin/${BASE:-main}...HEAD")
status=0

check() {
    if echo "$changed" | grep -qE "$1"; then
        if ! echo "$changed" | grep -qE "$2"; then
            echo "文档未同步：改动命中 /$1/，但 /$2/ 未更新"
            status=1
        fi
    fi
}

check '^\.env\.example$'                                  '^README\.md$'
check '^migrations/'                                      '^(docs/|internal/.*_test\.go)'
check '^(pyproject\.toml|\.golangci\.yml|\.github/workflows/)' '^docs/decisions/'
check '^scripts/check-layout\.sh$'                        '^docs/decisions/0034-layout\.md$'
check '^internal/http/'                                   '^docs/'

exit $status

Makefile（并进 check）

本地跑时基线取 main，所以先 git fetch origin main 再跑。BASE 可以在持续集成里改成合并目标分支。make check 的聚合入口只在质量门禁里定义一次，这一页只加子目标。

.PHONY: docsync docs-check

docsync:
	sh scripts/check-doc-sync.sh

# 挂进 check：check: fmt-check lint type docs-check secret complexity test
docs-check: docsync
	ruff check --output-format=concise .

仓库内链接检查

它只检查仓库内的相对链接。不检查外网链接——外网会因为网络和限流误报，每次都红会让人开始忽略这条检查。

lychee --offline --no-progress README.md 'docs/**/*.md'