|
|
@@ -1,200 +1,230 @@
|
|
|
-# 知行益家 (ZXYJ) - 家庭教育任务管理小程序
|
|
|
+# 浠艾福 (XAF) - 家庭教育服务平台
|
|
|
|
|
|
## 项目简介
|
|
|
|
|
|
-知行益家是一款家庭教育任务管理小程序，通过积分奖励机制激励孩子自主完成任务，培养时间管理和延迟满足能力。支持家长端、孩子端、成长规划师（Web端）三端使用。
|
|
|
+浠艾福是一个三方平台型家庭教育服务系统，连接**客户（家长）**、**服务商（成长规划师/活动方/供应商）** 和**平台运营**三方角色。家长为孩子（附属用户）购买成长规划服务，服务商交付任务下发、测评、成长档案等专业服务，平台提供撮合与运营管理。
|
|
|
|
|
|
-## 技术栈
|
|
|
+**技术栈：** Java 8 + Spring Boot 2.7.18 + MyBatis-Plus / uni-app Vue 2 小程序 / Vue 2 + Element UI Web管理端
|
|
|
|
|
|
-| 层级 | 技术 |
|
|
|
-|------|------|
|
|
|
-| 后端 | Java 1.8 + Spring Boot 2.7.18 + MyBatis-Plus |
|
|
|
-| 前端小程序 | uni-app (Vue 2) |
|
|
|
-| Web管理端 | Vue 2 + Element UI |
|
|
|
-| 数据库 | MySQL 8.0 |
|
|
|
-| 认证 | JWT |
|
|
|
-| 文档 | Swagger 3.0 |
|
|
|
+---
|
|
|
+
|
|
|
+## 业务模型
|
|
|
+
|
|
|
+```
|
|
|
+客户（家长）──消费──→ 服务商（规划师/活动方/供应商）
|
|
|
+ │ │
|
|
|
+ │ 授权监护 │ 交付服务
|
|
|
+ ▼ ▼
|
|
|
+ 附属（孩子）─────执行任务/接受服务────
|
|
|
+
|
|
|
+ 平台运营（管理员）── 审核 · 配置 · 数据支撑 ──→ 全链路
|
|
|
+```
|
|
|
+
|
|
|
+| 业务角色 | 系统角色 | 说明 |
|
|
|
+|---------|---------|------|
|
|
|
+| **客户** | `parent` | 付费决策者，管理家庭、审批任务、消费服务 |
|
|
|
+| **客户附属** | `child` | 无独立行为能力，在家长监护下执行任务、接受服务 |
|
|
|
+| **服务商** | `teacher` / `vendor_type` | 成长规划师、活动规划师、商品供应商等 |
|
|
|
+| **平台运营** | `admin` | 审核、系统配置、数据管理 |
|
|
|
+
|
|
|
+---
|
|
|
|
|
|
## 项目结构
|
|
|
|
|
|
```
|
|
|
cfc/
|
|
|
-├── cfc-backend/ # Java后端服务
|
|
|
-│ ├── src/main/java/com/etotem/cfc/
|
|
|
-│ │ ├── controller/ # REST API (按功能分组)
|
|
|
-│ │ │ ├── admin/ # 管理端接口
|
|
|
-│ │ │ ├── auth/ # 认证接口
|
|
|
-│ │ │ ├── guide/ # 成长规划师接口
|
|
|
-│ │ │ ├── task/ # 任务接口
|
|
|
-│ │ │ ├── reward/ # 奖励接口
|
|
|
-│ │ │ └── assessment/ # DAN评估接口
|
|
|
-│ │ ├── service/ # 业务逻辑
|
|
|
-│ │ ├── mapper/ # MyBatis Mapper
|
|
|
-│ │ ├── entity/ # 数据实体
|
|
|
-│ │ ├── dto/ # 数据传输对象
|
|
|
-│ │ └── config/ # 配置类
|
|
|
-│ └── src/main/resources/
|
|
|
-│ ├── application.yml # 配置文件
|
|
|
-│ └── schema.sql # 数据库初始化
|
|
|
+├── cfc-backend/ # Spring Boot 后端
|
|
|
+│ └── src/main/java/com/etotem/cfc/
|
|
|
+│ ├── controller/ # 48 个控制器，按 15 个功能子包分组
|
|
|
+│ │ ├── admin/ # 运营管理（管理员）
|
|
|
+│ │ ├── guide/ # 服务商（规划师）服务
|
|
|
+│ │ ├── auth/ # 认证
|
|
|
+│ │ ├── family/ # 家庭管理
|
|
|
+│ │ ├── task/ # 任务
|
|
|
+│ │ ├── growth/ # 成长档案
|
|
|
+│ │ ├── assessment/ # 测评预约/订单
|
|
|
+│ │ ├── reward/ | wish/ # 心愿/奖励
|
|
|
+│ │ ├── sncp/ # 社区
|
|
|
+│ │ ├── market/ | product/ # 商城/商品
|
|
|
+│ │ ├── vendor/ # 服务商入驻
|
|
|
+│ │ └── ... # payment, stats, streak 等
|
|
|
+│ ├── service/ # 业务逻辑层
|
|
|
+│ ├── entity/ # MyBatis-Plus 实体
|
|
|
+│ ├── mapper/ # MyBatis-Plus Mapper
|
|
|
+│ ├── dto/ # 数据传输对象
|
|
|
+│ ├── config/ # JWT / 多数据源 / 数据库初始化
|
|
|
+│ └── common/ # Result / JwtUtil
|
|
|
│
|
|
|
-├── cfc-frontend/ # 微信小程序前端
|
|
|
-│ ├── pages/ # 页面组件
|
|
|
-│ │ ├── index/ # 首页（角色分流）
|
|
|
-│ │ ├── parent/ # 家长端
|
|
|
-│ │ ├── child/ # 孩子端
|
|
|
-│ │ ├── teacher/ # 成长规划师端
|
|
|
-│ │ ├── assessment/ # DAN评估
|
|
|
-│ │ └── tasks/ # 任务相关
|
|
|
-│ ├── utils/ # 工具函数
|
|
|
-│ └── pages.json # 页面注册
|
|
|
+├── cfc-frontend/ # uni-app 微信小程序（~50 页面）
|
|
|
+│ ├── pages/ # 页面组件
|
|
|
+│ │ ├── index/ # 角色分流首页（parent-index / child-index / teacher-index）
|
|
|
+│ │ ├── parent/ # 客户（家长）端
|
|
|
+│ │ ├── child/ # 附属（孩子）端
|
|
|
+│ │ ├── teacher/ | guide/ # 服务商（规划师）端
|
|
|
+│ │ ├── assessment/ | growth/ # 测评 / 成长档案
|
|
|
+│ │ ├── tasks/ | rewards/ | wishes/# 任务 / 心愿
|
|
|
+│ │ ├── games/ # 小游戏（舒尔特/猜数字/数独）
|
|
|
+│ │ ├── discover/ | shop/ # 发现 / 商城（TabBar）
|
|
|
+│ │ ├── vendor/ # 服务商入驻
|
|
|
+│ │ └── profile/ | login/ # 个人 / 登录
|
|
|
+│ ├── components/ # 可复用组件（地址选择器、PlayfulButton、wuxing-sandbox 等）
|
|
|
+│ ├── store/ # Vuex 角色状态管理
|
|
|
+│ ├── pages.json # 页面注册（4 TabBar）
|
|
|
+│ └── uni.scss # 设计 Token 体系
|
|
|
│
|
|
|
-├── cfc-web/ # Web管理端
|
|
|
+├── cfc-web/ # Vue 2 + Element UI Web 管理端（29 页面）
|
|
|
│ └── src/
|
|
|
-│ ├── views/ # 页面组件
|
|
|
-│ ├── api/ # API调用
|
|
|
-│ └── router/ # 路由配置
|
|
|
+│ ├── views/ # admin/* + teacher/*
|
|
|
+│ ├── router/ # 角色权限守卫路由
|
|
|
+│ └── store/ # 认证状态
|
|
|
│
|
|
|
-└── docs/ # 项目文档
|
|
|
- ├── 需求分析/ # 需求分析文档
|
|
|
- ├── 系统设计/ # 系统设计文档
|
|
|
- └── 系统测试/ # 测试文档
|
|
|
+├── docs/ # 需求 / 设计 / 测试文档
|
|
|
+├── tests/ # 分层测试（unit / integration / e2e）
|
|
|
+└── .opencode/ # AI 开发工具配置 + 角色定义
|
|
|
```
|
|
|
|
|
|
+---
|
|
|
+
|
|
|
## 快速开始
|
|
|
|
|
|
-### 1. 环境准备
|
|
|
+### 环境要求
|
|
|
|
|
|
-- JDK 1.8+
|
|
|
-- Maven 3.6+
|
|
|
-- MySQL 8.0+
|
|
|
-- Node.js 14+ (前端开发)
|
|
|
-- 微信开发者工具
|
|
|
+- JDK 1.8+ / Maven 3.6+ / MySQL 8.0+
|
|
|
+- Node.js 14+ / 微信开发者工具
|
|
|
|
|
|
-### 2. 数据库初始化
|
|
|
+### 启动
|
|
|
|
|
|
```bash
|
|
|
-mysql -u root -p
|
|
|
-CREATE DATABASE cfc CHARACTER SET utf8mb4;
|
|
|
-
|
|
|
-# 执行初始化脚本
|
|
|
+# 1. 数据库
|
|
|
+mysql -u root -p -e "CREATE DATABASE cfc CHARACTER SET utf8mb4"
|
|
|
mysql -u root -p cfc < cfc-backend/src/main/resources/schema.sql
|
|
|
-```
|
|
|
-
|
|
|
-### 3. 启动后端
|
|
|
|
|
|
-```bash
|
|
|
+# 2. 后端
|
|
|
cd cfc-backend
|
|
|
mvn clean install
|
|
|
-mvn spring-boot:run
|
|
|
-```
|
|
|
-
|
|
|
-### 4. 启动小程序前端
|
|
|
+mvn spring-boot:run # localhost:8080
|
|
|
|
|
|
-```bash
|
|
|
+# 3. 小程序
|
|
|
cd cfc-frontend
|
|
|
npm install
|
|
|
npm run dev:mp-weixin
|
|
|
-```
|
|
|
|
|
|
-### 5. 启动Web管理端
|
|
|
-
|
|
|
-```bash
|
|
|
+# 4. Web 管理端
|
|
|
cd cfc-web
|
|
|
npm install
|
|
|
-npm run serve
|
|
|
+npm run serve # localhost:8082
|
|
|
```
|
|
|
|
|
|
-### 6. 访问API文档
|
|
|
+---
|
|
|
|
|
|
-启动后端后，访问：http://localhost:8080/swagger-ui.html
|
|
|
+## 核心功能模块
|
|
|
|
|
|
-## 核心功能
|
|
|
+| 模块 | 功能 | 客户 | 附属 | 服务商 | 运营 |
|
|
|
+|------|------|:----:|:----:|:------:|:----:|
|
|
|
+| **认证** | 微信/手机登录、角色切换 | ● | ● | ● | — |
|
|
|
+| **家庭** | 家庭创建、成员邀请、解绑 | ● | ○ | ○ | ● |
|
|
|
+| **任务** | 创建/下发、执行（含小游戏）、审核 | ● | ● | ● | ● |
|
|
|
+| **积分** | 余额、流水、手动调整 | ● | ● | — | ● |
|
|
|
+| **心愿** | 创建心愿、兑换、审批 | ● | ● | — | ● |
|
|
|
+| **测评** | 预约、支付、结果录入、报告 | ● | ● | ● | ● |
|
|
|
+| **成长档案** | 成长记录、成长计划 | ● | ● | ● | — |
|
|
|
+| **套餐市场** | 浏览、购买、服务套餐 | ● | — | ● | ● |
|
|
|
+| **消息** | 客户→服务商沟通 | ● | — | ● | — |
|
|
|
+| **小游戏** | 舒尔特方格/猜数字/数独 | — | ● | — | — |
|
|
|
+| **商城** | 商品/服务浏览购买 | ● | ● | ● | ● |
|
|
|
+| **运营管理** | 审核/配置/数据迁移 | — | — | — | ● |
|
|
|
|
|
|
-### 已完成
|
|
|
-
|
|
|
-| 功能 | 说明 |
|
|
|
-|------|------|
|
|
|
-| ✅ 用户认证 | 微信登录、手机验证码登录、JWT认证 |
|
|
|
-| ✅ 任务管理 | 创建、执行、审核任务，支持小游戏类任务 |
|
|
|
-| ✅ 积分系统 | 完成任务获积分、超时扣分、积分流水 |
|
|
|
-| ✅ 奖励体系 | 心愿单、兑换、审批流程 |
|
|
|
-| ✅ 双角色切换 | 家长模式/孩子模式即时切换 |
|
|
|
-| ✅ 成长规划师 | 套餐管理、家庭绑定、任务下发、DAN评估 |
|
|
|
-| ✅ 小游戏任务 | 舒尔特方格、猜数字、数独 |
|
|
|
-| ✅ 评估预约 | DAN评估预约、订单管理 |
|
|
|
+---
|
|
|
|
|
|
## 角色系统
|
|
|
|
|
|
-- **家长端**：管理孩子、创建任务、审批奖励、查看进度
|
|
|
-- **孩子端**：执行任务、完成任务、兑换奖励
|
|
|
-- **成长规划师**：服务家庭、创建套餐、下发任务、DAN评估
|
|
|
-
|
|
|
-## API接口（按模块）
|
|
|
+### 客户（家长） `role=parent`
|
|
|
+管理家庭、创建审批任务、购买套餐、预约测评、管理孩子账号、审批心愿兑换。
|
|
|
|
|
|
-### 认证模块
|
|
|
+### 客户附属（孩子） `role=child`
|
|
|
+在家长监护下执行任务、玩小游戏、兑换心愿、查看成长报告。不具备独立行为能力。
|
|
|
|
|
|
-| 接口 | 方法 | 说明 |
|
|
|
-|------|------|------|
|
|
|
-| /api/auth/phone-login | POST | 手机验证码登录 |
|
|
|
-| /api/auth/wechat-login | POST | 微信登录 |
|
|
|
-| /api/user/info | POST | 获取用户信息 |
|
|
|
+### 服务商 `role=teacher` / `vendor_type`
|
|
|
+- **成长规划师** `teacher`：创建套餐、绑定家庭、下发任务、录入测评结果
|
|
|
+- **活动规划师 / 活动服务商 / 商品供应商** `vendor_type`：商品管理、订单处理
|
|
|
|
|
|
-### 任务模块
|
|
|
+### 平台运营 `role=admin`
|
|
|
+用户管理、家庭管理、审核入驻/套餐/商品、系统配置、数据迁移、操作日志。
|
|
|
|
|
|
-| 接口 | 方法 | 说明 |
|
|
|
-|------|------|------|
|
|
|
-| /api/tasks/create | POST | 创建任务 |
|
|
|
-| /api/tasks/complete | POST | 完成任务 |
|
|
|
-| /api/tasks/review | POST | 审核任务 |
|
|
|
-| /api/tasks/minigame-options | POST | 获取小游戏列表 |
|
|
|
+---
|
|
|
|
|
|
-### 奖励模块
|
|
|
+## API 接口概览
|
|
|
|
|
|
-| 接口 | 方法 | 说明 |
|
|
|
-|------|------|------|
|
|
|
-| /api/rewards/create | POST | 创建奖励 |
|
|
|
-| /api/rewards/approve | POST | 审批奖励 |
|
|
|
-| /api/rewards/exchange | POST | 兑换奖励 |
|
|
|
+| 模块 | 控制器 | 端点 |
|
|
|
+|------|--------|------|
|
|
|
+| 认证 | `AuthController` | `/api/auth/*` — 登录/注册/切换角色 |
|
|
|
+| 家庭 | `FamilyController` | `/api/family/*` — 邀请码/绑定 |
|
|
|
+| 任务 | `TaskController` | `/api/tasks/*` — CRUD/审核/小游戏 |
|
|
|
+| 心愿 | `WishController` | `/api/wishes/*` — 创建/审批/兑换 |
|
|
|
+| 测评 | `AssessmentOrderController` | `/api/assessment/order/*` — 订单/支付 |
|
|
|
+| 测评 | `AssessmentAppointmentController` | `/api/assessment/appointment/*` — 预约/确认 |
|
|
|
+| 成长 | `GrowthRecordController` | `/api/growth/*` — 记录/外部同步 |
|
|
|
+| 服务商 | `GuideController` | `/api/guide/*` — 入驻/套餐/邀请 |
|
|
|
+| 服务商 | `GuideFamilyTaskController` | `/api/guide/families/*` — 任务下发/批量审核 |
|
|
|
+| 商城 | `ProductController` | `/api/product/*` — 商品/订单 |
|
|
|
+| 服务商入驻 | `VendorController` | `/api/vendor/*` — 申请/状态 |
|
|
|
+| 运营 | `AdminController` | `/api/admin/*` — 审核/用户/配置 |
|
|
|
+| 运营 | `AdminGuideController` | `/api/admin/guide/*` — 规划师审核 |
|
|
|
+| 运营 | `AdminPackageController` | `/api/admin/packages/*` — 套餐审核 |
|
|
|
|
|
|
-### 成长规划师模块
|
|
|
+完整 API 清单见后端 Swagger 文档（启动后访问 `http://localhost:8080/swagger-ui.html`）。
|
|
|
|
|
|
-| 接口 | 方法 | 说明 |
|
|
|
-|------|------|------|
|
|
|
-| /api/guide/package/create | POST | 创建套餐 |
|
|
|
-| /api/guide/families | POST | 绑定家庭列表 |
|
|
|
-| /api/guide/task/create | POST | 下发任务 |
|
|
|
-| /api/guide/assessment/enable | POST | 启用家庭评估 |
|
|
|
+---
|
|
|
|
|
|
-### 评估模块
|
|
|
+## UI 设计体系
|
|
|
|
|
|
-| 接口 | 方法 | 说明 |
|
|
|
-|------|------|------|
|
|
|
-| /api/assessment/appointment/create | POST | 创建评估预约 |
|
|
|
-| /api/assessment/appointment/confirm | POST | 确认预约 |
|
|
|
-| /api/assessment/record/create | POST | 录入测评结果 |
|
|
|
+小程序前端已完成视觉重设计，建立统一设计 Token 体系：
|
|
|
|
|
|
-## 测试
|
|
|
+| Token | 值 | 用途 |
|
|
|
+|-------|----|------|
|
|
|
+| `--color-primary` | `#F97316` 暖橙 | 主色调 |
|
|
|
+| `--color-accent` | `#0EA5E9` 蓝色 | 辅助色 |
|
|
|
+| `--bg` | `#FFF7ED` 暖白 | 背景色 |
|
|
|
+| `--shadow-clay` | 双阴影 | 儿童端 Claymorphism 卡片 |
|
|
|
+| `--shadow-md` | 单阴影 | 家长端/服务商端扁平卡片 |
|
|
|
|
|
|
-```bash
|
|
|
-cd cfc-backend
|
|
|
-mvn test
|
|
|
-```
|
|
|
+**已重设计页面（6页）：** 客户首页、客户任务、客户心愿、家长首页、审批任务、五行能量沙盘组件
|
|
|
|
|
|
-测试覆盖：Service层单元测试、集成测试、小游戏任务测试、成长规划师测试
|
|
|
+---
|
|
|
|
|
|
## 开发规范
|
|
|
|
|
|
-- 控制器分组：按功能模块分为 admin, auth, guide, task, reward, assessment
|
|
|
-- 接口规范：统一使用 `@PostMapping`，禁止 `@GetMapping`
|
|
|
-- ORM：使用 MyBatis-Plus 注解
|
|
|
-- 响应包装：统一 `Result<T>` 返回
|
|
|
-- DI注解：使用 `@Resource`，字段名与 Bean Name 一致
|
|
|
+- **接口：** 统一 `@PostMapping`，禁止 `@GetMapping/@PutMapping/@DeleteMapping`
|
|
|
+- **ORM：** MyBatis-Plus `@TableName` + `@TableId`
|
|
|
+- **响应：** 统一 `Result<T>`（code / message / data）
|
|
|
+- **认证：** JWT Bearer Token，`JwtInterceptor` 拦截 `/api/**`（8 个公开路径除外）
|
|
|
+- **DI：** `@Resource`，字段名匹配 Bean Name
|
|
|
+- **角色控制：** 控制器内手动检查 `@RequestAttribute("role")`
|
|
|
+- **小程序限制：** 禁止可选链 `?.`（用 `&&` 替代）、禁止 CSS Grid（用 flexbox）
|
|
|
+- **小程序设计：** Vue 2 Options API，不引入 Composition API
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 数据库
|
|
|
+
|
|
|
+| 配置 | 值 |
|
|
|
+|------|----|
|
|
|
+| 主机 | `192.168.16.251:3306` |
|
|
|
+| 库名 | `cfc` |
|
|
|
+| 账号 | `cfc / cfc@123` |
|
|
|
+| 角色 | `ENUM('parent','child','teacher','admin')` + 多角色字段 `roles` |
|
|
|
+| 次级 | `vendor_type`（`planner` / `activity_provider` / `product_supplier`） |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 小程序信息
|
|
|
|
|
|
-## 开发团队
|
|
|
+- **AppID：** `wx5ba8038ef16fb245`
|
|
|
+- **TabBar：** 首页 / 发现 / 商城 / 我的
|
|
|
+- **自定义 TabBar：** 角色感知（客户/附属/服务商显示不同内容）
|
|
|
|
|
|
-- 需求分析：知行益家项目组
|
|
|
-- 开发：AI辅助开发
|
|
|
+---
|
|
|
|
|
|
## 许可证
|
|
|
|
|
|
-MIT License
|
|
|
+MIT License
|
User