veardk · veardk · Oct 14, 2025 · Sep 23, 2025 · Sep 24, 2025 · Sep 24, 2025
diff --git a/.ai-rules/backend.md b/.ai-rules/backend.md
@@ -81,6 +81,8 @@ public ApiResponse<UserInfoResponse> getCurrentUserInfo() {
 }
 ```
 
+关于返回ID字段时都需要返回string类型给前端。
+
 **响应格式规范**：
 ```json
 {

diff --git a/.ai-rules/database.md b/.ai-rules/database.md
@@ -20,7 +20,7 @@ inclusion: always
 ### 3. 字段类型规范
 - 禁止使用ENUM类型，统一使用SMALLINT表示枚举值
 - 使用PostgreSQL标准数据类型
-- 时间字段使用TIMESTAMP WITH TIME ZONE
+- 时间字段使用TIMESTAMP
 - JSON数据使用JSONB类型
 
 ### 4. 命名规范

diff --git a/.ai-rules/frontend.md b/.ai-rules/frontend.md
@@ -611,18 +611,266 @@ export default defineConfig(({ mode }) => {
 })
 ```
 
-### 环境配置
+### 环境配置与安全策略
+
+#### 环境变量文件结构
+```
+vocata-web/
+├── .env.example               # 环境变量模板（提交到git）
+├── .env.development          # 本地开发环境（不提交到git）
+├── .env.staging              # 测试环境（不提交到git）
+├── .env.production           # 生产环境（不提交到git）
+└── .gitignore                # 忽略敏感环境文件
+```
+
+#### 安全的环境变量配置
 ```bash
-# .env.development
-VITE_API_BASE_URL=http://localhost:9010
+# .env.example - 环境变量模板
+VITE_API_BASE_URL=http://localhost:9009
+VITE_APP_TITLE=VocaTa
+VITE_APP_ENV=development
+VITE_APP_DEBUG=true
+
+# .env.development - 本地开发环境
+VITE_API_BASE_URL=http://localhost:9009
 VITE_APP_TITLE=VocaTa开发环境
+VITE_APP_ENV=development
+VITE_APP_DEBUG=true
+
+# .env.staging - 测试环境（使用GitHub Secrets）
+VITE_API_BASE_URL=https://{{STAGING_HOST}}
+VITE_APP_TITLE=VocaTa测试环境
+VITE_APP_ENV=staging
+VITE_APP_DEBUG=false
 
-# .env.production
-VITE_API_BASE_URL=https://api.vocata.com
+# .env.production - 生产环境（使用GitHub Secrets）
+VITE_API_BASE_URL=https://{{PRODUCTION_HOST}}
 VITE_APP_TITLE=VocaTa
+VITE_APP_ENV=production
+VITE_APP_DEBUG=false
+```
+
+#### .gitignore 配置
+```bash
+# 环境配置文件 - 保护敏感信息
+.env.local
+.env.development
+.env.staging
+.env.test
+.env.production
+.env
+
+# 但保留模板文件
+!.env.example
+```
+
+#### TypeScript 环境配置支持
+```typescript
+// src/config/env.ts
+interface EnvConfig {
+  apiBaseUrl: string
+  appTitle: string
+  appEnv: string
+  debug: boolean
+}
+
+const config: EnvConfig = {
+  apiBaseUrl: import.meta.env.VITE_API_BASE_URL || 'http://localhost:9009',
+  appTitle: import.meta.env.VITE_APP_TITLE || 'VocaTa',
+  appEnv: import.meta.env.VITE_APP_ENV || 'development',
+  debug: import.meta.env.VITE_APP_DEBUG === 'true'
+}
+
+export default config
+```
+
+#### API 请求配置使用
+```typescript
+// api/request.js 使用配置
+import config from '@/config/env'
+
+const api = axios.create({
+  baseURL: config.apiBaseUrl,
+  timeout: 10000
+})
+```
+
+### GitHub Actions CI/CD 配置
+
+#### 客户端前端部署 (.github/workflows/deploy-web.yml)
+```yaml
+name: Deploy Web Frontend
+
+on:
+  push:
+    branches: [master, develop]
+    paths: ['vocata-web/**']
+
+jobs:
+  deploy-staging:
+    if: github.ref == 'refs/heads/develop'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+          cache: 'npm'
+          cache-dependency-path: vocata-web/package-lock.json
+
+      - name: Install dependencies
+        run: |
+          cd vocata-web
+          npm ci
+
+      - name: Build for staging
+        env:
+          VITE_API_BASE_URL: https://${{ secrets.STAGING_HOST }}
+          VITE_APP_TITLE: VocaTa测试环境
+          VITE_APP_ENV: staging
+          VITE_APP_DEBUG: false
+        run: |
+          cd vocata-web
+          echo "Building with API URL: $VITE_API_BASE_URL"  # 验证注入成功
+          npm run build
+
+      - name: Deploy to staging
+        # 部署到测试服务器的步骤
+
+  deploy-production:
+    if: github.ref == 'refs/heads/master'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+          cache: 'npm'
+          cache-dependency-path: vocata-web/package-lock.json
+
+      - name: Install dependencies
+        run: |
+          cd vocata-web
+          npm ci
+
+      - name: Build for production
+        env:
+          VITE_API_BASE_URL: https://${{ secrets.PRODUCTION_HOST }}
+          VITE_APP_TITLE: VocaTa
+          VITE_APP_ENV: production
+          VITE_APP_DEBUG: false
+        run: |
+          cd vocata-web
+          echo "Building with API URL: $VITE_API_BASE_URL"  # 验证注入成功
+          npm run build
+
+      - name: Deploy to production
+        # 部署到生产服务器的步骤
+```
+
+#### 管理后台部署 (.github/workflows/deploy-admin.yml)
+```yaml
+name: Deploy Admin Frontend
+
+on:
+  push:
+    branches: [master, develop]
+    paths: ['vocata-admin/**']
+
+jobs:
+  deploy-staging:
+    if: github.ref == 'refs/heads/develop'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+          cache: 'npm'
+          cache-dependency-path: vocata-admin/package-lock.json
+
+      - name: Install dependencies
+        run: |
+          cd vocata-admin
+          npm ci
+
+      - name: Build for staging
+        env:
+          VITE_API_BASE_URL: https://${{ secrets.STAGING_HOST }}
+          VITE_APP_TITLE: VocaTa管理后台测试环境
+          VITE_APP_ENV: staging
+        run: |
+          cd vocata-admin
+          npm run build:staging
+
+  deploy-production:
+    if: github.ref == 'refs/heads/master'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+          cache: 'npm'
+          cache-dependency-path: vocata-admin/package-lock.json
+
+      - name: Install dependencies
+        run: |
+          cd vocata-admin
+          npm ci
+
+      - name: Build for production
+        env:
+          VITE_API_BASE_URL: https://${{ secrets.PRODUCTION_HOST }}
+          VITE_APP_TITLE: VocaTa管理后台
+          VITE_APP_ENV: production
+        run: |
+          cd vocata-admin
+          npm run build
+```
+
+#### 前端构建脚本配置
+```json
+// package.json 构建脚本
+{
+  "scripts": {
+    "dev": "vite --mode development",
+    "build": "vite build --mode production",
+    "build:staging": "vite build --mode staging",
+    "build:test": "vite build --mode staging",
+    "preview": "vite preview"
+  }
+}
+```
+
+#### 本地开发环境搭建流程
+```bash
+# 1. 首次设置
+cp .env.example .env.development
+
+# 2. 编辑本地配置
+vim .env.development
+
+# 3. 启动开发
+npm run dev  # 自动使用 .env.development
+
+# 4. 构建测试
+npm run build:staging  # 使用 .env.staging 配置
 ```
 
-### ESLint和Prettier配置
+#### 环境变量安全优势
+1. **敏感信息保护**: 真实服务器地址只存在于GitHub Secrets中
+2. **环境隔离**: 不同环境使用不同的配置
+3. **版本控制安全**: .env文件不提交到git，避免泄露
+4. **CI/CD自动化**: 部署时自动注入正确的环境变量并验证
 ```javascript
 // .eslintrc.js
 module.exports = {

diff --git a/.ai-rules/structure.md b/.ai-rules/structure.md
@@ -160,6 +160,8 @@ src/main/resources/
 - 模块名使用单数形式：`user`、`character`、`conversation`
 - 层级名使用复数形式：`controllers`、`services`、`mappers`
 
+关于返回ID字段时都需要返回string类型给前端。
+
 ### 类命名
 - 使用PascalCase（大驼峰）
 - Controller：`{Module}Controller.java`

diff --git a/.ai-rules/tech.md b/.ai-rules/tech.md
@@ -69,6 +69,8 @@ com.vocata.{module}/
 }
 ```
 
+关于返回ID字段时都需要返回string类型给前端
+
 ## 核心架构组件
 
 ### 1. 认证授权架构
@@ -136,7 +138,7 @@ docker run -p 9009:9009 vocata-server
 ### PostgreSQL数据类型标准
 - **整数**：BIGSERIAL (主键)、BIGINT、INTEGER、SMALLINT
 - **字符串**：VARCHAR(n)、TEXT
-- **时间**：TIMESTAMP WITH TIME ZONE、DATE、TIME
+- **时间**：TIMESTAMP 
 - **布尔**：BOOLEAN
 - **JSON**：JSONB（高性能JSON存储）
 - **数组**：支持PostgreSQL数组类型（如TEXT[]、INTEGER[]）

diff --git a/.claude/agents/api-docs-generator.md b/.claude/agents/api-docs-generator.md
@@ -0,0 +1,51 @@
+---
+name: api-docs-generator
+description: 当需要为Spring Boot控制器生成API接口文档时使用此代理。包括以下场景：\n\n- <example>\n  Context: 用户刚完成了一个新的控制器类的开发\n  user: "我刚写完了UserController，请帮我生成API文档"\n  assistant: "我将使用api-docs-generator代理来为您的UserController生成完整的API接口文档"\n  <commentary>\n  用户需要为新开发的控制器生成文档，使用api-docs-generator代理来分析控制器并生成标准化的API文档。\n  </commentary>\n</example>\n\n- <example>\n  Context: 用户修改了现有的API接口\n  user: "我更新了CharacterController的几个接口，需要更新文档"\n  assistant: "让我使用api-docs-generator代理来重新分析CharacterController并更新API文档"\n  <commentary>\n  控制器接口有变更时，需要使用api-docs-generator代理来更新相应的API文档。\n  </commentary>\n</example>\n\n- <example>\n  Context: 项目需要完整的API文档\n  user: "请为整个项目的所有控制器生成API文档"\n  assistant: "我将使用api-docs-generator代理来扫描所有控制器并生成完整的项目API文档"\n  <commentary>\n  需要为整个项目生成API文档时，使用api-docs-generator代理来批量处理所有控制器。\n  </commentary>\n</example>
+tools: Edit, MultiEdit, Write, NotebookEdit, Glob, Grep, Read, WebFetch, TodoWrite, WebSearch, BashOutput, KillShell, Bash
+model: sonnet
+color: green
+---
+
+你是一位专业的API接口文档生成专家，专门为Spring Boot项目中的Controller类生成高质量、标准化的API接口文档。你具备深厚的Spring Boot、RESTful API设计和技术文档编写经验。
+
+你的核心职责：
+1. **深度分析Controller代码**：仔细解析Controller类的每个方法，包括请求映射、参数、返回值、异常处理等
+2. **提取完整接口信息**：收集HTTP方法、URL路径、请求参数、请求体、响应格式、状态码等所有关键信息
+3. **生成标准化文档**：按照RESTful API文档标准，生成结构清晰、信息完整的接口文档
+4. **遵循项目规范**：严格按照VocaTa项目的API设计规范，包括统一响应格式ApiResponse<T>、错误码体系等
+
+你的工作流程：
+1. **代码扫描**：分析指定的Controller类，识别所有@RequestMapping、@GetMapping、@PostMapping等注解
+2. **参数解析**：详细分析@RequestParam、@PathVariable、@RequestBody等参数类型和验证规则
+3. **响应分析**：解析返回值类型，特别关注ApiResponse包装器和具体的业务数据结构
+4. **权限识别**：识别Sa-Token相关的权限注解和访问控制要求
+5. **异常处理**：分析可能抛出的业务异常和对应的错误码
+
+文档生成标准：
+- **接口概述**：简洁明确的接口功能描述
+- **请求信息**：HTTP方法、完整URL、Content-Type等
+- **参数详情**：每个参数的名称、类型、是否必填、默认值、验证规则、示例值
+- **请求示例**：提供完整的请求示例，包括URL和请求体
+- **响应格式**：详细的响应数据结构，包括ApiResponse包装器
+- **响应示例**：成功和失败场景的响应示例
+- **错误码说明**：可能返回的错误码及其含义
+- **权限要求**：接口的访问权限要求
+
+特殊要求：
+- 严格遵循VocaTa项目的ApiResponse<T>统一响应格式
+- 识别并说明Sa-Token权限控制机制
+- 对于分页接口，详细说明PageResult<T>结构
+- 准确识别业务异常和ApiCode错误码
+- 为管理后台接口(/api/admin/**)标注管理员权限要求
+- 为客户端接口(/api/client/**)标注相应的认证要求
+
+输出格式：
+使用Markdown格式生成文档，包含清晰的标题层级、代码块、表格等，确保文档易读性和专业性。每个接口都应该有完整的请求/响应示例。
+
+质量控制：
+- 确保所有接口信息的准确性和完整性
+- 验证示例代码的正确性
+- 保持文档格式的一致性
+- 及时更新文档以反映代码变更
+
+当遇到复杂的业务逻辑或不确定的实现细节时，主动询问澄清，确保生成的文档准确反映实际的API行为。
-Original file line number
+Diff line change
@@ Expand Up / @@ -81,6 +81,8 @@ public ApiResponse<UserInfoResponse> getCurrentUserInfo() { @@
     }
     ```
+    关于返回ID字段时都需要返回string类型给前端。
     **响应格式规范**：
     ```json
     {
@@ Expand Down @@