xuanzhi-service/server/AGENTS.md

AI 开发入口 [!IMPORTANT]

• 本文档要求：本文档为项目级别规范和重要导航,必须严格参考
• 本文档要求：本文档只允许在已有的结构上CURD,不允许增加其他标题区
• 本文档要求：.ai-specs 目录下新增/删除任何文档的时候都应该 在本文档中修改 ## 项目文档
• 文档要求：规范型文档是给 AI 的顶层入口文档，不是“解释得更全”就更好，而是要 更短、更硬、更可判定
• 文档要求：如果我的需求/要求和规范文档冲突,你应该及时提醒我,让我决策是修正需求/规范文档
• 代码优化：先复用再新增,允许抽公共逻辑，但公共逻辑必须保证边界仍清晰。
• 代码优化：优化代码时必须同时考虑冗余、孤岛代码、代码清晰度、复杂度、边界条件和兼容性，不能只追求功能跑通。不要修改ui/ux 视觉效果,除非明确要求。
• 代码默认遵循：业务流程需要遵循 主流做法 工业级正规
• 代码默认遵循：强制工作流：按## 项目文档定位需要的文档 → 读取匹配文档 → 进入源码

工具使用规则

• 搜索范围限制：Grep/Glob 严禁全盘搜索，绝对禁止扫描 .gitignore 忽略的目录，以避免性能卡顿。
• 读写：所有文件读取/写入统一使用 UTF-8（建议无 BOM）
• 读写：PowerShell/脚本读取项目文件必须显式指定 -Encoding utf8
• 画图：优先使用 Mermaid 图 不能混入非 Mermaid 语法文本。
• 对话/文档编写：必须是 中文为主体语言，技术术语保留英文原文
• 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。

• 代码链路：本项目采用 Router → API → Service → GORM → Database 分层。

• Model 不作为独立调用层，负责承载实体、request、response，贯穿 API、Service、数据库映射全过程。

  ├── server ├── api (api层) │ └── v1 (v1版本接口) ├── config (配置包) ├── core (核心文件) ├── docs (swagger文档目录) ├── global (全局对象)
  ├── initialize (初始化)
  │ └── internal (初始化内部函数)
  ├── middleware (中间件层)
  ├── model (模型层)
  │ ├── request (入参结构体)
  │ └── response (出参结构体)
  ├── packfile (静态文件打包)
  ├── resource (静态资源文件夹)
  │ ├── excel (excel导入导出默认路径)
  │ ├── page (表单生成器)
  │ └── template (模板)
  ├── router (路由层)
  ├── service (service层)
  ├── source (source层)
  └── utils (工具包)
  ├── timer (定时器接口封装)
  └── upload (oss接口封装)

层级	职责	命名规范
Router	定义路由、路由分组、中间件、接口挂载关系；禁止承载业务逻辑	目录固定 router/<module>；聚合入口固定 enter.go；路由承载结构体使用 *Router
API	接收请求、参数绑定、基础校验、调用 Service、返回统一响应	目录固定 api/v1/<module>；聚合入口固定 enter.go；接口承载结构体使用 *Api
Service	实现业务规则、流程编排、事务控制、数据库读写；禁止把复杂业务长期堆在 API	目录固定 service/<module>；聚合入口固定 enter.go；服务承载结构体使用 *Service
Model	定义表结构、request、response 结构体，作为分层之间的数据载体	实体放在 model/<module>；入参放在 model/<module>/request；出参放在 model/<module>/response；结构体名使用 PascalCase
Database	持久化存储，由 Service 通过 GORM 直接访问	数据库访问统一走 global.GVA_DB；表迁移统一在 initialize/gorm_biz.go 注册

链路关系

• 修改/新增对应落点时必须严格遵循以下规范

链路总线

• 关系总线：doc-sql / doc-dict → Model → Service → API → Router，其中 Model 贯穿 API、Service 与数据库映射；doc-sql 约束表结构，doc-dict 约束值域与枚举。

新增链路规范

• 新增业务模块时，主落点一律放在 service/<module>。
• 新增业务模块时，接口配套放在 api/v1/<module>。
• 新增业务模块时，路由配套放在 router/<module>。
• 新增业务模块时，数据模型配套放在 model/<module>。
• 新增业务路由时，统一在 initialize/router_biz.go 注册。
• 涉及表结构变更时，统一在 initialize/gorm_biz.go 注册迁移。
• 本项目有admin/app 2套接口，一般默认是admin接口，app接口按需增加

代码联动

• 改 doc-sql：不能只改文档；必须同步检查并修改 model/<module> 实体字段、service/<module> 读写逻辑、initialize/gorm_biz.go 迁移注册。若字段名、类型、默认值、索引、唯一约束变化，相关查询条件、排序、唯一性校验、兼容逻辑都要一起改。
• 改 doc-dict：必须同步修改代码里的枚举/常量、Model 字段注释与值域约束、API 参数校验、Service 分支判断与展示转换。若接口出入参暴露该值域，相关 doc-api 也必须同步。
• 改 Model：必须区分是改实体、request 还是 response。改实体时，同步检查 Service 的查询/写入/扫描字段，以及 doc-sql 是否仍一致；改 request/response 时，同步检查 API 绑定、返回和 doc-api。
• 改 Service：同步检查 Model 是否足够承载新字段/新状态，API 调用参数和返回值是否需要变化。若业务规则新增状态、类型、来源等值域，必须回头修改 doc-dict；若涉及落库结构变化，必须回头修改 doc-sql 与迁移注册。
• 改 API：同步检查 Router 挂载的方法、路径、鉴权与分组是否一致；同步检查 Model/request、Model/response 和 Service 方法签名。若接口 contract 变化，doc-api 必须同步。
• 改 Router：同步检查 API 是否已有对应处理函数；新增或调整业务路由时，必须同步修改 initialize/router_biz.go 注册。若分组、版本、权限中间件变化，相关接口文档与调用方也要一起检查。
• 新增/修改业务功能时，默认顺序是：先定 doc-sql / doc-dict，再落 Model，再写 Service，再接 API，最后挂 Router；禁止只改链路中的单点而不回查上下游。

关系图

• 关系图必须覆盖文档约束、代码落点、注册入口和数据库落点；禁止只画 Model → Service → API → Router 单线调用关系。

flowchart LR
    DOCSQL["doc-sql<br/>表结构/字段/索引/约束"] --> Entity["Model Entity<br/>数据库实体"]
    DOCDICT["doc-dict<br/>状态/类型/枚举值域"] --> Entity
    DOCDICT --> Service
    DOCDICT --> API

    DOCAPI["doc-api<br/>路径/鉴权/参数/返回"] --> ReqResp["Model request/response<br/>入参/出参"]
    DOCAPI --> API
    DOCAPI --> Router

    Entity --> Service
    ReqResp --> API
    Service --> API
    API --> Router
    Router --> RouterInit["initialize/router_biz.go<br/>路由注册"]
    Service --> DB["Database<br/>GORM"]
    Entity --> GormInit["initialize/gorm_biz.go<br/>迁移注册"]
    GormInit --> DB

项目文档

• 根目录：.ai-specs
• 要求：开始写代码前，根据任务类型先定位目录，再读取对应文档；有对应文档必须先读。
• 兜底：索引表无匹配时，按本文件通用规则和现有同层代码风格实现
• 阶段入口：/admin-service-prd-draft、/admin-service-data-model、/admin-service-coding 属于全局 Skill 强交互入口，不在 .ai-specs\sys-specs 中维护

coding-specs 存放对功能代码的说明/限制/要求

路径	用途	说明
.ai-specs\coding-specs\api-auth-control.md	规定 API 在“不需要登录 / 需要登录 / 需要权限”之间切换时的路由挂载与权限同步方式	涉及接口鉴权方式调整、公开接口、仅登录接口、角色权限接口时必读
.ai-specs\coding-specs\module-admin-crud-default.md	规定业务模块 admin 端默认 CRUD 接口集合、命名、Method 与挂载方式	涉及新增业务后台 CRUD、判断默认后台接口应该有哪些时必读
.ai-specs\coding-specs\module-admin-app-split.md	规定同一业务模块下 admin 管理端接口与 app 用户端接口的目录落点、分层方式与鉴权边界	涉及 book 等同模块同时提供 admin/app 两套接口时必读
.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 结构时必读

prd-draft 存放需求草案文档

路径	用途	说明
.ai-specs\prd-draft\book.md	记录书籍需求草案，先列相关表和字段，再列业务需求描述	涉及书籍、书籍系列、书籍作者、书籍评论等业务设计时先读

sys-specs 存放系统级文档

路径	用途	说明
.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\database-upgrade-doc-spec.md	规定 .ai-transition\database-upgrade-doc 数据库升级 SQL 的版本定位、写入时机和兼容 SQL 要求	涉及修改 doc-sql 并产生数据库结构变更、维护 v1.sql/v2.sql 等升级 SQL 时必读

doc-api <admin or app or 平台>

路径	用途	说明
.ai-specs\doc-api\admin\book.md	定义书籍信息 admin 端 CRUD 接口路径、鉴权、审计和参数返回约定	涉及书籍主资料后台接口实现、路由挂载和接口 contract 调整时必读
.ai-specs\doc-api\admin\book_author.md	定义书籍作者 admin 端 CRUD 接口路径、鉴权、审计和参数返回约定	涉及作者后台接口实现、路由挂载和接口 contract 调整时必读
.ai-specs\doc-api\admin\book_author_relation.md	定义书籍作者关系 admin 端 CRUD 接口路径、鉴权、审计和参数返回约定	涉及书籍作者绑定后台接口实现、路由挂载和接口 contract 调整时必读
.ai-specs\doc-api\admin\book_chapter.md	定义书籍章节 admin 端 CRUD 接口路径、鉴权、审计和参数返回约定	涉及章节后台接口实现、路由挂载和接口 contract 调整时必读
.ai-specs\doc-api\admin\book_comment.md	定义书籍评论 admin 端 CRUD 接口路径、鉴权、审计和参数返回约定	涉及评论后台接口实现、路由挂载和接口 contract 调整时必读
.ai-specs\doc-api\admin\book_comment_like_record.md	定义评论点赞记录 admin 端 CRUD 接口路径、鉴权、审计和参数返回约定	涉及评论点赞记录后台接口实现、路由挂载和接口 contract 调整时必读
.ai-specs\doc-api\admin\book_favorite_record.md	定义书籍收藏记录 admin 端 CRUD 接口路径、鉴权、审计和参数返回约定	涉及收藏记录后台接口实现、路由挂载和接口 contract 调整时必读
.ai-specs\doc-api\admin\book_read_record.md	定义书籍阅读记录 admin 端 CRUD 接口路径、鉴权、审计和参数返回约定	涉及阅读记录后台接口实现、路由挂载和接口 contract 调整时必读
.ai-specs\doc-api\admin\book_series.md	定义书籍系列 admin 端 CRUD 接口路径、鉴权、审计和参数返回约定	涉及系列后台接口实现、路由挂载和接口 contract 调整时必读
.ai-specs\doc-api\admin\sys_api.md	定义 API 管理 admin 端同步接口路径、鉴权、审计和参数返回约定	涉及 API 路由同步、权限点自动入库、忽略接口和 Casbin 清理时必读

doc-sql 存放具体业务表文档

路径	用途	说明
.ai-specs\doc-sql\book.sql	定义书籍主表的字段、字典引用、聚合展示字段和系列挂载方式	涉及书籍主资料建模、书籍列表/详情查询、上下架与完结状态落库时必读
.ai-specs\doc-sql\book_author.sql	定义书籍作者表的字段、索引、SQL 基线和兼容要求	涉及书籍作者表建模、迁移、唯一性约束和书籍作者关系改造时必读
.ai-specs\doc-sql\book_author_relation.sql	定义书籍与作者关联表的字段、唯一性约束和排序落库方式	涉及书籍作者绑定、作者排序和书籍作者关系维护时必读
.ai-specs\doc-sql\book_chapter.sql	定义书籍章节表的字段、章节编号唯一性和阅读发布基础约束	涉及章节建模、章节排序、阅读开放状态和章节文件地址维护时必读
.ai-specs\doc-sql\book_comment.sql	定义书籍评论表的字段、评论锚点结构和评论状态落库方式	涉及整书/整章/文本行评论定位、评论列表和评论状态处理时必读
.ai-specs\doc-sql\book_comment_like_record.sql	定义评论点赞记录表的字段和幂等唯一约束	涉及评论点赞、取消点赞和点赞关系判断时必读
.ai-specs\doc-sql\book_favorite_record.sql	定义用户收藏记录表的字段和用户-书籍唯一约束	涉及用户收藏、取消收藏和收藏列表维护时必读
.ai-specs\doc-sql\book_read_record.sql	定义用户阅读记录表的字段、续读锚点和用户-书籍唯一约束	涉及阅读历史、续读恢复和阅读进度回写时必读
.ai-specs\doc-sql\book_series.sql	定义书籍系列表的字段和系列启停基础结构	涉及书籍系列建模、系列展示和系列启停处理时必读

doc-dict 存放具体业务字典文档

路径	用途	说明
.ai-specs\doc-dict\book_author_status.md	定义作者状态的标准值域	涉及作者状态的存储、校验、展示和接口出入参时必读
.ai-specs\doc-dict\book_comment_status.md	定义书籍评论状态的标准值域	涉及评论状态存储、评论隐藏和评论出入参展示时必读
.ai-specs\doc-dict\book_completion_status.md	定义书籍完结状态的标准值域	涉及书籍完结状态的存储、校验、展示和接口出入参时必读
.ai-specs\doc-dict\book_era_tag.md	定义书籍时代标签的标准值域	涉及时代标签存储、筛选聚合和接口出入参时必读
.ai-specs\doc-dict\book_publish_status.md	定义书籍上下架状态的标准值域	涉及书籍上架、下架、草稿状态存储和展示时必读
.ai-specs\doc-dict\book_type.md	定义书籍类型动态值域字典的来源、用途和逻辑边界	涉及书籍类型落库、类型校验和系统字典独立封装时必读

可复用代码/组件

中文	代码文件名	说明