From 1ae79d2f2fd4b09b823686beeff6f189404444fb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E8=8D=92?= <van666666@foxmail.com>
Date: Tue, 21 Oct 2025 23:29:35 +0800
Subject: [PATCH] 1

---
 doc/公开订单提交功能说明.md | 337 ++++++++++++++++++++++++++++++++++++
 1 file changed, 337 insertions(+)
 create mode 100644 doc/公开订单提交功能说明.md

diff --git a/doc/公开订单提交功能说明.md b/doc/公开订单提交功能说明.md
new file mode 100644
index 0000000..abd135b
--- /dev/null
+++ b/doc/公开订单提交功能说明.md
@@ -0,0 +1,337 @@
+# 公开订单提交功能说明
+
+## 功能概述
+
+本功能提供了一个公开访问的订单提交页面，允许外部用户无需登录即可提交订单信息。该功能具有以下特点：
+
+1. **公开访问**：无需登录认证，直接访问即可使用
+2. **接口限流**：防止恶意刷单和攻击，每个IP每分钟最多3次请求
+3. **详细日志**：记录所有提交请求的详细信息，包括IP、时间、内容等
+4. **简化界面**：去掉历史记录功能，只保留订单提交和清空功能
+5. **安全保护**：只允许提交"单"指令，其他指令一律拒绝
+
+## 访问地址
+
+### 前端页面
+```
+http://your-domain.com/public/order-submit
+```
+
+### 后端接口
+```
+POST /public/order/submit
+```
+
+## 使用说明
+
+### 订单格式
+
+用户需要按照以下格式填写订单信息：
+
+```
+单：
+2025-01-01 001
+备注：测试订单
+分销标记：H-TF
+型号：ZQD180F-EB200
+链接：https://item.jd.com/...
+下单付款：1650
+后返金额：50
+地址：张三13800138000上海市浦东新区张江高科技园区...
+物流链接：https://...
+订单号：1234567890
+下单人：张三
+```
+
+### 字段说明
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| 单号 | 是 | 格式：YYYY-MM-DD XXX |
+| 备注 | 是 | 订单备注信息 |
+| 分销标记 | 是 | 分销渠道标识 |
+| 型号 | 是 | 商品型号 |
+| 链接 | 是 | 商品链接 |
+| 下单付款 | 是 | 付款金额（数字） |
+| 后返金额 | 是 | 返现金额（数字） |
+| 地址 | 是 | 收货地址（含姓名和电话） |
+| 物流链接 | 是 | 物流跟踪链接 |
+| 订单号 | 是 | 订单编号 |
+| 下单人 | 是 | 下单人姓名 |
+
+## 技术实现
+
+### 前端
+
+**文件路径**：`d:\code\ruoyi-vue\src\views\public\order-submit\index.vue`
+
+主要功能：
+- 订单信息输入框
+- 提交和清空按钮
+- 响应结果展示
+- 使用说明折叠面板
+- 警告信息弹窗
+
+### 后端
+
+**控制器**：`d:\code\RuoYi-Vue-master\ruoyi-java\ruoyi-admin\src\main\java\com\ruoyi\web\controller\public_\PublicOrderController.java`
+
+主要功能：
+- 接收订单提交请求
+- 参数验证
+- 安全检查（只允许"单"指令）
+- 调用订单处理服务
+- 详细日志记录
+
+### API接口
+
+**文件路径**：`d:\code\ruoyi-vue\src\api\public\order.js`
+
+```javascript
+export function submitPublicOrder(data) {
+  return request({
+    url: '/public/order/submit',
+    method: 'post',
+    data
+  })
+}
+```
+
+### 路由配置
+
+**前端路由**（`router/index.js`）：
+```javascript
+{
+  path: '/public/order-submit',
+  component: () => import('@/views/public/order-submit/index'),
+  hidden: true
+}
+```
+
+**后端安全配置**（`SecurityConfig.java`）：
+```java
+.antMatchers("/public/**").permitAll()
+```
+
+## 限流策略
+
+### 限流规则
+
+使用 `@RateLimiter` 注解实现限流：
+- **限流键**：基于IP地址
+- **时间窗口**：60秒
+- **请求次数**：3次
+- **超限提示**：访问过于频繁，请稍候再试
+
+### 实现原理
+
+基于Redis实现的令牌桶算法：
+1. 每个IP地址独立计数
+2. 在指定时间窗口内统计请求次数
+3. 超过限制次数后拒绝请求
+4. 时间窗口过期后自动重置计数
+
+## 日志记录
+
+### 日志内容
+
+每次请求都会记录以下信息：
+
+1. **请求信息**：
+   - 客户端IP地址
+   - User-Agent
+   - 请求时间
+
+2. **指令信息**：
+   - 指令内容长度
+   - 指令内容预览（前100字符）
+
+3. **执行结果**：
+   - 结果条数
+   - 是否包含警告
+   - 是否成功
+
+4. **异常信息**（如果发生）：
+   - 异常类型
+   - 异常消息
+   - 异常堆栈
+
+### 日志格式
+
+```
+======================================
+公开订单提交 - 开始
+客户端IP: 192.168.1.100
+User-Agent: Mozilla/5.0...
+请求时间: 2025-01-01 10:00:00
+指令内容长度: 256 字符
+指令内容预览: 单：2025-01-01 001...
+开始执行订单指令...
+订单指令执行完成
+执行结果条数: 1
+执行结果[0]: 成功
+公开订单提交 - 结束（成功）
+======================================
+```
+
+## 安全措施
+
+### 1. 指令白名单
+
+只允许以"单："开头的订单提交指令，其他指令一律拒绝。
+
+```java
+if (!trimmedCmd.startsWith("单：") && !trimmedCmd.startsWith("单:") && !trimmedCmd.startsWith("单")) {
+    return AjaxResult.error("只允许提交订单信息，指令必须以'单：'开头");
+}
+```
+
+### 2. IP限流
+
+每个IP地址每分钟最多提交3次，防止恶意刷单。
+
+### 3. 参数验证
+
+严格验证所有必填字段，缺少任何字段都会拒绝提交。
+
+### 4. 日志审计
+
+记录所有提交请求的详细信息，便于追溯和审计。
+
+### 5. 地址去重
+
+系统会检查24小时内是否有相同地址的订单，防止重复提交（白名单除外）。
+
+## 错误处理
+
+### 常见错误
+
+1. **参数为空**
+   - 错误信息：请输入订单信息
+   - 解决方法：填写完整的订单信息
+
+2. **指令格式错误**
+   - 错误信息：只允许提交订单信息，指令必须以'单：'开头
+   - 解决方法：确保指令以"单："开头
+
+3. **缺少字段**
+   - 错误信息：缺少表单字段 单号/下单人/下单价格/...
+   - 解决方法：补充缺失的字段信息
+
+4. **地址重复**
+   - 错误信息：此地址已经存在，请勿重复生成订单
+   - 解决方法：检查地址是否已提交过
+
+5. **访问频繁**
+   - 错误信息：访问过于频繁，请稍候再试
+   - 解决方法：等待1分钟后再次尝试
+
+## 监控建议
+
+### 1. 日志监控
+
+建议监控以下日志关键字：
+- `公开订单提交`：所有提交请求
+- `警告`：异常情况
+- `拒绝`：被拒绝的请求
+- `异常`：系统错误
+
+### 2. 性能监控
+
+建议监控以下指标：
+- 每分钟请求数
+- 平均响应时间
+- 错误率
+- 限流触发次数
+
+### 3. 安全监控
+
+建议监控以下行为：
+- 高频访问的IP地址
+- 频繁触发限流的IP
+- 非法指令尝试
+- 异常错误模式
+
+## 部署说明
+
+### 前端部署
+
+1. 确保路由配置正确
+2. 构建前端项目：`npm run build`
+3. 部署到Web服务器
+
+### 后端部署
+
+1. 确保SecurityConfig配置已更新
+2. 确保Redis服务正常运行（限流依赖Redis）
+3. 打包后端项目：`mvn clean package`
+4. 部署到应用服务器
+
+### 验证部署
+
+1. 访问前端页面：`http://your-domain.com/public/order-submit`
+2. 提交测试订单
+3. 检查后端日志
+4. 验证限流功能（快速提交4次，第4次应被拒绝）
+
+## 维护建议
+
+### 1. 定期清理日志
+
+由于详细日志会产生大量内容，建议：
+- 设置日志文件大小限制
+- 配置日志自动归档
+- 定期清理历史日志
+
+### 2. 调整限流策略
+
+根据实际使用情况，可以调整限流参数：
+```java
+@RateLimiter(
+    key = CacheConstants.RATE_LIMIT_KEY, 
+    time = 60,  // 时间窗口（秒）
+    count = 3,  // 允许次数
+    limitType = LimitType.IP
+)
+```
+
+### 3. 监控异常
+
+建议设置告警规则：
+- 错误率超过阈值时告警
+- 限流触发频繁时告警
+- 系统异常时立即告警
+
+### 4. 备份数据
+
+建议定期备份：
+- 订单数据
+- 日志文件
+- Redis数据
+
+## 常见问题
+
+### Q1: 如何修改限流次数？
+
+A: 修改 `PublicOrderController.java` 中的 `@RateLimiter` 注解参数。
+
+### Q2: 如何查看提交日志？
+
+A: 查看应用日志文件，搜索"公开订单提交"关键字。
+
+### Q3: 如何禁用某个IP的访问？
+
+A: 在 Spring Security 配置中添加IP黑名单规则。
+
+### Q4: 页面访问404怎么办？
+
+A: 检查前端路由配置和后端安全配置是否正确。
+
+### Q5: 提交报错"访问过于频繁"怎么办？
+
+A: 等待1分钟后再次尝试，或联系管理员调整限流策略。
+
+## 联系方式
+
+如有问题或建议，请联系技术支持团队。
+