145 lines
12 KiB
Markdown
145 lines
12 KiB
Markdown
# 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` 约束值域与枚举。
|
||
|
||
```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` 结构时必读 |
|
||
|
||
### 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` | 定义书籍文件处理状态的标准值域 | 涉及原始文件准备、章节拆分、章节校验、处理完成等流程状态时必读 |
|
||
|
||
|
||
## 可复用代码/组件
|
||
|
||
| 中文 | 代码文件名 | 说明 |
|
||
|:---|:---|:---|
|