基础项目

server/.ai-specs/doc-api/admin/book.md

@@ -0,0 +1,29 @@
+# 书籍信息 admin 接口
+
+## 基本信息
+
+- 模块：book
+- 资源：书籍
+- 端：admin
+- 鉴权：挂载 `PrivateGroup`，需要 `JWT + Casbin`
+- 操作审计：创建、更新、单删、批量删除写操作启用 `OperationRecord`
+- 路由前缀：`/book`
+
+## 默认 CRUD
+
+| 动作 | Method | 路径 | API 方法 | Service 方法 |
+|:---|:---|:---|:---|:---|
+| 创建 | `POST` | `/book/createBook` | `CreateBook` | `CreateBook` |
+| 单删 | `DELETE` | `/book/deleteBook` | `DeleteBook` | `DeleteBook` |
+| 批量删除 | `DELETE` | `/book/deleteBookByIds` | `DeleteBookByIds` | `DeleteBookByIds` |
+| 更新 | `PUT` | `/book/updateBook` | `UpdateBook` | `UpdateBook` |
+| 详情 | `GET` | `/book/findBook` | `FindBook` | `GetBook` |
+| 分页列表 | `GET` | `/book/getBookList` | `GetBookList` | `GetBookInfoList` |
+
+## 参数与返回
+
+- 创建、更新：`body` 使用 `book.Book`。
+- 单删、详情：`query id`。
+- 批量删除：`query ids[]`。
+- 分页列表：`query` 使用 `bookReq.BookSearch`，返回 `response.PageResult`。
+- 详情返回：`bookRes.BookResponse`。

server/.ai-specs/doc-api/admin/book_author.md

@@ -0,0 +1,29 @@
+# 书籍作者 admin 接口
+
+## 基本信息
+
+- 模块：book
+- 资源：作者
+- 端：admin
+- 鉴权：挂载 `PrivateGroup`，需要 `JWT + Casbin`
+- 操作审计：创建、更新、单删、批量删除写操作启用 `OperationRecord`
+- 路由前缀：`/book`
+
+## 默认 CRUD
+
+| 动作 | Method | 路径 | API 方法 | Service 方法 |
+|:---|:---|:---|:---|:---|
+| 创建 | `POST` | `/book/createBookAuthor` | `CreateBookAuthor` | `CreateBookAuthor` |
+| 单删 | `DELETE` | `/book/deleteBookAuthor` | `DeleteBookAuthor` | `DeleteBookAuthor` |
+| 批量删除 | `DELETE` | `/book/deleteBookAuthorByIds` | `DeleteBookAuthorByIds` | `DeleteBookAuthorByIds` |
+| 更新 | `PUT` | `/book/updateBookAuthor` | `UpdateBookAuthor` | `UpdateBookAuthor` |
+| 详情 | `GET` | `/book/findBookAuthor` | `FindBookAuthor` | `GetBookAuthor` |
+| 分页列表 | `GET` | `/book/getBookAuthorList` | `GetBookAuthorList` | `GetBookAuthorInfoList` |
+
+## 参数与返回
+
+- 创建、更新：`body` 使用 `book.BookAuthor`。
+- 单删、详情：`query id`。
+- 批量删除：`query ids[]`。
+- 分页列表：`query` 使用 `bookReq.BookAuthorSearch`，返回 `response.PageResult`。
+- 详情返回：`bookRes.BookAuthorResponse`。

server/.ai-specs/doc-api/admin/book_author_relation.md

@@ -0,0 +1,29 @@
+# 书籍作者关系 admin 接口
+
+## 基本信息
+
+- 模块：book
+- 资源：书籍作者关系
+- 端：admin
+- 鉴权：挂载 `PrivateGroup`，需要 `JWT + Casbin`
+- 操作审计：创建、更新、单删、批量删除写操作启用 `OperationRecord`
+- 路由前缀：`/book`
+
+## 默认 CRUD
+
+| 动作 | Method | 路径 | API 方法 | Service 方法 |
+|:---|:---|:---|:---|:---|
+| 创建 | `POST` | `/book/createBookAuthorRelation` | `CreateBookAuthorRelation` | `CreateBookAuthorRelation` |
+| 单删 | `DELETE` | `/book/deleteBookAuthorRelation` | `DeleteBookAuthorRelation` | `DeleteBookAuthorRelation` |
+| 批量删除 | `DELETE` | `/book/deleteBookAuthorRelationByIds` | `DeleteBookAuthorRelationByIds` | `DeleteBookAuthorRelationByIds` |
+| 更新 | `PUT` | `/book/updateBookAuthorRelation` | `UpdateBookAuthorRelation` | `UpdateBookAuthorRelation` |
+| 详情 | `GET` | `/book/findBookAuthorRelation` | `FindBookAuthorRelation` | `GetBookAuthorRelation` |
+| 分页列表 | `GET` | `/book/getBookAuthorRelationList` | `GetBookAuthorRelationList` | `GetBookAuthorRelationInfoList` |
+
+## 参数与返回
+
+- 创建、更新：`body` 使用 `book.BookAuthorRelation`。
+- 单删、详情：`query id`。
+- 批量删除：`query ids[]`。
+- 分页列表：`query` 使用 `bookReq.BookAuthorRelationSearch`，返回 `response.PageResult`。
+- 详情返回：`bookRes.BookAuthorRelationResponse`。

server/.ai-specs/doc-api/admin/book_chapter.md

@@ -0,0 +1,29 @@
+# 书籍章节 admin 接口
+
+## 基本信息
+
+- 模块：book
+- 资源：章节
+- 端：admin
+- 鉴权：挂载 `PrivateGroup`，需要 `JWT + Casbin`
+- 操作审计：创建、更新、单删、批量删除写操作启用 `OperationRecord`
+- 路由前缀：`/book`
+
+## 默认 CRUD
+
+| 动作 | Method | 路径 | API 方法 | Service 方法 |
+|:---|:---|:---|:---|:---|
+| 创建 | `POST` | `/book/createBookChapter` | `CreateBookChapter` | `CreateBookChapter` |
+| 单删 | `DELETE` | `/book/deleteBookChapter` | `DeleteBookChapter` | `DeleteBookChapter` |
+| 批量删除 | `DELETE` | `/book/deleteBookChapterByIds` | `DeleteBookChapterByIds` | `DeleteBookChapterByIds` |
+| 更新 | `PUT` | `/book/updateBookChapter` | `UpdateBookChapter` | `UpdateBookChapter` |
+| 详情 | `GET` | `/book/findBookChapter` | `FindBookChapter` | `GetBookChapter` |
+| 分页列表 | `GET` | `/book/getBookChapterList` | `GetBookChapterList` | `GetBookChapterInfoList` |
+
+## 参数与返回
+
+- 创建、更新：`body` 使用 `book.BookChapter`。
+- 单删、详情：`query id`。
+- 批量删除：`query ids[]`。
+- 分页列表：`query` 使用 `bookReq.BookChapterSearch`，返回 `response.PageResult`。
+- 详情返回：`bookRes.BookChapterResponse`。

server/.ai-specs/doc-api/admin/book_comment.md

@@ -0,0 +1,29 @@
+# 书籍评论 admin 接口
+
+## 基本信息
+
+- 模块：book
+- 资源：评论
+- 端：admin
+- 鉴权：挂载 `PrivateGroup`，需要 `JWT + Casbin`
+- 操作审计：创建、更新、单删、批量删除写操作启用 `OperationRecord`
+- 路由前缀：`/book`
+
+## 默认 CRUD
+
+| 动作 | Method | 路径 | API 方法 | Service 方法 |
+|:---|:---|:---|:---|:---|
+| 创建 | `POST` | `/book/createBookComment` | `CreateBookComment` | `CreateBookComment` |
+| 单删 | `DELETE` | `/book/deleteBookComment` | `DeleteBookComment` | `DeleteBookComment` |
+| 批量删除 | `DELETE` | `/book/deleteBookCommentByIds` | `DeleteBookCommentByIds` | `DeleteBookCommentByIds` |
+| 更新 | `PUT` | `/book/updateBookComment` | `UpdateBookComment` | `UpdateBookComment` |
+| 详情 | `GET` | `/book/findBookComment` | `FindBookComment` | `GetBookComment` |
+| 分页列表 | `GET` | `/book/getBookCommentList` | `GetBookCommentList` | `GetBookCommentInfoList` |
+
+## 参数与返回
+
+- 创建、更新：`body` 使用 `book.BookComment`。
+- 单删、详情：`query id`。
+- 批量删除：`query ids[]`。
+- 分页列表：`query` 使用 `bookReq.BookCommentSearch`，返回 `response.PageResult`。
+- 详情返回：`bookRes.BookCommentResponse`。

server/.ai-specs/doc-api/admin/book_comment_like_record.md

@@ -0,0 +1,29 @@
+# 评论点赞记录 admin 接口
+
+## 基本信息
+
+- 模块：book
+- 资源：评论点赞记录
+- 端：admin
+- 鉴权：挂载 `PrivateGroup`，需要 `JWT + Casbin`
+- 操作审计：创建、更新、单删、批量删除写操作启用 `OperationRecord`
+- 路由前缀：`/book`
+
+## 默认 CRUD
+
+| 动作 | Method | 路径 | API 方法 | Service 方法 |
+|:---|:---|:---|:---|:---|
+| 创建 | `POST` | `/book/createBookCommentLikeRecord` | `CreateBookCommentLikeRecord` | `CreateBookCommentLikeRecord` |
+| 单删 | `DELETE` | `/book/deleteBookCommentLikeRecord` | `DeleteBookCommentLikeRecord` | `DeleteBookCommentLikeRecord` |
+| 批量删除 | `DELETE` | `/book/deleteBookCommentLikeRecordByIds` | `DeleteBookCommentLikeRecordByIds` | `DeleteBookCommentLikeRecordByIds` |
+| 更新 | `PUT` | `/book/updateBookCommentLikeRecord` | `UpdateBookCommentLikeRecord` | `UpdateBookCommentLikeRecord` |
+| 详情 | `GET` | `/book/findBookCommentLikeRecord` | `FindBookCommentLikeRecord` | `GetBookCommentLikeRecord` |
+| 分页列表 | `GET` | `/book/getBookCommentLikeRecordList` | `GetBookCommentLikeRecordList` | `GetBookCommentLikeRecordInfoList` |
+
+## 参数与返回
+
+- 创建、更新：`body` 使用 `book.BookCommentLikeRecord`。
+- 单删、详情：`query id`。
+- 批量删除：`query ids[]`。
+- 分页列表：`query` 使用 `bookReq.BookCommentLikeRecordSearch`，返回 `response.PageResult`。
+- 详情返回：`bookRes.BookCommentLikeRecordResponse`。

server/.ai-specs/doc-api/admin/book_favorite_record.md

@@ -0,0 +1,29 @@
+# 书籍收藏记录 admin 接口
+
+## 基本信息
+
+- 模块：book
+- 资源：收藏记录
+- 端：admin
+- 鉴权：挂载 `PrivateGroup`，需要 `JWT + Casbin`
+- 操作审计：创建、更新、单删、批量删除写操作启用 `OperationRecord`
+- 路由前缀：`/book`
+
+## 默认 CRUD
+
+| 动作 | Method | 路径 | API 方法 | Service 方法 |
+|:---|:---|:---|:---|:---|
+| 创建 | `POST` | `/book/createBookFavoriteRecord` | `CreateBookFavoriteRecord` | `CreateBookFavoriteRecord` |
+| 单删 | `DELETE` | `/book/deleteBookFavoriteRecord` | `DeleteBookFavoriteRecord` | `DeleteBookFavoriteRecord` |
+| 批量删除 | `DELETE` | `/book/deleteBookFavoriteRecordByIds` | `DeleteBookFavoriteRecordByIds` | `DeleteBookFavoriteRecordByIds` |
+| 更新 | `PUT` | `/book/updateBookFavoriteRecord` | `UpdateBookFavoriteRecord` | `UpdateBookFavoriteRecord` |
+| 详情 | `GET` | `/book/findBookFavoriteRecord` | `FindBookFavoriteRecord` | `GetBookFavoriteRecord` |
+| 分页列表 | `GET` | `/book/getBookFavoriteRecordList` | `GetBookFavoriteRecordList` | `GetBookFavoriteRecordInfoList` |
+
+## 参数与返回
+
+- 创建、更新：`body` 使用 `book.BookFavoriteRecord`。
+- 单删、详情：`query id`。
+- 批量删除：`query ids[]`。
+- 分页列表：`query` 使用 `bookReq.BookFavoriteRecordSearch`，返回 `response.PageResult`。
+- 详情返回：`bookRes.BookFavoriteRecordResponse`。

server/.ai-specs/doc-api/admin/book_read_record.md

@@ -0,0 +1,29 @@
+# 书籍阅读记录 admin 接口
+
+## 基本信息
+
+- 模块：book
+- 资源：阅读记录
+- 端：admin
+- 鉴权：挂载 `PrivateGroup`，需要 `JWT + Casbin`
+- 操作审计：创建、更新、单删、批量删除写操作启用 `OperationRecord`
+- 路由前缀：`/book`
+
+## 默认 CRUD
+
+| 动作 | Method | 路径 | API 方法 | Service 方法 |
+|:---|:---|:---|:---|:---|
+| 创建 | `POST` | `/book/createBookReadRecord` | `CreateBookReadRecord` | `CreateBookReadRecord` |
+| 单删 | `DELETE` | `/book/deleteBookReadRecord` | `DeleteBookReadRecord` | `DeleteBookReadRecord` |
+| 批量删除 | `DELETE` | `/book/deleteBookReadRecordByIds` | `DeleteBookReadRecordByIds` | `DeleteBookReadRecordByIds` |
+| 更新 | `PUT` | `/book/updateBookReadRecord` | `UpdateBookReadRecord` | `UpdateBookReadRecord` |
+| 详情 | `GET` | `/book/findBookReadRecord` | `FindBookReadRecord` | `GetBookReadRecord` |
+| 分页列表 | `GET` | `/book/getBookReadRecordList` | `GetBookReadRecordList` | `GetBookReadRecordInfoList` |
+
+## 参数与返回
+
+- 创建、更新：`body` 使用 `book.BookReadRecord`。
+- 单删、详情：`query id`。
+- 批量删除：`query ids[]`。
+- 分页列表：`query` 使用 `bookReq.BookReadRecordSearch`，返回 `response.PageResult`。
+- 详情返回：`bookRes.BookReadRecordResponse`。

server/.ai-specs/doc-api/admin/book_series.md

@@ -0,0 +1,29 @@
+# 书籍系列 admin 接口
+
+## 基本信息
+
+- 模块：book
+- 资源：系列
+- 端：admin
+- 鉴权：挂载 `PrivateGroup`，需要 `JWT + Casbin`
+- 操作审计：创建、更新、单删、批量删除写操作启用 `OperationRecord`
+- 路由前缀：`/book`
+
+## 默认 CRUD
+
+| 动作 | Method | 路径 | API 方法 | Service 方法 |
+|:---|:---|:---|:---|:---|
+| 创建 | `POST` | `/book/createBookSeries` | `CreateBookSeries` | `CreateBookSeries` |
+| 单删 | `DELETE` | `/book/deleteBookSeries` | `DeleteBookSeries` | `DeleteBookSeries` |
+| 批量删除 | `DELETE` | `/book/deleteBookSeriesByIds` | `DeleteBookSeriesByIds` | `DeleteBookSeriesByIds` |
+| 更新 | `PUT` | `/book/updateBookSeries` | `UpdateBookSeries` | `UpdateBookSeries` |
+| 详情 | `GET` | `/book/findBookSeries` | `FindBookSeries` | `GetBookSeries` |
+| 分页列表 | `GET` | `/book/getBookSeriesList` | `GetBookSeriesList` | `GetBookSeriesInfoList` |
+
+## 参数与返回
+
+- 创建、更新：`body` 使用 `book.BookSeries`。
+- 单删、详情：`query id`。
+- 批量删除：`query ids[]`。
+- 分页列表：`query` 使用 `bookReq.BookSeriesSearch`，返回 `response.PageResult`。
+- 详情返回：`bookRes.BookSeriesResponse`。

server/.ai-specs/doc-api/admin/sys_api.md

@@ -0,0 +1,39 @@
+# API 管理 admin 接口
+
+## 基本信息
+
+- 模块：sys_api
+- 资源：API 管理
+- 端：admin
+- 鉴权：挂载 `PrivateGroup`，需要 `JWT + Casbin`
+- 操作审计：`/api/enterSyncApi` 启用 `OperationRecord`
+- 路由前缀：`/api`
+
+## 同步接口
+
+| 动作 | Method | 路径 | API 方法 | Service 方法 |
+|:---|:---|:---|:---|:---|
+| 预览同步差异 | `GET` | `/api/syncApi` | `SyncApi` | `SyncApi` |
+| 确认同步路由 | `POST` | `/api/enterSyncApi` | `EnterSyncApi` | `EnterSyncApi` / `SyncApiToDB` |
+| 获取 API 关联角色 | `GET` | `/api/getApiRoles` | `GetApiRoles` | `GetAuthoritiesByApi` |
+| 覆盖 API 关联角色 | `POST` | `/api/setApiRoles` | `SetApiRoles` | `SetApiAuthorities` |
+| 刷新 Casbin 缓存 | `GET` | `/api/freshCasbin` | `FreshCasbin` | `FreshCasbin` |
+
+## 参数与返回
+
+- `/api/syncApi`：无入参，返回 `newApis`、`deleteApis`、`ignoreApis`，只预览差异，不写库。
+- `/api/enterSyncApi`：允许空 body 或 `{}`，默认以当前 Gin 路由表 `global.GVA_ROUTERS` 为事实来源同步 `sys_apis`。
+- `/api/enterSyncApi`：兼容旧请求体 `systemRes.SysSyncApis`，传入 `newApis/deleteApis` 时按传入列表写入或删除。
+- `/api/getApiRoles`：query 传入 `path`、`method`，返回该 API 已关联的角色 ID 列表。
+- `/api/setApiRoles`：body 传入 `path`、`method`、`authorityIds`，全量覆盖该 API 的角色权限。
+- `/api/freshCasbin`：无入参，刷新 Casbin 缓存；该接口走公开路由但写入 `sys_ignore_apis`，不作为角色权限点维护。
+- 返回：统一使用 `response.Response`。
+
+## 同步规则
+
+- 新路由：`sys_apis` 中不存在同一 `path + method` 时自动新增。
+- 已有路由：保留原 `description`、`apiGroup` 等人工维护字段，不自动覆盖。
+- 忽略路由：存在于 `sys_ignore_apis` 的 `path + method` 不写入 `sys_apis`。
+- 失效路由：数据库中存在但当前 Gin 路由表不存在时，从 `sys_apis` 删除，并清理对应 Casbin 权限。
+- 默认管理员角色 `888` 必须具备 `/api/getApiRoles` 与 `/api/setApiRoles` 权限，避免出现“无权分配权限”的系统初始化死锁。
+- 公开接口、仅登录接口不应长期作为角色权限点维护；需要通过 `sys_ignore_apis` 排除。