upload project source code

后端源码/yifan.action-ai.cn/api/docs/api_examples/bazi_zeji_examples.md

@@ -0,0 +1,196 @@
+# 八字择吉测算API使用示例
+
+## 接口概述
+
+八字择吉测算业务提供基于传统八字命理学的择吉服务，帮助用户选择最适宜的吉日良辰进行重要活动。
+
+## 接口地址
+
+- **测算接口**: `POST /yifan_bazi_zeji/calculate`
+- **结果查询**: `GET /yifan_bazi_zeji/result/{zeji_id}`
+- **列表查询**: `GET /yifan_bazi_zeji/list`
+- **详情查询**: `GET /yifan_bazi_zeji/{zeji_id}`
+
+## 1. 八字择吉测算请求
+
+### 请求示例
+
+```bash
+curl -X POST "http://localhost:8000/api/v1/yifan_bazi_zeji/calculate" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -d '{
+    "name": "张三",
+    "gender": "male",
+    "birth_date": "1990年1月1日 子时",
+    "birth_date_api": "1990-01-01T00:30:00",
+    "birth_place": "北京市",
+    "zeji_type": "wedding",
+    "zeji_purpose": "选择结婚吉日，希望婚姻美满幸福",
+    "date_range_start": "2024-03-01",
+    "date_range_end": "2024-06-30"
+  }'
+```
+
+### 请求参数说明
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| name | string | 是 | 姓名 |
+| gender | string | 是 | 性别(male/female) |
+| birth_date | string | 是 | 生辰八字显示格式 |
+| birth_date_api | datetime | 是 | 生辰八字API格式 |
+| birth_place | string | 是 | 出生地 |
+| zeji_type | string | 是 | 择吉类型 |
+| zeji_purpose | string | 是 | 择吉目的描述 |
+| date_range_start | date | 是 | 期望日期范围开始 |
+| date_range_end | date | 是 | 期望日期范围结束 |
+
+### 择吉类型说明
+
+| 类型值 | 说明 | 适用场景 |
+|--------|------|----------|
+| wedding | 婚嫁择吉 | 结婚、订婚、求婚 |
+| business | 开业择吉 | 开店、公司成立、项目启动 |
+| move | 搬家择吉 | 搬迁、入宅、装修 |
+| travel | 出行择吉 | 旅游、出差、远行 |
+| investment | 投资择吉 | 投资、理财、购买 |
+| surgery | 手术择吉 | 医疗手术、体检 |
+| contract | 签约择吉 | 合同签署、协议达成 |
+| other | 其他择吉 | 其他重要事项 |
+
+### 响应示例
+
+```json
+{
+  "code": 200,
+  "msg": "八字择吉任务已创建，正在测算中",
+  "data": {
+    "zeji_id": 12345,
+    "status": 1
+  }
+}
+```
+
+## 2. 获取择吉结果
+
+### 请求示例
+
+```bash
+curl -X GET "http://localhost:8000/api/v1/yifan_bazi_zeji/result/12345" \
+  -H "Authorization: Bearer YOUR_TOKEN"
+```
+
+### 响应示例
+
+```json
+{
+  "code": 200,
+  "msg": "获取八字择吉结果成功",
+  "data": {
+    "zeji_id": 12345,
+    "name": "张三",
+    "zeji_type": "wedding",
+    "zeji_type_label": "婚嫁择吉",
+    "lucky_score": 88,
+    "lucky_level": "中吉",
+    "recommended_dates": [
+      {
+        "date": "2024-03-15",
+        "lunar_date": "二月初六",
+        "weekday": "星期五",
+        "score": 92,
+        "level": "大吉",
+        "best_times": ["09:00-11:00", "13:00-15:00"],
+        "reason": "此日天干地支与您八字相合，五行流通顺畅，最宜婚嫁庆典",
+        "yi": ["嫁娶", "祈福", "开市"],
+        "ji": ["动土", "安葬"]
+      },
+      {
+        "date": "2024-04-08",
+        "lunar_date": "二月三十",
+        "weekday": "星期一",
+        "score": 85,
+        "level": "中吉",
+        "best_times": ["10:00-12:00", "14:00-16:00"],
+        "reason": "月令相助，适宜举办喜庆之事",
+        "yi": ["嫁娶", "出行", "祭祀"],
+        "ji": ["破土", "开仓"]
+      }
+    ],
+    "wuxing_analysis": {
+      "personal_wuxing": "金旺木弱",
+      "suitable_elements": ["水", "木"],
+      "avoid_elements": ["火", "土"],
+      "balance_suggestion": "宜多接触水木属性事物，避免火土过旺"
+    },
+    "bazi_analysis": "您的八字显示金旺木弱，日主偏强，需要水来调和五行平衡。命中带有贵人星，适合在春季进行重要决策...",
+    "tiangang_analysis": "天干地支分析显示您的命格中庚金当令，适合在卯月、辰月进行婚嫁大事，能得到五行相助...",
+    "zeji_suggestions": "根据您的八字特点，建议选择水旺木盛的日子举办婚礼，最好选择上午时辰，有利于新婚和谐...",
+    "avoid_suggestions": "需要避开火土过旺的时间，特别是午时和未时，以免冲克您的命格...",
+    "best_time_periods": [
+      {
+        "time": "09:00-11:00",
+        "name": "巳时",
+        "description": "此时辰阳气上升，最利开创事业和婚姻大事"
+      },
+      {
+        "time": "13:00-15:00", 
+        "name": "未时",
+        "description": "午后时光，阴阳调和，适合庆典仪式"
+      }
+    ],
+    "fengshui_tips": "建议婚礼现场布置以绿色和蓝色为主色调，在东南方位设置主席台，有利于新人感情和谐...",
+    "lucky_directions": ["东南", "正东"],
+    "lucky_colors": ["绿色", "蓝色", "黑色"],
+    "lucky_numbers": [3, 8, 13, 18],
+    "unlocked": null,
+    "is_unlocked": false,
+    "unlock_price": 19.90
+  }
+}
+```
+
+## 3. 状态码说明
+
+| 状态值 | 状态名称 | 说明 |
+|--------|----------|------|
+| 1 | 已创建 | 测算任务已创建，等待处理 |
+| 2 | 测算中 | 正在进行AI测算 |
+| 5 | 测算成功 | 测算完成，可获取结果 |
+| 3 | 测算超时 | AI测算超时 |
+| 0 | 任务失败 | 测算过程中出现错误 |
+
+## 4. 错误处理
+
+### 常见错误码
+
+- `400`: 请求参数错误
+- `401`: 未授权访问
+- `404`: 记录不存在
+- `503`: AI服务不可用
+
+### 错误响应示例
+
+```json
+{
+  "code": 404,
+  "msg": "八字择吉测算记录不存在",
+  "data": null
+}
+```
+
+## 5. 使用注意事项
+
+1. **日期范围**: 建议期望日期范围不超过6个月，以确保推荐结果的准确性
+2. **生辰格式**: birth_date_api必须是标准的ISO 8601格式
+3. **异步处理**: 测算是异步进行的，需要轮询结果接口获取最终结果
+4. **权限控制**: 用户只能查看自己创建的测算记录
+5. **AI服务**: 依赖AI服务，如服务不可用会返回模拟数据
+
+## 6. 集成建议
+
+1. **前端轮询**: 建议每5-10秒轮询一次结果接口，直到状态为5(成功)或失败
+2. **错误重试**: 对于网络错误，建议实现重试机制
+3. **缓存策略**: 可以缓存已完成的测算结果，避免重复请求
+4. **用户体验**: 在测算过程中显示进度提示，提升用户体验

后端源码/yifan.action-ai.cn/api/docs/api_examples/caiyun_jiexi_examples.md

@@ -0,0 +1,265 @@
+# 财运解析API使用示例
+
+## 接口概述
+
+财运解析业务基于现有的命名方案，通过传统命理学和现代财富管理理论，为用户提供全面的财运分析和投资建议。
+
+## 接口地址
+
+- **财运解析**: `POST /yifan_caiyun_jiexi/analyze`
+- **结果查询**: `GET /yifan_caiyun_jiexi/result/{jiexi_id}`
+- **状态查询**: `GET /yifan_caiyun_jiexi/status/{jiexi_id}`
+- **列表查询**: `GET /yifan_caiyun_jiexi/list`
+- **详情查询**: `GET /yifan_caiyun_jiexi/{jiexi_id}`
+
+## 1. 财运解析请求
+
+### 请求示例
+
+```bash
+curl -X POST "http://localhost:8000/api/v1/yifan_caiyun_jiexi/analyze" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -d '{
+    "report_id": 12345
+  }'
+```
+
+### 请求参数说明
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| report_id | int | 是 | 方案ID(yifan_naming_reports表的ID) |
+
+### 响应示例
+
+```json
+{
+  "code": 200,
+  "msg": "财运解析任务已创建，正在分析中",
+  "data": {
+    "jiexi_id": 67890,
+    "status": 1,
+    "message": "财运解析任务已创建"
+  }
+}
+```
+
+## 2. 获取解析状态
+
+### 请求示例
+
+```bash
+curl -X GET "http://localhost:8000/api/v1/yifan_caiyun_jiexi/status/67890" \
+  -H "Authorization: Bearer YOUR_TOKEN"
+```
+
+### 响应示例
+
+```json
+{
+  "code": 200,
+  "msg": "获取财运解析状态成功",
+  "data": {
+    "jiexi_id": 67890,
+    "status": 2,
+    "message": "正在解析中",
+    "progress": 50
+  }
+}
+```
+
+## 3. 获取解析结果
+
+### 请求示例
+
+```bash
+curl -X GET "http://localhost:8000/api/v1/yifan_caiyun_jiexi/result/67890" \
+  -H "Authorization: Bearer YOUR_TOKEN"
+```
+
+### 响应示例
+
+```json
+{
+  "code": 200,
+  "msg": "获取财运解析结果成功",
+  "data": {
+    "jiexi_id": 67890,
+    "report_id": 12345,
+    "name": "张三",
+    "wealth_score": 85,
+    "wealth_level": "中富",
+    "wealth_trend": "上升",
+    "wealth_dimensions": {
+      "zhengcai": {
+        "score": 88,
+        "desc": "正财运强劲，工作收入稳定增长"
+      },
+      "piancai": {
+        "score": 75,
+        "desc": "偏财运中等，投资需谨慎选择"
+      },
+      "touzi": {
+        "score": 82,
+        "desc": "投资运较好，适合稳健型投资"
+      },
+      "shiye": {
+        "score": 90,
+        "desc": "事业财运极佳，创业成功率高"
+      },
+      "yiwai": {
+        "score": 65,
+        "desc": "意外财运一般，不宜过度依赖"
+      }
+    },
+    "wealth_periods": {
+      "qingnian": {
+        "score": 78,
+        "desc": "青年期财运渐起，需积累经验"
+      },
+      "zhongnian": {
+        "score": 92,
+        "desc": "中年期财运鼎盛，把握机遇"
+      },
+      "laonian": {
+        "score": 85,
+        "desc": "老年期财运稳固，重在保值"
+      }
+    },
+    "wealth_months": {
+      "1": 7, "2": 8, "3": 9, "4": 6, "5": 8, "6": 9,
+      "7": 7, "8": 6, "9": 8, "10": 9, "11": 8, "12": 7
+    },
+    "wealth_advice": "您的财运整体向好，建议在中年期把握事业发展机遇，通过稳健投资实现财富增值。",
+    "investment_advice": "适合稳健型投资，可考虑基金定投和房产投资，避免高风险投机。",
+    "career_advice": "事业财运极佳，建议在35-45岁期间考虑创业或职业转型。",
+    "risk_warning": "需注意偏财运波动，避免高风险投机性投资，保持理性投资心态。",
+    "fengshui_wealth": {
+      "directions": ["东南", "正南"],
+      "colors": ["金色", "红色", "绿色"],
+      "numbers": [8, 6, 9],
+      "items": ["貔貅", "金蟾", "发财树"]
+    },
+    "lucky_items": [
+      {
+        "name": "黄水晶",
+        "effect": "增强正财运",
+        "placement": "办公桌左侧"
+      },
+      {
+        "name": "招财猫",
+        "effect": "招揽客源财源",
+        "placement": "店铺收银台"
+      }
+    ],
+    "wealth_taboos": [
+      "避免在财运低谷月进行大额投资",
+      "不宜在卧室摆放镜子对床",
+      "避免钱包颜色过于暗沉"
+    ],
+    "unlocked": null,
+    "is_unlocked": false,
+    "unlock_price": 19.90
+  }
+}
+```
+
+## 4. 财运维度说明
+
+### 财运五维分析
+| 维度 | 权重 | 说明 |
+|------|------|------|
+| 正财运 | 40% | 工资收入、稳定收益能力 |
+| 偏财运 | 25% | 投资收益、意外之财能力 |
+| 投资运 | 20% | 理财投资的成功概率 |
+| 事业财 | 10% | 通过事业创造财富的能力 |
+| 意外财 | 5% | 中奖、继承等意外财富 |
+
+### 财运时期分析
+| 时期 | 年龄段 | 特点 |
+|------|--------|------|
+| 青年期 | 20-35岁 | 财运启动期，重在积累 |
+| 中年期 | 36-55岁 | 财运黄金期，把握机遇 |
+| 老年期 | 56岁以上 | 财运守成期，保值增值 |
+
+### 财运等级说明
+| 等级 | 分数范围 | 说明 |
+|------|----------|------|
+| 大富 | 90-100 | 财运极佳，富贵命格 |
+| 中富 | 75-89 | 财运良好，中产阶层 |
+| 小富 | 60-74 | 财运一般，小康水平 |
+| 平财 | 40-59 | 财运平平，温饱无忧 |
+| 欠财 | 0-39 | 财运较弱，需要努力 |
+
+## 5. 状态码说明
+
+| 状态值 | 状态名称 | 说明 |
+|--------|----------|------|
+| 1 | 已创建 | 解析任务已创建，等待处理 |
+| 2 | 解析中 | 正在进行AI解析 |
+| 5 | 解析成功 | 解析完成，可获取结果 |
+| 3 | 解析超时 | AI解析超时 |
+| 0 | 任务失败 | 解析过程中出现错误 |
+
+## 6. 错误处理
+
+### 常见错误码
+
+- `400`: 请求参数错误
+- `401`: 未授权访问
+- `404`: 记录不存在
+- `503`: AI服务不可用
+
+### 错误响应示例
+
+```json
+{
+  "code": 404,
+  "msg": "方案记录不存在",
+  "data": null
+}
+```
+
+## 7. 使用注意事项
+
+1. **方案依赖**: 必须先有有效的命名方案记录才能进行财运解析
+2. **重复解析**: 同一个方案ID只能生成一次财运解析，重复请求会返回已有结果
+3. **异步处理**: 解析是异步进行的，需要轮询状态接口获取进度
+4. **权限控制**: 用户只能查看自己创建的解析记录
+5. **AI服务**: 依赖AI服务，如服务不可用会返回模拟数据
+
+## 8. 集成建议
+
+1. **前端轮询**: 建议每3-5秒轮询一次状态接口，直到状态为5(成功)或失败
+2. **错误重试**: 对于网络错误，建议实现重试机制
+3. **缓存策略**: 可以缓存已完成的解析结果，避免重复请求
+4. **用户体验**: 在解析过程中显示进度条，提升用户体验
+5. **解锁功能**: 可以实现付费解锁深度内容的功能
+
+## 9. 业务流程
+
+```mermaid
+sequenceDiagram
+    participant User as 用户
+    participant API as 财运解析API
+    participant AI as AI服务
+    participant DB as 数据库
+
+    User->>API: 提交方案ID
+    API->>DB: 查询方案详情
+    API->>DB: 创建解析记录
+    API-->>User: 返回解析ID和状态
+    
+    API->>AI: 异步调用AI解析
+    AI-->>API: 返回解析结果
+    API->>DB: 保存解析结果
+    
+    User->>API: 轮询解析状态
+    API->>DB: 查询解析状态
+    API-->>User: 返回当前状态
+    
+    User->>API: 获取解析结果
+    API->>DB: 查询解析结果
+    API-->>User: 返回完整结果
+```

后端源码/yifan.action-ai.cn/api/docs/业务逻辑.md

@@ -0,0 +1,278 @@
+# FastAPI Admin 业务逻辑
+
+## 1. 项目概述
+
+FastAPI Admin 是一个基于 FastAPI 构建的企业级后台管理系统框架，提供完整的 RBAC 权限控制体系、多租户架构支持、任务调度系统和日志监控功能。
+
+## 2. 技术架构
+
+### 2.1 核心技术栈
+
+| 技术 | 版本 | 说明 |
+|------|------|------|
+| FastAPI | 0.115.2 | 现代 Web 框架 |
+| SQLAlchemy | 2.0.36 | ORM 框架 |
+| Alembic | 1.15.1 | 数据库迁移工具 |
+| Pydantic | 2.x | 数据验证与序列化 |
+| APScheduler | 3.11.0 | 定时任务调度 |
+| Redis | 5.2.1 | 缓存与会话存储 |
+| Uvicorn | 0.30.6 | ASGI 服务器 |
+| Python | 3.10+ | 运行环境 |
+
+### 2.2 多数据库支持
+
+- MySQL
+- PostgreSQL
+- SQLite
+
+### 2.3 架构设计
+
+采用经典的 MVC 分层架构：
+
+```sh
+📦 分层架构 (MVC)
+├── 🎯 Controller   # 控制器层 - 处理HTTP请求
+├── 🏢 Service      # 业务层 - 核心业务逻辑
+├── 💾 CRUD         # 数据访问层 - 数据库操作
+└── 📊 Model        # 模型层 - 数据模型定义
+```
+
+## 3. 核心业务模块
+
+### 3.1 系统管理模块 (module_system)
+
+#### 3.1.1 用户管理
+
+- 支持不同类型用户：系统用户、租户管理员、租户普通用户、客户用户
+- 实现用户与角色、岗位的多对多关联
+- 提供用户状态管理、密码重置等功能
+
+#### 3.1.2 角色管理
+
+- 完整的 RBAC 权限体系
+- 支持菜单权限和数据权限双重控制
+- 自定义数据权限范围设置
+
+#### 3.1.3 菜单管理
+
+- 树形菜单结构设计
+- 支持目录、菜单、按钮/权限三种类型
+- 系统级菜单与租户级菜单隔离
+
+#### 3.1.4 部门管理
+
+- 树形部门结构
+- 支持无限层级嵌套
+- 部门负责人设置
+
+#### 3.1.5 租户管理
+
+- 多租户 SaaS 架构
+- 租户数据完全隔离
+- 系统租户管理所有普通租户
+
+#### 3.1.6 客户管理
+
+- 租户内部的二级业务单元
+- 客户数据隔离
+- 客户用户权限控制
+
+### 3.2 系统监控模块 (module_monitor)
+
+- 操作日志记录与查询
+- 系统资源监控
+- 性能指标统计
+
+### 3.3 AI 功能模块 (module_ai)
+
+- OpenAI 大模型集成
+- AI 辅助功能
+
+### 3.4 定时任务模块 (module_task)
+
+- 基于 APScheduler 的任务调度
+- 支持多种任务类型
+- 任务执行日志记录
+
+## 4. 数据模型与关系
+
+### 4.1 核心数据模型
+
+#### 4.1.1 UserModel (用户模型)
+
+- 表名：`sys_user`
+- 关键字段：
+  - username: 用户名/登录账号
+  - name: 昵称
+  - user_type: 用户类型(0:系统用户 1:租户用户 2:客户用户)
+  - dept_id: 所属部门
+
+#### 4.1.2 RoleModel (角色模型)
+
+- 表名：`sys_role`
+- 关键字段：
+  - name: 角色名称
+  - code: 角色编码
+  - data_scope: 数据权限范围(1:仅本人 2:本部门 3:本部门及以下 4:全部 5:自定义)
+
+#### 4.1.3 MenuModel (菜单模型)
+
+- 表名：`sys_menu`
+- 关键字段：
+  - name: 菜单名称
+  - type: 菜单类型(1:目录 2:菜单 3:按钮/权限 4:链接)
+  - permission: 权限标识
+  - route_path: 路由路径
+  - parent_id: 父菜单ID
+
+#### 4.1.4 DeptModel (部门模型)
+
+- 表名：`sys_dept`
+- 关键字段：
+  - name: 部门名称
+  - code: 部门编码
+  - leader: 部门负责人
+  - parent_id: 父级部门ID
+
+### 4.2 关联关系表
+
+#### 4.2.1 UserRolesModel (用户角色关联)
+
+- 表名：`sys_user_roles`
+- 关键字段：user_id, role_id
+
+#### 4.2.2 RoleMenusModel (角色菜单关联)
+
+- 表名：`sys_role_menus`
+- 关键字段：role_id, menu_id
+
+#### 4.2.3 RoleDeptsModel (角色部门关联)
+
+- 表名：`sys_role_depts`
+- 关键字段：role_id, dept_id
+
+#### 4.2.4 UserPositionsModel (用户岗位关联)
+
+- 表名：`sys_user_positions`
+- 关键字段：user_id, position_id
+
+## 5. 数据隔离与权限体系
+
+### 5.2 数据权限机制
+
+#### 5.2.1 权限范围定义
+
+- 1(仅本人): `WHERE created_id = current_user.id`
+- 2(本部门): `WHERE user.dept_id = current_user.dept_id`
+- 3(本部门及以下):
+- 4(全部数据):
+- 5(自定义): `WHERE dept_id IN (SELECT dept_id FROM role_depts WHERE role_id IN current_user.role_ids)`
+
+#### 5.2.2 权限叠加规则
+
+- 一个用户可以有多个角色
+- 取所有角色data_scope的最大值(4>3>2>5>1)
+- 5(自定义)需要合并所有角色关联的部门
+
+## 6. 核心业务流程
+
+### 6.1 用户登录流程
+
+1. 用户提交用户名密码
+2. 系统验证用户凭据
+3. 加载用户角色和权限信息
+4. 生成JWT Token
+5. 返回用户信息和权限列表
+
+### 6.2 权限验证流程
+
+1. 用户请求受保护的API接口
+2. 中间件验证JWT Token
+3. 加载用户权限列表
+4. 验证用户是否拥有该接口的权限
+5. 根据数据权限过滤查询结果
+
+### 6.3 数据权限过滤流程
+
+1. 获取当前用户角色的data_scope
+2. 根据data_scope构建SQL过滤条件
+3. 将过滤条件应用到数据库查询
+4. 返回符合权限要求的数据
+
+## 7. 特色功能
+
+### 7.1 智能代码生成
+
+- 基于模板的代码生成工具
+- 支持模型、CRUD、API接口等自动生成
+- 提高开发效率
+
+### 7.2 AI 集成
+
+- OpenAI 大模型调用接口
+- 支持在管理系统中集成AI功能
+
+### 7.3 云存储支持
+
+- 阿里云 OSS 对象存储集成
+- 支持文件上传、下载、管理
+
+### 7.4 任务调度系统
+
+- 基于APScheduler的定时任务
+- 支持多种调度策略
+- 任务执行状态监控
+
+## 8. 系统安全
+
+### 8.1 认证与授权
+
+- JWT Token认证
+- 细粒度的RBAC权限控制
+- 密码加密存储(bcrypt)
+
+### 8.2 数据安全
+
+- 多级别数据隔离
+- 操作日志记录
+- 敏感数据加密存储
+
+### 8.3 接口安全
+
+- 请求参数验证(Pydantic)
+- 接口限流保护
+- CORS配置管理
+
+## 9. 部署与维护
+
+### 9.1 环境要求
+
+- Python 3.10+
+- 数据库: MySQL 8.0+ / PostgreSQL 13+ / SQLite 3.x
+- Redis 6.0+
+
+### 9.2 数据库迁移
+
+- 使用Alembic管理数据库版本
+- 支持多数据库平台迁移
+- 提供初始化脚本
+
+### 9.3 日志系统
+
+- 操作日志记录
+- 系统日志监控
+- 异常记录与告警
+
+## 10. 扩展开发
+
+### 10.1 模块扩展
+
+- 标准化的模块开发流程
+- 支持自定义业务模块
+- 插件化架构设计
+
+### 10.2 数据模型扩展
+
+- 基于SQLAlchemy 2.0的声明式模型
+- 支持模型继承与混入
+- 兼容多数据库平台