项目初始化提交，移除仓库默认README

2026-08-21 09:37:21 +08:00
parent 729e1d0c35
commit 000993df80
30 changed files with 1497 additions and 0 deletions
@@ -0,0 +1,53 @@
+---
+name: java-backend-doc-maintainer
+description: "项目级 skill（由全局 java-backend-doc-maintainer 在用户手动启用本工程时写入）。在本 Spring Boot 工程内：新增/重命名/删除 .java 源文件时自动同步 后端文件速查表.md；发生重大功能变化或用户手动输出 \"更新后端项目知识库\" 时更新 后端项目知识库.md。仅在当前工程生效，打开其他工程不会触发。"
+agent_created: true
+---
+
+# Java 后端文档维护（项目级自动维护）
+
+> 本 skill 由全局 java-backend-doc-maintainer 在用户于本工程手动触发时写入，仅对当前 Spring Boot 工程生效。生效后：文件增删改自动维护文档，无需每次手动。
+
+## 两份文档与触发时机
+| 文档 | 位置 | 触发 |
+| --- | --- | --- |
+| 后端文件速查表.md | 工程根（pom.xml 同级） | 本工程内**新增 / 重命名 / 删除** .java 时自动同步；或用户手动输出 **"更新后端文件速查表"** 全量重建 |
+| 后端项目知识库.md | 同上 | **重大功能变化**时更新；或用户手动输出 **"更新后端项目知识库"** 强制梳理 |
+
+## 工程根目录
+即本 skill 所在工程的 `pom.xml` 同级目录（已激活，无需再向上查找）。
+
+## 一、后端文件速查表.md（文件级索引）
+维护触发：**本工程内新增 / 重命名 / 删除** 一个 `.java` 源文件（`src/main/java` 或 `src/test/java`）时立即同步；纯内容改动（不改文件名/路径）不触发。
+
+内容结构（保持表格，按层分组）：
+- 顶部：工程名、基础包、最近更新时间、维护规则。
+- 分组表（每组一个二级标题）：Controller / Service / Repository / Entity·Model / DTO·VO·Request / Config / Common（aspect、annotation、util、interceptor、listener）/ 其他（task、event、enums）。
+- 每行字段：`路径(相对工程根)` ｜ `类名` ｜ `职责(一句话)` ｜ `关键关联`（如关联实体、对外接口、调用的服务）。
+- 重命名：更新该行路径与类名，并在表末"变更记录"追加（旧路径 → 新路径，时间）。
+- 删除：移除该行，变更记录追加"删除 路径 时间"。
+- 新增：插入对应分组，变更记录追加"新增 路径 时间"。
+- 若文件缺失，从 `references/backend-file-index.template.md` 复制骨架，先全量扫描现有源码再填，不要留空。
+
+## 二、后端项目知识库.md（架构 / 功能 / 约定）
+维护触发（满足任一即更新）：
+1. 用户手动输出 **"更新后端项目知识库"**（最高优先，立即全量梳理）。
+2. 发生重大功能变化：新增业务模块 / 领域、新增一组对外 API、引入新中间件或外部系统对接、核心流程 / 权限模型 / 数据模型重大调整、技术栈版本迁移。判断标准：影响"系统由哪些部分组成、如何协作、有哪些约定"的变化；普通 bug 修复、单文件小改不触发。
+
+内容结构见 `references/backend-knowledge.template.md`：
+- 项目概览（定位、技术栈版本、运行方式）
+- 模块 / 包结构（各层职责）
+- 核心领域模型与关系（逻辑外键请注明）
+- 关键业务流程
+- 工程约定与模式（异常返回结构、鉴权、CORS、缓存、事务边界等——只记录真实存在的，不臆造）
+- 集成点（DB / Redis / MQ / Nacos / SSO-CAS / 外部 API，写用途不写密钥）
+- 重要设计决策与原因
+- 待办 / 已知坑
+
+若文件缺失，从 `references/backend-knowledge.template.md` 复制骨架再填。
+
+## 反幻觉与纪律
+- 维护前用 Glob / Grep / Read 核实文件真实存在、类名真实、职责真实。
+- 不因为"应该长这样"而编造；不确定就标注"待核实"。
+- 两份文件保持可机器读取的表格 / 标题结构，方便后续 AI 速查。
+- 不写入密钥、密码、token；`bootstrap.yml` / `application.yml` 等未经授权不改动，仅给诊断建议。
@@ -0,0 +1,49 @@
+# 后端文件速查表
+
+> 工程：<工程名> ｜ 基础包：<base package> ｜ 最近更新：<YYYY-MM-DD>
+> 维护规则：本表在**新增 / 重命名 / 删除** .java 源文件时自动同步；纯内容改动不触发。也可手动输出"更新后端文件速查表"全量重建。
+
+## Controller（接口层）
+| 路径(相对工程根) | 类名 | 职责 | 关键关联 |
+| --- | --- | --- | --- |
+| src/main/java/<base>/controller/XxxController.java | XxxController | 一句话职责 | 关联实体/接口 |
+
+## Service
+| 路径(相对工程根) | 类名 | 职责 | 关键关联 |
+| --- | --- | --- | --- |
+| src/main/java/<base>/service/XxxService.java | XxxService | 一句话职责 | 调用/被调用 |
+
+## Repository
+| 路径(相对工程根) | 类名 | 职责 | 关键关联 |
+| --- | --- | --- | --- |
+| src/main/java/<base>/repository/XxxRepository.java | XxxRepository | 数据访问 | 实体 |
+
+## Entity / Model
+| 路径(相对工程根) | 类名 | 职责 | 关键关联 |
+| --- | --- | --- | --- |
+| src/main/java/<base>/entity/Xxx.java | Xxx | 实体 | 逻辑外键 |
+
+## DTO / VO / Request
+| 路径(相对工程根) | 类名 | 职责 | 关键关联 |
+| --- | --- | --- | --- |
+| src/main/java/<base>/model/XxxDto.java | XxxDto | 入参/出参 | 关联实体 |
+
+## Config
+| 路径(相对工程根) | 类名 | 职责 | 关键关联 |
+| --- | --- | --- | --- |
+| src/main/java/<base>/config/XxxConfig.java | XxxConfig | 配置 | Bean/拦截器 |
+
+## Common（aspect/annotation/util/interceptor/listener）
+| 路径(相对工程根) | 类名 | 职责 | 关键关联 |
+| --- | --- | --- | --- |
+| src/main/java/<base>/common/Xxx.java | Xxx | 公共能力 | 使用点 |
+
+## 其他（task/event/enums）
+| 路径(相对工程根) | 类名 | 职责 | 关键关联 |
+| --- | --- | --- | --- |
+| src/main/java/<base>/enums/XxxEnum.java | XxxEnum | 枚举 | 使用点 |
+
+## 变更记录
+| 时间 | 类型 | 说明 |
+| --- | --- | --- |
+| YYYY-MM-DD | 初始化 | 建表 |
@@ -0,0 +1,35 @@
+# 后端项目知识库
+
+> 工程：<工程名> ｜ 技术栈：Spring Boot <x.y.z> / JDK <n> / <ORM> ｜ 最近更新：<YYYY-MM-DD>
+> 维护规则：发生重大功能变化、或收到"更新后端项目知识库"指令时更新。
+
+## 一、项目概览
+- 定位：
+- 技术栈与版本（Spring Boot / JDK / JPA-MyBatis / 构建工具）：
+- 启动 / 运行方式（端口、profile、入口类）：
+
+## 二、模块与包结构
+（各层 / 各 package 的职责，例如 controller 负责接口、service 负责业务、repository 负责数据访问）
+
+## 三、核心领域模型与关系
+（实体、关键字段、相互关系；若存在逻辑外键请注明"无物理外键，靠业务字段关联"）
+
+## 四、关键业务流程
+（主要用例 / 请求链路，例如登录、授权、数据集成）
+
+## 五、工程约定与模式
+（仅记录本项目真实存在的约定，不臆造）
+- 异常返回结构（如统一 HTTP 200 + `{code,msg,data}`）：
+- 鉴权方式（如 CAS SSO / JWT / header 触发式 CORS）：
+- 缓存（如 Redis 序列化需注册 JavaTimeModule）：
+- 事务边界：
+- 分页查询约定（如 BasePageQuery / BasePageResult）：
+
+## 六、集成点
+（数据库 / Redis / 消息队列 / 配置中心 Nacos / SSO-CAS / 外部 API，写明用途，不写密钥）
+
+## 七、重要设计决策与原因
+（为何这样分层、关键取舍，例如"去 L1/L2 分层配置、回归单层 + 重启兜底"）
+
+## 八、待办与已知坑
+（未完成的白名单策略、待修项、历史踩坑）