# 浠艾福 (XAF) - 家庭教育服务平台 ## 项目简介 浠艾福是一个三方平台型家庭教育服务系统，连接**客户（家长）**、**服务商（成长规划师/活动方/供应商）** 和**平台运营**三方角色。家长为孩子（附属用户）购买成长规划服务，服务商交付任务下发、测评、成长档案等专业服务，平台提供撮合与运营管理。 **技术栈：** Java 8 + Spring Boot 2.7.18 + MyBatis-Plus / uni-app Vue 2 小程序 / Vue 2 + Element UI Web管理端 --- ## 业务模型 ``` 客户（家长）──消费──→ 服务商（规划师/活动方/供应商） │ │ │ 授权监护 │ 交付服务 ▼ ▼ 附属（孩子）─────执行任务/接受服务──── 平台运营（管理员）── 审核 · 配置 · 数据支撑 ──→ 全链路 ``` | 业务角色 | 系统角色 | 说明 | |---------|---------|------| | **客户** | `parent` | 付费决策者，管理家庭、审批任务、消费服务 | | **客户附属** | `child` | 无独立行为能力，在家长监护下执行任务、接受服务 | | **服务商** | `teacher` / `vendor_type` | 成长规划师、活动规划师、商品供应商等 | | **平台运营** | `admin` | 审核、系统配置、数据管理 | --- ## 项目结构 ``` cfc/ ├── 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/ # 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/ # Vue 2 + Element UI Web 管理端（29 页面） │ └── src/ │ ├── views/ # admin/* + teacher/* │ ├── router/ # 角色权限守卫路由 │ └── store/ # 认证状态 │ ├── docs/ # 需求 / 设计 / 测试文档 ├── tests/ # 分层测试（unit / integration / e2e） └── .opencode/ # AI 开发工具配置 + 角色定义 ``` --- ## 快速开始 ### 环境要求 - JDK 1.8+ / Maven 3.6+ / MySQL 8.0+ - Node.js 14+ / 微信开发者工具 ### 启动 ```bash # 1. 数据库 mysql -u root -p -e "CREATE DATABASE cfc CHARACTER SET utf8mb4" mysql -u root -p cfc < cfc-backend/src/main/resources/schema.sql # 2. 后端 cd cfc-backend mvn clean install mvn spring-boot:run # localhost:8080 # 3. 小程序 cd cfc-frontend npm install npm run dev:mp-weixin # 4. Web 管理端 cd cfc-web npm install npm run serve # localhost:8082 ``` --- ## 核心功能模块 | 模块 | 功能 | 客户 | 附属 | 服务商 | 运营 | |------|------|:----:|:----:|:------:|:----:| | **认证** | 微信/手机登录、角色切换 | ● | ● | ● | — | | **家庭** | 家庭创建、成员邀请、解绑 | ● | ○ | ○ | ● | | **任务** | 创建/下发、执行（含小游戏）、审核 | ● | ● | ● | ● | | **积分** | 余额、流水、手动调整 | ● | ● | — | ● | | **心愿** | 创建心愿、兑换、审批 | ● | ● | — | ● | | **测评** | 预约、支付、结果录入、报告 | ● | ● | ● | ● | | **成长档案** | 成长记录、成长计划 | ● | ● | ● | — | | **套餐市场** | 浏览、购买、服务套餐 | ● | — | ● | ● | | **消息** | 客户→服务商沟通 | ● | — | ● | — | | **小游戏** | 舒尔特方格/猜数字/数独 | — | ● | — | — | | **商城** | 商品/服务浏览购买 | ● | ● | ● | ● | | **运营管理** | 审核/配置/数据迁移 | — | — | — | ● | --- ## 角色系统 ### 客户（家长） `role=parent` 管理家庭、创建审批任务、购买套餐、预约测评、管理孩子账号、审批心愿兑换。 ### 客户附属（孩子） `role=child` 在家长监护下执行任务、玩小游戏、兑换心愿、查看成长报告。不具备独立行为能力。 ### 服务商 `role=teacher` / `vendor_type` - **成长规划师** `teacher`：创建套餐、绑定家庭、下发任务、录入测评结果 - **活动规划师 / 活动服务商 / 商品供应商** `vendor_type`：商品管理、订单处理 ### 平台运营 `role=admin` 用户管理、家庭管理、审核入驻/套餐/商品、系统配置、数据迁移、操作日志。 --- ## API 接口概览 | 模块 | 控制器 | 端点 | |------|--------|------| | 认证 | `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`）。 --- ## UI 设计体系 小程序前端已完成视觉重设计，建立统一设计 Token 体系： | Token | 值 | 用途 | |-------|----|------| | `--color-primary` | `#F97316` 暖橙 | 主色调 | | `--color-accent` | `#0EA5E9` 蓝色 | 辅助色 | | `--bg` | `#FFF7ED` 暖白 | 背景色 | | `--shadow-clay` | 双阴影 | 儿童端 Claymorphism 卡片 | | `--shadow-md` | 单阴影 | 家长端/服务商端扁平卡片 | **已重设计页面（6页）：** 客户首页、客户任务、客户心愿、家长首页、审批任务、五行能量沙盘组件 --- ## 开发规范 - **接口：** 统一 `@PostMapping`，禁止 `@GetMapping/@PutMapping/@DeleteMapping` - **ORM：** MyBatis-Plus `@TableName` + `@TableId` - **响应：** 统一 `Result`（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：** 角色感知（客户/附属/服务商显示不同内容） --- ## 许可证 MIT License