优先级: P1 预计工时: ~3 天(后端)+ ~2 天(前端 cfc-web) 日期: 2026-10-22 状态: 设计完成
随着平台用户规模增长,机构和企业管理员需要有属于自己的入口来查看和管理其组织内的规划师和用户,同时获得针对本组织的统计大屏,而不依赖平台运营员逐条导出。
核心目标:
users 体系,新成员无需重新注册| 角色 | 数据来源 | 权限范围 |
|---|---|---|
| 平台角色(admin/operator/finance) | users.roles 包含 admin 等 |
可管理所有组织,看全平台数据 |
| 组织管理员(org_admin) | users.roles 包含 org_admin,organizations.admin_user_id = userId |
仅能查看/管理自己所属的组织 |
| 组织成员 | org_members 表 |
普通用户或规划师,通过已有登录体系(家长端/规划师端)进入,不额外提供独立登录 |
organizations(组织主表)CREATE TABLE IF NOT EXISTS organizations (
id BIGINT AUTO_INCREMENT PRIMARY KEY,
name VARCHAR(128) NOT NULL COMMENT '组织名称',
type VARCHAR(32) COMMENT 'enterprise/institution/other',
code VARCHAR(64) UNIQUE COMMENT '组织编号(唯一标识)',
admin_user_id BIGINT COMMENT '组织管理员 userId(关联 users.id)',
contact_name VARCHAR(64) COMMENT '联系人姓名',
contact_phone VARCHAR(20) COMMENT '联系人手机号',
description TEXT COMMENT '组织简介',
status VARCHAR(16) DEFAULT 'active' COMMENT 'active/disabled',
created_at DATETIME,
updated_at DATETIME,
INDEX idx_org_admin (admin_user_id),
INDEX idx_org_status (status)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='机构/企业组织';
org_members(组织成员关联表)CREATE TABLE IF NOT EXISTS org_members (
id BIGINT AUTO_INCREMENT PRIMARY KEY,
org_id BIGINT NOT NULL COMMENT '关联 organizations.id',
user_id BIGINT NOT NULL COMMENT '关联 users.id',
member_type VARCHAR(32) NOT NULL COMMENT 'planner/user',
status VARCHAR(16) DEFAULT 'active' COMMENT 'active/inactive',
joined_at DATETIME,
INDEX idx_org_member_org (org_id),
INDEX idx_org_member_user (user_id),
UNIQUE KEY uk_org_member (org_id, user_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='组织成员';
users.id,成员复用现有登录和档案体系users 表 + roles 字段,新增 org_admin 角色即可,无需为 Admin 表单独加字段路由前缀
/api/admin/org/*,由现有JwtInterceptor保护;Controller 内手动检查角色。
| 路径 | 说明 | 关键参数 |
|---|---|---|
POST /api/admin/org/list |
组织列表(分页/筛选) | keyword, type, status, page, size |
POST /api/admin/org/create |
创建组织(同步创建管理员账号) | name, type, code, adminPhone, adminRealName |
POST /api/admin/org/update |
更新组织信息 | id, name, type, contactName, contactPhone, description |
POST /api/admin/org/disable |
停用/启用组织 | id, status |
POST /api/admin/org/detail |
组织详情(含管理员信息) | id |
create 接口逻辑:
adminPhone 查找已有 users 记录(如有则复用);否则创建新 users 记录roles = ["org_admin"]、role = "org_admin"(单一身份,不叠加其他后台角色)code 为空时服务端自动生成(ORG + 6 位随机大写字母数字,重试至唯一)organizations 记录,admin_user_id 指向该 userIdorganization + adminUser| 路径 | 说明 | 权限说明 |
|---|---|---|
POST /api/admin/org/member/list |
成员列表(含简要家庭/任务/订单信息,默认只返回 status=active) |
平台看全量;org_admin 只看自己组织 |
POST /api/admin/org/my-org |
组织管理员获取自己所属的组织(首页跳转目标;停用返回错误) | 无参数,从 JWT 取 userId |
POST /api/admin/org/user/search |
按手机号/昵称搜索平台用户(添加成员时下拉选人用) | 同上 |
POST /api/admin/org/member/add |
添加成员(已存在记录则复活为 active 并更新 memberType) | 同上 |
POST /api/admin/org/member/remove |
移除成员(软删,status=inactive) | 同上 |
POST /api/admin/org/member/change-type |
变更成员类型(planner ↔ user),同时会把 inactive 成员复活为 active | 同上 |
member/list 返回字段说明:
userId:关联的用户IDnickname:昵称phone:手机号(脱敏后显示,如 138****1234)memberType:planner(规划师)或 user(普通用户)joinedAt:加入组织时间familyCount:该成员关联的家庭数(仅计 org_members 直属家庭,不含 teacherFamilyIds 绑定)totalOrders:该成员关联的有效订单总数(仅计 product_orders 状态为 COMPLETED/PAID,buyer_id=userId,不含套餐/包年订单)totalConsumption:该成员关联的消费总额(单位分,product_orders.total_amount 完成订单求和)member/add 参数:
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| orgId | Long | 是 | 目标组织ID |
| userId | Long | 是 | 被添加用户ID |
| memberType | String | 是 | planner / user |
org/user/search 返回字段:
{
"id": 1001,
"nickname": "张三",
"phone": "138****1234",
"avatar": "/static/avatar.jpg",
"memberType": "user",
"status": "active"
}
| 路径 | 说明 |
|---|---|
POST /api/admin/org/stats/overview |
总览卡片:成员总数、规划师数、家庭数、总订单、总消费 |
POST /api/admin/org/stats/families |
家庭维度:活跃家庭数、成员任务完成率、打卡率 |
POST /api/admin/org/stats/active |
活跃度趋势:近30天/7天 任务完成/打卡/报告上传量 |
POST /api/admin/org/stats/revenue |
营收:订单金额/会员订阅/佣金,按时间段分组 |
POST /api/admin/org/stats/trend |
日/周维度趋势图数据(活跃成员数/订单数/收入) |
请求参数(所有 stats 接口): orgId(body 传入)+ 可选 startDate / endDate(仅 date 部分 yyyy-MM-dd,不传默认近 30 天)。
overview(总览卡片)
| 指标 | 口径 |
|---|---|
成员总数 memberCount |
org_members 中 org_id=? AND status='active' 行数 |
规划师数 plannerCount |
同上再加 member_type='planner' |
普通用户数 userCount |
同上再加 member_type='user' |
家庭数 familyCount |
上述成员 user_id 集合 → families.creator_id IN (...) 去重计数 |
总订单数 totalOrders |
上述 user_id 集合 → product_orders 中 buyer_id IN (...) AND status IN ('PAID','COMPLETED') 计数 |
总消费 totalConsumption(分) |
上述 order 集合的 total_amount 总和 |
families(家庭维度)
| 指标 | 口径 |
|---|---|
活跃家庭数 activeFamilyCount |
families.creator_id IN (成员user_id集合) AND updated_at >= 近30天 计数 |
成员任务完成率 taskCompletionRate(%) |
近30天 tasks 中 status='completed' 数 ÷ 同范围 tasks 总数;无分母时返回 0 |
打卡率 checkinRate(%) |
近30天有任意打卡记录(daily_checkin/health_checkins/emotion_checkin)的成员数 ÷ 成员总数 |
active(活跃度,按天分组)
| 指标 | 口径 |
|---|---|
| 任务完成数 | 按 tasks.completed_at 日期分组计数(范围 startDate~endDate,status='completed') |
| 打卡数 | 按 created_at 日期分组,daily_checkin + health_checkin + emotion_checkin 求和 |
| 报告上传数 | 按 created_at 日期分组,dan_report_uploads 计数 |
revenue(营收,按天/周分组)
| 指标 | 口径 |
|---|---|
| 订单金额 | product_orders 中成员相关订单按 paid_at 分组 total_amount 求和(状态 PAID/COMPLETED,成员关联字段 buyer_id) |
| 会员订阅金额 | member_subscription_order 按 created_at 分组 amount 求和(状态已支付) |
| 佣金支出 | commission_records 中受益人属于成员的按 created_at 分组 amount 求和 |
trend(趋势图)
| 指标 | 口径 |
|---|---|
| 活跃成员数 | 当日有任一上述行为(任务/打卡/订单)的成员去重数 |
| 订单数 | 当日 product_orders(PAID/COMPLETED)数 |
| 收入(分) | 当日 order amount 求和 |
org_members 查询拿到 user_id 集合,再用 IN (...) 批量查询,由数据库聚合(GROUP BY / COUNT / SUM)org:stats:overview:{orgId},TTL 5 分钟;不做缓存也要保证接口 2s 内返回AdminRoles 新增 org_admin(组织管理员)到 RESIDENT_ROLES,并补充 roleLabel() 映射 org_admin → 组织管理员。新增工具方法:
/** 判断 roles 是否包含 org_admin */
public static boolean isOrgAdmin(List<String> roles)
/** 判断是否纯组织管理员视角(拥有 org_admin 且不含平台角色) */
public static boolean isOrgAdminOnly(List<String> roles)
requireOrgAccess(orgId, userId, roleObj, rolesObj):
1. 若为平台角色(admin/operator/finance)→ 放行(可指定任意 orgId)
2. 若 roles 含 org_admin:
a. 查 organizations 中 admin_user_id = userId 且 status='active' 的组织(若停用 → 返回"组织已停用")
b. 取该组织的 orgId,与请求中的 orgId 比较,一致 → 放行
3. 否则 → 403 无权限
/api/admin/org/** 下与自身组织相关的接口;不能访问用户管理、商品、佣金等其他管理端接口(现有 requirePlatformRole 会拦截,org_admin 不属于平台角色)/api/admin/org/user/search,不开放 /api/admin/user/search 给 org_admin/api/admin/org/** 时统一返回"组织已停用",防止数据外露;平台角色不受影响router.beforeEach 中新增逻辑——token 角色含 org_admin 且不含平台角色时,访问 /dashboard 或 /org 列表页自动重定向到其组织的 /org/:id/dashboard;访问其他管理端路由时拦截提示无权限src/views/admin/org/| 文件 | 路由 | 说明 |
|---|---|---|
List.vue |
/org |
组织列表(搜索/状态筛选/新建入口) |
Form.vue |
/org/create、/org/:id/edit |
组织信息表单(含管理员账号创建) |
Detail.vue |
/org/:id |
成员管理 Tab(成员列表/添加/移除/改类型) |
Dashboard.vue |
/org/:id/dashboard |
统计大屏(总览卡片 + 家庭/活跃/营收/趋势图) |
在 Layout.vue「系统配置」下新增:
{ path: '/org', label: '组织管理', icon: 'el-icon-office-building', perm: 'system:org' }
组织管理员登录管理端后,自动跳转至自己组织的 Dashboard(/org/:id/dashboard),不展示列表页。跳转链路:Login.vue 登录成功 → 按角色分流 → 检测 roles 含 org_admin 且不含平台角色 → 调 POST /api/admin/org/my-org 拿到自己的组织 → 跳 Dashboard。若组织已停用,则跳转登录页并提示"组织已停用"。
遵循项目统一规范:
t.replace('T', ' ').substring(0, 19) → yyyy-MM-dd HH:mm:ssyyyy-MM-dd新增 src/api/org.js,封装上述所有接口,统一错误处理。
DatabaseInitializer.runMigrations() 新增:
// 迁移N: 创建 organizations 表(组织管理功能)
try {
jdbcTemplate.execute("CREATE TABLE IF NOT EXISTS organizations (...)");
log.info("已创建 organizations 表");
} catch (Exception e) {
// 表已存在,忽略
}
// 迁移N: 创建 org_members 表(组织成员关联)
try {
jdbcTemplate.execute("CREATE TABLE IF NOT EXISTS org_members (...)");
log.info("已创建 org_members 表");
} catch (Exception e) {
// 表已存在,忽略
}
同步更新 schema.sql。
| 新增文件 | 说明 |
|---|---|
entity/Organization.java |
组织实体(@TableName("organizations")) |
entity/OrgMember.java |
组织成员实体(@TableName("org_members")) |
mapper/OrganizationMapper.java |
组织 Mapper |
mapper/OrgMemberMapper.java |
成员 Mapper |
service/OrganizationService.java |
组织 CRUD + getByAdminId + 管理员账号创建 |
service/OrgMemberService.java |
成员管理(add/remove/change-type/list 聚合家庭/订单摘要) |
service/OrgStatsService.java |
统计大屏(5 个口径的批量聚合查询) |
controller/admin/AdminOrgController.java |
组织 CRUD + my-org + user/search |
controller/admin/AdminOrgMemberController.java |
成员管理接口 |
controller/admin/AdminOrgStatsController.java |
统计大屏接口 |
| 修改文件 | 说明 |
|---|---|
config/DatabaseInitializer.java |
新增建表迁移(见第七节) |
resources/schema.sql |
新增两张表的 CREATE TABLE IF NOT EXISTS 语句 |
common/AdminRoles.java |
org_admin 加入 RESIDENT_ROLES;补 roleLabel 映射、isOrgAdmin/isOrgAdminOnly 方法 |
| 新增文件 | 说明 |
|---|---|
src/views/admin/org/List.vue |
组织列表页 |
src/views/admin/org/Form.vue |
组织表单页 |
src/views/admin/org/Detail.vue |
组织详情页(成员管理) |
src/views/admin/org/Dashboard.vue |
统计大页面 |
src/api/org.js |
API 封装 |
| 修改文件 | 说明 |
|---|---|
src/router/index.js |
新增 4 条路由(含 org_admin 守卫分流) |
src/views/Layout.vue |
新增菜单项 + 组织管理员专属菜单显隐 |
src/views/Login.vue |
登录成功后按 org_admin 角色分流 |
mvn clean compile 验证teacher 等角色登录)/api/admin/org/user/search、my-org)IN 查询,禁止 N+1)requireOrgAccess(建议抽 common/AdminOrgAccess.java 静态工具类)src/api/org.js → 4 页面 → 路由/菜单/Login 分流 → 本地 npm run serve 冒烟校验方式:每步后端改动后 mvn clean compile;前端改完后 npm run serve 启动页面冒烟(不要求完整跑通)。
mvn clean compile 编译通过/api/admin/users)users 登录,仅通过 org_members 表建立归属关系/api/admin/stats/dashboard 不做改动;组织管理员看到的大屏是其专属视图无。所有设计决策已在讨论阶段确认。