# 后端服务功能模块

## 1. 用户认证模块 (`/auth`)

### 1.1 发送验证码
- **路径**: `POST /auth/send-code`
- **功能**: 向用户手机号发送短信验证码
- **参数**: `phoneNumber` (手机号)
- **依赖**: 阿里云短信服务

### 1.2 验证码登录
- **路径**: `POST /auth/login`
- **功能**: 使用手机号+验证码登录，返回用户信息和Token
- **参数**: `phoneNumber`, `code`
- **返回**: `userId`, `phoneNumber`, `token`

### 1.3 验证Token
- **路径**: `POST /auth/validate-token`
- **功能**: 验证Token有效性，自动刷新即将过期的Token
- **参数**: `token`

### 1.4 刷新Token
- **路径**: `POST /auth/refresh-token`
- **功能**: 刷新用户Token
- **参数**: `token`

### 1.5 注销登录
- **路径**: `POST /auth/logout`
- **功能**: 删除Token，注销登录
- **参数**: `token`

---

## 2. 用户资料模块 (`/user`)

### 2.1 获取用户资料
- **路径**: `GET /user/profile`
- **参数**: `id` (用户ID)
- **返回**: 昵称、性别、生日、个性签名

### 2.2 更新用户资料
- **路径**: `PUT /user/profile`
- **功能**: 更新用户资料（含敏感词检测）
- **参数**: `id`, `nickname`, `gender`, `birthday`, `signature`

### 2.3 单独更新昵称
- **路径**: `PUT /user/nickname`
- **功能**: 更新用户昵称（含敏感词检测）
- **参数**: `userId`, `nickname`

### 2.4 单独更新签名
- **路径**: `PUT /user/signature`
- **功能**: 更新用户个性签名（含敏感词检测）
- **参数**: `userId`, `signature`

---

## 3. 铜钱系统模块 (`/coin`)

### 3.1 查询余额
- **路径**: `GET /coin/balance`
- **参数**: `userId`

### 3.2 按手机号查询余额
- **路径**: `GET /coin/balance/phone`
- **参数**: `phoneNumber`

### 3.3 消费铜钱
- **路径**: `POST /coin/consume`
- **参数**: `userId`

### 3.4 按手机号消费铜钱
- **路径**: `POST /coin/consume/phone`
- **参数**: `phoneNumber`

### 3.5 重置余额
- **路径**: `POST /coin/reset`
- **功能**: 重置用户铜钱余额为0（用于注销）
- **参数**: `userId`

### 3.6 按手机号重置余额
- **路径**: `POST /coin/reset/phone`
- **参数**: `phoneNumber`

### 3.7 增加铜钱
- **路径**: `POST /coin/increase/phone`
- **参数**: `phoneNumber`, `coinCount`

### 3.8 同步用户铜钱
- **路径**: `POST /coin/sync`
- **功能**: 手动触发用户铜钱记录同步

---

## 4. 支付模块 (`/payment`)

### 4.1 获取支付宝订单
- **路径**: `GET /payment/alipay/order`
- **参数**: `userId`, `amount`, `coinCount`
- **返回**: 支付宝支付订单信息

### 4.2 支付宝异步通知
- **路径**: `POST /payment/notify`
- **功能**: 处理支付宝异步回调通知
- **返回**: `success` 或 `fail`

### 4.3 更新余额
- **路径**: `POST /payment/update-balance`
- **功能**: 处理支付结果，更新用户铜钱余额
- **参数**: `userId`, `orderNo`, `tradeNo`, `amount`, `coinCount`, `status`

---

## 5. 卦象历史模块 (`/divination-history`)

### 5.1 保存卦象记录
- **路径**: `POST /divination-history/save`
- **参数**: `userId`, `phoneNumber`, `localRecordId`, `jsonData`, `aiResult`, `questionType`, `question`, `timestamp`

### 5.2 获取卦象记录
- **路径**: `POST /divination-history/get`
- **参数**: `phoneNumber`, `questionType` (可选)

### 5.3 删除卦象记录
- **路径**: `POST /divination-history/delete`
- **参数**: `phoneNumber`, `localRecordId` 或 `localRecordIds`

### 5.4 统计记录数量
- **路径**: `GET /divination-history/count/{phoneNumber}`

### 5.5 批量软删除
- **路径**: `POST /divination-history/deactivate-all`
- **功能**: 用户注销时批量软删除卦象记录
- **参数**: `phoneNumber`, `userId`

---

## 6. 解卦溯源模块 (`/divination`)

### 6.1 增强解卦
- **路径**: `POST /divination/enhanced`
- **功能**: 调用DeepSeek API进行解卦，支持用户追踪
- **参数**: `userId`, `questionType`, `question`, `divinationData`

### 6.2 查询用户解卦记录
- **路径**: `GET /divination/records/user/{userId}`
- **参数**: `page`, `size`

### 6.3 按手机号查询记录
- **路径**: `GET /divination/records/phone/{phoneNumber}`
- **参数**: `page`, `size`

### 6.4 按追踪ID查询
- **路径**: `GET /divination/records/trace/{traceId}`

### 6.5 时间范围查询
- **路径**: `GET /divination/records/user/{userId}/daterange`
- **参数**: `startTime`, `endTime`, `page`, `size`

### 6.6 查询失败记录
- **路径**: `GET /divination/records/failed`

### 6.7 查询慢请求
- **路径**: `GET /divination/records/slow`
- **参数**: `durationMs` (默认10000ms)

### 6.8 统计用户解卦次数
- **路径**: `GET /divination/stats/user/{userId}/count`

### 6.9 统计时间范围内记录数
- **路径**: `GET /divination/stats/daterange/count`
- **参数**: `startTime`, `endTime`

---

## 7. DeepSeek代理模块 (`/deepseek`)

### 7.1 AI聊天代理
- **路径**: `POST /deepseek/chat`
- **功能**: 代理DeepSeek API，自动附加用户信息
- **参数**: 聊天请求体

---

## 8. 内容审核模块 (`/content-moderation`)

### 8.1 检测问题内容
- **路径**: `POST /content-moderation/check-question`
- **功能**: 检测用户问题是否包含敏感词
- **参数**: `userId`, `question`

---

## 9. 敏感词管理模块 (`/admin/sensitive-words`)

### 9.1 获取统计信息
- **路径**: `GET /admin/sensitive-words/statistics`

### 9.2 添加敏感词
- **路径**: `POST /admin/sensitive-words/add`
- **参数**: `word`, `type`

### 9.3 移除敏感词
- **路径**: `DELETE /admin/sensitive-words/remove`
- **参数**: `word`

### 9.4 测试检测
- **路径**: `POST /admin/sensitive-words/test/nickname`
- **路径**: `POST /admin/sensitive-words/test/signature`
- **路径**: `POST /admin/sensitive-words/test/question`
- **参数**: `content`

---

## 10. 违规记录管理模块 (`/admin/violations`)

### 10.1 获取违规记录列表
- **路径**: `GET /admin/violations/list`
- **参数**: `page`, `size`, `userId`, `contentType`, `violationType`, `startTime`, `endTime`

### 10.2 用户违规统计
- **路径**: `GET /admin/violations/user/{userId}/stats`

### 10.3 违规类型统计
- **路径**: `GET /admin/violations/stats/types`

### 10.4 高频违规用户
- **路径**: `GET /admin/violations/frequent-violators`
- **参数**: `days`, `threshold`

### 10.5 清理违规记录
- **路径**: `DELETE /admin/violations/cleanup`
- **参数**: `daysToKeep`

### 10.6 获取违规详情
- **路径**: `GET /admin/violations/{id}`

---

## 11. 敏感词迁移管理模块 (`/admin/sensitive-word-migration`)

### 11.1 获取配置状态
- **路径**: `GET /admin/sensitive-word-migration/status`

### 11.2 切换服务
- **路径**: `POST /admin/sensitive-word-migration/switch`
- **功能**: 切换本地词库/阿里云服务
- **参数**: `useAliyun`

### 11.3 设置降级策略
- **路径**: `POST /admin/sensitive-word-migration/fallback`
- **参数**: `enableFallback`

### 11.4 对比测试
- **路径**: `POST /admin/sensitive-word-migration/compare`
- **功能**: 对比本地和阿里云检测结果
- **参数**: `content`, `contentType`, `userId`

### 11.5 批量对比测试
- **路径**: `POST /admin/sensitive-word-migration/batch-compare`

### 11.6 健康检查
- **路径**: `GET /admin/sensitive-word-migration/health-check`

---

## 12. 通知模块 (`/notifications`)

### 12.1 获取最新通知
- **路径**: `GET /notifications/latest`

### 12.2 获取所有通知
- **路径**: `GET /notifications/all`

---

## 13. 用户反馈模块 (`/feedback`)

### 13.1 提交反馈
- **路径**: `POST /feedback`
- **参数**: `user_id`, `phone_number`, `content`

---

## 14. 版本管理模块 (`/version`)

### 14.1 检查版本更新
- **路径**: `POST /version/check`
- **参数**: `clientVersion`, `clientVersionCode`

### 14.2 获取最新版本
- **路径**: `GET /version/latest`

---

## 15. 网络访问日志模块 (`/admin/network-logs`)

### 15.1 按用户查询日志
- **路径**: `GET /admin/network-logs/user/{userId}`

### 15.2 按IP查询日志
- **路径**: `GET /admin/network-logs/ip/{clientIp}`

### 15.3 按时间范围查询
- **路径**: `GET /admin/network-logs/time-range`

### 15.4 查询失败记录
- **路径**: `GET /admin/network-logs/failed`

### 15.5 检测可疑IP
- **路径**: `GET /admin/network-logs/suspicious`

### 15.6 统计IP访问次数
- **路径**: `GET /admin/network-logs/count/ip`

### 15.7 清理过期日志
- **路径**: `DELETE /admin/network-logs/cleanup`

---

## 16. 用户数据管理模块 (`/admin/user-data`)

### 16.1 同步用户数据
- **路径**: `POST /admin/user-data/sync`

### 16.2 验证用户数据
- **路径**: `GET /admin/user-data/validate/user/{userId}`
- **路径**: `GET /admin/user-data/validate/phone/{phoneNumber}`

### 16.3 修复数据一致性
- **路径**: `POST /admin/user-data/fix/{phoneNumber}`

### 16.4 批量验证
- **路径**: `POST /admin/user-data/validate/batch`

### 16.5 测试用户信息
- **路径**: `GET /admin/user-data/test/user-info/{userId}`

---

## 17. 数据清理模块 (`/admin/data-cleanup`)

### 17.1 清理所有表
- **路径**: `DELETE /admin/data-cleanup/all`

### 17.2 清理验证码
- **路径**: `DELETE /admin/data-cleanup/verification-codes`

### 17.3 清理支付记录
- **路径**: `DELETE /admin/data-cleanup/payment-records`

### 17.4 清理反馈记录
- **路径**: `DELETE /admin/data-cleanup/feedback`

---

## 第三方服务集成

| 服务 | 用途 | 配置 |
|------|------|------|
| 阿里云短信 | 发送验证码 | `aliyun.sms.*` |
| 阿里云内容安全 | 敏感词检测 | `aliyun.content-security.*` |
| DeepSeek API | AI解卦/聊天 | `thirdparty.deepseek.api-key` |
| 支付宝 | 支付充值 | `alipay.*` |
| MySQL | 数据持久化 | `spring.datasource.*` |
| Redis | Token缓存/会话 | `spring.data.redis.*` |