# xccm-wxapp

**Repository Path**: qfmx/xccm-wxapp

## Basic Information

- **Project Name**: xccm-wxapp
- **Description**: 七分妙夏创造与魔法小程序
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-03
- **Last Updated**: 2026-06-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 创造与魔法攻略助手

基于微信小程序原生框架开发的攻略助手，提供完整的图鉴、配方、炼丹、成就等游戏资料查询功能。仓库内已接入 FastAPI 后端，运行时通过 PostgreSQL 提供只读资料接口。

## 功能特性

### ✅ 已实现功能

- **图鉴手册**：怪物、道具、装备、宠物、食物分类浏览
  - 支持关键词搜索（名称、描述等多字段）
  - 支持稀有度筛选
  - 详情页展示完整属性
  - 宠物融合路线追踪

- **配方系统**：装备打造、食物烹饪、卷轴制作、药剂炼制
  - 按类型和稀有度筛选
  - 材料清单和制作要求
  - 配方详情页

- **炼丹指南**：完整的炼丹配方数据库
  - 按品阶（1-4级）筛选
  - 按类别（修为、体魄、魂魄、特殊、元素、实用）筛选
  - 材料搜索和过滤
  - 炼制条件、成功率、技巧提示
  - 副产物追踪

- **成就系统**：收集探险、生产制造、战斗挑战、BOSS挑战
  - 分类展示成就进度
  - 成就详情和奖励说明

- **宠物融合**：8大融合宠物系列追踪
  - 各阶段形态展示
  - 融合路线可视化
  - 资质数据对比

### 🚧 开发中 / 占位功能

- **地图模块**：资源点交互地图（当前为占位页面）

## 技术栈

- 微信小程序原生框架
- TypeScript 4.9
- Less CSS 预处理器
- WXML / JSON
- npm 包管理
- FastAPI + SQLAlchemy + Alembic（后端）
- PostgreSQL（后端正式数据存储）
- uv（后端 Python 环境管理）

## 环境要求

- Node.js 14+
- npm 6+
- 微信开发者工具
- 小程序基础库：`2.32.3`
- Python 3.11+
- uv
- PostgreSQL（执行数据库迁移和导入脚本时需要）

## 安装与开发

### 小程序

```bash
# 安装依赖
npm install

# TypeScript 类型检查
npx tsc --noEmit

# 项目结构检查
node miniprogram/verify-structure.js
```

### 后端

```bash
cd backend
uv sync

# 启动 FastAPI 服务
uv run uvicorn backend.main:app --reload

# 代码检查和测试
uv run ruff check .
uv run pytest
```

后端接口文档：

```text
http://127.0.0.1:8000/docs
```

健康检查：

```text
http://127.0.0.1:8000/api/health
```

## 运行方式

### 小程序运行

1. 使用微信开发者工具打开项目根目录
2. 确认项目配置文件为 `project.config.json`
3. 点击"编译"运行小程序

> 如果开发者工具出现缓存导致的旧配置问题，执行"工具 → 清缓存 → 清除文件缓存"，然后重新编译。

> **API 地址自动切换**：开发者工具中自动使用 `http://127.0.0.1:8000/api`，真机调试/体验版/正式版自动使用 `https://cm.allms.cn/api`。配置见 `miniprogram/config/api.ts`。

### 后端运行

当前后端接口运行时查询 PostgreSQL。首次启动或资料更新后，需要执行数据库迁移和导入脚本：

```bash
cd backend
copy .env.example .env
uv run alembic upgrade head
uv run python -m backend.scripts.import_miniprogram_data
```

## 项目结构

```
xccm-wxapp/
├── miniprogram/          # 微信小程序源码
│   ├── app.json          # 全局配置
│   ├── app.less          # 全局样式
│   ├── app.ts            # 应用入口
│   ├── model.ts          # 类型定义（统一导出）
│   ├── data/             # 静态资料数据
│   ├── pages/            # 页面
│   ├── components/       # 公共组件
│   └── utils/            # 工具函数
├── backend/              # FastAPI 后端
│   ├── src/backend/
│   │   ├── main.py       # FastAPI 应用入口
│   │   ├── routers/      # 只读资料接口
│   │   ├── models/       # SQLAlchemy 模型
│   │   ├── schemas/      # Pydantic 响应模型
│   │   └── scripts/      # 数据导入脚本
│   ├── alembic/          # 数据库迁移
│   └── tests/            # 后端测试
└── docs/                 # 项目文档
```

## 数据维护

静态资料源文件保留在 `miniprogram/data/`，用于通过导入脚本同步到 PostgreSQL；API 运行时不直接读取这些 JSON 文件：

- `monsters.json` / `monsters.data.ts` - 怪物数据
- `items.json` / `items.data.ts` - 道具数据
- `equipments.json` / `equipments.data.ts` - 装备数据
- `pets.json` / `pets.data.ts` - 宠物数据
- `foods.json` / `foods.data.ts` - 食物数据
- `recipes.json` / `recipes.data.ts` - 配方数据
- `alchemy.json` / `alchemy.data.ts` - 炼丹配方数据
- `fusion-pets.json` / `fusionPets.data.ts` - 宠物融合数据
- `achievements.json` / `achievements.data.ts` - 成就数据

类型定义集中在 `miniprogram/model.ts`，对外统一导出。

## 后端接口

已实现首批只读接口：

- `GET /api/health`
- `GET /api/handbook?type=monster&keyword=&rarity=&page=1&page_size=20`
- `GET /api/handbook/{item_id}`
- `GET /api/recipes?type=&keyword=&rarity=&page=1&page_size=20`
- `GET /api/recipes/{recipe_id}`
- `GET /api/alchemy?tier=&category=&keyword=&material=&page=1&page_size=20`
- `GET /api/alchemy/{pill_id}`
- `GET /api/achievement-guides?category=&difficultyLevel=&recommendation=&keyword=&page=1&page_size=30`
- `GET /api/achievement-guides/{guide_id}`
- `GET /api/fusion-pets?series_id=&priority=&keyword=`
- `GET /api/fusion-pets/{fusion_pet_id}`

## 核心功能说明

### 图鉴搜索

支持按以下字段搜索：
- 怪物：名称、描述、类型、稀有度、等级、位置、技能
- 装备：名称、描述、部位、稀有度、等级
- 宠物：名称、描述、品质、稀有度、进化阶段
- 食物：名称、描述、效果类型、稀有度
- 道具：名称、描述、类型、稀有度

### 炼丹筛选

- **品阶筛选**：一级至四级丹药
- **类别筛选**：修为、体魄、魂魄、特殊、元素、实用、副产物
- **材料过滤**：按所需材料筛选
- **搜索功能**：支持名称、效果、材料搜索

### 宠物融合追踪

- 系列化展示融合路线
- 每阶段形态和资质对比
- 融合材料清单
- 技能列表

## 开发注意事项

- 所有文件必须使用 **无 BOM 的 UTF-8 编码**
- 修改 TypeScript 后建议执行 `npx tsc` 确保 `.js` 文件同步
- WXML 中避免复杂的表达式逻辑
- 样式统一使用 Less，遵循 Sunny UI 设计规范
- 后端 `.env` 不提交，正式小程序请求必须使用 HTTPS 域名并在微信公众平台配置合法请求域名
- 后端接口字段尽量兼容 `miniprogram/model.ts`，减少小程序改造成本

## 版本历史

### v3.1 (当前版本)
- ✅ 我的页面新增头像、昵称、等级徽章
- ✅ 我的页面新增关于我们/版本更新日志
- ✅ 联系我们改为微信客服会话
- ✅ API 配置支持开发者工具本地地址与真机调试线上地址自动切换
- ✅ 修复图鉴/炼金页面箭头图标显示异常（`>` → `›`）

### v3.0
- ✅ 图鉴手册添加搜索功能
- ✅ 页面逻辑重构，统一数据加载入口
- ✅ 炼丹模块完整实现
- ✅ 成就系统完整实现
- ✅ 修复 WXML 标签闭合问题
- ✅ 优化布局稳定性（固定各区域高度）
- ✅ 删除"极品装备"Tab（与装备分类合并）
- ✅ 优化 Tab 栏左对齐和滑动体验
- ✅ 修复装饰元素遮挡文字问题

### v2.0
- ✅ 新增宠物融合系列
- ✅ 新增炼丹系统
- ✅ 新增成就系统
- ✅ 优化 UI 样式（Sunny UI 风格）

### v1.0
- ✅ 基础图鉴功能
- ✅ 配方系统
- ✅ 地图和个人中心占位页面

## 许可证

本项目仅供学习交流使用。