docs: reword comments and protocol descriptions for readability

db/migrations/00001_schema.sql

@@ -1,5 +1,5 @@
 -- +goose Up
--- 可选的文本值在没有或不适用时为 NULL；空串只表示值本身为空，例如被清空的房间描述。
+-- 可选的文本值没有或不适用时为 NULL。空串只表示值本身为空，例如被清空的房间描述。
 CREATE TABLE members (
     id uuid PRIMARY KEY DEFAULT uuidv7(),
     token_hash bytea NOT NULL UNIQUE,
@@ -15,12 +15,12 @@ CREATE TABLE rooms (
     name text NOT NULL,
     description text NOT NULL,
     password_hash text,
-    -- 接管房间时加 1；落盘以它为条件，因此过期的 owner 无法写入。
+    -- 每次接管房间时加 1。落盘以 term 为条件，所以过期的 owner 无法写入。
     term bigint NOT NULL DEFAULT 0,
     play_mode text NOT NULL DEFAULT 'sequential' CHECK (play_mode IN ('sequential', 'random', 'rotation')),
     entry_seq bigint NOT NULL DEFAULT 0,
     created_at timestamptz NOT NULL DEFAULT now(),
-    -- 第一次生成 API Key 时创建，此后重置 Key、修改密码都不换。
+    -- bot 成员在第一次生成 API Key 时创建，之后重置 Key、修改密码都不会更换。
     bot_member_id uuid REFERENCES members,
     CHECK (bot_member_id IS NULL OR kind = 'persistent')
 );
@@ -46,7 +46,7 @@ CREATE TABLE room_entries (
     added_at timestamptz NOT NULL,
     started_at timestamptz CHECK ((slot = 'current') = (started_at IS NOT NULL)),
     page_url text NOT NULL,
-    -- 条目的轮次在入队时定下，轮流播放时点赞数相同的歌按它排列。
+    -- 条目的轮次在入队时定下。轮流播放时，点赞数相同的歌按轮次排列。
     round bigint NOT NULL DEFAULT 0,
     PRIMARY KEY (room_id, entry_id)
 );
@@ -105,7 +105,7 @@ CREATE TABLE credentials (
     updated_at timestamptz NOT NULL DEFAULT now()
 );
 
--- 至多一行；没有这一行时品牌名是默认的 Alisten。
+-- site 表至多一行。没有这一行时，品牌名是默认的 Alisten。
 CREATE TABLE site (
     id boolean PRIMARY KEY DEFAULT true CHECK (id),
     brand_name text NOT NULL

db/migrations/00003_member_accounts.sql

@@ -16,7 +16,7 @@ WHERE NOT EXISTS (SELECT FROM rooms r WHERE r.bot_member_id = m.id);
 ALTER TABLE members DROP COLUMN token_hash;
 
 -- 设置了用户名的成员是已注册的账号，否则是游客。用户名只能由小写字母、数字、下划线和连字符组成，所以按原文唯一即可。
--- 邮箱属于账号，在所有设备上一致；游客没有账号，不替匿名身份保存个人信息，邮箱只存在游客自己的浏览器里。
+-- 邮箱属于账号，在所有设备上一致。游客没有账号，不替匿名身份保存个人信息，所以游客的邮箱只存在游客自己的浏览器里。
 ALTER TABLE members
     ADD COLUMN username text UNIQUE,
     ADD COLUMN password_hash text,
@@ -24,7 +24,7 @@ ALTER TABLE members
     ADD COLUMN email text,
     ADD CONSTRAINT members_email_check CHECK (email IS NULL OR username IS NOT NULL);
 
--- site 表没有行或者 brand_name 为 NULL 时，品牌名是默认的 Alisten；没有行时开放注册。
+-- site 表没有行或者 brand_name 为 NULL 时，品牌名是默认的 Alisten。site 表没有行时开放注册。
 ALTER TABLE site
     ALTER COLUMN brand_name DROP NOT NULL,
     ADD COLUMN registration_open boolean NOT NULL DEFAULT true;

db/migrations/00004_playlists.sql

@@ -2,7 +2,7 @@
 CREATE TABLE playlists (
     id uuid PRIMARY KEY DEFAULT uuidv7(),
     owner_id uuid NOT NULL REFERENCES members ON DELETE CASCADE,
-    -- 每个账号恰好一个“我喜欢”：注册时创建，不能改名或删除。
+    -- 每个账号恰好有一个“我喜欢”，在注册时创建，不能改名或删除。
     kind text NOT NULL CHECK (kind IN ('favorites', 'custom')),
     name text NOT NULL,
     -- 新加入的曲目取 item_seq + 1 作为排序值，排在最前。
@@ -15,7 +15,7 @@ CREATE TABLE playlists (
 CREATE INDEX ON playlists (owner_id);
 CREATE UNIQUE INDEX ON playlists (owner_id) WHERE kind = 'favorites';
 
--- 展示用的元数据存一份快照：歌单里的歌不一定准备过，tracks 表里可能没有。
+-- 展示用的元数据存一份快照，因为歌单里的歌不一定准备过，tracks 表里可能没有。
 CREATE TABLE playlist_items (
     playlist_id uuid NOT NULL REFERENCES playlists ON DELETE CASCADE,
     source text NOT NULL,

db/migrations/00005_listens.sql

@@ -2,7 +2,7 @@
 -- 关闭之后不再记录新的播放历史，已有的保留。
 ALTER TABLE members ADD COLUMN record_listens boolean NOT NULL DEFAULT true;
 
--- 成员在房间里听到过的歌，每首只留最近一次。元数据存一份快照，不关联 tracks：管理员删除已存储的媒体时会连带删掉 tracks 中对应的行。
+-- 成员在房间里听到过的歌，每首只留最近一次。元数据存一份快照，不关联 tracks，因为管理员删除已存储的媒体时会连带删掉 tracks 中对应的行。
 CREATE TABLE listens (
     member_id uuid NOT NULL REFERENCES members ON DELETE CASCADE,
     source text NOT NULL,

db/migrations/00006_playlist_shares.sql

@@ -1,3 +1,3 @@
 -- +goose Up
--- 分享链接中的随机串，NULL 表示没有分享。明文保存：所有者随时可以再复制一次链接。
+-- 分享链接中的随机串，NULL 表示没有分享。明文保存，这样所有者随时可以再复制一次链接。
 ALTER TABLE playlists ADD COLUMN share_id text UNIQUE;

db/migrations/00007_member_github.sql

@@ -1,5 +1,5 @@
 -- +goose Up
--- 绑定了 GitHub 的成员也是已注册的账号，可以没有用户名和密码；账号的邮箱因此也可以属于只绑定了 GitHub 的成员。
+-- 绑定了 GitHub 的成员也是已注册的账号，可以没有用户名和密码。所以账号的邮箱也可以属于只绑定了 GitHub 的成员。
 ALTER TABLE members
     ADD COLUMN github_id bigint UNIQUE,
     DROP CONSTRAINT members_email_check,

db/queries/apikeys.sql

@@ -1,6 +1,6 @@
 -- name: LockRoomBot :one
--- 用互斥的 FOR NO KEY UPDATE，不用 FOR SHARE：同一个房间的重置要依次进行，
--- 同时到达的首次生成才只会创建一个 bot 成员，最后只留下一把 Key。
+-- 用互斥的 FOR NO KEY UPDATE，不用 FOR SHARE，因为同一个房间的重置要依次进行。
+-- 这样同时到达的首次生成只会创建一个 bot 成员，最后只留下一把 Key。
 SELECT bot_member_id FROM rooms WHERE id = @id FOR NO KEY UPDATE;
 
 -- name: SetRoomBot :exec

db/queries/history.sql

@@ -1,5 +1,5 @@
 -- name: AutoDJSeeds :many
--- 只看最近 1000 次播放：按 plays (room_id, started_at) 的索引倒序读到 1000 行就停，耗时与历史的长度无关。
+-- 只看最近 1000 次播放。查询按 plays (room_id, started_at) 的索引倒序读，读到 1000 行就停，所以耗时与历史的长度无关。
 SELECT track_id FROM (
     SELECT DISTINCT ON (track_id) track_id, tier, rank
     FROM (

db/queries/listens.sql

@@ -1,6 +1,6 @@
 -- name: LockListeners :many
--- 按 ID 的顺序锁住开启了记录的成员：同一个成员的历史依次写入，删掉超出上限的部分时不会多删或少删；
--- 加锁的顺序固定，同时写几个成员的事务之间不会死锁。
+-- 按 ID 的顺序锁住开启了记录的成员。这样同一个成员的历史依次写入，删掉超出上限的部分时不会多删或少删。
+-- 加锁的顺序固定，所以同时写几个成员的事务之间不会死锁。
 SELECT id FROM members WHERE id = ANY(@ids::uuid[]) AND record_listens ORDER BY id FOR NO KEY UPDATE;
 
 -- name: UpsertListens :exec
@@ -14,7 +14,7 @@ SET title = excluded.title, artist = excluded.artist, album = excluded.album, co
     heard_at = greatest(listens.heard_at, excluded.heard_at);
 
 -- name: MoveListens :exec
--- 并入的规则与 UpsertListens 相同，并入的那份算新写入的；to_id 关闭了记录时只删不并。
+-- 并入的规则与 UpsertListens 相同，并入的那份算新写入的。to_id 关闭了记录时只删不并。
 WITH moved AS (
     DELETE FROM listens WHERE member_id = sqlc.arg(from_id)::uuid
     RETURNING source, track_id, title, artist, album, cover_url, cover_key, duration_ms, page_url, heard_at
@@ -29,7 +29,7 @@ SET title = excluded.title, artist = excluded.artist, album = excluded.album, co
     heard_at = greatest(listens.heard_at, excluded.heard_at);
 
 -- name: TrimListens :exec
--- 排序与 MemberListens 相同：留下的正是读取时返回的那些。
+-- 排序与 MemberListens 相同，所以留下的正是读取时返回的那些。
 DELETE FROM listens l
 USING (
     SELECT member_id, source, track_id,

db/queries/members.sql

@@ -9,7 +9,7 @@ INSERT INTO member_sessions (token_hash, member_id) VALUES (@token_hash, @member
 SELECT * FROM members WHERE id = (SELECT member_id FROM member_sessions WHERE token_hash = @token_hash);
 
 -- name: UpdateMember :one
--- 只覆盖传入的列，分别修改昵称和头像的两个并发请求因此不会互相还原；头像哈希和邮箱传入空串表示清除。游客的邮箱总是 NULL。
+-- 只覆盖传入的列，所以分别修改昵称和头像的两个并发请求不会互相还原。头像哈希和邮箱传入空串表示清除。游客的邮箱总是 NULL。
 UPDATE members
 SET name = coalesce(sqlc.narg(name), name),
     avatar_hash = CASE WHEN sqlc.narg(avatar_hash)::text IS NULL THEN avatar_hash ELSE NULLIF(sqlc.narg(avatar_hash)::text, '') END,
@@ -21,12 +21,12 @@ RETURNING *;
 SELECT username, email, github_id FROM members WHERE id = @id;
 
 -- name: RegisterMember :execrows
--- 只给游客设置。只绑定了 GitHub 的账号补设用户名和密码要删除其他会话，用 AddMemberCredentials。
+-- 只给游客设置。只绑定了 GitHub 的账号补设用户名和密码时还要删除其他会话，所以用 AddMemberCredentials。
 UPDATE members SET username = @username, password_hash = @password_hash
 WHERE id = @id AND username IS NULL AND github_id IS NULL;
 
 -- name: AddMemberCredentials :execrows
--- 只给只绑定了 GitHub 的账号设置，它的“我喜欢”已经在绑定时创建了。
+-- 只给只绑定了 GitHub 的账号设置。这种账号的“我喜欢”已经在绑定时创建了。
 UPDATE members SET username = @username, password_hash = @password_hash
 WHERE id = @id AND username IS NULL AND github_id IS NOT NULL;
 
@@ -40,7 +40,7 @@ SELECT * FROM members WHERE id = @id AND (username IS NOT NULL OR github_id IS N
 SELECT * FROM members WHERE github_id = @github_id;
 
 -- name: BindGitHub :one
--- 只给还没有绑定 GitHub 的成员绑定，已经绑定过的成员不受影响，没有返回的行。was_guest 表示成员原来是游客：这次绑定就是注册。
+-- 只给还没有绑定 GitHub 的成员绑定。已经绑定过的成员不受影响，查询没有返回的行。was_guest 表示成员原来是游客，这次绑定就是注册。
 UPDATE members SET github_id = @github_id
 WHERE id = @id AND github_id IS NULL
 RETURNING (username IS NULL)::boolean AS was_guest;
@@ -53,15 +53,15 @@ UPDATE members SET github_id = NULL WHERE id = @id AND password_hash IS NOT NULL
 UPDATE members SET password_hash = @password_hash WHERE id = @id AND username IS NOT NULL;
 
 -- name: LockAccountPassword :one
--- 用互斥的 FOR NO KEY UPDATE，不用 FOR SHARE：同一个账号的修改和重置依次进行，后一个读到的是前一个写入的密码哈希。
+-- 用互斥的 FOR NO KEY UPDATE，不用 FOR SHARE。这样同一个账号的修改和重置依次进行，后一个读到的是前一个写入的密码哈希。
 SELECT coalesce(password_hash, '')::text AS password_hash FROM members WHERE id = @id AND username IS NOT NULL FOR NO KEY UPDATE;
 
 -- name: MemberHasSession :one
 SELECT EXISTS (SELECT FROM member_sessions WHERE token_hash = @token_hash AND member_id = @member_id);
 
 -- name: LockMemberPassword :one
--- 让修改密码等到这次登录提交之后，它随后删除会话时会删掉这次登录签发的会话。
--- 用互斥的 FOR NO KEY UPDATE，不用 FOR SHARE：同一个账号的几次登录依次并入游客的历史，否则两边会按相反的顺序抢同一批历史行而死锁。
+-- 这把锁让修改密码等到这次登录提交之后才进行，所以修改密码随后删除会话时，会删掉这次登录签发的会话。
+-- 用互斥的 FOR NO KEY UPDATE，不用 FOR SHARE，这样同一个账号的几次登录会依次并入游客的历史。否则两次登录会按相反的顺序抢同一批历史行而死锁。
 SELECT coalesce(password_hash, '')::text AS password_hash FROM members WHERE id = @id FOR NO KEY UPDATE;
 
 -- name: DeleteSession :execrows

db/queries/playlists.sql

@@ -17,7 +17,7 @@ WHERE p.owner_id = @owner_id AND (i.cover_url IS NOT NULL OR i.cover_key IS NOT
 ORDER BY i.playlist_id, i.position DESC;
 
 -- name: LockFavorites :exec
--- 新建歌单前锁住这个账号的“我喜欢”：同一个账号并发新建时依次计数，不会越过上限。
+-- 新建歌单前锁住这个账号的“我喜欢”，这样同一个账号并发新建时会依次计数，不会越过上限。
 SELECT id FROM playlists WHERE owner_id = @owner_id AND kind = 'favorites' FOR UPDATE;
 
 -- name: CountPlaylists :one
@@ -37,7 +37,7 @@ UPDATE playlists SET name = @name, updated_at = now() WHERE id = @id AND owner_i
 DELETE FROM playlists WHERE id = @id AND owner_id = @owner_id AND kind = 'custom';
 
 -- name: LockPlaylist :one
--- 改动曲目前锁住歌单：并发加入时依次检查上限、分配排序值。删除歌单先锁歌单行再级联删除曲目，其他操作也要先锁歌单再动曲目，否则会互相死锁。
+-- 改动曲目前锁住歌单，这样并发加入时会依次检查上限、分配排序值。删除歌单时先锁歌单行再级联删除曲目，所以其他操作也要先锁歌单再动曲目，否则会互相死锁。
 SELECT item_seq FROM playlists WHERE id = @id AND owner_id = @owner_id FOR UPDATE;
 
 -- name: PlaylistHasItem :one
@@ -71,7 +71,7 @@ WITH deleted AS (
 UPDATE playlists SET updated_at = now() WHERE id IN (SELECT playlist_id FROM deleted);
 
 -- name: CopyPlaylistItems :execrows
--- 按请求的先后复制：第一首的排序值最大。请求里重复的歌只取第一次出现的位置。
+-- 按请求的先后顺序复制，第一首的排序值最大。请求里重复的歌只取第一次出现的位置。
 WITH wanted AS (
     SELECT s.source, k.track_id, min(s.ord) AS ord
     FROM unnest(@sources::text[]) WITH ORDINALITY AS s(source, ord)
@@ -119,7 +119,7 @@ JOIN members m ON m.id = p.owner_id
 WHERE p.share_id = sqlc.arg(share_id)::text;
 
 -- name: CopySharedPlaylistItems :one
--- 确认分享还在和复制曲目在同一条语句里，看到的是同一个快照：要么完整复制，要么读不到分享。不锁来源歌单：两个人同时复制
+-- 确认分享还在和复制曲目放在同一条语句里，两者看到的是同一个快照，所以要么完整复制，要么读不到分享。不锁来源歌单，因为两个人同时复制
 -- 对方分享的“我喜欢”时，各自已经锁住了自己的“我喜欢”，再去锁对方的就会互相等待。
 WITH shared AS (
     SELECT id FROM playlists WHERE share_id = sqlc.arg(share_id)::text

db/queries/tickets.sql

@@ -1,5 +1,5 @@
 -- name: LockRoomPassword :one
--- FOR SHARE 让修改密码和删除房间等到这次签发提交之后，它们随后删除票据时会删掉这一张。
+-- FOR SHARE 让修改密码和删除房间等到这次签发提交之后才进行。这样两者随后删除票据时，会把这一张也删掉。
 SELECT coalesce(password_hash, '')::text AS password_hash FROM rooms WHERE id = @id FOR SHARE;
 
 -- name: CreateTicket :exec

db/queries/tracks.sql

@@ -3,7 +3,7 @@ SELECT title, artist, album, cover_url, cover_key, page_url, duration_ms, gain,
 WHERE source = @source AND track_id = @track_id;
 
 -- name: SavePreparedTrack :exec
--- 准备任务只对未完成的任务去重，同一首歌可能先后准备两次，以后一次的结果为准。
+-- 准备任务只对未完成的任务去重，所以同一首歌可能先后准备两次，以后一次的结果为准。
 INSERT INTO tracks (source, track_id, title, artist, album, cover_url, cover_key, page_url, duration_ms, gain, lyric, lyric_words, lyric_trans, media_key, media_size)
 VALUES (@source, @track_id, @title, @artist, @album, @cover_url, @cover_key, @page_url, @duration_ms, @gain, @lyric, @lyric_words, @lyric_trans, @media_key, @media_size)
 ON CONFLICT (source, track_id) DO UPDATE SET