rui/rui-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 迁移 spring-ai 通用文档到 rui-docs

Browse Source 
- 添加 backend/项目实施规范.md
- 添加 backend/业务应用模块创建规则.md
- 添加 backend/guides/deployment-guide.md
- 添加 frontend/admin-ui-icon-guide.md
- 添加 frontend/admin-ui-status.md
- 更新 README.md 文档索引
This commit is contained in:
pigeon
2026-06-04 09:03:21 +08:00
parent d0771597a6
commit 0666c3ec7b
9 changed files with 2340 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+29 -2
View File
@@ -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/）
| 文档 | 说明 |
backend/guides/AI开发操作手册.md
+317
View File
@@ -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<PayResult> 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 协作，禁止直接引用其他模块代码！
backend/guides/deployment-guide.md
+294
View File
@@ -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
```
---
> **最后提醒**：生产环境部署前务必在测试环境验证！
backend/业务应用模块创建规则.md
+340
View File
@@ -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/ （可选）
```
> `<relativePath>` 一律不加，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 管理，不加 `<version>`
- **内部模块依赖**（`rui-{领域}-*`）：加 `<version>${project.version}</version>`
## app/pom.xml 模板
```xml
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>com.rui</groupId>
<artifactId>rui-parent</artifactId>
<version>1.0.0-SNAPSHOT</version>
</parent>
<artifactId>rui-app</artifactId>
<packaging>pom</packaging>
<name>rui-app</name>
<description>睿核科技 — 业务应用模块聚合</description>
<modules>
<module>rui-payment</module>
<!-- 新增模块在此添加 -->
</modules>
</project>
```
## api 模块 POM 模板
```xml
<dependencies>
<dependency>
<groupId>com.alibaba.cloud</groupId>
<artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
</dependency>
<dependency>
<groupId>com.alibaba.cloud</groupId>
<artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-webmvc</artifactId>
</dependency>
<dependency>
<groupId>com.rui</groupId>
<artifactId>rui-{领域}-core</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>com.rui</groupId>
<artifactId>rui-common-security</artifactId>
</dependency>
<dependency>
<groupId>com.rui</groupId>
<artifactId>rui-common-web</artifactId>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<executions>
<execution>
<id>repackage</id>
<goals><goal>repackage</goal></goals>
<configuration><attach>true</attach></configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
```
## 启动类模板
```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<Trade> create(@RequestBody TradeRequest req) { ... }
}
// 对外入口 — 免认证
@RestController
@RequestMapping("/payment/entry")
public class PaymentEntryController {
@PostMapping("/alipay")
public R<PayResult> 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) { ... }
}
```
backend/模块间通信规范.md
+152
View File
@@ -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<UserDTO> getUserById(@PathVariable Long id);
@GetMapping("/api/v1/user/current")
Result<UserDTO> getCurrentUser();
}
```
### 2. 模块 → 模块（如收银 → 支付）
```java
// 通过 FeignClient 调用其他业务模块
@FeignClient("rui-payment")
public interface PaymentFeignClient {
@PostMapping("/api/v1/pay/order")
Result<PayResult> createPayOrder(@RequestBody PayOrderDTO dto);
@GetMapping("/api/v1/pay/status/{orderNo}")
Result<PayStatus> 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 通信，禁止任何直接代码引用！
backend/跨团队协作工作流.md
+433
View File
@@ -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 讨论。
backend/项目实施规范.md
+440
View File
@@ -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<T> │
│ <────────────────────────────────────────── │
│ │
│ 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<T> | ✅ 已规则化 |
| 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<T>，实际代码使用 Result<T> | 统一术语，删除或更新旧文档 |
### 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<Entity>`，使用 `@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 项目及后续同类项目
> **维护方式**: 随项目实施迭代更新
frontend/admin-ui-icon-guide.md
+129
View File
@@ -0,0 +1,129 @@
# Admin-UI 图标体系说明文档
> 本文档记录 admin-ui 图标配置、映射规则及相关注意事项，避免每次重复分析代码。
---
## 一、图标体系概览
admin-ui 支持 **两类图标**，由 `RuiIcon.vue` 组件统一处理：
| 类型 | 格式示例 | 来源 | 渲染方式 |
|------|---------|------|---------|
| **Element Plus 图标** | `Setting`、`UserFilled`、`HomeFilled` | `@element-plus/icons-vue` | `<el-icon>` |
| **Tabler 图标（Iconify）** | `tabler:settings`、`tabler:users` | `@iconify/vue` | `<Icon :icon="..." />` |
**判断规则**（`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
<!-- SideLayout.vue / TopNavLayout.vue -->
<template #title>
<RuiIcon v-if="item.icon" :icon="item.icon" :size="16" class="menu-icon" />
<span>{{ item.title }}</span>
</template>
<!-- DoubleLayout.vue（图标栏） -->
<div class="icon-btn">
<RuiIcon :icon="item.icon" :size="20" />
</div>
```
**样式适配**（确保图标颜色与菜单主题一致）：
```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`，修改图标体系时必须同步更新。
frontend/admin-ui-status.md
+206
View File
@@ -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`，请确保与代码同步更新。