服务端

2026-04-22 15:49:50 +08:00
parent 05ee541420
commit 8164eec650
18 changed files with 1115 additions and 251 deletions
--- a/server/AGENTS.md
+++ b/server/AGENTS.md
@@ -0,0 +1,141 @@
+# AI 开发入口 [!IMPORTANT]
+
+- **本文档要求**：本文档为项目级别规范和重要导航,必须严格参考
+- **本文档要求**：本文档只允许在已有的结构上CURD,不允许增加其他标题区
+- **本文档要求**：.ai-specs 目录下新增/删除任何文档的时候都应该 在本文档中修改 `## 项目文档`
+- **文档要求**：规范型文档是给 AI 的顶层入口文档，不是“解释得更全”就更好，而是要 更短、更硬、更可判定
+- **代码优化**：先复用再新增,允许抽公共逻辑，但公共逻辑必须保证边界仍清晰。
+- **代码优化**：优化代码时必须同时考虑冗余、孤岛代码、代码清晰度、复杂度、边界条件和兼容性，不能只追求功能跑通。不要修改ui/ux 视觉效果,除非明确要求。
+- **代码默认遵循**：业务流程需要遵循 `主流做法` `工业级正规`
+- **代码默认遵循**：强制工作流：按`## 项目文档`定位需要的文档 → 读取匹配文档 → 进入源码
+
+## 工具使用规则
+
+- **搜索范围限制**：Grep/Glob 严禁全盘搜索，绝对禁止扫描 `.gitignore` 忽略的目录，以避免性能卡顿。
+- **读写**：所有文件读取/写入统一使用 UTF-8（建议无 BOM）
+- **读写**：PowerShell/脚本读取项目文件必须显式指定 `-Encoding utf8`
+- **画图**：优先使用 `mermaid flowchart `
+- **对话/文档编写**：必须是 中文为主体语言，技术术语保留英文原文
+
+## 项目架构
+- **技术栈**：本项目为 `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` 约束值域与枚举。
+
+```mermaid
+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` 结构时必读 |
+
+### logic-specs     存放业务说明文档不设计代码
+
+| 路径 | 用途 | 说明 |
+|:---|:---|:---|
+| `.ai-specs\logic-specs\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` | 规定业务模块中文名与英文名的统一登记方式 | 涉及新增/修改业务模块命名、中英文对照、目录命名时必读 |
+
+### 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` | 定义书籍完结状态的标准值域 | 涉及书籍完结状态的存储、校验、展示和接口出入参时必读 |
+
+
+## 可复用代码/组件
+
+| 中文 | 代码文件名 | 说明 |
+|:---|:---|:---|