# 星图-后端

**Repository Path**: app_36/star-map---backend

## Basic Information

- **Project Name**: 星图-后端
- **Description**: flutter_components 同级目录下的独立后端项目（项目名：星图-后端），基于 FastAPI + SQLite，为首页和产线模块提供真实 HTTP 数据接口。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-27
- **Last Updated**: 2026-03-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 星图-后端

`flutter_components` 同级目录下的独立后端项目（项目名：星图-后端），基于 FastAPI + SQLite，为首页和产线模块提供真实 HTTP 数据接口。

## 1. 启动方式

### 1.1 一键脚本启动（推荐）

```bash
cd /Users/hujintao/Desktop/python/ai/flutter_components_backend
chmod +x ./tool/testing/start_backend.sh
./tool/testing/start_backend.sh
```

可选环境变量：
- `HOST`（默认 `0.0.0.0`）
- `PORT`（默认 `8000`）
- `RELOAD`（默认 `1`，设置为 `0` 可关闭热重载）

示例：

```bash
HOST=127.0.0.1 PORT=9000 RELOAD=0 ./tool/testing/start_backend.sh
```

### 1.2 手动启动

```bash
cd /Users/hujintao/Desktop/python/ai/flutter_components_backend
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn main:app --host 0.0.0.0 --port 8000 --reload
```

启动后：
- Swagger: `http://127.0.0.1:8000/docs`
- 根地址: `http://127.0.0.1:8000/`
- SQLite 文件：项目根目录 `flutter_components.db`（首次启动自动建表+初始化数据）

### 1.3 重启服务

开发中若需**先停再起**（例如端口仍被占用）：

```bash
# 查看占用 8000 的进程
lsof -i :8000
# 结束对应 PID 后，再执行 1.1 / 1.2 的启动命令
kill <PID>
```

可选：使用 `nohup` 在后台运行（便于关闭终端后仍保留服务），日志可重定向到文件，例如（请先 `cd` 到本项目根目录）：

```bash
nohup .venv/bin/python -m uvicorn main:app --host 127.0.0.1 --port 8000 --reload > /tmp/flutter_components_backend_uvicorn.log 2>&1 &
```

## 2. 对接 Flutter 端

`flutter_components/assets/.env` 中把 `base_url_debug` 改为：

```env
base_url_debug=http://127.0.0.1:8000/
```

> Flutter 端会自动拼接 `pc-api/` 前缀，因此接口前缀保持 `/pc-api` 即可。

分类、商品列表、产线等读接口请与 Banner **同样传入 `locale`**（`en_US` / `zh_CN`），以便界面语言与文案一致；省略时后端默认 `en_US`。

## 3. 已实现接口（首页 + 产线）

**展示语言 `locale`（统一约定）**  
下列读接口均支持可选 Query **`locale`**：`en_US` | `zh_CN`，**省略时默认为 `en_US`**（分类名、商品标题、产线文案等按该语言输出）；非法值返回 **`400`**。映射表见 `app/core/catalog_locale.py`，与 Banner/热词接口使用同一套 `resolve_home_locale` 校验逻辑。  
涉及接口包括：`/product/pc-get-all-category-by-level`、`/product/second-hp/recommended-rankings`、`/product/second-hp/category-recommended-page-list`、`/product/second-hp/product-rankings-all`、`/product/second-hp/product-rankings-all-category-agg`、`/product/search/search-list`、`/system/tenant/tenantRecommendList`、`/product/production-line/list`（另含首页 Banner、热词、课程展示开关等，见下）。

- `GET /pc-api/product/pc-get-all-category-by-level`
  - 支持 `level`（默认 `1`）。一级分类下挂二级子分类；返回中 `name` 与 **`nameZh`** 与当前 `locale` 展示一致。
- `GET /pc-api/product/second-hp/recommended-rankings`
- `GET /pc-api/product/second-hp/category-recommended-page-list`
  - 常用参数：`pageNo`、`pageSize`、`categoryId`、`keyword`、`type`（默认 `product`）。
  - **`type`（字符串）**：`product` | `supplier`（`tenantId != 1`）| `shop`（`tenantId == 1`）| `production_line`（出现在产线节点中的商品）。
  - 参数约束：`pageNo >= 1`，`1 <= pageSize <= 100`，`type` 非法值返回 `422`。
  - 传**一级 `categoryId`** 时，会包含该分类下**所有子类**的商品（见 `query_products`）。
  - 种子数据中一级分类 `101` 下合计 **20 条**商品，便于 **`pageSize=10` 分两页** 联调。
- `GET /pc-api/product/second-hp/product-rankings-all`
  - **`type`（整数，默认 `6`）**：榜单排序类型，与 Flutter 约定一致（1 新品 … 7 猜您喜欢）。
  - 参数约束：`1 <= type <= 7`，非法值返回 `422`。
- `GET /pc-api/product/second-hp/product-rankings-all-category-agg`
  - 二级分类聚合列表，`type` 影响排序规则，且 `1 <= type <= 7`。
- `GET /pc-api/product/production-line/list`
  - 可选参数：`locale`（见上文统一约定）。
- `GET /pc-api/promotion/banner/list`
  - 可选参数：`locale`（`en_US`/`zh_CN`，默认 `en_US`）。
- `GET /pc-api/product/search/search-box-hot-words`
  - 可选参数：`locale`（`en_US`/`zh_CN`，默认 `en_US`）。
- `GET /pc-api/course/mall-homepage/display`
  - 可选参数：`locale`（`en_US`/`zh_CN`，默认 `en_US`）。

## 4. 管理接口（可维护数据）

- 分类
  - `GET /pc-api/admin/categories`
  - `POST /pc-api/admin/categories`
  - `PUT /pc-api/admin/categories/{category_id}`
  - `DELETE /pc-api/admin/categories/{category_id}`
- 产品
  - `GET /pc-api/admin/products`
  - `POST /pc-api/admin/products`
  - `PUT /pc-api/admin/products/{product_id}`
  - `DELETE /pc-api/admin/products/{product_id}`
- 产线
  - `GET /pc-api/admin/production-lines`
  - `POST /pc-api/admin/production-lines`
  - `PUT /pc-api/admin/production-lines/{line_id}`
  - `DELETE /pc-api/admin/production-lines/{line_id}`
- 首页多语言配置
  - Banner：`GET/POST /pc-api/admin/home/banners`，`PUT/DELETE /pc-api/admin/home/banners/{record_id}`
  - 热词：`GET/POST /pc-api/admin/home/hot-words`，`PUT/DELETE /pc-api/admin/home/hot-words/{record_id}`
  - 展示开关：`GET/POST /pc-api/admin/home/displays`，`PUT/DELETE /pc-api/admin/home/displays/{record_id}`

## 5. 响应结构

与 Flutter 现有 `HKHttpService` 对齐，统一返回：

```json
{
  "code": 0,
  "msg": "success",
  "data": {}
}
```

## 6. 数据库说明

- 使用 SQLite（Python 内置 `sqlite3`），默认文件为项目根目录 **`flutter_components.db`**（已加入 `.gitignore`，本地生成即可）。
- 首次启动时在 `startup` 自动执行：
  - 建表（`CREATE TABLE IF NOT EXISTS ...`）
  - 种子数据初始化（仅当表为空时写入；数据定义见 `app/data/mock_data.py`）
- 若需与种子完全一致（含 20 条一级分类 `101` 商品等），可删除 `flutter_components.db` 后重启服务。

## 7. 分层与目录约定

- 分层依赖方向：`api -> service -> repository -> infrastructure`。
- 目录职责：
  - `app/api/`：路由编排与参数接收。
  - `app/services/`：业务编排与跨仓储逻辑；含首页资源 `home_service`、列表展示本地化 `catalog_locale_service` 等。
  - `app/repository.py`：数据访问与聚合查询。
  - `app/core/`：响应封装、i18n、分类/商品/产线展示文案映射（`catalog_locale`）、枚举/类型归一化等通用能力。
  - `app/data/`：本地 mock/seed 数据源。
  - `app/seed.py`：schema 初始化与种子数据灌入。

## 8. 四段式注释规范

项目核心模块与对外函数采用统一四段式 docstring：

- 功能概述
- 实现思路
- 输入输出
- 注意事项

适用范围：
- `api/service/repository/core` 的对外函数与关键可复用函数。
- 模块入口文件（文件级注释）。

目的：
- 提升可维护性（职责与边界清晰）。
- 提升可测试性（输入输出与异常语义可追踪）。
- 提升可扩展性（扩展点、兼容策略提前显式化）。

## 9. 自动化测试

```bash
cd /Users/hujintao/Desktop/python/ai/flutter_components_backend
python3 -m unittest tests.test_api -v
# 或一键脚本
./tool/testing/run_backend_tests.sh
```

覆盖内容：
- 首页接口可用性（分类、推荐榜单、产线）
- 管理接口 CRUD（分类、产品、产线）
- 首页多语言接口（`locale=en_US/zh_CN`、默认值与非法 locale）
- 展示类读接口非法 `locale` 返回 **`400`**（与 Banner 行为一致）
- 首页查询参数约束（非法分页/非法 type/非法 level 返回 `422`）

说明：
- 测试会临时启动 `127.0.0.1:18000` 的本地服务
- 测试开始前会删除项目根目录下的 `flutter_components.db`（若存在），以保证种子数据完整、分页与分类断言稳定
- 若接口报错，测试断言会输出 HTTP 状态码与响应体，便于排查

## 10. CI（GitHub Actions）

已提供最小 CI 配置文件：`.github/workflows/backend-ci.yml`

- 触发时机：`workflow_dispatch` / `push` / `pull_request`
- Python 版本矩阵：`3.10`、`3.11`
- 执行内容：安装依赖并运行 `./tool/testing/run_backend_tests.sh`