基础项目

server/.ai-specs/doc-sql/book.sql

@@ -0,0 +1,66 @@
+-- # 书籍信息表
+--
+-- ## 基本信息
+--
+-- 模块：book
+-- 表名：book
+-- 模型：model/book/book.go
+-- 迁移接入：initialize/gorm_biz.go
+-- 删除策略：硬删表
+-- 书籍类型字典：book_type
+-- 时代标签字典：book_era_tag
+-- 完结状态字典：book_completion_status
+-- 上下架状态字典：book_publish_status
+-- 职责：承载书籍主资料、展示聚合值和章节来源配置，是书籍列表、详情、搜索和推荐的核心主体。
+
+CREATE TABLE book (
+  id bigserial PRIMARY KEY,
+  created_at timestamp with time zone NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at timestamp with time zone NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  title varchar(255) NOT NULL,
+  subtitle varchar(255),
+  book_type varchar(64) NOT NULL,
+  era_tag varchar(32) NOT NULL DEFAULT 'unknown',
+  cover_url varchar(500),
+  publisher varchar(128),
+  published_at date,
+  intro text,
+  hot_score bigint NOT NULL DEFAULT 0 CHECK (hot_score >= 0),
+  rating numeric(3,1) NOT NULL DEFAULT 0.0 CHECK (rating >= 0 AND rating <= 10),
+  comment_count bigint NOT NULL DEFAULT 0 CHECK (comment_count >= 0),
+  word_count bigint NOT NULL DEFAULT 0 CHECK (word_count >= 0),
+  completion_status varchar(32) NOT NULL DEFAULT 'serializing',
+  publish_status varchar(32) NOT NULL DEFAULT 'draft',
+  series_id bigint,
+  series_sort integer NOT NULL DEFAULT 0 CHECK (series_sort >= 0),
+  raw_txt_url varchar(500)
+);
+
+COMMENT ON TABLE book IS '书籍信息表';
+COMMENT ON COLUMN book.id IS '主键';
+COMMENT ON COLUMN book.created_at IS '创建时间';
+COMMENT ON COLUMN book.updated_at IS '更新时间';
+COMMENT ON COLUMN book.title IS '书名主标题';
+COMMENT ON COLUMN book.subtitle IS '书籍副标题';
+COMMENT ON COLUMN book.book_type IS '书籍类型字典值，对应 book_type';
+COMMENT ON COLUMN book.era_tag IS '时代标签字典值，对应 book_era_tag';
+COMMENT ON COLUMN book.cover_url IS '封面图片 URL';
+COMMENT ON COLUMN book.publisher IS '出版社名称';
+COMMENT ON COLUMN book.published_at IS '出版日期';
+COMMENT ON COLUMN book.intro IS '书籍简介';
+COMMENT ON COLUMN book.hot_score IS '热度聚合值';
+COMMENT ON COLUMN book.rating IS '书籍评分，范围 0-10';
+COMMENT ON COLUMN book.comment_count IS '点评数聚合值';
+COMMENT ON COLUMN book.word_count IS '书籍总字数';
+COMMENT ON COLUMN book.completion_status IS '书籍完结状态字典值，对应 book_completion_status';
+COMMENT ON COLUMN book.publish_status IS '书籍上下架状态字典值，对应 book_publish_status';
+COMMENT ON COLUMN book.series_id IS '所属系列 ID，可为空';
+COMMENT ON COLUMN book.series_sort IS '同系列内展示排序';
+COMMENT ON COLUMN book.raw_txt_url IS '原始 txt 文件 URL';
+
+CREATE INDEX idx_book_book_type ON book (book_type);
+CREATE INDEX idx_book_era_tag ON book (era_tag);
+CREATE INDEX idx_book_publish_status ON book (publish_status);
+CREATE INDEX idx_book_completion_status ON book (completion_status);
+CREATE INDEX idx_book_series_id_series_sort ON book (series_id, series_sort);
+CREATE INDEX idx_book_created_at ON book (created_at);

server/.ai-specs/doc-sql/book_author.sql

@@ -1,19 +1,15 @@
-# 书籍作者表
+-- # 书籍作者表
+--
+-- ## 基本信息
+--
+-- 模块：book
+-- 表名：book_author
+-- 模型：model/book/book_author.go
+-- 迁移接入：initialize/gorm_biz.go
+-- 删除策略：硬删表
+-- 状态字典：book_author_status
+-- 职责：承载书籍作者主体信息，用于作者资料展示、书籍作者关联和后台作者管理。
 
-## 基本信息
-
-- 模块：book
-- 表名：`book_author`
-- 模型：`model/book/book_author.go`
-- 迁移接入：`initialize/gorm_biz.go`
-- 状态字典：`book_author_status`
-- 职责：承载书籍作者主体信息，用于作者资料展示、书籍作者关联和后台作者管理。
-
-## 建议 SQL
-
-> 以下 SQL 以当前项目 PostgreSQL 为准，主要表达字段、约束和索引语义；实际落库以 `GORM Model` 和 `initialize/gorm_biz.go` 为准。
-
-```sql
 CREATE TABLE book_author (
   id bigserial PRIMARY KEY,
   created_at timestamp with time zone NOT NULL DEFAULT CURRENT_TIMESTAMP,
@@ -36,4 +32,3 @@ COMMENT ON COLUMN book_author.cover_url IS '作者封面图片 URL';
 CREATE UNIQUE INDEX uk_book_author_name ON book_author (name);
 CREATE INDEX idx_book_author_author_status ON book_author (author_status);
 CREATE INDEX idx_book_author_created_at ON book_author (created_at);
-```

server/.ai-specs/doc-sql/book_author_relation.sql

@@ -0,0 +1,31 @@
+-- # 书籍作者关联表
+--
+-- ## 基本信息
+--
+-- 模块：book
+-- 表名：book_author_relation
+-- 模型：model/book/book_author_relation.go
+-- 迁移接入：initialize/gorm_biz.go
+-- 删除策略：硬删表
+-- 职责：承载书籍与作者的多对多关系及展示顺序，保证同一本书下作者关联唯一。
+
+CREATE TABLE book_author_relation (
+  id bigserial PRIMARY KEY,
+  created_at timestamp with time zone NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at timestamp with time zone NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  book_id bigint NOT NULL,
+  author_id bigint NOT NULL,
+  author_sort integer NOT NULL DEFAULT 1 CHECK (author_sort > 0)
+);
+
+COMMENT ON TABLE book_author_relation IS '书籍作者关联表';
+COMMENT ON COLUMN book_author_relation.id IS '主键';
+COMMENT ON COLUMN book_author_relation.created_at IS '创建时间';
+COMMENT ON COLUMN book_author_relation.updated_at IS '更新时间';
+COMMENT ON COLUMN book_author_relation.book_id IS '关联书籍 ID';
+COMMENT ON COLUMN book_author_relation.author_id IS '关联作者 ID';
+COMMENT ON COLUMN book_author_relation.author_sort IS '作者展示顺序';
+
+CREATE UNIQUE INDEX uk_book_author_relation_book_id_author_id ON book_author_relation (book_id, author_id);
+CREATE INDEX idx_book_author_relation_author_id ON book_author_relation (author_id);
+CREATE INDEX idx_book_author_relation_book_id_author_sort ON book_author_relation (book_id, author_sort);

server/.ai-specs/doc-sql/book_chapter.sql

@@ -0,0 +1,40 @@
+-- # 书籍章节表
+--
+-- ## 基本信息
+--
+-- 模块：book
+-- 表名：book_chapter
+-- 模型：model/book/book_chapter.go
+-- 迁移接入：initialize/gorm_biz.go
+-- 删除策略：硬删表
+-- 职责：承载书籍章节发布单元、章节文件地址和阅读锚点基础信息，保证同一本书内章节编号稳定且唯一。
+
+CREATE TABLE book_chapter (
+  id bigserial PRIMARY KEY,
+  created_at timestamp with time zone NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at timestamp with time zone NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  book_id bigint NOT NULL,
+  title varchar(255) NOT NULL,
+  chapter_no integer NOT NULL CHECK (chapter_no > 0),
+  is_readable boolean NOT NULL DEFAULT false,
+  content_file_url varchar(500) NOT NULL,
+  total_lines integer NOT NULL DEFAULT 0 CHECK (total_lines >= 0),
+  is_enabled boolean NOT NULL DEFAULT true,
+  CHECK (NOT is_readable OR total_lines > 0)
+);
+
+COMMENT ON TABLE book_chapter IS '书籍章节表';
+COMMENT ON COLUMN book_chapter.id IS '主键';
+COMMENT ON COLUMN book_chapter.created_at IS '创建时间';
+COMMENT ON COLUMN book_chapter.updated_at IS '更新时间';
+COMMENT ON COLUMN book_chapter.book_id IS '所属书籍 ID';
+COMMENT ON COLUMN book_chapter.title IS '章节标题';
+COMMENT ON COLUMN book_chapter.chapter_no IS '同书内章节顺序编号';
+COMMENT ON COLUMN book_chapter.is_readable IS '是否对 app 端开放阅读';
+COMMENT ON COLUMN book_chapter.content_file_url IS '章节内容文件 URL';
+COMMENT ON COLUMN book_chapter.total_lines IS '章节正文总行数';
+COMMENT ON COLUMN book_chapter.is_enabled IS '章节是否启用';
+
+CREATE UNIQUE INDEX uk_book_chapter_book_id_chapter_no ON book_chapter (book_id, chapter_no);
+CREATE INDEX idx_book_chapter_book_id_is_enabled_is_readable ON book_chapter (book_id, is_enabled, is_readable);
+CREATE INDEX idx_book_chapter_created_at ON book_chapter (created_at);

server/.ai-specs/doc-sql/book_comment.sql

@@ -0,0 +1,43 @@
+-- # 书籍评论表
+--
+-- ## 基本信息
+--
+-- 模块：book
+-- 表名：book_comment
+-- 模型：model/book/book_comment.go
+-- 迁移接入：initialize/gorm_biz.go
+-- 删除策略：硬删表
+-- 评论状态字典：book_comment_status
+-- 职责：承载书籍、章节和文本行三级评论定位信息，并冗余维护评论点赞聚合值。
+
+CREATE TABLE book_comment (
+  id bigserial PRIMARY KEY,
+  created_at timestamp with time zone NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at timestamp with time zone NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  member_user_id bigint NOT NULL,
+  book_id bigint NOT NULL,
+  chapter_id bigint NOT NULL DEFAULT 0 CHECK (chapter_id >= 0),
+  line_index integer NOT NULL DEFAULT 0 CHECK (line_index >= 0),
+  content text NOT NULL,
+  like_count bigint NOT NULL DEFAULT 0 CHECK (like_count >= 0),
+  comment_status varchar(32) NOT NULL DEFAULT 'normal',
+  CHECK ((chapter_id = 0 AND line_index = 0) OR (chapter_id > 0 AND line_index >= 0))
+);
+
+COMMENT ON TABLE book_comment IS '书籍评论表';
+COMMENT ON COLUMN book_comment.id IS '主键';
+COMMENT ON COLUMN book_comment.created_at IS '创建时间';
+COMMENT ON COLUMN book_comment.updated_at IS '更新时间';
+COMMENT ON COLUMN book_comment.member_user_id IS '评论用户的会员 ID';
+COMMENT ON COLUMN book_comment.book_id IS '所属书籍 ID';
+COMMENT ON COLUMN book_comment.chapter_id IS '评论目标章节 ID，0 表示整本书';
+COMMENT ON COLUMN book_comment.line_index IS '评论目标文本行下标，0 表示整章或整本书';
+COMMENT ON COLUMN book_comment.content IS '评论正文内容';
+COMMENT ON COLUMN book_comment.like_count IS '评论点赞聚合值';
+COMMENT ON COLUMN book_comment.comment_status IS '评论状态字典值，对应 book_comment_status';
+
+CREATE INDEX idx_book_comment_book_id ON book_comment (book_id);
+CREATE INDEX idx_book_comment_book_id_chapter_id_line_index ON book_comment (book_id, chapter_id, line_index);
+CREATE INDEX idx_book_comment_member_user_id ON book_comment (member_user_id);
+CREATE INDEX idx_book_comment_comment_status ON book_comment (comment_status);
+CREATE INDEX idx_book_comment_created_at ON book_comment (created_at);

server/.ai-specs/doc-sql/book_comment_like_record.sql

@@ -0,0 +1,31 @@
+-- # 评论点赞记录表
+--
+-- ## 基本信息
+--
+-- 模块：book
+-- 表名：book_comment_like_record
+-- 模型：model/book/book_comment_like_record.go
+-- 迁移接入：initialize/gorm_biz.go
+-- 删除策略：硬删表
+-- 职责：承载用户对评论的有效点赞关系，支持点赞/取消点赞的幂等判断和计数维护。
+
+CREATE TABLE book_comment_like_record (
+  id bigserial PRIMARY KEY,
+  created_at timestamp with time zone NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at timestamp with time zone NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  comment_id bigint NOT NULL,
+  member_user_id bigint NOT NULL,
+  liked_at timestamp with time zone NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+COMMENT ON TABLE book_comment_like_record IS '评论点赞记录表';
+COMMENT ON COLUMN book_comment_like_record.id IS '主键';
+COMMENT ON COLUMN book_comment_like_record.created_at IS '创建时间';
+COMMENT ON COLUMN book_comment_like_record.updated_at IS '更新时间';
+COMMENT ON COLUMN book_comment_like_record.comment_id IS '被点赞评论 ID';
+COMMENT ON COLUMN book_comment_like_record.member_user_id IS '点赞用户的会员 ID';
+COMMENT ON COLUMN book_comment_like_record.liked_at IS '点赞发生时间';
+
+CREATE UNIQUE INDEX uk_book_comment_like_record_comment_id_member_user_id ON book_comment_like_record (comment_id, member_user_id);
+CREATE INDEX idx_book_comment_like_record_member_user_id ON book_comment_like_record (member_user_id);
+CREATE INDEX idx_book_comment_like_record_liked_at ON book_comment_like_record (liked_at);

server/.ai-specs/doc-sql/book_favorite_record.sql

@@ -0,0 +1,31 @@
+-- # 用户收藏记录表
+--
+-- ## 基本信息
+--
+-- 模块：book
+-- 表名：book_favorite_record
+-- 模型：model/book/book_favorite_record.go
+-- 迁移接入：initialize/gorm_biz.go
+-- 删除策略：硬删表
+-- 职责：承载用户对书籍的收藏关系，保证同一用户对同一本书只保留一条有效收藏记录。
+
+CREATE TABLE book_favorite_record (
+  id bigserial PRIMARY KEY,
+  created_at timestamp with time zone NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at timestamp with time zone NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  member_user_id bigint NOT NULL,
+  book_id bigint NOT NULL,
+  favorited_at timestamp with time zone NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+COMMENT ON TABLE book_favorite_record IS '用户收藏记录表';
+COMMENT ON COLUMN book_favorite_record.id IS '主键';
+COMMENT ON COLUMN book_favorite_record.created_at IS '创建时间';
+COMMENT ON COLUMN book_favorite_record.updated_at IS '更新时间';
+COMMENT ON COLUMN book_favorite_record.member_user_id IS '收藏用户的会员 ID';
+COMMENT ON COLUMN book_favorite_record.book_id IS '收藏书籍 ID';
+COMMENT ON COLUMN book_favorite_record.favorited_at IS '收藏发生时间';
+
+CREATE UNIQUE INDEX uk_book_favorite_record_member_user_id_book_id ON book_favorite_record (member_user_id, book_id);
+CREATE INDEX idx_book_favorite_record_member_user_id_favorited_at ON book_favorite_record (member_user_id, favorited_at);
+CREATE INDEX idx_book_favorite_record_book_id ON book_favorite_record (book_id);

server/.ai-specs/doc-sql/book_read_record.sql

@@ -0,0 +1,39 @@
+-- # 用户阅读记录表
+--
+-- ## 基本信息
+--
+-- 模块：book
+-- 表名：book_read_record
+-- 模型：model/book/book_read_record.go
+-- 迁移接入：initialize/gorm_biz.go
+-- 删除策略：硬删表
+-- 职责：承载用户按“用户+书籍”维度的最新阅读历史和续读锚点，支持阅读恢复与历史展示。
+
+CREATE TABLE book_read_record (
+  id bigserial PRIMARY KEY,
+  created_at timestamp with time zone NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at timestamp with time zone NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  member_user_id bigint NOT NULL,
+  book_id bigint NOT NULL,
+  book_title_snapshot varchar(255) NOT NULL,
+  read_progress numeric(5,2) NOT NULL DEFAULT 0.00 CHECK (read_progress >= 0 AND read_progress <= 100),
+  chapter_id bigint NOT NULL CHECK (chapter_id > 0),
+  line_index integer NOT NULL CHECK (line_index > 0),
+  last_read_at timestamp with time zone NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+COMMENT ON TABLE book_read_record IS '用户阅读记录表';
+COMMENT ON COLUMN book_read_record.id IS '主键';
+COMMENT ON COLUMN book_read_record.created_at IS '创建时间';
+COMMENT ON COLUMN book_read_record.updated_at IS '更新时间';
+COMMENT ON COLUMN book_read_record.member_user_id IS '阅读用户的会员 ID';
+COMMENT ON COLUMN book_read_record.book_id IS '所属书籍 ID';
+COMMENT ON COLUMN book_read_record.book_title_snapshot IS '阅读书籍标题快照';
+COMMENT ON COLUMN book_read_record.read_progress IS '阅读进度百分比';
+COMMENT ON COLUMN book_read_record.chapter_id IS '当前续读章节 ID';
+COMMENT ON COLUMN book_read_record.line_index IS '当前续读文本行下标，正文首行为 1';
+COMMENT ON COLUMN book_read_record.last_read_at IS '最近一次阅读时间';
+
+CREATE UNIQUE INDEX uk_book_read_record_member_user_id_book_id ON book_read_record (member_user_id, book_id);
+CREATE INDEX idx_book_read_record_member_user_id_last_read_at ON book_read_record (member_user_id, last_read_at);
+CREATE INDEX idx_book_read_record_book_id ON book_read_record (book_id);

server/.ai-specs/doc-sql/book_series.sql

@@ -0,0 +1,33 @@
+-- # 书籍系列表
+--
+-- ## 基本信息
+--
+-- 模块：book
+-- 表名：book_series
+-- 模型：model/book/book_series.go
+-- 迁移接入：initialize/gorm_biz.go
+-- 删除策略：硬删表
+-- 职责：承载书籍系列主体信息，用于组织同一作品的分部顺序和系列展示。
+
+CREATE TABLE book_series (
+  id bigserial PRIMARY KEY,
+  created_at timestamp with time zone NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at timestamp with time zone NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  name varchar(128) NOT NULL,
+  cover_url varchar(500),
+  intro text,
+  is_enabled boolean NOT NULL DEFAULT true
+);
+
+COMMENT ON TABLE book_series IS '书籍系列表';
+COMMENT ON COLUMN book_series.id IS '主键';
+COMMENT ON COLUMN book_series.created_at IS '创建时间';
+COMMENT ON COLUMN book_series.updated_at IS '更新时间';
+COMMENT ON COLUMN book_series.name IS '系列名称';
+COMMENT ON COLUMN book_series.cover_url IS '系列封面图片 URL';
+COMMENT ON COLUMN book_series.intro IS '系列简介';
+COMMENT ON COLUMN book_series.is_enabled IS '系列是否启用';
+
+CREATE INDEX idx_book_series_name ON book_series (name);
+CREATE INDEX idx_book_series_is_enabled ON book_series (is_enabled);
+CREATE INDEX idx_book_series_created_at ON book_series (created_at);