diff --git a/README.md b/README.md index 23438c5..c845524 100644 --- a/README.md +++ b/README.md @@ -14,11 +14,20 @@ rui-docs/ │ └── coding-standards.md ├── backend/ # 后端相关文档 │ ├── design/ # 设计文档 -│ └── specs/ # 规格说明 +│ ├── specs/ # 规格说明 +│ ├── guides/ # 操作指南 +│ │ ├── AI开发操作手册.md +│ │ └── deployment-guide.md +│ ├── 模块间通信规范.md +│ ├── 跨团队协作工作流.md +│ ├── 项目实施规范.md +│ └── 业务应用模块创建规则.md └── frontend/ # 前端相关文档 ├── design/ # 设计文档 ├── specs/ # 规格说明 - └── plans/ # 实施计划 + ├── plans/ # 实施计划 + ├── admin-ui-icon-guide.md + └── admin-ui-status.md ``` ## 🔗 使用方式 @@ -61,6 +70,24 @@ cd rui-docs |------|------|----------| | `cashier-admin-implementation.md` | 收银系统后台管理功能完善实施计划 | 2026-06-04 | +### 后端文档（backend/） + +| 文档 | 说明 | 更新日期 | +|------|------|----------| +| `模块间通信规范.md` | 微服务模块间通信规范（Feign/REST） | 2026-06-04 | +| `跨团队协作工作流.md` | 多团队/多 AI 协作流程规范 | 2026-06-04 | +| `项目实施规范.md` | 项目整体实施规范与架构说明 | 2026-06-04 | +| `业务应用模块创建规则.md` | 业务模块（app/）创建标准 | 2026-06-04 | +| `guides/AI开发操作手册.md` | AI 开发环境配置与操作指南 | 2026-06-04 | +| `guides/deployment-guide.md` | 项目部署指南 | 2026-06-04 | + +### 前端文档（frontend/） + +| 文档 | 说明 | 更新日期 | +|------|------|----------| +| `admin-ui-icon-guide.md` | Admin-UI 图标使用指南 | 2026-06-04 | +| `admin-ui-status.md` | Admin-UI 状态管理文档 | 2026-06-04 | + ### 通用规范（standards/） | 文档 | 说明 | diff --git a/backend/guides/AI开发操作手册.md b/backend/guides/AI开发操作手册.md new file mode 100644 index 0000000..8d9c770 --- /dev/null +++ b/backend/guides/AI开发操作手册.md @@ -0,0 +1,317 @@ +# 多 AI 隔离开发操作手册 + +## 🎯 快速开始 + +### 1. 项目结构总览 + +``` +~/rhkj/ +├── rui-frontend/ ← 前端 AI 工作目录 +│ ├── admin-ui/ +│ ├── cashier-mobile/ +│ └── customer-mobile/ +│ +├── spring-ai/ ← 后端框架 AI 工作目录 +│ ├── backend/ +│ │ ├── rui-common/ +│ │ ├── rui-gateway/ +│ │ ├── rui-auth/ +│ │ └── rui-service/ +│ └── docs/ +│ +├── spring-ai/app/ +│ ├── rui-cashier/ ← 收银 AI 工作目录 +│ └── rui-payment/ ← 支付 AI 工作目录 +│ +└── rui-framework/ ← 框架模块 AI 工作目录 +``` + +--- + +## 🤖 AI 配置与启动 + +### 前端 AI + +**工作目录：** `~/rhkj/rui-frontend` + +**启动步骤：** +```bash +# 1. 进入前端目录 +cd ~/rhkj/rui-frontend + +# 2. 打开 OpenCode（或其他 AI 工具） +# 根据您使用的工具，执行相应命令 +# 例如：cursor . 或 code . + +# 3. 在 AI 对话中输入： +``` + +**AI 指令：** +``` +你是前端开发专家。当前项目是 rui-frontend（睿核科技前端工程）。 + +技术栈：Vue 3 + TypeScript + Vite + pnpm + +你的职责： +1. 开发 admin-ui（管理后台） +2. 开发 cashier-mobile（收银移动端） +3. 开发 customer-mobile（顾客移动端） + +约束条件： +- 禁止修改后端代码 +- 禁止修改 API 接口定义 +- 通过 REST API 与后端通信 +- 参考 AGENTS.md 文件了解详细边界 + +当前任务：[描述您的需求] +``` + +--- + +### 后端框架 AI + +**工作目录：** `~/rhkj/spring-ai` + +**启动步骤：** +```bash +# 1. 进入后端目录 +cd ~/rhkj/spring-ai + +# 2. 打开 OpenCode + +# 3. 在 AI 对话中输入： +``` + +**AI 指令：** +``` +你是 Java 后端开发专家。当前项目是 spring-ai（睿核科技后端框架）。 + +技术栈：Spring Boot 3.x + Spring Cloud + JDK 21 + Maven + MyBatis Plus + +你的职责： +1. 维护 rui-common（公共组件） +2. 维护 rui-gateway（网关服务） +3. 维护 rui-auth（认证授权） +4. 维护 rui-service（系统服务：用户、权限等） + +约束条件： +- 禁止修改前端代码 +- 禁止编写业务逻辑（收银、支付等） +- 只提供基础设施和公共服务 +- 通过 FeignClient/REST API 暴露服务 +- 参考 AGENTS.md 文件了解详细边界 + +当前任务：[描述您的需求] +``` + +--- + +### 收银模块 AI + +**工作目录：** `~/rhkj/spring-ai/app/rui-cashier` + +**启动步骤：** +```bash +# 1. 进入收银模块目录 +cd ~/rhkj/spring-ai/app/rui-cashier + +# 2. 打开 OpenCode + +# 3. 在 AI 对话中输入： +``` + +**AI 指令：** +``` +你是 Java 业务开发专家。当前项目是 rui-cashier（睿核科技收银系统）。 + +技术栈：Spring Boot + MyBatis Plus + MySQL + +你的职责： +1. 开发订单管理功能 +2. 开发会员管理功能 +3. 开发商品管理功能 +4. 开发营业报表功能 +5. 开发积分系统 + +约束条件： +- 禁止修改前端代码 +- 禁止修改框架代码（在 spring-ai 仓库） +- 禁止直接引用支付模块代码 +- 通过 FeignClient 调用框架服务 +- 通过 REST API 暴露接口供前端调用 +- 参考 AGENTS.md 文件了解详细边界 + +当前任务：[描述您的需求] +``` + +--- + +### 支付模块 AI + +**工作目录：** `~/rhkj/spring-ai/app/rui-payment` + +**启动步骤：** +```bash +# 1. 进入支付模块目录 +cd ~/rhkj/spring-ai/app/rui-payment + +# 2. 打开 OpenCode + +# 3. 在 AI 对话中输入： +``` + +**AI 指令：** +``` +你是 Java 业务开发专家。当前项目是 rui-payment（睿核科技支付系统）。 + +技术栈：Spring Boot + MyBatis Plus + MySQL + +你的职责： +1. 开发支付订单管理 +2. 开发支付渠道管理 +3. 开发退款管理 +4. 开发分账系统 +5. 开发对账系统 + +约束条件： +- 禁止修改前端代码 +- 禁止修改框架代码（在 spring-ai 仓库） +- 禁止直接引用收银模块代码 +- 通过 FeignClient 调用框架服务 +- 通过 REST API 暴露接口供收银模块调用 +- 参考 AGENTS.md 文件了解详细边界 + +当前任务：[描述您的需求] +``` + +--- + +## 📋 常用操作命令 + +### 代码推送（所有 AI 通用） + +```bash +# 查看修改 +git status + +# 添加修改 +git add . + +# 提交（使用规范格式） +git commit -m "feat: 功能描述 + +- 详细修改点1 +- 详细修改点2" + +# 推送到 Gitea +git push gitea main + +# 查看推送结果（钉钉会收到通知） +``` + +### 查看 CI/CD 构建状态 + +```bash +# 查看 Actions 运行状态 +# 访问：https://git.dev.vifo.cc/rui/{仓库名}/actions +``` + +### 模块间通信示例 + +**收银模块调用支付模块：** +```java +// 在 rui-cashier 模块中 +@FeignClient("rui-payment") +public interface PaymentFeignClient { + + @PostMapping("/api/v1/pay/order") + Result createPayOrder(@RequestBody PayOrderDTO dto); +} +``` + +**前端调用收银接口：** +```typescript +// 在 rui-frontend 中 +const API_BASE = '/api'; + +const cashierApi = { + createOrder: (data) => axios.post(`${API_BASE}/cashier/order`, data), + getOrderList: () => axios.get(`${API_BASE}/cashier/order/list`) +}; +``` + +--- + +## 🔔 协作流程 + +### 当需要其他 AI 支持时 + +1. **在 Gitea 创建 Issue** + ``` + 标题：[需求] 收银模块需要支付接口支持 + 内容： + - 需求描述：创建订单后需要发起支付 + - 期望接口：POST /api/v1/pay/order + - 请求参数：{ orderNo, amount, payType } + - 所属仓库：rui-payment + ``` + +2. **等待对应 AI 处理** + - 支付 AI 会看到钉钉通知 + - 支付 AI 实现接口并推送代码 + +3. **联调测试** + - 收银 AI 使用新接口 + - 测试环境验证 + +--- + +## 📁 重要文件位置 + +| 文件 | 位置 | 说明 | +|------|------|------| +| AI 边界配置 | `AGENTS.md` | 每个仓库根目录 | +| 通信规范 | `spring-ai/docs/module-communication.md` | 模块间通信规范 | +| CI 配置 | `.gitea/workflows/*.yml` | 自动化构建 | +| 后端 POM | `spring-ai/backend/pom.xml` | Maven 根配置 | + +--- + +## ⚠️ 注意事项 + +1. **不要跨仓库修改代码** - 每个 AI 只能修改自己的仓库 +2. **提交前检查** - 确认修改范围符合 AGENTS.md +3. **及时推送** - 代码完成后立即推送到 Gitea +4. **查看通知** - 关注钉钉消息了解其他模块动态 + +--- + +## 🆘 故障排除 + +### 推送失败 +```bash +# 检查远程仓库 +git remote -v + +# 确认是 Gitea 地址 +gitea ssh://git@git.dev.vifo.cc:222/rui/xxx.git + +# 如果失败，检查 SSH 密钥 +ssh -p 222 git@git.dev.vifo.cc +``` + +### CI 构建失败 +```bash +# 查看构建日志 +# 访问：https://git.dev.vifo.cc/rui/{仓库}/actions +``` + +### 钉钉没收到通知 +```bash +# 检查 Webhook 配置 +# 访问：https://git.dev.vifo.cc/rui/{仓库}/settings/hooks +``` + +--- + +> **最后提醒**：每个 AI 严格在自己的边界内工作，通过 REST API 协作，禁止直接引用其他模块代码！ \ No newline at end of file diff --git a/backend/guides/deployment-guide.md b/backend/guides/deployment-guide.md new file mode 100644 index 0000000..0d1a462 --- /dev/null +++ b/backend/guides/deployment-guide.md @@ -0,0 +1,294 @@ +# 部署指南 + +## 🎯 部署架构 + +``` +┌─────────────────────────────────────────┐ +│ Nginx 网关 │ +│ (负载均衡/静态资源) │ +└──────────────┬──────────────────────────┘ + │ + ┌───────┴───────┐ + ▼ ▼ +┌─────────────┐ ┌─────────────┐ +│ 前端静态资源 │ │ rui-gateway │ +│ (dist目录) │ │ Spring Cloud│ +└─────────────┘ │ Gateway │ + └──────┬──────┘ + │ + ┌────────────┼────────────┐ + ▼ ▼ ▼ + ┌─────────┐ ┌─────────┐ ┌─────────┐ + │rui-auth │ │rui- │ │rui- │ + │(认证) │ │service │ │cashier │ + └─────────┘ │(系统) │ │(收银) │ + └─────────┘ └─────────┘ + │ + ┌──────┴──────┐ + ▼ ▼ + ┌──────────┐ ┌──────────┐ + │rui-payment│ │ MySQL │ + │ (支付) │ │ (数据库) │ + └──────────┘ └──────────┘ +``` + +--- + +## 🐳 Docker 部署 + +### 1. 构建镜像 + +```bash +# 进入后端目录 +cd ~/rhkj/spring-ai/backend + +# Maven 打包 +mvn clean package -DskipTests + +# 构建 Docker 镜像（以 gateway 为例） +cd rui-gateway +docker build -t rui-gateway:latest . + +# 构建其他服务... +cd ../rui-auth && docker build -t rui-auth:latest . +cd ../rui-service/rui-service-system && docker build -t rui-service-system:latest . +``` + +### 2. docker-compose.yml + +```yaml +version: '3.8' + +services: + # MySQL + mysql: + image: mysql:8.0 + container_name: rui-mysql + environment: + MYSQL_ROOT_PASSWORD: root123 + MYSQL_DATABASE: rui_cloud + ports: + - "3306:3306" + volumes: + - mysql-data:/var/lib/mysql + + # Redis + redis: + image: redis:7-alpine + container_name: rui-redis + ports: + - "6379:6379" + + # Nacos (注册中心) + nacos: + image: nacos/nacos-server:v2.2.3 + container_name: rui-nacos + environment: + MODE: standalone + ports: + - "8848:8848" + + # Gateway + gateway: + image: rui-gateway:latest + container_name: rui-gateway + ports: + - "8080:8080" + depends_on: + - nacos + + # Auth + auth: + image: rui-auth:latest + container_name: rui-auth + depends_on: + - nacos + - mysql + - redis + + # Service + service-system: + image: rui-service-system:latest + container_name: rui-service-system + depends_on: + - nacos + - mysql + - redis + +volumes: + mysql-data: +``` + +### 3. 启动服务 + +```bash +# 启动所有服务 +docker-compose up -d + +# 查看日志 +docker-compose logs -f gateway + +# 停止服务 +docker-compose down +``` + +--- + +## 🚀 生产环境部署 + +### 1. 服务器准备 + +| 服务器 | 配置 | 部署内容 | +|--------|------|---------| +| 服务器 1 | 4C8G | Gateway + Auth + Nacos | +| 服务器 2 | 4C8G | Service + Cashier + Payment | +| 服务器 3 | 4C8G | MySQL + Redis | +| 服务器 4 | 2C4G | Nginx + 前端静态资源 | + +### 2. 部署脚本 + +```bash +#!/bin/bash +# deploy.sh - 生产环境部署脚本 + +set -e + +# 配置 +SERVER_USER="root" +SERVER_IP="192.168.1.100" +JAR_PATH="target/*.jar" +BACKUP_DIR="/opt/backup" +APP_DIR="/opt/rui" + +# 备份旧版本 +echo "备份旧版本..." +ssh $SERVER_USER@$SERVER_IP "mkdir -p $BACKUP_DIR && cp $APP_DIR/*.jar $BACKUP_DIR/ 2>/dev/null || true" + +# 上传新版本 +echo "上传新版本..." +scp $JAR_PATH $SERVER_USER@$SERVER_IP:$APP_DIR/ + +# 重启服务 +echo "重启服务..." +ssh $SERVER_USER@$SERVER_IP "cd $APP_DIR && ./restart.sh" + +echo "部署完成！" +``` + +--- + +## 📊 监控与日志 + +### 日志查看 + +```bash +# 查看实时日志 +docker logs -f rui-gateway + +# 查看最近 100 行 +docker logs --tail=100 rui-gateway + +# 查看指定时间范围 +docker logs --since="2024-01-01T00:00:00" rui-gateway +``` + +### 健康检查 + +```bash +# Gateway 健康检查 +curl http://localhost:8080/actuator/health + +# 服务注册状态 +curl http://localhost:8848/nacos/v1/ns/instance/list?serviceName=rui-gateway +``` + +--- + +## 🔧 常见问题 + +### 1. 服务无法注册到 Nacos + +**原因**：Nacos 地址配置错误 +**解决**： +```yaml +spring: + cloud: + nacos: + discovery: + server-addr: nacos:8848 # 使用容器名或 IP +``` + +### 2. 数据库连接失败 + +**原因**：MySQL 未启动或网络不通 +**解决**： +```bash +# 检查 MySQL 状态 +docker ps | grep mysql + +# 测试连接 +docker exec -it rui-mysql mysql -uroot -p -e "SELECT 1" +``` + +### 3. 端口冲突 + +**原因**：端口被占用 +**解决**： +```bash +# 查看端口占用 +netstat -tlnp | grep 8080 + +# 修改 docker-compose.yml 端口映射 +ports: + - "8081:8080" # 宿主机8081映射到容器8080 +``` + +--- + +## 📈 性能优化 + +### JVM 参数 + +```bash +java -jar \ + -Xms512m \ + -Xmx1024m \ + -XX:+UseG1GC \ + -XX:MaxGCPauseMillis=200 \ + app.jar +``` + +### 连接池配置 + +```yaml +spring: + datasource: + hikari: + minimum-idle: 5 + maximum-pool-size: 20 + idle-timeout: 300000 + max-lifetime: 1200000 + connection-timeout: 20000 +``` + +--- + +## 🔄 滚动更新 + +```bash +# 1. 启动新版本（不停止旧版本） +docker-compose up -d --no-deps --scale gateway=2 gateway + +# 2. 等待新版本健康检查通过 +sleep 30 + +# 3. 停止旧版本 +docker-compose stop gateway_1 + +# 4. 移除旧版本 +docker-compose rm -f gateway_1 +``` + +--- + +> **最后提醒**：生产环境部署前务必在测试环境验证！ \ No newline at end of file diff --git a/backend/业务应用模块创建规则.md b/backend/业务应用模块创建规则.md new file mode 100644 index 0000000..00d623d --- /dev/null +++ b/backend/业务应用模块创建规则.md @@ -0,0 +1,340 @@ +# 业务应用模块创建规则 + +> 在 `app/` 目录下创建业务模块，按子模块模式拆分。 +> `app/` 目录整体不提交到 git。 + +## 模块结构 + +``` +app/ +├── pom.xml # 聚合所有业务模块 +└── rui-{领域}/ + ├── pom.xml # 领域聚合 POM + ├── rui-{领域}-api/ # [可部署] REST API 服务（有 main Class） + ├── rui-{领域}-common/ # [库] DTO、枚举、配置、工具 + ├── rui-{领域}-core/ # [库] Mapper、Entity、Service（数据库层） + ├── rui-{领域}-provider/ # [库] 第三方集成（可选） + └── rui-{领域}-task/ # [库] MQ 监听器 + 定时任务（可选） +``` + +### 三模块（最小配置） + +| 模块 | 类型 | 作用 | +|------|------|------| +| `-api` | 可部署 | REST 控制器、启动类、application.yml | +| `-common` | 库 | DTO、VO、枚举、常量、配置属性 | +| `-core` | 库 | Mapper、Entity、Service（MyBatis Plus） | + +### 五模块（含第三方集成和异步任务） + +| 模块 | 类型 | 作用 | +|------|------|------| +| `-provider` | 库（可选） | 第三方 SDK/API 封装（支付、短信、AI 等） | +| `-task` | 库（可选） | MQ 监听器、定时任务、异步处理 | + +## 包命名 + +``` +com.rui.{领域}.api # api 模块 +com.rui.{领域} # common 模块 +com.rui.{领域}.core # core 模块 +com.rui.{领域}.provider # provider 模块 +com.rui.{领域}.task # task 模块 +``` + +## POM 层级 + +``` +app/pom.xml → parent: rui-parent (不加 relativePath) + └── rui-{领域}/pom.xml → parent: rui-app + ├── rui-{领域}-api/ → parent: rui-{领域} + ├── rui-{领域}-common/ + ├── rui-{领域}-core/ + ├── rui-{领域}-provider/ （可选） + └── rui-{领域}-task/ （可选） +``` + +> `` 一律不加，Maven 自动从本地仓库查找父 POM。 + +## 依赖关系 + +``` +common ——→ rui-common-core +core ———→ rui-common-mybatis, rui-common-security, common +api ———→ core, rui-common-security, rui-common-web +provider → common +task ———→ core, common +``` + +- **框架依赖**（`rui-common-*`）：版本由 `rui-parent` BOM 管理，不加 `` +- **内部模块依赖**（`rui-{领域}-*`）：加 `${project.version}` + +## app/pom.xml 模板 + +```xml + + + 4.0.0 + + + com.rui + rui-parent + 1.0.0-SNAPSHOT + + + rui-app + pom + + rui-app + 睿核科技 — 业务应用模块聚合 + + + rui-payment + + + +``` + +## api 模块 POM 模板 + +```xml + + + com.alibaba.cloud + spring-cloud-starter-alibaba-nacos-config + + + com.alibaba.cloud + spring-cloud-starter-alibaba-nacos-discovery + + + org.springframework.boot + spring-boot-starter-webmvc + + + com.rui + rui-{领域}-core + ${project.version} + + + com.rui + rui-common-security + + + com.rui + rui-common-web + + + + + + + org.springframework.boot + spring-boot-maven-plugin + + + repackage + repackage + true + + + + + +``` + +## 启动类模板 + +```java +package com.rui.{领域}.api; + +import com.rui.common.security.annotation.EnableResourceServer; +import org.springframework.boot.SpringApplication; +import org.springframework.boot.autoconfigure.SpringBootApplication; + +@SpringBootApplication +@EnableResourceServer +public class {Domain}ApiApplication { + public static void main(String[] args) { + SpringApplication.run({Domain}ApiApplication.class, args); + } +} +``` + +## 日志配置模板 + +api 模块需复制日志配置文件： + +```bash +cp docs/logback-spring-template.xml \ + app/rui-{领域}/rui-{领域}-api/src/main/resources/logback-spring.xml +``` + +- 无需修改，自动读取 `spring.application.name` 作为日志目录名 +- 按级别分文件（debug / info / warn / error） +- 控制台彩色输出，dev 环境显示 DEBUG + +## 注意事项 + +1. **`app/` 目录加入 `.gitignore`**，业务模块不提交到框架仓库 +2. api 模块需配置 `@EnableResourceServer`（资源服务器模式） +3. **各模块 Bean 通过 `AutoConfiguration.imports` 自动注入**，不在启动类上使用 `scanBasePackages`（参见下方「模块 Bean 注入规范」） +4. Mapper 扫描由 `rui-common-mybatis` 统一处理（`@MapperScan("com.rui.**.mapper")`），各模块无需重复配置 +5. 白名单 URL 通过 `security.oauth2.ignore-urls` 在 Nacos 配置 +6. 本地开发配置如 `config/application-dev.yml` 也需 gitignore + +## Git 规则 + +业务应用模块（`app/` 目录下的模块）使用**独立的 Git 仓库**管理，与框架主仓库完全分离。 + +### 仓库初始化 + +```bash +cd app/rui-{领域} +git init +git add . +git commit -m "feat(init): 初始化{领域}模块" +git remote add origin git@gitee.com:pigeon/rui-{领域}.git +git push -u origin master +``` + +### 提交规范 + +与框架主仓库一致： + +- **格式**：`type(scope): 中文描述` +- **type**：`feat`（新功能）、`fix`（修复）、`docs`（文档）、`refactor`（重构）、`chore`（构建） +- **示例**：`feat(payment): 添加支付宝下单接口` + +### 推送规则 + +- **本地开发**：修改后自动 `git commit`，但不自动推送 +- **推送时机**：由开发者手动执行 `git push`，或在完成阶段性开发后统一推送 +- **自动推送阈值**：当未推送提交数 **超过 10 个** 时，自动推送到远程 +- **禁止**：将业务模块代码提交到框架主仓库（`app/` 已加入 `.gitignore`） + +### 与框架主仓库的关系 + +``` +spring-ai/ # 框架主仓库（git） +├── backend/ # 提交到框架仓库 +├── docs/ # 提交到框架仓库 +├── app/ # 不提交到框架仓库（.gitignore） +│ └── rui-payment/ # 独立 Git 仓库 +│ ├── .git/ # 独立的 git 历史 +│ └── ... +``` + +## 模块 Bean 注入规范 + +### `@SpringBootApplication` 禁止扩大扫描范围 + +**API 启动类上的 `@SpringBootApplication` 不得使用 `scanBasePackages` 参数扩大包扫描范围。** + +- 错误示例：`@SpringBootApplication(scanBasePackages = {"com.rui.payment"})` +- 正确示例：`@SpringBootApplication` + +启动类应仅扫描自身所在包（`com.rui.{领域}.api`）及其子包。 + +### 跨模块 Bean 通过 AutoConfiguration 注入 + +其他模块需要暴露给 Spring 容器的 Bean（`@Service`、`@Component`、`@Mapper` 等），**由各模块自行通过 `AutoConfiguration.imports` 注册**。 + +**实现方式**： + +1. 在模块中创建自动配置类（通常在 `config` 包下）： + +```java +package com.rui.{领域}.core.config; + +import org.springframework.boot.autoconfigure.AutoConfiguration; +import org.springframework.context.annotation.ComponentScan; + +@AutoConfiguration +@ComponentScan("com.rui.{领域}.core") +public class PaymentCoreAutoConfiguration { +} +``` + +2. 在模块的 `src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports` 中注册： + +``` +com.rui.{领域}.core.config.PaymentCoreAutoConfiguration +``` + +**原则**： +- 每个可复用模块（core、provider、task）必须有自己的 `AutoConfiguration` +- 启动类只需引入依赖，无需关心其他模块的包路径 +- `rui-common-mybatis` 已通过 `AutoConfiguration.imports` 自动注入并包含 `@MapperScan("com.rui.**.mapper")`，各模块无需重复配置 Mapper 扫描 + +## Controller 路径规范 + +### URL 格式 + +``` +/{模块}/{功能}/{方法} +``` + +例如：`/payment/trade/create`、`/order/refund/query` + +### 控制器分类 + +| 控制器命名 | 路径 | 认证 | 说明 | +|-----------|------|------|------| +| `XxxController` | `/{模块}/{功能}/*` | 需认证 | 常规业务接口 | +| `XxxEntryController` | `/{模块}/entry/**` | 免认证 | 对外入口（收银台、H5 等） | +| `XxxNotifyController` | `/{模块}/notify/**` | 免认证 | 第三方回调（支付、消息等） | +| `XxxInnerController` | `/{模块}/inner/**` | 通过 `@Inner` 注解控制 | 内部 Feign 调用 | + +### Nacos 白名单配置 + +```yaml +# Spring Boot 4 使用 PathPattern，不支持 /**/ 中间通配 +# 需按模块显式列出白名单路径 +security: + oauth2: + ignore-urls: + - /payment/entry/** + - /payment/notify/** + - /user/entry/** + - /actuator/** +``` + +### 示例 + +```java +// 常规接口 — 需认证 +@RestController +@RequestMapping("/payment/trade") +public class PaymentTradeController { + @PostMapping("/create") + public R create(@RequestBody TradeRequest req) { ... } +} + +// 对外入口 — 免认证 +@RestController +@RequestMapping("/payment/entry") +public class PaymentEntryController { + @PostMapping("/alipay") + public R alipay(@RequestBody PayRequest req) { ... } +} + +// 第三方回调 — 免认证 +@RestController +@RequestMapping("/payment/notify") +public class PaymentNotifyController { + @PostMapping("/alipay") + public String alipayNotify(HttpServletRequest request) { ... } +} + +// 内部调用 — @Inner 保护 +@RestController +@RequestMapping("/payment/inner") +public class PaymentInnerController { + @Inner + @GetMapping("/trade/{id}") + public Trade getTrade(@PathVariable Long id) { ... } +} +``` diff --git a/backend/模块间通信规范.md b/backend/模块间通信规范.md new file mode 100644 index 0000000..7d3bfe0 --- /dev/null +++ b/backend/模块间通信规范.md @@ -0,0 +1,152 @@ +# 模块间通信规范 + +## 🎯 设计原则 + +1. **松耦合** - 模块间通过 REST API 通信，禁止直接引用代码 +2. **接口契约** - 通过 API 定义进行协作 +3. **独立部署** - 每个模块可独立构建和部署 +4. **版本管理** - API 支持版本控制 + +## 🔗 通信方式 + +### 1. 模块 → 框架（spring-ai） + +```java +// 使用 FeignClient 调用框架服务 +@FeignClient("rui-service-user") +public interface UserFeignClient { + + @GetMapping("/api/v1/user/{id}") + Result getUserById(@PathVariable Long id); + + @GetMapping("/api/v1/user/current") + Result getCurrentUser(); +} +``` + +### 2. 模块 → 模块（如收银 → 支付） + +```java +// 通过 FeignClient 调用其他业务模块 +@FeignClient("rui-payment") +public interface PaymentFeignClient { + + @PostMapping("/api/v1/pay/order") + Result createPayOrder(@RequestBody PayOrderDTO dto); + + @GetMapping("/api/v1/pay/status/{orderNo}") + Result getPayStatus(@PathVariable String orderNo); +} +``` + +### 3. 前端 → 后端 + +```typescript +// 前端通过网关调用服务 +const API_GATEWAY = '/api'; + +// 调用收银服务 +const cashierApi = { + createOrder: (data) => axios.post(`${API_GATEWAY}/cashier/order`, data), + getOrderList: () => axios.get(`${API_GATEWAY}/cashier/order/list`) +}; + +// 调用支付服务 +const paymentApi = { + createPay: (data) => axios.post(`${API_GATEWAY}/pay/order`, data), + queryPayStatus: (orderNo) => axios.get(`${API_GATEWAY}/pay/status/${orderNo}`) +}; +``` + +## 📐 API 规范 + +### URL 设计 +``` +/api/v1/{模块}/{资源}/{操作} + +示例： +- GET /api/v1/cashier/order/list 查询订单列表 +- POST /api/v1/cashier/order 创建订单 +- GET /api/v1/cashier/order/{id} 查询订单详情 +- PUT /api/v1/cashier/order/{id} 更新订单 +- DELETE /api/v1/cashier/order/{id} 删除订单 +``` + +### 返回格式 +```json +{ + "code": 200, + "message": "success", + "data": { + // 业务数据 + } +} +``` + +### 错误处理 +```json +{ + "code": 500, + "message": "支付失败：余额不足", + "data": null +} +``` + +## 🗄️ 数据库隔离 + +| 模块 | 数据库/Schema | 说明 | +|------|--------------|------| +| rui-service | `rui_system` | 系统服务数据 | +| rui-cashier | `rui_cashier` | 收银业务数据 | +| rui-payment | `rui_payment` | 支付业务数据 | + +**禁止**： +- 直接访问其他模块的数据库 +- 直接查询其他模块的表 + +## 🚀 部署架构 + +``` +┌─────────────┐ +│ Nginx │ ← 网关入口 +└──────┬──────┘ + │ +┌──────▼──────┐ +│ rui-gateway │ ← Spring Cloud Gateway +└──────┬──────┘ + │ + ┌───┼───┐ + ▼ ▼ ▼ +┌──┐ ┌──┐ ┌──┐ +│用户│ │收银│ │支付│ ← 微服务模块 +│服务│ │服务│ │服务│ +└──┘ └──┘ └──┘ +``` + +## 📋 开发流程 + +1. **模块 A 需要模块 B 的接口** + - 模块 A 在自身仓库定义 FeignClient 接口 + - 模块 B 实现并暴露 REST API + - 不需要依赖模块 B 的代码 + +2. **模块间数据传递** + - 使用 DTO（Data Transfer Object） + - DTO 定义在各自模块，不共享 + - 字段名保持一致 + +3. **接口变更** + - 向后兼容 + - 版本号控制 + - 通知相关模块 + +## 🔔 注意事项 + +1. **超时设置**：FeignClient 默认超时 1 秒，根据业务调整 +2. **熔断降级**：使用 Sentinel 或 Hystrix +3. **链路追踪**：使用 SkyWalking 或 Zipkin +4. **日志规范**：统一日志格式，包含 traceId + +--- + +> **核心原则**：模块间只通过 REST API 通信，禁止任何直接代码引用！ \ No newline at end of file diff --git a/backend/跨团队协作工作流.md b/backend/跨团队协作工作流.md new file mode 100644 index 0000000..2433ca7 --- /dev/null +++ b/backend/跨团队协作工作流.md @@ -0,0 +1,433 @@ +# 跨团队协作工作流规范 + +> **版本**: v1.0 +> **创建日期**: 2026-06-04 +> **适用范围**: rui 项目所有开发角色（框架、应用、前端） + +--- + +## 一、背景与目的 + +### 1.1 问题背景 + +rui 项目采用多仓结构： +- **后端仓库**：`spring-ai`（backend + app/*） +- **前端仓库**：`rui-frontend`（admin-ui + cashier-mobile + customer-mobile） + +在使用 OpenCode AI 辅助开发时存在以下痛点： + +- **上下文污染**：一个 OpenCode 会话同时处理框架、应用、前端，导致理解混乱 +- **边界模糊**：开发应用模块时直接修改框架代码，破坏框架稳定性 +- **协作困难**：前端需要接口时无法有效通知后端，应用发现框架 Bug 时修复流程不规范 + +### 1.2 目标 + +- **仓库隔离**：前后端独立仓库，各自独立发版 +- **会话隔离**：每个 OpenCode 会话只处理一个职责领域 +- **边界清晰**：通过文件访问限制防止跨域修改 +- **规范协作**：通过 Gitee Issue 模板实现标准化跨团队沟通 +- **可追溯性**：所有跨团队协作都有记录，便于后续审计 + +--- + +## 二、角色与职责边界 + +### 2.1 仓库结构 + +``` +# 后端仓库：spring-ai +spring-ai/ +├── backend/ # 基础框架 +├── app/ # 应用模块（支付、收银等） +├── docs/ # 后端文档 +└── ... + +# 前端仓库：rui-frontend +rui-frontend/ +├── admin-ui/ # 管理后台（Vue 3） +├── cashier-mobile/ # 收银系统移动端 +├── customer-mobile/ # 收银系统顾客端 +└── ... +``` + +### 2.2 三种开发角色 + +| 角色 | 所属仓库 | 负责目录 | 可修改范围 | 只读范围 | 会话配置 | +|------|---------|---------|-----------|---------|---------| +| **框架开发** | spring-ai | `backend/` | `backend/**` | `app/**` | `framework.json` | +| **应用开发** | spring-ai | `app/{模块}/` | `app/{模块}/**` | `backend/**` | `app-module.json` | +| **前端开发** | rui-frontend | `admin-ui/` | `admin-ui/**` | `cashier-mobile/`, `customer-mobile/` | `admin-ui.json` | + +### 2.2 职责矩阵 + +| 操作 | 框架会话 | 应用会话 | 前端会话 | +|------|---------|---------|---------| +| 修改框架代码 | ✅ | ❌ 禁止 | ❌ 禁止 | +| 修改应用代码 | ❌ 禁止 | ✅ | ❌ 禁止 | +| 修改前端代码 | ❌ 禁止 | ❌ 禁止 | ✅ | +| 报告框架 Bug | ✅ 接收并处理 | ✅ 创建 Issue | ✅ 创建 Issue | +| 请求新接口 | ✅ 实现 | ✅ 实现 | ✅ 创建 Issue | +| 修改接口文档 | ✅ | ✅ | ❌ 禁止 | + +--- + +## 三、协作场景与流程 + +### 场景一：前端/应用需要后端接口 + +**触发条件**：前端（rui-frontend 仓库）或应用模块在开发过程中需要新的后端接口支持 + +**协作流程**（跨仓库协作）： + +``` +rui-frontend/ spring-ai/ +┌─────────────┐ ┌─────────────┐ +│ 前端会话 │ │ 后端 │ +│ (admin-ui) │ │ 会话 │ +└──────┬──────┘ └──────┬──────┘ + │ │ + │ 在 spring-ai 仓库创建 │ + │ Issue [API-REQ] │ + └────────────────────────→│ + │ │ + │ 回复：接口已实现 │ + │ Swagger 地址：xxx │ + │←────────────────────────┘ + │ │ + │ 根据 Swagger 开发/联调 │ + │ │ +``` + +**详细步骤**： + +1. **需求方**（前端或应用）在 Gitee 创建 Issue + - 使用模板：`api_request.md` + - 标题格式：`[API-REQ] 一句话描述` + - 标签：`api-request`, `cross-team` + - 必填信息：接口路径、请求/响应格式、业务规则 + +2. **实现方**（后端）处理 Issue + - 在 backend/ 下实现接口 + - 更新 Swagger 文档 + - 提交 PR 并关联 Issue + - 在 Issue 中回复接口信息 + +3. **需求方**验证并关闭 Issue + - 根据 Swagger 开发/联调 + - 确认无误后关闭 Issue + +**示例**： +- 前端 Issue：`[API-REQ] 用户管理需要批量导入接口` +- 后端回复：`接口已实现，Swagger: /doc.html#/用户管理/importUsers` + +--- + +### 场景二：应用发现框架 Bug + +**触发条件**：应用模块在开发过程中发现基础框架存在问题 + +**协作流程**： + +``` +┌─────────────┐ 创建 Issue ┌─────────────┐ +│ 应用模块 │ ──────────────────→ │ 框架 │ +│ 会话 │ [FRAMEWORK] 模板 │ 会话 │ +└─────────────┘ └─────────────┘ + ↑ │ + │ 回复：已修复 + 版本号 │ + └──────────────────────────────────┘ + ↑ │ + │ 升级依赖并验证 │ + └──────────────────────────────────┘ +``` + +**详细步骤**： + +1. **发现方**（应用模块）在 Gitee 创建 Issue + - 使用模板：`framework_bug.md` + - 标题格式：`[FRAMEWORK] 一句话描述` + - 标签：`framework`, `cross-team`, `bug` + - 必填信息：复现路径、期望/实际行为、影响评估 + +2. **框架方**处理 Issue + - 复现问题 + - 在 backend/ 下修复 + - 发布新版本（更新 pom.xml 版本号） + - 在 Issue 中回复修复版本 + +3. **应用方**升级依赖 + - 更新 pom.xml 中的框架依赖版本 + - 验证问题是否修复 + - 关闭 Issue + +**重要原则**： +- ❌ **严禁**应用会话直接修改 backend/ 下的代码 +- ✅ 即使是很小的改动，也要走 Issue 流程 +- ✅ 紧急情况下可先临时 workaround，但必须同步创建 Issue + +**示例**： +- 应用 Issue：`[FRAMEWORK] BaseController 分页查询在 search 为空时 NPE` +- 框架回复：`已修复，版本 v2.1.3，请升级依赖` + +--- + +### 场景三：通用跨团队任务 + +**触发条件**：不属于接口需求或框架 Bug 的其他协作任务 + +**协作流程**： + +1. **提出方**在 Gitee 创建 Issue + - 使用模板：`cross_team_task.md` + - 标题格式：`[CROSS] 一句话描述` + - 明确说明：谁来做、做什么、何时完成 + +2. **接收方**处理并关闭 + +**适用场景**： +- 需要其他模块提供配置数据 +- 需要协调数据库变更 +- 需要共享文档或工具 + +--- + +## 四、OpenCode 会话启动规范 + +### 4.1 启动前准备 + +每次启动 OpenCode 前，明确当前角色： + +| 我要做什么 | 应该启动的会话 | 工作区配置 | +|-----------|--------------|-----------| +| 开发框架通用能力 | 框架会话 | `framework.json` | +| 开发支付模块 | 应用会话（支付） | `app-module.json` | +| 开发用户模块 | 应用会话（用户） | `app-module.json` | +| 开发前端页面 | 前端会话 | `admin-ui.json` | + +### 4.2 启动方式 + +#### 方式一：手动指定（推荐） + +启动 OpenCode 时，明确指定仓库和角色： + +**后端仓库（spring-ai）**： +``` +工作目录：/Users/zhangsheng/rhkj/spring-ai +角色：框架开发 +限制：只能修改 backend/ 下的代码 +``` + +**前端仓库（rui-frontend）**： +``` +工作目录：/Users/zhangsheng/rhkj/rui-frontend +角色：前端开发 +限制：只能修改 admin-ui/ 下的代码 +``` + +#### 方式二：使用工作区配置（如果 OpenCode 支持） + +**后端仓库**参考 `.opencode/workspace/` 目录下的 JSON 配置文件： +- `framework.json` - 框架开发 +- `app-module.json` - 应用模块开发 + +**前端仓库**参考 `rui-frontend/.opencode/workspace/` 目录下的配置文件（需自行创建）。 + +### 4.3 会话切换规则 + +- **同一功能内**：保持同一会话，不要频繁切换 +- **跨模块切换**：使用 `/new` 创建新会话 +- **对话轮次过多**（超过 20-30 轮）：建议新建会话 + +--- + +## 五、Gitee Issue 使用规范 + +### 5.1 Issue 模板位置 + +``` +.gitee/issue_templates/ +├── api_request.md # 接口需求 +├── framework_bug.md # 框架问题 +└── cross_team_task.md # 通用任务 +``` + +### 5.2 标签规范 + +| 标签 | 用途 | 颜色 | +|------|------|------| +| `api-request` | 接口需求 | 蓝色 | +| `framework` | 框架相关问题 | 红色 | +| `cross-team` | 跨团队协作 | 紫色 | +| `bug` | 缺陷 | 红色 | +| `frontend→backend` | 前端调后端 | 绿色 | +| `app→framework` | 应用调框架 | 橙色 | + +### 5.3 标题规范 + +| 类型 | 格式 | 示例 | +|------|------|------| +| 接口需求 | `[API-REQ] {模块}需要{功能}` | `[API-REQ] 用户模块需要批量导入接口` | +| 框架问题 | `[FRAMEWORK] {问题简述}` | `[FRAMEWORK] BaseController 分页查询 NPE` | +| 通用任务 | `[CROSS] {任务简述}` | `[CROSS] 协调订单表索引变更` | + +### 5.4 处理时效 + +| 优先级 | 响应时间 | 解决时间 | +|--------|---------|---------| +| P0-阻塞 | 2 小时内 | 24 小时内 | +| P1-高 | 4 小时内 | 3 天内 | +| P2-中 | 1 天内 | 1 周内 | +| P3-低 | 2 天内 | 排期处理 | + +--- + +## 六、目录访问控制 + +### 6.1 框架会话（backend/） + +``` +可修改： + backend/ + docs/framework/ + +只读（禁止修改）： + app/ + admin-ui/ + docs/superpowers/ # 除非涉及框架规范更新 +``` + +### 6.2 应用会话（app/{模块}/） + +``` +可修改： + app/{当前模块}/ + docs/{当前模块}/ + +只读（禁止修改）： + backend/ + admin-ui/ + app/其他模块/ # 需要调用时通过 Feign/HTTP +``` + +### 6.3 前端会话（admin-ui/） + +``` +可修改： + admin-ui/ + +只读（禁止修改）： + backend/ + app/ +``` + +--- + +## 七、最佳实践 + +### 7.1 沟通优先于修改 + +- 发现其他域的问题 → 先创建 Issue → 不要直接修改 +- 需要其他域支持 → 先创建 Issue → 等待响应 + +### 7.2 信息完整减少往返 + +创建 Issue 时尽量提供完整信息： +- ✅ 包含复现路径 +- ✅ 包含期望结果 +- ✅ 包含截图/日志 +- ❌ 避免只有"这个功能有问题"这样模糊的描述 + +### 7.3 及时关闭已完成的 Issue + +- 接口验证通过后立即关闭 +- Bug 修复验证后立即关闭 +- 长期未关闭的 Issue 需要定期 review + +### 7.4 版本管理 + +- 框架修复后及时更新版本号 +- 应用模块及时升级框架依赖 +- 在 Issue 中明确记录版本信息 + +### 7.5 紧急问题处理 + +遇到阻塞性紧急问题： +1. 先在应用侧做临时 workaround（记录 commit） +2. 同步创建 Issue 通知框架团队 +3. 框架修复后，移除 workaround 并升级依赖 + +--- + +## 八、常见问题 + +### Q1: 我发现框架有个很明显的小 bug，也必须走 Issue 流程吗？ + +**答**：是的。即使是一行代码的修改，也要走 Issue 流程。因为： +- 框架代码影响所有应用模块 +- 需要评估影响范围 +- 需要同步版本更新 + +### Q2: 前端仓库（rui-frontend）和后端仓库（spring-ai）是什么关系？ + +**答**： +- **独立仓库**：前端和后端是完全独立的 Git 仓库 +- **通过 API 关联**：前端通过 HTTP 接口调用后端服务 +- **通过 Issue 协作**：跨仓库的需求通过 Gitee Issue 进行沟通 +- **独立部署**：前端和后端可以独立构建、独立部署 + +### Q3: 为什么前端要独立仓库？ + +**答**： +- **技术栈不同**：前端使用 Vue/Node.js，后端使用 Java/Spring +- **构建工具不同**：前端用 Vite/pnpm，后端用 Maven +- **发布节奏不同**：前端可以独立发版，不需要等后端 +- **团队分工**：前端和后端可能由不同团队维护 +- **避免污染**：node_modules（几百 MB）不进入后端仓库 + +### Q4: 前端如何获取后端接口信息？ + +**答**： +1. 查看后端 Swagger 文档：`http://{backend-host}/doc.html` +2. 通过 Gitee Issue 询问后端团队 +3. 参考已有的 service/ 目录下的 API 定义 + +### Q5: 前端可以直接看 backend 的代码来了解接口吗？ + +**答**：可以查看（只读），但不应该依赖阅读源码来了解接口。应该： +- 查看 Swagger 文档 +- 通过 Issue 询问后端 +- 参考已有的 service/ 目录下的 API 定义 + +### Q6: 应用模块之间如何协作？ + +**答**：应用模块之间通过以下方式协作： +- **接口调用**：使用 FeignClient 调用 `/inner/` 路径 +- **MQ 消息**：通过消息队列解耦 +- **共享 DTO**：定义在 `rui-xxx-common` 模块中 + +跨应用模块的接口需求同样使用 `api_request.md` 模板。 + +### Q7: 如果框架会话和应用会话同时修改了代码怎么办？ + +**答**：由于有目录访问限制，不会出现同时修改同一文件的情况。框架只改 backend/，应用只改 app/，天然隔离。 + +--- + +## 九、相关文档 + +- [项目规范](../AGENTS.md) +- [前端仓库](../../rui-frontend/README.md) +- [设计文档模板](superpowers/templates/design-template.md) +- [实施计划模板](superpowers/templates/plan-template.md) + +--- + +## 十、更新记录 + +| 版本 | 日期 | 更新内容 | 作者 | +|------|------|---------|------| +| v1.0 | 2026-06-04 | 初稿 | OpenCode | + +--- + +> **提示**：本文档是活文档，随着团队协作实践的发展会持续更新。如有建议，请提交 PR 或创建 Issue 讨论。 diff --git a/backend/项目实施规范.md b/backend/项目实施规范.md new file mode 100644 index 0000000..644cd49 --- /dev/null +++ b/backend/项目实施规范.md @@ -0,0 +1,440 @@ +# 睿核科技 (rui) — 项目实施规范 + +> 本文档基于对当前 spring-ai 项目的全面分析，整理项目结构、业务流、现有规范、推荐修改项及缺少的专业结构，供后续项目实施参考。 + +--- + +## 一、项目概述 + +| 项目属性 | 值 | +|---------|-----| +| **项目名称** | spring-ai | +| **项目类型** | Spring Cloud 微服务架构（通用平台框架） | +| **组织方式** | Monorepo（backend + 可扩展前端） | +| **JDK** | 21 | +| **Spring Boot** | 4.0.3 | +| **Spring Cloud** | 2025.1.1 | +| **Alibaba Cloud** | 2025.1.0.0 | +| **MyBatis Plus** | 3.5.16 | +| **包管理** | Maven + flatten-maven-plugin | +| **配置中心** | Nacos | +| **注册中心** | Nacos | + +--- + +## 二、项目架构图 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ 客户端（Web/App/小程序） │ +└─────────────────────────────┬───────────────────────────────┘ + │ + ┌─────────▼─────────┐ + │ rui-gateway │ ← 灰度路由、负载均衡、请求清洗 + │ :9300 │ + └─────────┬─────────┘ + │ + ┌───────────────────┼───────────────────┐ + │ │ │ + ┌─────▼─────┐ ┌──────▼──────┐ ┌──────▼──────┐ + │ rui-auth │ │rui-service-*│ │ rui-service-*│ + │ :9301 │ │ :9302+ │ │ :9302+ │ + └─────┬─────┘ └──────┬──────┘ └──────┬──────┘ + │ │ │ + │ ┌────────▼────────┐ │ + │ │ Nacos Config │ │ + │ │ Nacos Discovery│ │ + │ └─────────────────┘ │ + │ │ │ + ┌─────▼───────────────────▼───────────────────▼─────┐ + │ rui-common（通用基础层） │ + │ core / web / security / oauth2 / mybatis / feign │ + └───────────────────────────────────────────────────┘ +``` + +--- + +## 三、模块结构与端口分配 + +### 3.1 核心框架层 + +| 模块 | 类型 | 端口 | 职责 | +|------|------|------|------| +| **rui-dependencies** | BOM | - | 全局依赖版本管理（Spring Boot/Cloud/Alibaba） | +| **rui-parent** | Parent POM | - | 统一插件配置（Lombok、flatten、Spring Boot Maven） | + +### 3.2 通用基础层（rui-common） + +| 子模块 | 职责 | 是否已创建 | +|--------|------|-----------| +| rui-common-core | 核心工具类（Result、BaseEntity、TenantContextHolder） | ✅ | +| rui-common-mybatis | MyBatis Plus + Druid + 多租户拦截器 | ✅ | +| rui-common-security | 资源服务器配置、JWT、@Inner 注解、安全切面 | ✅ | +| rui-common-oauth2 | OAuth2 授权服务器、多种认证 Provider | ✅ | +| rui-common-web | BaseController、QueryBuilder、全局异常处理、OpenAPI | ✅ | +| rui-common-feign | Feign 增强（自动注入租户头、自定义 Registrar） | ✅ | +| rui-common-mq | MQ 抽象接口 | ✅ | +| rui-common-mq-redis | Redis 实现 MQ | ✅ | +| rui-common-mq-rabbitmq | RabbitMQ 实现 MQ | ✅ | +| rui-common-authenticator | TOTP 动态码认证 | ✅ | + +### 3.3 业务服务层（rui-service） + +| 服务名 | 端口 | 状态 | 职责 | +|--------|------|------|------| +| **rui-gateway** | **9300** | ✅ 已创建 | 网关（路由、灰度发布、负载均衡、日志） | +| **rui-auth** | **9301** | ✅ 已创建 | 认证授权中心（薄壳，核心逻辑在 rui-common-oauth2） | +| **rui-service-system** | **9302** | ✅ 已创建 | 系统基础服务（租户、客户端、角色/菜单/字典） | +| **rui-service-user** | **9303** | ✅ 已创建 | 用户中心服务（用户详情、等级体系、登录凭证） | +| rui-service-msg | 9304 | ⏳ 预留 | 消息通知服务（SMS/邮件/站内信/App推送） | +| rui-service-file | 9305 | ⏳ 预留 | 文件存储服务（OSS/本地存储） | +| rui-service-order | 9306 | ⏳ 预留 | 订单服务 | +| rui-service-pay | 9307 | ⏳ 预留 | 支付服务（支付通道、回调、对账） | +| rui-service-search | 9308 | ⏳ 预留 | 搜索服务（Elasticsearch 封装） | +| rui-service-cache | 9309 | ⏳ 预留 | 缓存服务（Redis 分布式锁等封装） | +| rui-service-log | 9310 | ⏳ 预留 | 日志收集服务（ELK 集成） | +| rui-service-monitor | 9311 | ⏳ 预留 | 监控告警服务（Micrometer/Prometheus） | + +--- + +## 四、核心业务流 + +### 4.1 认证授权流程（OAuth2） + +``` +┌─────────────┐ POST /auth/oauth2/token ┌──────────────┐ +│ 客户端 │ ────────────────────────────────> │ rui-auth │ +│ (前端/App) │ │ :9301 │ +└─────────────┘ └──────┬───────┘ + │ + 1. 获取客户端信息 │ + (ClientInnerController) + :9302 /system/inner/client/* + │ + 2. 获取用户信息 │ + (UserInnerController) + :9303 /user/inner/auth/* + │ + ▼ + 3. 生成 JWT Token + (RuiTokenCustomizer) + 存储到 Redis + │ + ▼ +┌─────────────┐ 返回 Token ┌──────────────┐ +│ 客户端 │ <────────────────── │ rui-auth │ +└─────────────┘ └──────────────┘ +``` + +**支持的认证方式**： +- `password` — 用户名密码 +- `sms` — 短信验证码 +- `weixin` — 微信登录 +- `alipay` — 支付宝登录 +- `client_credentials` — 客户端凭证 +- `refresh_token` — 刷新令牌 + +### 4.2 资源访问流程 + +``` +┌─────────────┐ 携带 Token ┌──────────────┐ 路由 ┌──────────────┐ +│ 客户端 │ ──────────────────> │ rui-gateway │ ───────────> │ 业务服务 │ +└─────────────┘ │ :9300 │ │ :9302/9303+ │ + └──────┬───────┘ └──────┬───────┘ + │ │ + 灰度路由决策 资源服务器校验 + (权重/用户/IP/Header) (JWT 验证) + │ │ + 内部请求头清洗 @Inner 校验 + (INTERNAL_REQUEST) (SecurityInnerAspect) +``` + +### 4.3 内部服务调用流程（Feign） + +``` +业务服务 A 业务服务 B + │ │ + │ Feign 调用 │ + │ ──────────────────────────────────────────> │ + │ │ + │ 自动注入 Header │ + │ - Authorization (OAuth2 Token) │ + │ - INTERNAL_REQUEST: INTERNAL │ + │ - X-Tenant-Id (租户ID) │ + │ │ + │ 通过 @Inner 注解校验 │ + │ (SecurityInnerAspect) │ + │ │ + │ 返回 Result │ + │ <────────────────────────────────────────── │ + │ │ + │ Remote 服务层解包 │ + │ (转换为具体类型) │ +``` + +--- + +## 五、现有规范清单 + +### 5.1 编码规范 + +| # | 规范项 | 要求 | 是否加入规则 | +|---|--------|------|------------| +| 1 | 文档语言 | 所有文档、注释必须使用中文 | ✅ 已规则化（AGENTS.md） | +| 2 | 标识符 | 类名/方法名/变量名使用英文 | ✅ 已规则化 | +| 3 | JDK | 21（强制） | ✅ 已规则化 | +| 4 | Lombok | 强制使用，禁止手写 getter/setter/builder | ✅ 已规则化 | +| 5 | 实体类 | 必须继承 BaseEntity，加 @EqualsAndHashCode(callSuper = true) | ✅ 已规则化 | +| 6 | Service 注入 | 构造器注入（private final + 构造器） | ✅ 已规则化 | +| 7 | 类名前缀 | 不加 Rui 前缀，除非与框架类冲突 | ✅ 已规则化 | +| 8 | 版本管理 | 统一使用 ${revision} + flatten-maven-plugin | ✅ 已规则化 | +| 9 | 代码注释 | 所有代码注释使用中文 | ❌ **建议加入规则** | + +### 5.2 Feign 规范 + +| # | 规范项 | 要求 | 是否加入规则 | +|---|--------|------|------------| +| 1 | contextId | 必须使用，隔离 Bean 命名空间 | ✅ 已规则化 | +| 2 | 服务名 | value = "${feign.providers.xxx:默认名}" 外部化 | ✅ 已规则化 | +| 3 | 返回值 | Inner API 统一返回 Result | ✅ 已规则化 | +| 4 | 注册方式 | META-INF/spring.factories 注册 CloudFeignAutoConfiguration | ✅ 已规则化 | +| 5 | 调用头 | @Headers("INTERNAL_REQUEST: INTERNAL") 自动注入 | ✅ 已规则化 | +| 6 | 解包方式 | Remote 服务层解包并转换 | ✅ 已规则化 | +| 7 | 降级处理 | 禁止使用 fallback/fallbackFactory，Remote 层 try-catch | ✅ 已规则化 | + +### 5.3 URL 路由规范 + +| # | 规范项 | 要求 | 是否加入规则 | +|---|--------|------|------------| +| 1 | 格式 | /{模块}/{目录层级...}/{功能}/{方法} | ✅ 已规则化 | +| 2 | 模块位置 | 模块标识在最前（方便网关路由） | ✅ 已规则化 | +| 3 | 内部标识 | 内部接口统一使用 /inner | ✅ 已规则化 | +| 4 | 网关配置 | 网关只需配置 /{模块}/** | ✅ 已规则化 | + +### 5.4 Controller 分类规范 + +| 控制器命名 | 路径前缀 | 认证要求 | 用途 | 是否加入规则 | +|-----------|---------|---------|------|------------| +| XxxController | /{模块}/{功能}/** | 需认证 | 常规业务接口 | ✅ 已规则化 | +| XxxEntryController | /{模块}/entry/** | 免认证 | 对外入口（注册、登录前） | ✅ 已规则化 | +| XxxNotifyController | /{模块}/notify/** | 免认证 | 第三方回调（支付、Webhook） | ✅ 已规则化 | +| XxxInnerController | /{模块}/inner/** | @Inner 控制 | 内部 Feign 调用 | ✅ 已规则化 | + +### 5.5 数据库规范 + +| # | 规范项 | 要求 | 是否加入规则 | +|---|--------|------|------------| +| 1 | 实体基类 | 继承 BaseEntity（含 id, createTime, updateTime, tenantId, deleted） | ✅ 已实现 | +| 2 | 多租户 | 使用 MyBatis Plus 多租户拦截器（TenantLineInnerInterceptor） | ✅ 已实现 | +| 3 | 逻辑删除 | 使用 @TableLogic 注解，字段名 deleted | ✅ 已实现 | +| 4 | 自动填充 | 使用 MetaObjectHandler 自动填充创建/更新时间 | ✅ 已实现 | +| 5 | 表命名 | 统一前缀 rui_{模块}_{表名}（如 rui_user_credential） | ⚠️ **建议规则化** | +| 6 | 字段命名 | 下划线命名，主键 id，租户 tenant_id | ⚠️ **建议规则化** | +| 7 | SQL 防注入 | 启用 BlockAttackInnerInterceptor（防全表更新/删除） | ✅ 已实现 | + +### 5.6 Git 规范 + +| # | 规范项 | 要求 | 是否加入规则 | +|---|--------|------|------------| +| 1 | 自动提交 | 每次修改后自动 git commit，不推送 | ✅ 已规则化 | +| 2 | 推送时机 | 由用户提示或累积多次提交后统一推送 | ✅ 已规则化 | +| 3 | 忽略目录 | app/、config/ 加入 .gitignore | ✅ 已规则化 | +| 4 | 提交信息 | 使用中文描述，格式：type(scope): 描述 | ❌ **建议加入规则** | +| 5 | 分支策略 | main 为主分支，功能分支开发 | ❌ **建议加入规则** | + +### 5.7 Maven 规范 + +| # | 规范项 | 要求 | 是否加入规则 | +|---|--------|------|------------| +| 1 | 版本管理 | ${revision} + flatten-maven-plugin | ✅ 已规则化 | +| 2 | 版本发布 | mvn deploy -Drevision=x.x.x | ✅ 已规则化 | +| 3 | 正式仓库 | https://maven.dev.vifo.cc/repository/maven-releases/ | ✅ 已规则化 | +| 4 | 快照仓库 | https://maven.dev.vifo.cc/repository/maven-snapshots/ | ✅ 已规则化 | +| 5 | 依赖引入 | 版本在 rui-dependencies 中统一管理 | ✅ 已规则化 | +| 6 | relativePath | 子模块必须指定 relativePath 指向 rui-parent | ✅ 已实现 | + +### 5.8 配置中心规范（Nacos） + +| # | 规范项 | 要求 | 是否加入规则 | +|---|--------|------|------------| +| 1 | 配置拆分 | 每个服务独立 Data ID（rui-{服务名}.yaml） | ✅ 已实现 | +| 2 | 共享配置 | rui-common.yaml 存放全局配置 | ✅ 已实现 | +| 3 | 数据库配置 | rui-data.yaml 存放 MySQL/Druid/MyBatis 配置 | ✅ 已实现 | +| 4 | 端口配置 | 每个服务配置在各自 Nacos 配置文件中 | ✅ 已实现 | +| 5 | 灰度配置 | 在 rui-gateway.yaml 中配置 grayscale.rules | ✅ 已实现 | +| 6 | 配置推送 | 使用 push-nacos-config.sh 统一推送 | ✅ 已实现 | + +--- + +## 六、推荐修改项 + +### 6.1 高优先级（建议立即修改） + +| # | 修改项 | 当前问题 | 修改建议 | +|---|--------|---------|---------| +| 1 | **rui-auth 过于单薄** | 仅 2 个 Java 文件（启动类 + 配置类） | 将 AuthServerConfig 下沉到 rui-common-oauth2，或补充 Token 管理、Session 管理等接口 | +| 2 | **rui-service-system 不完整** | 仅 4 个文件，无完整 Controller/Service/Mapper | 尽快补齐租户管理、菜单/角色/字典的 CRUD 接口 | +| 3 | **Mapper XML 缺失** | 全局未找到 .xml Mapper 文件 | 确认是否全注解 SQL（当前 JdbcTemplate 直接写 SQL），建议补充 MyBatis Plus 的 Mapper 接口 | +| 4 | **rui-dependencies 中声明了未存在的模块** | rui-common-mq-mqtt 在 BOM 中声明但目录不存在 | 删除该声明或创建对应模块 | +| 5 | **自动配置注册方式不统一** | 部分模块使用 spring.factories，部分未注册 | 统一使用 META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports | +| 6 | **BaseController 字段反射注入** | bindCurrentUser 使用反射调用 setter | 改用 MetaObjectHandler 统一处理，或使用构造器注入 | +| 7 | **文档术语不统一** | docs/spring-rui 代码分析报告.md 提到 R，实际代码使用 Result | 统一术语，删除或更新旧文档 | + +### 6.2 中优先级（近期完善） + +| # | 修改项 | 当前问题 | 修改建议 | +|---|--------|---------|---------| +| 1 | **单元测试缺失** | 未见到 src/test/java 目录 | 补充 JUnit 5 + Mockito 测试框架，编写基础单元测试 | +| 2 | **日志追踪缺失** | 无 TraceID 链路追踪 | 引入 MDC + TraceID 过滤器，实现请求全链路追踪 | +| 3 | **QueryBuilder 区间查询弱** | putBetween 仅支持字符串拼接 | 支持日期/数字区间查询，前端传递 JSON 格式查询条件 | +| 4 | **MybatisProperties 利用率低** | 已定义配置但 TenantHandler 仍部分硬编码 | 完全配置驱动，租户字段名、逻辑删除字段名均可配置 | +| 5 | **灰度负载均衡缺少降级计数** | 灰度实例不可用时直接回退稳定实例 | 增加灰度实例健康检查，记录降级次数和比例 | +| 6 | **app/ 目录验证** | .gitignored，当前为空 | 按 docs/业务应用模块创建规则.md 创建示例模块（如 rui-payment），验证规范可行性 | + +### 6.3 低优先级（按需实施） + +| # | 修改项 | 当前问题 | 修改建议 | +|---|--------|---------|---------| +| 1 | **分布式链路追踪** | 无 SkyWalking / Micrometer Tracing | 引入 Micrometer Tracing + Brave 实现链路追踪 | +| 2 | **监控告警模块** | Nacos 有配置占位，backend 无代码 | 集成 Micrometer + Prometheus，或接入 Sentinel Dashboard | +| 3 | **工具类补齐** | 部分通用工具可能缺失 | 移植 SpringUtil、JsonUtil、IdWorker 等工具类到 rui-common-core | +| 4 | **缓存抽象层** | Redis 使用直接，无统一缓存接口 | 在 rui-common-core 中定义 CacheManager 接口，支持多级缓存 | +| 5 | **限流降级** | 缺少统一限流策略 | 在网关层集成 Sentinel，或基于 Redis 实现分布式限流 | + +--- + +## 七、缺少的专业结构 + +### 7.1 必须补充的结构 + +| 结构 | 缺失模块 | 重要性 | 实施建议 | +|------|---------|--------|---------| +| **完整的 rui-service-system** | rui-service-system | 🔴 高 | 补充 SystemTenant、SystemMenu、SystemRole、SystemDict、SystemConfig 的 Entity、Mapper、Service、Controller | +| **Mapper 接口层** | rui-service-user、rui-service-system | 🔴 高 | 为所有 Entity 创建 Mapper 接口，继承 BaseMapper，使用 @Mapper 注解 | +| **单元测试目录** | 所有模块 | 🔴 高 | 创建 src/test/java 和 src/test/resources，编写至少一个示例测试类 | +| **自动配置注册** | rui-common-* 模块 | 🟡 中 | 每个模块创建 META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports | +| **业务应用示例模块** | app/ 目录 | 🟡 中 | 创建 rui-payment-api/common/core/provider/task 示例，验证业务模块创建规则 | + +### 7.2 建议补充的结构 + +| 结构 | 说明 | 重要性 | 实施建议 | +|------|------|--------|---------| +| **API 文档自动生成** | OpenAPI/SpringDoc 已集成，但未统一配置 | 🟡 中 | 统一配置 API 文档标题、版本、鉴权方式，生成在线文档 | +| **数据库变更管理** | 缺少 Flyway/Liquibase | 🟡 中 | 引入 Flyway 管理数据库版本，脚本放在 src/main/resources/db/migration/ | +| **代码质量检查** | 缺少 Checkstyle/SpotBugs | 🟢 低 | 配置 Checkstyle 规则，集成到 Maven 构建流程 | +| **Docker 支持** | 缺少 Dockerfile / docker-compose | 🟢 低 | 为每个服务创建 Dockerfile，提供 docker-compose.yml 本地开发环境 | +| **Kubernetes 配置** | 缺少 K8s YAML | 🟢 低 | 提供基础的 Deployment、Service、ConfigMap 模板 | +| **SonarQube 集成** | 缺少代码质量扫描 | 🟢 低 | 配置 SonarQube 扫描，设置质量门禁 | + +--- + +## 八、新规范建议（需加入 AGENTS.md） + +### 8.1 建议立即加入的规则 + +```markdown +## 数据库规范 + +- **表命名**: 统一前缀 `rui_{模块}_{表名}`，如 `rui_user_credential` +- **字段命名**: 下划线命名法，主键 `id`，租户 `tenant_id`，逻辑删除 `deleted` +- **实体类**: 必须继承 `BaseEntity`，使用 `@TableName` 指定表名 +- **Mapper**: 必须继承 `BaseMapper`，使用 `@Mapper` 注解 +- **SQL**: 优先使用 MyBatis Plus 条件构造器，复杂 SQL 使用 XML 或 @Select + +## Git 提交规范 + +- **格式**: `type(scope): 中文描述` +- **type**: feat/fix/docs/style/refactor/test/chore +- **示例**: `feat(user): 添加用户等级查询接口` +- **要求**: 每次提交原子性，不混合多个功能修改 + +## 代码注释规范 + +- **语言**: 所有注释使用中文 +- **类注释**: 说明类的作用、作者、创建日期 +- **方法注释**: 说明方法用途、参数、返回值 +- **复杂逻辑**: 必须添加行内注释说明业务意图 + +## 接口版本规范 + +- **REST API**: 对外接口建议添加版本前缀，如 `/v1/user/info` +- **兼容性**: 重大变更升级版本号，保持向后兼容 +``` + +### 8.2 建议后续加入的规则 + +```markdown +## 测试规范 + +- **覆盖率**: 核心业务逻辑覆盖率不低于 80% +- **测试类型**: 单元测试（JUnit 5 + Mockito）+ 集成测试（@SpringBootTest） +- **命名**: 测试类以 Test 结尾，测试方法以 should_ 开头 + +## 日志规范 + +- **级别**: DEBUG（开发调试）、INFO（业务流水）、WARN（可恢复异常）、ERROR（严重错误） +- **格式**: 包含 TraceID、用户ID、操作类型、耗时 +- **禁止**: 禁止输出密码、Token、身份证号等敏感信息 + +## 异常处理规范 + +- **自定义异常**: 业务异常统一继承 BizException +- **错误码**: 统一错误码规范，按模块分配区间 +- **全局处理**: 通过 GlobalExceptionHandler 统一处理，不遗漏异常 +``` + +--- + +## 九、Nacos 配置清单（已推送） + +| Data ID | 服务 | 端口 | 状态 | +|---------|------|------|------| +| rui-common.yaml | 全局共享 | - | ✅ | +| rui-data.yaml | DB 模块共享 | - | ✅ | +| rui-gateway.yaml | 网关 | 9300 | ✅ | +| rui-auth.yaml | 认证中心 | 9301 | ✅ | +| rui-service-system.yaml | 系统服务 | 9302 | ✅ | +| rui-service-user.yaml | 用户服务 | 9303 | ✅ | +| rui-service-msg.yaml | 消息服务 | 9304 | ⏳ 预留 | +| rui-service-file.yaml | 文件服务 | 9305 | ⏳ 预留 | +| rui-service-order.yaml | 订单服务 | 9306 | ⏳ 预留 | +| rui-service-pay.yaml | 支付服务 | 9307 | ⏳ 预留 | +| rui-service-search.yaml | 搜索服务 | 9308 | ⏳ 预留 | +| rui-service-cache.yaml | 缓存服务 | 9309 | ⏳ 预留 | +| rui-service-log.yaml | 日志服务 | 9310 | ⏳ 预留 | +| rui-service-monitor.yaml | 监控服务 | 9311 | ⏳ 预留 | + +--- + +## 十、后续实施路线图 + +### Phase 1：基础完善（1-2 周） + +1. ✅ 补齐 rui-service-system 的完整 CRUD +2. ✅ 为所有 Entity 补充 Mapper 接口 +3. ✅ 统一自动配置注册方式 +4. ✅ 补充单元测试基类和示例 +5. ✅ 创建 app/ 目录示例模块 + +### Phase 2：功能增强（2-4 周） + +1. 引入日志链路追踪（TraceID） +2. 完善 QueryBuilder 区间查询 +3. 补充 API 文档自动生成配置 +4. 引入 Flyway 数据库版本管理 +5. 完善灰度发布的降级策略 + +### Phase 3：生产就绪（4-6 周） + +1. 引入分布式链路追踪（SkyWalking/Micrometer） +2. 完善监控告警模块 +3. 配置 Docker 和 docker-compose +4. 集成 SonarQube 代码质量检查 +5. 编写完整的运维部署文档 + +--- + +> **文档版本**: v1.0 +> **创建日期**: 2026-05-28 +> **适用范围**: spring-ai 项目及后续同类项目 +> **维护方式**: 随项目实施迭代更新 diff --git a/frontend/admin-ui-icon-guide.md b/frontend/admin-ui-icon-guide.md new file mode 100644 index 0000000..d11571a --- /dev/null +++ b/frontend/admin-ui-icon-guide.md @@ -0,0 +1,129 @@ +# Admin-UI 图标体系说明文档 + +> 本文档记录 admin-ui 图标配置、映射规则及相关注意事项，避免每次重复分析代码。 + +--- + +## 一、图标体系概览 + +admin-ui 支持 **两类图标**，由 `RuiIcon.vue` 组件统一处理： + +| 类型 | 格式示例 | 来源 | 渲染方式 | +|------|---------|------|---------| +| **Element Plus 图标** | `Setting`、`UserFilled`、`HomeFilled` | `@element-plus/icons-vue` | `` | +| **Tabler 图标（Iconify）** | `tabler:settings`、`tabler:users` | `@iconify/vue` | `` | + +**判断规则**（`RuiIcon.vue`）： +- 如果字符串包含 `:` → 使用 Iconify 渲染（Tabler 图标） +- 否则 → 使用 Element Plus 图标组件渲染 + +--- + +## 二、图标选择器 + +**文件位置**：`admin-ui/src/components/IconPicker.vue` + +**支持四类图标**： +1. **Element Plus** - 动态读取 `@element-plus/icons-vue` 全部图标 +2. **Tabler** - 硬编码 102 个常用图标，以 `tabler:` 为前缀 +3. **SVG** - 内联 SVG 代码 +4. **图片/URL** - 粘贴图片 URL + +**推荐使用 Tabler 图标**（`tabler:` 前缀），与后端菜单存储格式保持一致。 + +--- + +## 三、后端菜单图标存储格式 + +**当前标准**：所有菜单图标统一使用 `tabler:` 前缀格式 + +**示例**： +``` +tabler:settings → 系统管理 +tabler:users → 用户管理 +tabler:menu-2 → 菜单管理 +tabler:user-shield → 角色管理 +tabler:building → 部门管理 +tabler:book → 字典管理 +tabler:id → 岗位管理 +tabler:gift → 租户套餐 +tabler:shield-check → 数据权限 +tabler:award → 用户等级 +tabler:history → 等级日志 +tabler:device-desktop → 演示中心 +tabler:palette → 图标演示 +tabler:list → 列表演示 +``` + +**历史变更**： +- 早期使用 Element Plus 图标组件名（如 `SettingOutlined`） +- 已执行升级脚本 `docs/sql/update_menu_icon.sql` 统一改为 `tabler:` 格式 + +--- + +## 四、前端图标映射规则 + +**文件位置**：`admin-ui/src/composables/useMenu.ts` + +`getIconName()` 函数处理逻辑： +1. 如果 `icon` 字段以 `tabler:` 开头 → **直接透传返回** +2. 否则 → 按原有映射规则转换为 Element Plus 图标名 + +**注意**： +- 后端返回的 `icon` 字段应始终使用 `tabler:` 格式 +- 前端布局文件（SideLayout/TopNavLayout/DoubleLayout）已改为使用 `RuiIcon` 组件渲染菜单图标，支持 `tabler:` 格式 + +--- + +## 五、布局文件中的图标渲染 + +**修改后的渲染方式**（统一使用 `RuiIcon`）： + +```vue + + + + +
+ +
+``` + +**样式适配**（确保图标颜色与菜单主题一致）： +```css +.menu-icon { + margin-right: 5px; + color: inherit; +} +``` + +--- + +## 六、新增功能时的图标规范 + +1. **优先使用 Tabler 图标**（`tabler:` 前缀） +2. **在 IconPicker 中添加**：如果 IconPicker 的 Tabler 列表中没有需要的图标，添加到 `IconPicker.vue` 的 `tablerIcons` 数组 +3. **后端菜单配置**：在 `config/menus/*.json` 中配置图标时，使用 `tabler:xxx` 格式 +4. **前端自动适配**：无需修改前端代码，`RuiIcon` 组件会自动识别并渲染 + +--- + +## 七、常见问题 + +### Q: 为什么菜单图标显示不出来？ +A: 检查后端返回的 `icon` 字段格式： +- 正确：`tabler:settings` +- 错误：`settings`、`Setting`、`tabler-settings` + +### Q: 如何查看所有可用的 Tabler 图标？ +A: 在菜单管理页面点击图标选择器，切换到 "Tabler" 标签页查看。 + +### Q: 能否使用 Element Plus 图标？ +A: 可以，但不推荐。如果必须使用，直接写图标组件名（如 `Setting`），不要加 `tabler:` 前缀。 + +--- + +> **维护提示**：本文档位于 `/docs/admin-ui-icon-guide.md`，修改图标体系时必须同步更新。 diff --git a/frontend/admin-ui-status.md b/frontend/admin-ui-status.md new file mode 100644 index 0000000..02284f2 --- /dev/null +++ b/frontend/admin-ui-status.md @@ -0,0 +1,206 @@ +# Admin-UI 功能状态跟踪文档 + +> 本文档用于记录 admin-ui 前端功能实现状态，避免每次重复分析。 +> **规则**：每次修改 admin-ui 功能后，必须同步更新此文档。 + +--- + +## 一、项目概览 + +- **技术栈**: Vue 3 + Element Plus + Pinia + Vue Router + Axios +- **构建工具**: Vite + TypeScript + UnoCSS +- **布局类型**: 侧边栏 / 顶栏 / 混合 / 双栏（4种布局支持） +- **国际化**: 支持 zh-CN / en-US + +--- + +## 二、功能模块清单 + +### 1. 系统框架功能 + +| 功能 | 状态 | 说明 | +|------|------|------| +| 登录页 | ✅ 完成 | 支持账号密码登录、记住密码 | +| 布局切换 | ✅ 完成 | 4种布局（侧边栏/顶栏/混合/双栏）| +| 主题配置 | ✅ 完成 | 暗黑/明亮模式、主题色、字号 | +| 多标签页 | ✅ 完成 | TagsBar 支持右键菜单（关闭/刷新/全屏/关闭其他/关闭所有）| +| 个人中心 | ✅ 完成 | 个人信息修改、密码修改 | +| 全屏功能 | ✅ 完成 | 支持页面全屏 | +| 国际化 | ✅ 完成 | 中文/英文切换 | +| 路由守卫 | ✅ 完成 | 未登录自动跳转、已登录禁止访问登录页 | + +### 2. 用户管理模块 + +| 功能 | 页面 | 状态 | 说明 | +|------|------|------|------| +| 用户信息 | user/info/Index.vue | ✅ 完成 | 增删改查、批量删除、状态切换、导出、角色分配、详情查看 | +| 用户详情 | user/detail/Index.vue | ✅ 完成 | 增删改查、批量删除、导出 | +| 等级管理 | user/level/Index.vue | ✅ 完成 | 增删改查、批量删除、状态切换、导出 | +| 等级日志 | user/level-log/Index.vue | ✅ 完成 | 增删改查、批量删除、状态切换、导出 | +| 收货地址 | user/address/Index.vue | ⚠️ 待检查 | 页面存在，需确认功能完整性 | +| 账户流水 | user/account/Index.vue | ⚠️ 待检查 | 页面存在，需确认功能完整性 | + +**缺失功能**: +- ❌ **用户管理页面缺少导入功能**（后端 `/user/admin/user/import` 已提供） +- ❌ **缺少用户详情管理页面**（后端 `/user/admin/detail/**` 已提供） + +### 3. 系统管理模块 + +| 功能 | 页面 | 状态 | 说明 | +|------|------|------|------| +| 菜单管理 | system/menu/Index.vue | ✅ 完成 | 树形展示、图标选择、平台切换、修复图标 | +| 角色管理 | system/role/Index.vue | ✅ 完成 | 增删改查、菜单权限分配、状态切换、导出 | +| 部门管理 | system/dept/Index.vue | ✅ 完成 | 树形展示、增删改查、状态切换 | +| 字典管理 | system/dict/Index.vue | ✅ 完成 | 字典项管理、增删改查、状态切换、导出 | +| 参数配置 | system/config/Index.vue | ⚠️ 待检查 | 页面存在，需确认功能完整性 | +| 操作日志 | system/log/Index.vue | ✅ 完成 | 查看详情、清空日志、删除、导出 | +| 登录日志 | system/login-log/Index.vue | ✅ 完成 | 清空日志、删除、导出 | +| 租户管理 | system/tenant/Index.vue | ✅ 完成 | 初始化租户、修改密码、模块编辑、增删改查、导出 | +| OAuth2客户端 | system/oauth2-client/Index.vue | ⚠️ 待检查 | 页面存在，需确认功能完整性 | + +**缺失功能**: +- ❌ **部门管理页面缺少导出功能**（后端 `/system/admin/dept/export` 已提供） +- ❌ **菜单管理页面缺少导出功能**（后端 `/system/admin/menu/export` 已提供） + +### 4. 订单管理模块 + +| 功能 | 页面 | 状态 | 说明 | +|------|------|------|------| +| 订单列表 | order/list/Index.vue | ⚠️ 待检查 | 页面存在，需确认功能完整性 | +| 退款记录 | order/refund/Index.vue | ⚠️ 待检查 | 页面存在，需确认功能完整性 | + +### 5. 内容管理模块 (CMS) + +| 功能 | 页面 | 状态 | 说明 | +|------|------|------|------| +| 文章管理 | cms/article/Index.vue | ⚠️ 待检查 | 页面存在，需确认功能完整性 | +| 分类管理 | cms/category/Index.vue | ⚠️ 待检查 | 页面存在，需确认功能完整性 | +| 轮播图 | cms/banner/Index.vue | ⚠️ 待检查 | 页面存在，需确认功能完整性 | + +### 6. 营销中心模块 + +| 功能 | 页面 | 状态 | 说明 | +|------|------|------|------| +| 优惠券 | marketing/coupon/Index.vue | ⚠️ 待检查 | 页面存在，需确认功能完整性 | +| 活动管理 | marketing/activity/Index.vue | ⚠️ 待检查 | 页面存在，需确认功能完整性 | + +### 7. 演示模块 + +| 功能 | 页面 | 状态 | 说明 | +|------|------|------|------| +| 图标演示 | demo/Icons.vue | ✅ 完成 | Tabler 图标库展示 | +| 列表演示 | demo/list/Index.vue | ✅ 完成 | 标准 CRUD 示例 | + +--- + +## 三、前后端 API 对照表 + +### 已对接的后端 API + +| 后端 Controller | 前端 Service | 对接状态 | +|----------------|-------------|---------| +| UserController | userService.ts | ✅ 已对接（缺少 import） | +| UserDetailController | ❌ 无 | ❌ 未对接 | +| UserLevelController | levelService.ts | ✅ 已对接 | +| UserLevelLogController | levelLogService.ts | ✅ 已对接 | +| SysMenuController | menuService.ts | ✅ 已对接 | +| SysRoleController | roleService.ts | ✅ 已对接 | +| SysDeptController | deptService.ts | ✅ 已对接 | +| SysDictTypeController | dictService.ts | ✅ 已对接 | +| SysDictItemController | dictItemService.ts | ✅ 已对接 | +| SysConfigController | configService.ts | ✅ 已对接 | +| SysOperLogController | operLogService.ts | ✅ 已对接 | +| SysLoginLogController | loginLogService.ts | ✅ 已对接 | +| SysTenantController | tenantService.ts | ✅ 已对接 | +| SystemOAuth2ClientController | oauth2ClientService.ts | ✅ 已对接 | + +### 后端有但前端未对接的 API + +| 后端接口 | 说明 | 优先级 | +|---------|------|--------| +| `GET/POST /user/admin/user/import` | 用户导入 | 低 | +| `GET /system/admin/dept/export` | 部门导出 | 低 | +| `GET /system/admin/menu/export` | 菜单导出 | 低 | +| `POST /system/admin/menu/fix-icons` | 修复菜单图标 | 中（已在前端调用） | +| `POST /system/admin/tenant/{tenantId}/init` | 初始化租户 | 已对接 | +| `POST /system/admin/tenant/{tenantId}/admin/password` | 修改租户管理员密码 | 已对接 | +| `GET /user/admin/detail/**` | 用户详情管理 | **高**（完整页面缺失） | + +--- + +## 四、待办事项 (TODO) + +### 高优先级 +- [x] **用户详情管理页面** - ✅ 已完成 + +### 中优先级 +- [ ] **订单管理功能完善** - 检查订单列表和退款记录页面功能完整性 +- [ ] **CMS 功能完善** - 检查文章、分类、轮播图页面功能完整性 +- [ ] **营销中心功能完善** - 检查优惠券、活动管理页面功能完整性 +- [ ] **用户地址、账户流水页面** - 确认功能是否完整 + +### 低优先级 +- [ ] **导入导出功能补全** - 用户管理导入、部门管理导出、菜单管理导出 +- [ ] **参数配置页面** - 确认功能完整性 +- [ ] **OAuth2客户端页面** - 确认功能完整性 + +--- + +## 五、更新记录 + +| 日期 | 更新内容 | 更新人 | +|------|---------|--------| +| 2025-06-01 | 初始版本，完成系统框架、用户管理、系统管理模块的详细分析 | AI Assistant | +| 2025-06-01 | 新增用户详情管理页面（Index.vue + UserDetailFormDialog.vue），完善路由、国际化、Service 导出 | AI Assistant | +| 2025-06-01 | 菜单配置改为 config/menus/ 目录按模块拆分；增加模块管理功能（Nacos配置 + 后端API + 前端模块编辑） | AI Assistant | + +--- + +## 六、使用说明 + +### 维护规范 + +1. **新增功能时**：在对应模块表格中添加一行，标记状态 +2. **修改功能时**：更新对应行的状态和说明 +3. **发现问题时**：添加到「待办事项」章节 +4. **完成事项时**：将 TODO 项标记为完成，并记录到「更新记录」 + +### 提示词模板（复制即用） + +#### 场景 1：查看 admin-ui 当前功能状态 +``` +请读取 docs/admin-ui-status.md 文档，告诉我 admin-ui 当前的功能完成情况和还有哪些待办事项。 +``` + +#### 场景 2：基于文档开发新功能 +``` +请读取 docs/admin-ui-status.md 文档，根据「待办事项」中的高优先级任务，帮我实现【具体功能名称】。 +实现完成后，记得同步更新 docs/admin-ui-status.md 文档中的状态。 +``` + +#### 场景 3：检查某个模块是否完整 +``` +请读取 docs/admin-ui-status.md 文档，检查【模块名称】模块的功能是否完整，还有哪些缺失？ +``` + +#### 场景 4：完成修改后更新文档 +``` +我已经完成了【修改内容】，请更新 docs/admin-ui-status.md 文档： +1. 将对应功能状态标记为完成 +2. 如完成待办事项，将其标记为 [x] +3. 在「更新记录」中添加一行 +``` + +#### 场景 5：对比前后端接口 +``` +请读取 docs/admin-ui-status.md 文档，检查「前后端 API 对照表」，告诉我还有哪些后端接口前端未对接。 +``` + +#### 场景 6：新对话快速上手 +``` +请读取 docs/admin-ui-status.md 文档，快速了解 admin-ui 项目现状，无需分析整个项目。 +``` + +--- + +> **提示**：本文档位于 `/docs/admin-ui-status.md`，请确保与代码同步更新。