2026-10-22-org-admin-management-design.md 17 KB

机构/企业组织管理

优先级: P1 预计工时: ~3 天(后端)+ ~2 天(前端 cfc-web) 日期: 2026-10-22 状态: 设计完成


一、背景与目标

随着平台用户规模增长,机构和企业管理员需要有属于自己的入口来查看和管理其组织内的规划师和用户,同时获得针对本组织的统计大屏,而不依赖平台运营员逐条导出。

核心目标:

  1. 平台运营可创建组织(企业/机构),并绑定组织管理员账号
  2. 组织管理员能统一管理组织内规划师和用户成员
  3. 组织管理员拥有一张专属统计大屏,仅展示本组织相关数据
  4. 复用现有 users 体系,新成员无需重新注册

二、用户角色

角色 数据来源 权限范围
平台角色(admin/operator/finance) users.roles 包含 admin 等 可管理所有组织,看全平台数据
组织管理员(org_admin) users.roles 包含 org_admin,organizations.admin_user_id = userId 仅能查看/管理自己所属的组织
组织成员 org_members 表 普通用户或规划师,通过已有登录体系(家长端/规划师端)进入,不额外提供独立登录

三、数据模型

新建表 1: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='机构/企业组织';

新建表 2: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,成员复用现有登录和档案体系
  • 组织管理员独立于 Admin 表:复用 users 表 + roles 字段,新增 org_admin 角色即可,无需为 Admin 表单独加字段
  • 与 SupplySystem 独立:两者互不耦合,Org 管理成长规划师与用户,Supply 管理供应链结算

四、API 接口设计

路由前缀 /api/admin/org/*,由现有 JwtInterceptor 保护;Controller 内手动检查角色。

4.1 组织管理(仅平台角色)

路径 说明 关键参数
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 接口逻辑:

  1. 按 adminPhone 查找已有 users 记录(如有则复用);否则创建新 users 记录
  2. 为新用户设置 roles = ["org_admin"]、role = "org_admin"(单一身份,不叠加其他后台角色)
  3. code 为空时服务端自动生成(ORG + 6 位随机大写字母数字,重试至唯一)
  4. 创建 organizations 记录,admin_user_id 指向该 userId
  5. 返回 organization + adminUser

4.2 组织成员管理(平台角色 + 组织管理员)

路径 说明 权限说明
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:关联的用户ID
  • nickname:昵称
  • 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"
}

4.3 统计大屏(平台角色 + 组织管理员)

路径 说明
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 求和

性能约束(必须遵守)

  • 禁止 per-member 循环查询:所有统计必须先用一次 org_members 查询拿到 user_id 集合,再用 IN (...) 批量查询,由数据库聚合(GROUP BY / COUNT / SUM)
  • 组织规模上限预估 500 成员;超出时先做性能压测再考虑缓存
  • 可选优化:热点统计(overview)加 Redis 缓存,key org:stats:overview:{orgId},TTL 5 分钟;不做缓存也要保证接口 2s 内返回

五、权限规则

5.1 角色定义

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)

5.2 接口鉴权

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 无权限

5.3 排除规则

  • 组织管理员仅能访问 /api/admin/org/** 下与自身组织相关的接口;不能访问用户管理、商品、佣金等其他管理端接口(现有 requirePlatformRole 会拦截,org_admin 不属于平台角色)
  • 成员搜索走组织专属接口 /api/admin/org/user/search,不开放 /api/admin/user/search 给 org_admin
  • 组织停用(status=disabled)后:组织管理员登录管理端仍可进入(token 有效),但访问 /api/admin/org/** 时统一返回"组织已停用",防止数据外露;平台角色不受影响
  • 前端路由守卫:router.beforeEach 中新增逻辑——token 角色含 org_admin 且不含平台角色时,访问 /dashboard 或 /org 列表页自动重定向到其组织的 /org/:id/dashboard;访问其他管理端路由时拦截提示无权限

六、前端设计(cfc-web)

新增页面: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:ss
  • 仅日期场景:截取前 10 位 → yyyy-MM-dd

API 封装

新增 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。


八、涉及模块清单

后端(cfc-backend)

新增文件 说明
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 方法

前端(cfc-web)

新增文件 说明
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 角色分流

八点五、实现顺序与依赖

  1. 后端基础层:Entity → Mapper → DatabaseInitializer + schema.sql → mvn clean compile 验证
  2. AdminRoles 改造:加角色常量/方法(不破坏既有 teacher 等角色登录)
  3. OrganizationService/OrgMemberService:组织 CRUD + 成员管理(含 /api/admin/org/user/search、my-org)
  4. OrgStatsService:5 个统计接口(批量 IN 查询,禁止 N+1)
  5. Controller 鉴权:三个 Controller 统一调 requireOrgAccess(建议抽 common/AdminOrgAccess.java 静态工具类)
  6. 前端:src/api/org.js → 4 页面 → 路由/菜单/Login 分流 → 本地 npm run serve 冒烟

校验方式:每步后端改动后 mvn clean compile;前端改完后 npm run serve 启动页面冒烟(不要求完整跑通)。


九、验收标准

  • mvn clean compile 编译通过
  • 平台角色可创建/编辑/停用组织,可见所有组织
  • 组织管理员登录后自动跳转至自己组织的 Dashboard
  • 组织管理员不可访问其他管理端接口(如 /api/admin/users)
  • 成员列表显示用户昵称/手机脱敏/类型/状态,可搜索和筛选
  • 添加成员后,可在其家庭/订单/任务统计中看到数据归集到该组织
  • 统计大屏各维度数据与后端 DB 查询结果一致
  • 创建组织的 API 响应包含组织信息和管理员账号信息
  • 移除成员后(status=inactive),该成员不再计入统计

十、边界与约束

  • 不引入新的登录体系:成员复用现有 users 登录,仅通过 org_members 表建立归属关系
  • 不修改现有 family/guide 关系:组织管理是独立的关系维度,不影响现有的家庭/规划师层级
  • 平台总览不含组织数据:/api/admin/stats/dashboard 不做改动;组织管理员看到的大屏是其专属视图
  • 组织数据不导出到 C 端小程序:大屏和管理功能仅限管理端(cfc-web)

十一、待确认事项

无。所有设计决策已在讨论阶段确认。