# begin_shop_manage

**Repository Path**: yangsj/begin_shop_manage

## Basic Information

- **Project Name**: begin_shop_manage
- **Description**: No description available
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-18
- **Last Updated**: 2026-06-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Begin Shop Manage

门店商品管理与商品知识库问答系统。基于 FastAPI + MySQL，不使用向量数据库，不使用 embedding。

## 核心流程

1. 维护商品基础信息（名称、描述、发货链接）。
2. 为每个商品维护 Markdown 商品知识库。
3. 用户提问时，系统读取该商品知识库和商品基础信息。
4. 服务按问题做轻量关键词匹配（TF-IDF），筛出相关知识片段。
5. 将"商品知识片段 + 用户问题"交给大模型生成客服回复。

未配置大模型时，接口会返回本地匹配到的知识片段作为兜底，方便调试知识库内容。

## 技术栈

- FastAPI + Uvicorn
- MySQL / PyMySQL
- Pydantic v2
- bcrypt（密码加密）
- Pillow（图形验证码）
- requests（调用大模型 API）

## 快速启动

```bash
pip install -r requirements.txt
cp config.example.yaml config.yaml
mysql -h 127.0.0.1 -u root -p < sql/init.sql
uvicorn app.main:app --reload --port 8080
```

也可以使用启动脚本：

```bash
./scripts/start.sh
```

脚本会后台启动服务，并在前台 `tail -f logs/app.log`。关闭日志跟随后，服务仍会继续运行；服务 PID 写入 `run/app.pid`。

数据库配置支持环境变量覆盖 `config.yaml`：

```bash
DB_USERNAME=root DB_PASSWORD=your_password ./scripts/start.sh
```

也可以在项目根目录创建 `.env`：

```bash
DB_HOST=127.0.0.1
DB_PORT=3306
DB_USERNAME=root
DB_PASSWORD=your_password
DB_NAME=begin_shop_manage
APP_PORT=8080
```

多环境启动支持 `mini`、`mac`、`aliyun`、`win` 四套配置：

```bash
cp .env.mac.example .env.mac
APP_ENV=mac ./scripts/start.sh

cp .env.aliyun.example .env.aliyun
APP_ENV=aliyun ./scripts/start.sh

cp .env.win.example .env.win
APP_ENV=win ./scripts/start.sh
```

每个环境会加载 `.env.<环境名>`，日志写入 `logs/<环境名>.log`，PID 写入 `run/<环境名>.pid`。

访问：

- 管理后台：http://localhost:8080/
- API 文档：http://localhost:8080/docs

默认管理员账号：`admin` / `admin123`

## 内部 API

需要 Bearer Token 鉴权（登录后获取）。

### 用户与认证

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| POST | `/api/users/register` | 注册用户 |
| POST | `/api/users/login` | 登录（需图形验证码） |
| POST | `/api/users/logout` | 退出登录 |
| GET | `/api/captcha` | 获取图形验证码 |
| PUT | `/api/users/password` | 修改密码 |
| PUT | `/api/users/nickname` | 修改昵称 |
| PUT | `/api/users/role` | 修改用户角色（管理员） |
| GET | `/api/users` | 用户列表（管理员） |
| GET | `/api/users/{user_id}` | 用户详情 |

### 商品管理

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| POST | `/api/products` | 创建商品 |
| GET | `/api/products` | 商品列表 |
| GET | `/api/products/{product_id}` | 商品详情 |
| PUT | `/api/products/{product_id}` | 更新商品 |
| DELETE | `/api/products/{product_id}` | 删除商品 |

### 知识库管理

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| POST | `/api/knowledge` | 创建知识文档 |
| GET | `/api/knowledge` | 知识文档列表 |
| GET | `/api/knowledge/{knowledge_id}` | 知识文档详情 |
| PUT | `/api/knowledge/{knowledge_id}` | 更新知识文档 |
| DELETE | `/api/knowledge/{knowledge_id}` | 删除知识文档 |

### 对话与问答

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| POST | `/api/chat` | 商品知识库问答 |
| GET | `/api/chat/delivery-check` | 判断是否为发货请求 |
| GET | `/api/conversations` | 对话记录列表 |
| POST | `/api/conversations` | 创建对话记录 |
| GET | `/api/conversations/session/{session_id}` | 按会话查询对话 |
| POST | `/api/conversations/batch-delete` | 批量删除对话 |
| POST | `/api/conversations/to-knowledge/{conversation_id}` | 对话转知识库 |
| GET | `/api/conversations/knowledge` | 已转知识的对话 |
| GET | `/api/conversations/mock` | 模拟对话测试 |

### 日志

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/api/logs` | 操作日志（管理员，全部） |
| GET | `/api/logs/mine` | 当前用户操作日志 |

### 系统配置（管理员）

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/api/pages` | 页面配置列表 |
| GET | `/api/pages/me` | 当前用户可见页面 |
| PUT | `/api/pages/{page_code}` | 更新页面配置 |
| GET | `/api/roles` | 角色列表 |
| GET | `/api/roles/permissions` | 全部权限列表 |
| GET | `/api/roles/{role_code}/permissions` | 角色权限详情 |
| PUT | `/api/roles/{role_code}/permissions` | 更新角色权限 |
| GET | `/api/prompt-configs` | 提示词配置列表 |
| PUT | `/api/prompt-configs/{config_key}` | 更新提示词配置 |
| GET | `/api/model-configs` | 模型配置列表 |
| PUT | `/api/model-configs/{config_key}` | 更新模型配置 |
| GET | `/api/db/mysql/tables` | 数据库表列表 |
| GET | `/api/db/mysql/tables/{table_name}/schema` | 表结构 |
| GET | `/api/db/mysql/tables/{table_name}/data` | 表数据 |

## 开放 API（三方调用）

无需 Bearer Token，接收 JSON 参数。当前未启用签名验证，后续按需增加。

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| POST | `/openApi/product` | 创建商品 |
| POST | `/openApi/chat` | 商品知识库问答 |

请求示例：

```bash
# 创建商品
curl -X POST http://localhost:8080/openApi/product \
  -H 'Content-Type: application/json' \
  -d '{"user_id":"Uxxx","name":"商品名","description":"描述","delivery_link":""}'

# 知识库问答
curl -X POST http://localhost:8080/openApi/chat \
  -H 'Content-Type: application/json' \
  -d '{"user_id":"Uxxx","product_id":"Pxxx","session_id":"s1","query":"这个问题怎么处理？"}'
```

## 配置

首次启动前，复制 `config.example.yaml` 为 `config.yaml`，按本机环境编辑数据库连接和应用配置：
```yaml
database:
  host: "127.0.0.1"
  port: 3306
  username: "root"
  password: "your_mysql_password"
  database: "begin_shop_manage"
  charset: "utf8mb4"
  pool_size: 10
app:
  host: "0.0.0.0"
  port: 8080
  debug: false
  secret_key: "change-me-in-production"
  cors_origins:
    - "http://127.0.0.1:8080"
    - "http://localhost:8080"
```

- `database`：MySQL 连接信息（必填）。
- `app.secret_key`：JWT 签名密钥，生产环境务必更换。
- `app.cors_origins`：允许的前端跨域来源。
以下配置已迁移到管理后台在线管理（存数据库）：

- **大模型配置**：管理后台 → 模型配置（`config.yaml` 中的 `llm` 为兜底，优先用数据库配置）
- **提示词配置**：管理后台 → 提示词配置
- **页面配置**：管理后台 → 页面配置
- **角色权限**：管理后台 → 角色权限