# AI 开发入口 [!IMPORTANT]

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

## 工具使用规则

- **搜索范围限制**：Grep/Glob 严禁全盘搜索，绝对禁止扫描 `server\docs`、`.worktrees`、`web\node_modules`、`web\dist`、`server\log`、`server\uploads`、`rm_file` 等大目录，以避免性能卡顿。
- **读写**：所有文件读取/写入统一使用 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` 单线调用关系。

```mermaid
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\doc-api-doc-spec.md` | 规定 `doc-api` 从空文档生成接口 contract 的输入源、admin CRUD 模板、字段来源和硬性要求 | 涉及新增/修改 `.ai-specs\doc-api` 接口文档时必读 |
| `.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\common_enabled_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` | 定义书籍类型动态值域字典的来源、用途和逻辑边界 | 涉及书籍类型落库、类型校验和系统字典独立封装时必读 |


## 可复用代码/组件

| 中文 | 代码文件名 | 说明 |
|:---|:---|:---|