xuanzhi-service/server/AGENTS.md

AI 开发入口 [!IMPORTANT]

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

工具使用规则

• 搜索范围限制：Grep/Glob 严禁全盘搜索，绝对禁止扫描 .gitignore 忽略的目录，以避免性能卡顿。
• 读写：所有文件读取/写入统一使用 UTF-8（建议无 BOM）
• 读写：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。

• 代码链路：本项目采用 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 注册

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

架构关系

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

flowchart LR
    DOCSQL["doc-sql<br/>表结构/字段/索引/约束"] --> Model
    DOCDICT["doc-dict<br/>状态/类型/枚举值域"] --> Model
    DOCDICT --> Service
    DOCDICT --> API
    Model --> Service
    Service --> API
    API --> Router  无法显示出图像啊

• 改 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；禁止只改链路中的单点而不回查上下游。

项目文档

• 根目录：.ai-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 结构时必读

requirements 存放需求草案文档

路径	用途	说明
.ai-specs\requirements\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\requirements-stage-spec.md	规定 requirements 需求草案阶段的文档边界、结构和输出方式	涉及新增/修改 .ai-specs\requirements\*.md 时必读

doc-api <admin or app or 平台>

路径	用途	说明

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

路径	用途	说明
.ai-specs\doc-sql\book_author.md	定义书籍作者表的字段、索引、SQL 基线和兼容要求	涉及书籍作者表建模、迁移、唯一性约束和书籍作者关系改造时必读

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

路径	用途	说明
.ai-specs\doc-dict\book_author_status.md	定义作者状态的标准值域	涉及作者状态的存储、校验、展示和接口出入参时必读
.ai-specs\doc-dict\book_completion_status.md	定义书籍完结状态的标准值域	涉及书籍完结状态的存储、校验、展示和接口出入参时必读
.ai-specs\doc-dict\book_process_status.md	定义书籍文件处理状态的标准值域	涉及原始文件准备、章节拆分、章节校验、处理完成等流程状态时必读

可复用代码/组件

中文	代码文件名	说明