# 毛球管家

**Repository Path**: pikapi/fur-ball-butler

## Basic Information

- **Project Name**: 毛球管家
- **Description**: 宠物管家
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-09-21
- **Last Updated**: 2026-09-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 毛球管家（maoqiu-guanjia）

「毛球管家」是一个宠物管理系统的单体仓库（monorepo），覆盖 C 端微信小程序与 B 端后台管理，核心业务包括：

- **宠物档案**：多宠物信息管理、证件照、健康记录
- **提醒**：喂养 / 疫苗 / 驱虫 / 就医等周期性提醒
- **记账**：宠物开销流水（配合自定义 tab「记账」）
- **AI 识别**：扫码 / 拍照识别（宠物鼻纹识别等，tab「AI识别」与扫描历史页）

## 界面预览

### 小程序端（microapp）

| 首页 | 宠物档案 | 提醒 | 记账 | AI 识别 |
|---|---|---|---|---|
| ![首页](microapp/docs/images/首页%20Home.png) | ![宠物档案](microapp/docs/images/宠物档案%20Profile.png) | ![提醒](microapp/docs/images/提醒%20Remind.png) | ![记账](microapp/docs/images/记账%20Wallet.png) | ![AI识别](microapp/docs/images/AI识别%20Scan.png) |
| 添加宠物 | 识别历史 | 登录 | 设置 | TabBar |
| ![添加宠物](microapp/docs/images/添加宠物%20AddPet.png) | ![识别历史](microapp/docs/images/识别历史%20ScanHistory.png) | ![登录](microapp/docs/images/登录%20Login.png) | ![设置](microapp/docs/images/设置%20Settings.png) | ![TabBar](microapp/docs/images/TabBar.png) |

### 管理端（pet-frontend）

| 工作台 | 宠物档案 | 提醒管理 | 支出记账 |
|---|---|---|---|
| ![Main](pet-frontend/docs/images/Main.png) | ![管理端宠物档案](pet-frontend/docs/images/管理端%20宠物档案.png) | ![管理端提醒管理](pet-frontend/docs/images/管理端%20提醒管理.png) | ![管理端支出记账](pet-frontend/docs/images/管理端%20支出记账.png) |
| AI 识别记录 | 用户管理 | 全部注册用户 | 角色管理 |
| ![管理端AI识别记录](pet-frontend/docs/images/管理端%20AI识别记录.png) | ![管理端用户管理](pet-frontend/docs/images/管理端%20用户管理.png) | ![全部注册用户](pet-frontend/docs/images/管理端%20全部注册用户.png) | ![管理端角色管理](pet-frontend/docs/images/管理端%20角色管理.png) |
| 系统设置 | 表格悬停与筛选 | 账号行操作菜单 | 新增管理账号 |
| ![管理端系统设置](pet-frontend/docs/images/管理端%20系统设置.png) | ![表格悬停与筛选](pet-frontend/docs/images/管理端%20表格悬停与筛选.png) | ![账号行操作菜单](pet-frontend/docs/images/管理端%20账号行操作菜单.png) | ![新增管理账号](pet-frontend/docs/images/管理端%20新增管理账号.png) |
| 编辑账号抽屉 | 新建角色弹窗 | 新建角色选择权限 | 编辑角色弹窗 |
| ![编辑账号抽屉](pet-frontend/docs/images/管理端%20编辑账号抽屉.png) | ![新建角色弹窗](pet-frontend/docs/images/管理端%20新建角色弹窗.png) | ![新建角色选择权限](pet-frontend/docs/images/管理端%20新建角色选择权限.png) | ![编辑角色弹窗](pet-frontend/docs/images/管理端%20编辑角色弹窗.png) |

## 项目结构

```
pet.w/
├── microapp/        # 微信小程序端（C 端）
├── pet-backend/     # 后台服务（Spring Boot，管理端 + 小程序端 API）
├── pet-frontend/    # 后台管理端页面（Vue 3 + TypeScript）
├── docs/            # 项目文档
└── .specify/        # Spec Kit 工作流与宪章（constitution.md）
```

> 当前仓库内 `microapp` 已具雏形；`pet-backend` / `pet-frontend` 按上述约定放置。

## 技术栈

### 小程序端（microapp）

| 项 | 说明 |
|---|---|
| 框架 | 微信原生小程序（无跨端框架） |
| 基础库 | 3.5.5 |
| UI | 自定义 tabBar + 自定义导航栏（`navigationStyle: custom`） |
| 页面 | 首页 / 提醒 / AI识别 / 记账 / 档案，及添加宠物、扫描历史、登录、设置等 |

### 后端（pet-backend）

| 项 | 说明 |
|---|---|
| 语言 / 运行时 | Java 17（JDK 17） |
| 框架 | Spring Boot 3.5.5 |
| ORM | MyBatis-Plus |
| 数据库 | MySQL |
| 缓存 | Redis |

### 后台管理端页面（pet-frontend）

| 项 | 说明 |
|---|---|
| 框架 | Vue 3 + TypeScript |
| 包管理 | pnpm |

## 快速开始

### 小程序端

1. 使用 [微信开发者工具](https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html) 导入 `microapp/` 目录；
2. 在 `microapp/project.config.json` 中配置自己的 AppID（或选择测试号）；
3. 本地调试时如需直连后端，可在开发者工具「详情 → 本地设置」中关闭域名校验（详见 `microapp/project.private.config.json`）。

### 后端

```bash
# 前置：JDK 17、Maven、MySQL 已就绪（Redis 可选）
cd pet-backend
mvn spring-boot:run
```

1. 数据库连接在 `pet-backend/src/main/resources/application.yml` 配置（默认 `127.0.0.1:3306/maoqiu`，库不存在时自动创建，启动时自动执行 `db/schema.sql` 建表与 `db/data.sql` 演示种子数据）；
2. 登录态与验证码存储默认 `memory`（单机开发免 Redis），多实例部署设 `maoqiu.token-store=redis` 切换；
3. 接口前缀约定：小程序端 `/micro/**`，管理端 `/admin/**`；响应统一 `{code, message, data}`，`code=0` 成功、`40100` 登录失效；
4. 一期开发模式：小程序验证码登录固定码 `123456`（`maoqiu.dev-sms-code`）、微信登录 `code` 传 `mock:<openid>` 可直登种子账号、管理端可配 `maoqiu.dev-captcha-answer` 联调口令（默认不启用）；
5. 冒烟脚本：`bash smoke-micro.sh`（小程序端链路）、`bash smoke-admin.sh`（管理端链路，需以 `--maoqiu.dev-captcha-answer=dev1234` 启动）。

### 后台管理端

```bash
cd pet-frontend
pnpm install
pnpm dev      # 本地开发
pnpm build    # 生产构建
```

## 开发约定

- 治理规范：spec / plan 阶段门禁见 [.specify/memory/constitution.md](.specify/memory/constitution.md)（毛球管家宪章）；逐回合编码行为见仓库根 `CLAUDE.md`。
- 需求 → 计划 → 任务 → 实现走 Spec Kit 工作流：`/speckit-specify` → `/speckit-plan` → `/speckit-tasks` → `/speckit-implement`。
- 交付物正文使用简体中文，代码标识符、库名、API 名称、文件路径等专有名词保留英文。
- 提交遵循 [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)，提交信息使用中文。

## 模块状态一览

| 模块 | 状态 |
|---|---|
| microapp 小程序端 | 页面骨架与交互原型进行中（后端 API 已就绪，待前端接入） |
| pet-backend 后端服务 | 一期接口已完成：/micro（登录、档案、提醒、记账、识别、首页）与 /admin（登录、工作台、五大列表），角色权限管理为二期 |
| pet-frontend 后台管理端 | 页面骨架完成（mock 数据），待接入 /admin API |