wangys/K12Study
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
Files
4b38a4c952bfa54b081818a345f99b0d151d189f
K12Study/docs/plan/architecture.md
wangys 4b38a4c952 init
2026-04-14 16:27:47 +08:00

8.3 KiB
Raw Blame History

K12Study 首版项目框架规划

Progress

  • 根目录骨架已创建：backend、frontend、app、init/pg
  • backend Maven 多模块目录与基础 POM 已落地
  • gateway、auth、upms、boot-dev、python-ai 首版占位代码已创建
  • init/pg 已按模块拆分，并接入根目录 sys_area.sql
  • 学校租户表命名已修正为 tb_sys_tenant
  • 跨包 DTO、Enums 已收口到对应 api-* 模块
  • Web 端已从 workspace 收敛为单一 React 项目
  • Web 端请求层已切换为原生 fetch 封装
  • 根目录已新增独立 app 微信小程序骨架
  • VS Code docker-dev 双模式已补齐：external 直连外部 PG/Redis，internal 内置 PG/Redis
  • backend Maven 聚合编译、frontend 构建、python-ai 语法校验已通过
  • boot-dev 本地模式烟测已通过，/api/auth/login、/api/upms/routes、/api/actuator/health 可访问
  • 下一步继续补真实持久化、分片路由封装与更完整联调

Summary

  • 根目录固定为：
    • backend
    • frontend
    • app
  • 参考 Tik / urbanLifeline 的模块拆分和基础层组织，但不复用 Dubbo、Vue 和旧业务实现。
  • 首版目标是“可运行骨架”：
    • 后端：Spring Boot + Spring Cloud Gateway + Spring RESTful + JWT + RBAC + MyBatis-Plus + PostgreSQL + Redis
    • Web：单一 React 项目，只保留 api / types / utils / components / dynamic layout / dynamic route
    • App：独立微信小程序骨架
    • AI：独立 Python 服务占位
  • 本地开发采用双模式：
    • 分布式目录与服务边界长期保留
    • boot-dev 聚合模块一键启动主要 Java 能力
  • /api 只属于 gateway 和 boot-dev 的外层上下文，不属于子服务自身前缀。

Key Changes

  • backend 采用 Maven 多模块，固定为：
    • backend/common：common-core、common-web、common-security、common-mybatis、common-redis、common-api
    • backend/apis：api-auth、api-upms、api-ai
    • backend/gateway：统一入口、鉴权、路由、跨域、trace 透传
    • backend/auth：登录、token、当前用户
    • backend/upms：用户、角色、权限、菜单、动态路由元数据、组织与区域基座
    • backend/ai-client：Java 调 Python 的适配层
    • backend/boot-dev：本地聚合启动模块
    • backend/python-ai：独立 Python AI 服务占位
  • 服务通信固定为 REST，不使用 Dubbo
  • 认证固定为 JWT + RBAC
    • gateway 统一验签
    • 下游服务走网关信任模式
  • 数据访问固定为 MyBatis-Plus + PostgreSQL + Redis
    • PostgreSQL 预留分库分表、分区、读写分离扩展位
    • Redis 负责 token、权限缓存、动态路由缓存、热点数据
  • frontend 固定为单一 React 项目：
    • frontend/src/api
    • frontend/src/types
    • frontend/src/utils
    • frontend/src/components
    • frontend/src/layouts
    • frontend/src/router
    • 只保留基础壳与底层能力，不做业务页面堆砌
  • app 固定为根目录独立微信小程序工程：
    • app/src/app.*
    • app/src/pages/*
    • app/src/api
    • app/src/utils
  • boot-dev 本地模式固定策略：
    • 保持和分布式服务同样的模块结构与接口边界
    • 本地可单进程启动
    • 可用一个 PostgreSQL 实例承载所有逻辑分片，但字段、路由键、表结构必须与未来分布式模式一致

Region / Tenant Model

  • 系统是“总校 -> 省级分校 -> 市区分校”的多层级租户结构
  • 每个校区下再有部门，当前部门维度至少支持“年级、学科”等业务组织
  • 区域是分库分表的核心路由维度：
    • 以“省份区域”作为首要分片依据
    • 业务表设计时必须显式保留区域路由字段
  • sys_area.sql 视为区域基础数据来源约束：
    • 首版必须预留 sys_area 基础表和初始化脚本接入位
    • 区域编码、层级、父子关系以 sys_area.sql 为准
  • 首版数据模型明确区分两棵树：
    • 区域树：省 / 市 / 区县
    • 组织树：总校 / 分校 / 校区 / 部门
  • 首版 upms 基础对象固定包含：
    • SysArea
    • SysTenant
    • SysDept
    • SysUser
    • SysRole
    • SysPermission
  • 所有租户级业务主表统一预留字段：
    • province_code
    • area_code
    • tenant_id 或 school_id
    • tenant_path
    • dept_id
    • dept_path
  • 路由与隔离规则固定：
    • 区域字段负责数据库路由与物理分片
    • tenant_path / dept_path 负责组织级数据隔离
    • 不允许只靠 dept_path 承担全部多租户职责

Database Init Layout

  • PostgreSQL 初始化脚本固定放在 init 目录下，且按模块独立管理
  • 目录结构固定为类似：
    • init/pg/00_create_db.sql
    • init/pg/01_create_schema.sql
    • init/pg/sys/sys_area.sql
    • init/pg/auth/*.sql
    • init/pg/upms/*.sql
    • init/pg/ai/*.sql
  • 原则固定：
    • 每个模块维护自己的建表 SQL、索引 SQL、初始化数据 SQL
    • 不把所有表混在一个超大 SQL 文件中
    • 公共基础表单独归 sys 或 common 目录
  • sys_area.sql 固定归属：
    • 放在 init/pg/sys/
    • 作为区域基础数据的首批初始化脚本
  • 模块 SQL 的职责边界固定：
    • auth：登录、token、认证相关表
    • upms：用户、角色、权限、菜单、学校租户、部门、区域引用关系
    • ai：AI 调用记录、任务记录、模型配置占位
  • 初始化脚本执行规则固定：
    • 先执行库 / Schema 基础脚本
    • 再执行 sys
    • 再执行各业务模块
    • 各模块内部按 create table -> index -> init data 顺序组织
  • 本地开发模式固定：
    • boot-dev 使用同一套 init/pg 脚本
    • 即使单库启动，也不能做一套“临时简化 SQL”绕过正式字段设计

Public APIs / Interfaces

  • 外部访问前缀固定为：
    • /api/auth/**
    • /api/upms/**
    • /api/actuator/health 或 /actuator/**
  • 子服务内部前缀固定为：
    • auth：/auth/**
    • upms：/upms/**
  • 路由映射固定为：
    • gateway: /api/auth/** -> auth: /auth/**
    • gateway: /api/upms/** -> upms: /upms/**
    • boot-dev 本地聚合模式下同样暴露 /api/auth/**、/api/upms/**
  • 统一响应结构固定为：
    • code
    • message
    • data
    • traceId
  • upms 首版接口能力必须覆盖：
    • 当前用户信息
    • 用户 / 角色 / 权限基座
    • 区域树查询
    • 学校租户树查询
    • 部门树查询
    • 动态路由元数据查询
  • React 动态路由元数据至少包含：
    • id
    • path
    • name
    • component
    • layout
    • children
    • meta
  • Python AI 服务首版只固定：
    • GET /health

VS Code Docker Dev

  • 支持两种开发模式：
    • external：PG、Redis 等直连外部数据库
    • internal：开发容器内部创建 PG、Redis
  • 代码同步方式为 bind mount：
    • 宿主机目录直接挂载到容器工作目录
    • 本地修改会实时反映到容器内
    • 不依赖额外“同步脚本”复制代码

Test Plan

  • backend 根级 Maven 聚合可编译通过
  • backend/boot-dev 可单进程启动，并对外暴露 /api/auth/**、/api/upms/**
  • backend/gateway 可独立启动并完成到 auth、upms 的路由转发
  • JWT 鉴权链路可烟测通过
  • frontend 单项目可完成 install、dev、build
  • React 端可基于 upms 返回的动态路由元数据完成路由挂载
  • app 可用微信开发者工具直接打开骨架工程
  • backend/python-ai 可独立启动并通过 /health
  • PostgreSQL 与 Redis 本地联调配置可跑通
  • SQL 初始化验证必须覆盖：
    • init/pg 下脚本可按顺序执行
    • sys_area.sql 可独立导入
    • auth、upms 模块脚本可独立维护且组合执行无冲突
  • 区域与租户模型最小验证必须覆盖：
    • 区域树可查询
    • 学校租户树可查询
    • 部门树可挂接到学校租户下
    • 带不同 province_code / area_code 的数据写入与查询能走统一路由键封装

Assumptions

  • 不使用 Dubbo
  • 首版不做真实业务页面、不做学生端真实业务、不做真实 AI 推理
  • upms 继续承担首版系统管理中心职责
  • sys_area.sql 是必须接入的区域基础数据脚本，且归档在 init/pg/sys/
  • 部门当前先按“年级、学科等组织维度”建模，不在首版细化更复杂教学组织规则