This commit is contained in:
2026-04-23 21:19:30 +08:00
parent 2809e80087
commit cc40d743cb
4 changed files with 272 additions and 91 deletions

View File

@@ -1,89 +0,0 @@
# 书籍信息表
- 书名:
- 子标题
- 书籍类型:字典
- 书籍标签 : 字典 ,标签是多个 要考虑用标签搜索书籍的性能问题
- 书有系列:第一部 第二部, 上部 下部 , 所以有排序功能
- 封面图片: url
- 出版社:
- 出版时间:
- 简介:
- 热度:
- 评分: 0-10分
- 点评数:
- 字数:
- 书籍完结状态: 字典, 完结/连载
- 书籍处理状态: 字典, 文件准备 / 拆分章节 / 验证章节 / 完成
- 书籍系列Id
- 系列内排序: 用于同系列书籍排序
- 作者: 通过书籍作者关联表维护, 支持多个作者和排序
- 原始书籍文件: 保存整本书文件存储地址
- 内容存储: 原始整本书文件保存后, 系统再拆分成多个章节文件保存
# 书籍系列表
- 名字
- 封面图片
- 书籍通过 系列Id + 系列内排序 挂到系列下
# 书籍章节表
- 书籍Id
- 章节标题
- 章节排序
- 是否可观看
- 章节文件存储地址
- 阅读历史和评论都通过 章节Id + 行号 定位
# 书籍作者表
- 名字
- 状态:字典
- 简介
- 封面图片: url
# 书籍作者关联表
- 书籍Id
- 作者Id
- 作者排序
- 一本书可关联多个作者, 一个作者可关联多本书
# 用户观看书籍历史表
- 会员用户Id
- 书籍Id
- 观看书籍进度 : 前端显示 50%
- 观看章节Id
- 观看章节行数
- 主定位以 章节Id + 行号 为准
# 用户收藏书籍历史表
- 会员用户Id
- 书籍Id
# 书籍评论表
- 评论用户Id
- 评论书籍Id
- 评论章节Id
- 评论章节行数 比如第二章第5行
- 评论内容
- 评论点赞数
- 作者是否点赞
- 主定位以 章节Id + 行号 为准
# 关系图
```mermaid
flowchart LR
Book["书籍"] --> Series["书籍系列"]
Book --> SourceFile["整本原始文件"]
Book --> Chapter["书籍章节"]
Book --> BookAuthorRel["书籍作者关联"]
BookAuthorRel --> Author["书籍作者"]
SourceFile -.拆分生成.-> Chapter
User["用户"] --> History["观看书籍历史"]
User --> Favorite["收藏书籍历史"]
User --> Comment["书籍评论"]
History --> Book
History --> Chapter
Favorite --> Book
Comment --> Book
Comment --> Chapter
```

View File

@@ -0,0 +1,161 @@
# 书籍 需求草案
- **阶段** 当前阶段只整理本需求文档,归并已确认需求,未确认项显式标注“需补”,不要求同步修改代码和下游文档
- **要求** 对错误、冲突或不闭环需求应及时纠正并提示;需求整理以逻辑闭环、链路清晰、实现轻量为目标,避免为单点功能引入复杂链路
## 表
### 书籍信息表
- 书名:主标题
- 子标题:副标题
- 书籍类型:字典 `book_type`,必填
- 时代标签:字典 `book_era_tag`,必填
- 封面图片URL封面图地址
- 出版社:出版机构
- 出版时间:出版日期
- 简介:书籍简介
- 热度:展示聚合值
- 评分:`0-10` 分,建议一位小数
- 点评数:展示聚合值
- 字数:全书总字数
- 书籍完结状态:字典 `book_completion_status`
- 上下架状态:字典 `book_publish_status`
- 系列ID所属系列可为空
- 系列内排序:同系列展示顺序
- 原始书籍文件URL原始 `txt` 文件地址
### 书籍章节表
- 书籍ID所属书籍
- 章节标题:章节名称
- 章节编号:同书内顺序编号
- 是否可阅读:是否对 `app` 端开放阅读
- 章节内容文件URL单章内容文件地址
- 总行数:章节内容行数
- 是否启用:章节启停状态
### 书籍系列表
- 名称:系列名称
- 封面图片URL系列封面地址
- 简介:系列简介
- 是否启用:系列启停状态
### 书籍作者表
- 名称:作者名称
- 状态:字典 `book_author_status`
- 简介:作者简介
- 封面图片URL作者封面地址
### 书籍作者关联表
- 书籍ID关联书籍
- 作者ID关联作者
- 作者排序:作者展示顺序
### 用户阅读记录表
- 会员用户ID阅读用户
- 书籍ID所属书籍
- 阅读书籍标题快照:用于阅读历史列表展示
- 阅读进度:前端展示百分比
- 阅读章节ID当前续读章节
- 阅读文本行Index当前续读文本行下标正文首行为 `1`,不允许为 `0`
- 最后阅读时间:最近一次阅读时间
### 用户收藏记录表
- 会员用户ID收藏用户
- 书籍ID收藏书籍
- 收藏时间:收藏发生时间
### 书籍评论表
- 评论用户ID评论用户
- 评论书籍ID所属书籍
- 评论章节ID评论目标章节`0` 表示整本书
- 评论文本行Index评论目标文本行下标`0` 表示整章
- 评论内容:评论正文
- 评论点赞数:普通用户点赞聚合值
- 评论状态:字典 `book_comment_status`
### 评论点赞记录表
- 评论ID被点赞评论
- 点赞用户ID点赞用户
- 点赞时间:点赞发生时间
## 需求描述
### 书籍主体
- 书籍是核心主体,列表、详情、搜索、推荐都以书籍信息为主。
- 一本书可以不属于任何系列;属于系列时,按 `系列内排序` 展示。
- 一本书不直接存作者名字符串;作者通过关联关系维护,时代标签通过书籍主表字段维护。
- 每本书必须关联 `1` 个书籍类型;`book_type` 使用系统字典动态值承载,并通过业务侧独立封装读写。
- `book_publish_status` 当前值域为:`draft``off_shelf``on_shelf`
- 热度、评分、点评数可冗余存储,但业务上按聚合值理解。
### 数据来源与上传
- 原始 `txt` 仅作为书籍原始备份和参考来源,不直接作为当前对外章节内容的生效来源。
- 上传原始文件只更新原始文件,不自动覆盖现有章节数据。
- 当前章节数据由后台通过单章文件上传方式新增和替换维护。
- `原始 txt` 一键分割章节功能当前仅保留业务占位,现阶段不定义实现方式和对接细节。
- 章节表、章节发布、阅读定位和评论定位仍属于当前业务范围,不因一键分割章节能力暂缓而取消。
### 章节发布
- 同一本书下,章节编号必须唯一,并按章节编号排序阅读。
- 书内统一定位锚点使用 `书籍ID + 章节ID + 文本行Index`,因此章节内容落地后必须能稳定生成文本行下标。
- 正文实际行号统一从 `1` 开始;`文本行Index=0` 只用于整本书或整章这类非正文行定位。
- 章节一旦对外发布,章节编号和定位规则应保持稳定,避免阅读记录失效。
- 不可阅读或已禁用章节不对 `app` 端展示;若用户通过阅读记录回到该位置,只提示当前章节不可访问,不继续打开正文。
### 章节重建策略
- 原始 `txt` 一键分割章节与重建能力当前仅保留业务占位,现阶段不定义具体模式、流程和交互规则。
- 后续若启动该能力,再单独补充分割策略、覆盖边界和历史定位兼容规则。
### 连载与完结
- 书籍完结状态用于展示和搜索,区分连载与完结。
- 完结状态仅作为业务标签,不直接限制后台新增或修改章节。
- 已发布章节允许修订正文内容。
- 修订已发布章节正文时,必须通过锚点兼容机制保证历史阅读记录和评论定位仍然可用。
- 若新的正文内容无法兼容既有 `章节ID + 文本行Index` 定位,则不允许直接覆盖已发布章节。
### 系列
- 系列用于组织同一作品的上部/下部、第一部/第二部等顺序关系。
- 系列下书籍通过 `系列ID + 系列内排序` 关联,系列自身不直接承载章节内容。
- 未启用系列不影响已挂载书籍基础信息,但 `app` 端不应继续以系列形式对外展示。
### 作者
- 作者名称应唯一,避免同名重复建档。
- 每本书至少关联 `1` 个作者。
- 同一本书下,同一个作者只能关联一次。
- 禁用作者不再允许被新增关联,但历史上已关联的书籍仍可保留展示。
- 作者排序决定书籍详情页和列表页的作者展示顺序。
### 时代标签
- 时代标签使用系统字典 `book_era_tag` 承载,不单独建设标签主数据表。
- `book_era_tag` 当前值域为:未知时代、远古、汉、唐、宋、元、明、清、近代、现代。
- 每本书必须设置 `1` 个时代标签;无法判断时使用 `未知时代`
- 时代标签对外读写入口独立封装,不直接暴露系统字典通用入口。
- 时代标签用于书籍筛选和聚合,不使用主表字符串自由录入。
### 阅读记录
- 阅读记录同时承担“用户阅读历史”和“续读书签锚点”两种用途,不拆成两套数据。
- 阅读历史列表按“用户 + 书籍”维度展示;每个用户对每本书只保留一条最新阅读记录。
- 用户再次进入同一本书时,应优先按该记录中的最新锚点恢复到上次阅读位置;新的阅读行为覆盖旧的续读位置、阅读进度和最后阅读时间。
- 主定位以 `书籍ID + 章节ID + 文本行Index` 为准,进度百分比和书籍标题快照仅用于列表展示和回显。
- 章节禁用或书籍下架后,阅读记录仍保留用于历史展示;再次进入时只提示当前书籍或章节不可访问,不恢复正文内容。
### 收藏
- 每个用户对每本书只能收藏一次。
- 仅上架书籍允许新增收藏;下架后历史收藏记录保留,但不再新增。
### 评论
- 评论统一通过 `书籍ID + 章节ID + 文本行Index` 表达评论目标。
-`章节ID=0` 时,表示对整本书的评价;此时 `文本行Index` 也应为 `0`
-`章节ID>0``文本行Index=0` 时,表示对整章的评价。
-`章节ID>0``文本行Index>0` 时,表示对书中某一句话的评论。
- `book_comment_status` 当前值域为:`normal``hidden`
- 评论默认只允许发生在已上架书籍上;若评论目标指向具体章节或具体文本行,则对应章节必须可阅读。
- 后台必须具备隐藏或下架评论能力,不能直接依赖物理删除处理违规内容。
- 评论点赞数表示普通用户点赞聚合值,不承载其他认可语义。
### 评论点赞
- 点赞关系以“用户 + 评论”唯一确定,同一用户对同一评论只能存在一条有效点赞关系。
- 点赞功能只支持“点赞 / 取消点赞”两种操作,不扩展表情、权重、连击、分值等复杂玩法。
- 点赞和取消点赞都要按幂等处理,重复点赞或重复取消点赞不应导致计数异常。
- 评论列表和详情展示的 `评论点赞数` 直接使用评论表聚合值,不在读请求里实时汇总点赞记录。
- 点赞记录只用于维护点赞关系和判断“当前用户是否已点赞”,不承载通知、积分、排行榜等额外流程。

View File

@@ -0,0 +1,107 @@
# 需求草案阶段规范
## 适用范围
- 新增/修改 `.ai-specs/requirements/*.md` 前必须先读本文件。
- 本文件只约束 `requirements` 文档,不替代 `doc-dict``doc-sql``doc-api` 和代码实现规范。
## 阶段目标
- `制定需求草案阶段`:只整理本需求文档,归并已确认需求,未确认项显式标注“需补”,不要求同步修改代码和下游文档。
- `归档阶段`:需求草案已稳定,可作为下游文档和实现依据;新增需求或未确认变更必须退回 `制定需求草案阶段`
- 两个阶段正文结构一致:涉及表时先写 `## 表`,再写 `## 需求描述`;不涉及表时只写 `## 需求描述`
## 强制规则
- 文档路径固定:`.ai-specs/requirements/<topic>.md`
- 文档标题固定:`# <主题> 需求草案`
- 标题下方空一行后必须紧跟两行阶段元信息,格式固定为 `- **阶段** <阶段说明>``- **要求** <阶段要求>`
- 阶段元信息只能从下表选择一组,禁止混用、改名或自行扩写。
| 阶段 | 阶段行 | 要求行 |
|:---|:---|:---|
| 制定需求草案阶段 | `- **阶段** 当前阶段只整理本需求文档,归并已确认需求,未确认项显式标注“需补”,不要求同步修改代码和下游文档` | `- **要求** 对错误、冲突或不闭环需求应及时纠正并提示;需求整理以逻辑闭环、链路清晰、实现轻量为目标,避免为单点功能引入复杂链路` |
| 归档阶段 | `- **阶段** 当前阶段为需求归档,需求草案已稳定,可作为下游文档和实现依据,原则上不再追加未确认内容` | `- **要求** 只允许修正错误、消除歧义和同步已确认结论;新增需求或未确认变更必须退回制定需求草案阶段处理` |
- 一个文档只描述一个业务主题。
- 正文只允许出现 `## 表``## 需求描述` 两类二级标题。
- `## 需求描述` 必须存在;`## 表` 按需存在,不涉及表时必须省略。
- 禁止为了满足格式硬造表或保留空表区。
- 有表时,每张表使用一个 `### <表名>`;字段统一写成 `- <字段名><字段说明>`
- 有表时,`## 表` 只写字段和极简业务含义;不写流程、规则、性能、实现判断。
- 有表且字段涉及字典时,只引用字典码,例如“字典 `<dict-code>`”或“字典,需补 `<dict-code>`”;确认值域写到 `## 需求描述`
- 有表且字段本质上是多值、多对多或独立主体时,必须拆成独立表或关联表,禁止塞进主表字符串字段。
- `## 需求描述` 下每个业务主题使用一个 `### <需求标题>`,只写规则、流程、边界、范围和例外。
- `###` 下只允许 `-` 扁平列表;禁止四级标题、嵌套标题、编号大纲、代码块、图和表格。
## 禁止事项
- 禁止写 API 路径、Method、鉴权方式、请求响应结构。
- 禁止写 Router、API、Service、定时任务、缓存、消息队列等实现设计。
- 禁止写 SQL 建表语句、字段类型、索引、唯一约束、迁移脚本。
- 禁止新增 `## 背景``## 范围``## 总览``## 关系图``## TODO` 等既定结构外标题。
- 禁止把需求规则混写到 `## 表`,也禁止把字段清单重复抄到 `## 需求描述`
- 禁止无表业务为了套模板编造表、字段、关联关系或空的 `## 表`
- 禁止把未确认事项写成确定结论;未确认内容必须标记“需补”或“待确认”。
- 禁止在 `归档阶段` 继续收集新需求;新增需求必须退回 `制定需求草案阶段`
## 文档结构
- 有表结构:`# <主题> 需求草案` → 两行阶段元信息 → `## 表` → 多个 `### <表名>``## 需求描述` → 多个 `### <需求标题>`
- 无表结构:`# <主题> 需求草案` → 两行阶段元信息 → `## 需求描述` → 多个 `### <需求标题>`
- 有表时,`### <表名>` 使用业务表名,例如“书籍信息表”“书籍章节表”“订单支付记录表”,不要求等于最终数据库表名。
- `### <需求标题>` 使用业务主题名,例如“数据来源与上传”“章节重建策略”“评论点赞”“当前范围”。
- 没有合适标题的信息,归并到语义最近的 `### <需求标题>`;确需新增标题时,只能在 `## 需求描述` 下新增三级标题。
## 输出模板
无表业务模板:
````md
# <主题> 需求草案
- **阶段** 当前阶段只整理本需求文档,归并已确认需求,未确认项显式标注“需补”,不要求同步修改代码和下游文档
- **要求** 对错误、冲突或不闭环需求应及时纠正并提示;需求整理以逻辑闭环、链路清晰、实现轻量为目标,避免为单点功能引入复杂链路
## 需求描述
### <需求1>
- <规则、边界或待确认事项>
### <需求2>
- <规则、例外或范围>
````
有表业务模板:
````md
# <主题> 需求草案
- **阶段** 当前阶段只整理本需求文档,归并已确认需求,未确认项显式标注“需补”,不要求同步修改代码和下游文档
- **要求** 对错误、冲突或不闭环需求应及时纠正并提示;需求整理以逻辑闭环、链路清晰、实现轻量为目标,避免为单点功能引入复杂链路
## 表
### <表1>
- <字段1><说明>
- <字段2><说明或需补>
- <字段3>:字典 `<dict-code>`
### <表2>
- <字段1><说明>
## 需求描述
### <需求1>
- <规则、边界或待确认事项>
### <需求2>
- <规则、例外或范围>
````
## 与后续文档的关系
- `requirements` 是 `doc-dict`、`doc-sql`、`doc-api` 和代码实现的上游输入,不是替代物。
- 出现状态、类型、级别、来源、模式、分类等值域时,下一步先补 `.ai-specs/doc-dict/*.md`。
- 涉及表、字段、关系且已稳定后,下一步补 `.ai-specs/doc-sql/*.md`;无表需求不强制补 `doc-sql`。
- 默认链路:`requirements(制定需求草案阶段 -> 归档阶段) -> doc-dict / doc-sql -> Model -> Service -> API -> Router`。

View File

@@ -16,6 +16,7 @@
- **读写**PowerShell/脚本读取项目文件必须显式指定 `-Encoding utf8`
- **画图**:优先使用 `mermaid flowchart `
- **对话/文档编写**:必须是 中文为主体语言,技术术语保留英文原文
- **git push**:每次 push 的时候,如果当前是子分支就合并到主分支上
## 项目架构
- **技术栈**:本项目为 `Go` 服务端,基于 `gin-vue-admin` 体系Web 框架使用 `Gin`ORM 使用 `GORM`,配置使用 `Viper`,日志使用 `Zap`,鉴权与权限控制使用 `JWT + Casbin`,接口文档使用 `Swagger`,缓存优先使用 `Redis`;关系型数据库统一通过 `GORM` 接入,数据库使用 `PostgreSQL` ;按配置可启用 `MongoDB``cron``Excelize`、多云 `OSS/S3`,部署默认支持 `Docker`
@@ -102,11 +103,11 @@ flowchart LR
| `.ai-specs\coding-specs\sys-params.md` | 规定 `sys_params` 的读写方式与单参数独立 API 的封装方式 | 涉及系统参数读写、基于 `sys_params` 封装业务配置接口时必读 |
| `.ai-specs\coding-specs\vo-model-request-response.md` | 规定项目中实体、API 入参、API 出参与通用结构在 `model` 体系内的落点与复用边界 | 涉及 `vo` 放置方式、是否复用实体、何时新增 `request/response` 结构时必读 |
### logic-specs 存放业务说明文档不设计代码
### requirements 存放需求草案文档
| 路径 | 用途 | 说明 |
|:---|:---|:---|
| `.ai-specs\logic-specs\book.md` | 记录书籍相关主体与字段草案 | 涉及书籍、书籍系列、书籍作者、书籍评论等业务设计时先读 |
| `.ai-specs\requirements\book.md` | 记录书籍需求草案,先列相关表和字段,再列业务需求描述 | 涉及书籍、书籍系列、书籍作者、书籍评论等业务设计时先读 |
### sys-specs 存放系统级文档
@@ -115,6 +116,7 @@ flowchart LR
| `.ai-specs\sys-specs\business-table-spec.md` | 规定新增业务表的 SQL 设计、索引、约束、迁移和兼容要求 | 涉及新增/修改业务表、字段、索引、唯一约束、迁移注册时必读 |
| `.ai-specs\sys-specs\business-dictionary-spec.md` | 规定新增业务字典的定义方式,以及代码枚举与字典值的一一对应关系 | 涉及新增业务状态、类型、级别、来源、模式、分类等值域时必读 |
| `.ai-specs\sys-specs\module-naming-spec.md` | 规定业务模块中文名与英文名的统一登记方式 | 涉及新增/修改业务模块命名、中英文对照、目录命名时必读 |
| `.ai-specs\sys-specs\requirements-stage-spec.md` | 规定 `requirements` 需求草案阶段的文档边界、结构和输出方式 | 涉及新增/修改 `.ai-specs\requirements\*.md` 时必读 |
### doc-api <admin or app or `平台`>