From cc40d743cb0627bccd0da594721f8ce0125094c3 Mon Sep 17 00:00:00 2001 From: wdh-home <243823965@qq.com> Date: Thu, 23 Apr 2026 21:19:30 +0800 Subject: [PATCH] =?UTF-8?q?=E9=9C=80=E6=B1=82?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- server/.ai-specs/logic-specs/book.md | 89 ---------- server/.ai-specs/requirements/book.md | 161 ++++++++++++++++++ .../sys-specs/requirements-stage-spec.md | 107 ++++++++++++ server/AGENTS.md | 6 +- 4 files changed, 272 insertions(+), 91 deletions(-) delete mode 100644 server/.ai-specs/logic-specs/book.md create mode 100644 server/.ai-specs/requirements/book.md create mode 100644 server/.ai-specs/sys-specs/requirements-stage-spec.md diff --git a/server/.ai-specs/logic-specs/book.md b/server/.ai-specs/logic-specs/book.md deleted file mode 100644 index fac5f7b..0000000 --- a/server/.ai-specs/logic-specs/book.md +++ /dev/null @@ -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 -``` diff --git a/server/.ai-specs/requirements/book.md b/server/.ai-specs/requirements/book.md new file mode 100644 index 0000000..903bc87 --- /dev/null +++ b/server/.ai-specs/requirements/book.md @@ -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`。 +- 评论默认只允许发生在已上架书籍上；若评论目标指向具体章节或具体文本行，则对应章节必须可阅读。 +- 后台必须具备隐藏或下架评论能力，不能直接依赖物理删除处理违规内容。 +- 评论点赞数表示普通用户点赞聚合值，不承载其他认可语义。 + +### 评论点赞 +- 点赞关系以“用户 + 评论”唯一确定，同一用户对同一评论只能存在一条有效点赞关系。 +- 点赞功能只支持“点赞 / 取消点赞”两种操作，不扩展表情、权重、连击、分值等复杂玩法。 +- 点赞和取消点赞都要按幂等处理，重复点赞或重复取消点赞不应导致计数异常。 +- 评论列表和详情展示的 `评论点赞数` 直接使用评论表聚合值，不在读请求里实时汇总点赞记录。 +- 点赞记录只用于维护点赞关系和判断“当前用户是否已点赞”，不承载通知、积分、排行榜等额外流程。 diff --git a/server/.ai-specs/sys-specs/requirements-stage-spec.md b/server/.ai-specs/sys-specs/requirements-stage-spec.md new file mode 100644 index 0000000..e7f9cc7 --- /dev/null +++ b/server/.ai-specs/sys-specs/requirements-stage-spec.md @@ -0,0 +1,107 @@ +# 需求草案阶段规范 + +## 适用范围 + +- 新增/修改 `.ai-specs/requirements/*.md` 前必须先读本文件。 +- 本文件只约束 `requirements` 文档，不替代 `doc-dict`、`doc-sql`、`doc-api` 和代码实现规范。 + +## 阶段目标 + +- `制定需求草案阶段`：只整理本需求文档，归并已确认需求，未确认项显式标注“需补”，不要求同步修改代码和下游文档。 +- `归档阶段`：需求草案已稳定，可作为下游文档和实现依据；新增需求或未确认变更必须退回 `制定需求草案阶段`。 +- 两个阶段正文结构一致：涉及表时先写 `## 表`，再写 `## 需求描述`；不涉及表时只写 `## 需求描述`。 + +## 强制规则 + +- 文档路径固定：`.ai-specs/requirements/.md` +- 文档标题固定：`# <主题> 需求草案` +- 标题下方空一行后必须紧跟两行阶段元信息，格式固定为 `- **阶段** <阶段说明>` 和 `- **要求** <阶段要求>`。 +- 阶段元信息只能从下表选择一组，禁止混用、改名或自行扩写。 + +| 阶段 | 阶段行 | 要求行 | +|:---|:---|:---| +| 制定需求草案阶段 | `- **阶段** 当前阶段只整理本需求文档，归并已确认需求，未确认项显式标注“需补”，不要求同步修改代码和下游文档` | `- **要求** 对错误、冲突或不闭环需求应及时纠正并提示；需求整理以逻辑闭环、链路清晰、实现轻量为目标，避免为单点功能引入复杂链路` | +| 归档阶段 | `- **阶段** 当前阶段为需求归档，需求草案已稳定，可作为下游文档和实现依据，原则上不再追加未确认内容` | `- **要求** 只允许修正错误、消除歧义和同步已确认结论；新增需求或未确认变更必须退回制定需求草案阶段处理` | + +- 一个文档只描述一个业务主题。 +- 正文只允许出现 `## 表` 和 `## 需求描述` 两类二级标题。 +- `## 需求描述` 必须存在；`## 表` 按需存在，不涉及表时必须省略。 +- 禁止为了满足格式硬造表或保留空表区。 +- 有表时，每张表使用一个 `### <表名>`；字段统一写成 `- <字段名>：<字段说明>`。 +- 有表时，`## 表` 只写字段和极简业务含义；不写流程、规则、性能、实现判断。 +- 有表且字段涉及字典时，只引用字典码，例如“字典 ``”或“字典，需补 ``”；确认值域写到 `## 需求描述`。 +- 有表且字段本质上是多值、多对多或独立主体时，必须拆成独立表或关联表，禁止塞进主表字符串字段。 +- `## 需求描述` 下每个业务主题使用一个 `### <需求标题>`，只写规则、流程、边界、范围和例外。 +- `###` 下只允许 `-` 扁平列表；禁止四级标题、嵌套标题、编号大纲、代码块、图和表格。 + +## 禁止事项 + +- 禁止写 API 路径、Method、鉴权方式、请求响应结构。 +- 禁止写 Router、API、Service、定时任务、缓存、消息队列等实现设计。 +- 禁止写 SQL 建表语句、字段类型、索引、唯一约束、迁移脚本。 +- 禁止新增 `## 背景`、`## 范围`、`## 总览`、`## 关系图`、`## TODO` 等既定结构外标题。 +- 禁止把需求规则混写到 `## 表`，也禁止把字段清单重复抄到 `## 需求描述`。 +- 禁止无表业务为了套模板编造表、字段、关联关系或空的 `## 表`。 +- 禁止把未确认事项写成确定结论；未确认内容必须标记“需补”或“待确认”。 +- 禁止在 `归档阶段` 继续收集新需求；新增需求必须退回 `制定需求草案阶段`。 + +## 文档结构 + +- 有表结构：`# <主题> 需求草案` → 两行阶段元信息 → `## 表` → 多个 `### <表名>` → `## 需求描述` → 多个 `### <需求标题>`。 +- 无表结构：`# <主题> 需求草案` → 两行阶段元信息 → `## 需求描述` → 多个 `### <需求标题>`。 +- 有表时，`### <表名>` 使用业务表名，例如“书籍信息表”“书籍章节表”“订单支付记录表”，不要求等于最终数据库表名。 +- `### <需求标题>` 使用业务主题名，例如“数据来源与上传”“章节重建策略”“评论点赞”“当前范围”。 +- 没有合适标题的信息，归并到语义最近的 `### <需求标题>`；确需新增标题时，只能在 `## 需求描述` 下新增三级标题。 + +## 输出模板 + +无表业务模板： + +````md +# <主题> 需求草案 + +- **阶段** 当前阶段只整理本需求文档，归并已确认需求，未确认项显式标注“需补”，不要求同步修改代码和下游文档 +- **要求** 对错误、冲突或不闭环需求应及时纠正并提示；需求整理以逻辑闭环、链路清晰、实现轻量为目标，避免为单点功能引入复杂链路 + +## 需求描述 + +### <需求1> +- <规则、边界或待确认事项> + +### <需求2> +- <规则、例外或范围> +```` + +有表业务模板： + +````md +# <主题> 需求草案 + +- **阶段** 当前阶段只整理本需求文档，归并已确认需求，未确认项显式标注“需补”，不要求同步修改代码和下游文档 +- **要求** 对错误、冲突或不闭环需求应及时纠正并提示；需求整理以逻辑闭环、链路清晰、实现轻量为目标，避免为单点功能引入复杂链路 + +## 表 + +### <表1> +- <字段1>：<说明> +- <字段2>：<说明或需补> +- <字段3>：字典 `` + +### <表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`。 diff --git a/server/AGENTS.md b/server/AGENTS.md index 4d035a9..d76b990 100644 --- a/server/AGENTS.md +++ b/server/AGENTS.md @@ -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