docs: 更新 README 和 PROJECT_SUMMARY 文档

- README.md 更新：
  * 文档生成部分：添加详细的命令说明和使用方法
  * 新增 SWAGGER_PORT 配置说明章节，包括变量定义、影响范围、修改方法
  * 更新系统接口表格中的 Swagger 描述
  * 说明应用内置 Swagger UI 的使用方法

- PROJECT_SUMMARY.md 更新：
  * 添加项目概述描述
  * 更新 API 文档部分，反映已实现的功能
  * 更新构建和部署部分，添加端口配置和进程管理功能
  * 详细分类 Make 命令，添加所有新命令说明
  * 更新系统接口说明，添加 Swagger UI 访问地址
  * 更新下一步建议，使用新的文档生成命令
  * 新增"最新优化功能"章节，详细说明端口配置和文档优化

PROJECT_SUMMARY.md

@@ -1,6 +1,8 @@
 # Yinli API 项目总结
 
-## 🎉 
+## 🎉 项目概述
+
+基于 Golang Gin 框架构建的高性能 RESTful API 服务，集成了 JWT 认证、Redis 缓存、频率限制、CORS 等安全特性，支持多环境部署和完整的 API 文档生成。
 
 以下是项目的详细总结：
 
@@ -45,6 +47,9 @@
 - ✅ 支持多环境启动命令（`make dev`、`make stage`、`make prod`）
 - ✅ Docker 容器化支持
 - ✅ 自动生成 Docker Compose 文件
+- ✅ 端口配置变量化（`SERVER_PORT`、`SWAGGER_PORT`）
+- ✅ 端口占用检查和自动处理
+- ✅ 端口进程管理命令（`kill-port`、`kill-port-force`）
 
 ### 8. 测试框架
 - ✅ 使用 Testify 测试框架
@@ -53,8 +58,13 @@
 - ✅ 接口测试框架（需要数据库连接时可启用）
 
 ### 9. API 文档
-- ✅ Swagger 文档集成准备
+- ✅ Swagger 文档自动生成（`make docs`）
-- ✅ 支持按环境分离文档生成
+- ✅ 自动安装 swag 工具（如果未安装）
+- ✅ 自动过滤生成过程中的警告信息
+- ✅ 自动修复生成的 `docs.go` 文件兼容性问题
+- ✅ 支持按环境分离文档生成（dev/stage/prod）
+- ✅ Docker Swagger UI 服务（`make docs-serve`）
+- ✅ 应用内置 Swagger UI（`/swagger/index.html`）
 - ✅ 文档保存在 `doc/` 目录
 
 ### 10. 详细文档
@@ -91,7 +101,7 @@ make docker-compose-dev
 make docker-up-dev
 
 # 查看日志
-make docker-logs
+make docker-logs-dev
 
 # 停止服务
 make docker-down-dev
@@ -175,17 +185,51 @@ yinli-api/
 
 ## 🛠️ 可用的 Make 命令
 
+### 开发命令
 ```bash
 make help                # 显示所有可用命令
 make dev                 # 启动开发环境
 make stage               # 启动预发布环境
 make prod                # 启动生产环境
+```
+
+### 构建命令
+```bash
 make build               # 构建应用程序
-make test                # 运行测试
+make build-all           # 构建所有平台版本
-make docker-up-dev       # 启动 Docker 开发环境
 make clean               # 清理构建文件
 ```
 
+### 测试命令
+```bash
+make test                # 运行测试
+make test-coverage       # 运行测试并生成覆盖率报告
+```
+
+### 文档命令
+```bash
+make docs                # 生成 API 文档（自动安装 swag）
+make docs-serve          # 启动 Swagger UI 服务器（Docker）
+make docs-stop           # 停止 Swagger UI 服务器
+```
+
+### Docker 命令
+```bash
+make docker-up-dev       # 启动 Docker 开发环境
+make docker-up-stage     # 启动 Docker 预发布环境
+make docker-up-prod      # 启动 Docker 生产环境
+make docker-down-dev     # 停止开发环境容器
+make docker-logs-dev     # 查看开发环境日志
+make docker-ps           # 查看所有容器状态
+```
+
+### 端口管理命令
+```bash
+make kill-port PORT=1234        # 终止指定端口的进程
+make kill-port-force PORT=1234  # 强制终止指定端口的进程
+make kill-1234                  # 终止默认端口 1234 的进程
+```
+
 ## 📡 API 接口列表
 
 ### 认证接口
@@ -204,7 +248,9 @@ make clean               # 清理构建文件
 
 ### 系统接口
 - `GET /health` - 健康检查
-- `GET /swagger/*` - API 文档
+- `GET /swagger/*` - API 文档（Swagger UI）
+  - 访问地址：`http://localhost:$(SERVER_PORT)/swagger/index.html`
+  - 需要先执行 `make docs` 生成文档
 
 ## 🔒 安全特性
 
@@ -258,7 +304,31 @@ make docker-logs-prod
 3. **环境变量**: 在生产环境中设置敏感配置的环境变量
 4. **SSL 证书**: 在生产环境中配置 HTTPS
 5. **监控日志**: 添加应用监控和日志收集
-6. **API 文档**: 运行 `make install-tools` 安装 Swagger 工具并生成文档
+6. **API 文档**: 运行 `make docs` 自动生成 Swagger 文档，使用 `make docs-serve` 启动 Swagger UI 服务器
+
+## 🔧 最新优化功能
+
+### 端口配置管理
+- **SERVER_PORT 变量**：统一管理应用服务器端口（默认 1234）
+  - 自动更新配置文件中的 `server.port`
+  - 自动更新 Docker Compose 端口映射
+  - 支持端口占用检查和自动处理
+
+- **SWAGGER_PORT 变量**：统一管理 Swagger UI 端口（默认 8081）
+  - Docker Swagger UI 容器端口映射
+  - 静态文件服务器端口
+
+### API 文档生成优化
+- **自动安装工具**：`make docs` 自动检查并安装 swag 工具
+- **警告过滤**：自动过滤生成过程中的警告信息
+- **兼容性修复**：自动修复生成的 `docs.go` 文件兼容性问题
+- **Docker Swagger UI**：使用 Docker 运行完整的 Swagger UI 界面
+- **应用内置 UI**：支持通过 `/swagger/index.html` 访问文档
+
+### Docker 命令优化
+- **命令命名统一**：`docker-logs` → `docker-logs-dev`，保持命名一致性
+- **自动重试机制**：Docker 容器停止失败时自动重试
+- **权限错误处理**：自动检测并处理 rootless Docker 权限问题
 
 ## 🎯 项目特色
 

README.md

@@ -290,10 +290,42 @@ make check        # 执行所有检查
 ### 文档生成
 
 ```bash
-make docs         # 生成 API 文档
+make docs         # 生成 API 文档（自动安装 swag 工具）
-make docs-serve   # 启动文档服务器
+make docs-serve   # 启动 Swagger UI 文档服务器（使用 Docker）
+make docs-stop    # 停止 Swagger UI 文档服务器
 ```
 
+**文档生成说明**：
+
+1. **生成 API 文档**：
+   ```bash
+   make docs
+   ```
+   - 自动检查并安装 `swag` 工具（如果未安装）
+   - 自动过滤生成过程中的警告信息
+   - 自动修复生成的 `docs.go` 文件中的兼容性问题
+   - 文档生成到 `doc/dev/` 目录
+
+2. **启动 Swagger UI 服务器**：
+   ```bash
+   make docs-serve
+   ```
+   - 使用 Docker 运行 Swagger UI 容器
+   - 提供完整的 Swagger UI 界面（非简单的文件列表）
+   - 默认端口：`8081`（可通过 `SWAGGER_PORT` 变量修改）
+   - 访问地址：`http://localhost:8081`
+
+3. **停止 Swagger UI 服务器**：
+   ```bash
+   make docs-stop
+   ```
+   - 停止并移除 Swagger UI 容器
+
+4. **应用内置 Swagger UI**：
+   - 启动应用后，访问：`http://localhost:$(SERVER_PORT)/swagger/index.html`
+   - 例如：`http://localhost:1234/swagger/index.html`
+   - 注意：需要先执行 `make docs` 生成文档，并在 `main.go` 中导入 docs 包
+
 ### Docker 操作
 
 ```bash
@@ -413,6 +445,53 @@ make dev
 curl http://localhost:1234/health
 ```
 
+### SWAGGER_PORT 配置
+
+`SWAGGER_PORT` 是定义在 `Makefile` 中的变量，用于统一管理 Swagger UI 文档服务器的端口配置。
+
+**变量定义位置**：
+```makefile
+# Makefile 第 23 行
+SWAGGER_PORT := 8081
+```
+
+**影响范围**：
+
+1. **Docker Swagger UI 容器端口映射**：
+   - `make docs-serve` 启动 Swagger UI 容器时，使用 `-p $(SWAGGER_PORT):8080` 进行端口映射
+   - 容器内部端口固定为 8080，外部访问端口为 `SWAGGER_PORT` 的值
+
+2. **静态文件服务器端口**：
+   - 当 Docker 不可用时，`make docs-serve` 会使用 Python HTTP 服务器
+   - 服务器监听在 `SWAGGER_PORT` 指定的端口
+
+3. **访问地址**：
+   - Swagger UI 访问地址：`http://localhost:$(SWAGGER_PORT)`
+   - 默认访问地址：`http://localhost:8081`
+
+**修改方法**：
+
+1. **修改 Makefile**：
+   ```makefile
+   # 在 Makefile 第 23 行修改
+   SWAGGER_PORT := 8081  # 改为你想要的端口
+   ```
+
+2. **注意事项**：
+   - 确保修改后的端口未被其他服务占用
+   - 如果修改了端口，访问地址也需要相应更新
+   - 修改后需要重新执行 `make docs-serve` 才能生效
+
+**示例**：
+```bash
+# 将 SWAGGER_PORT 改为 9090
+# 1. 编辑 Makefile，修改 SWAGGER_PORT := 9090
+# 2. 启动 Swagger UI 服务器
+make docs-serve
+# 3. 访问 Swagger UI
+# 浏览器打开: http://localhost:9090
+```
+
 ## 📡 API 接口
 
 ### 认证接口
@@ -443,7 +522,7 @@ curl http://localhost:1234/health
 | 方法 | 路径 | 描述 | 认证 |
 |------|------|------|------|
 | GET | `/health` | 健康检查 | ❌ |
-| GET | `/swagger/*` | API 文档 | ❌ |
+| GET | `/swagger/*` | API 文档（Swagger UI） | ❌ |
 
 ## 🧪 接口测试