K12Study/docs/plan/architecture.md

# K12Study 首版项目框架规划

## Progress

- [x] 根目录骨架已创建：`backend`、`frontend`、`app`、`init/pg`
- [x] `backend` Maven 多模块目录与基础 POM 已落地
- [x] `gateway`、`auth`、`upms`、`boot-dev`、`python-ai` 首版占位代码已创建
- [x] `init/pg` 已按模块拆分，并接入根目录 `sys_area.sql`
- [x] 学校租户表命名已修正为 `tb_sys_tenant`
- [x] 跨包 DTO、Enums 已收口到对应 `api-*` 模块
- [x] Web 端已从 workspace 收敛为单一 React 项目
- [x] Web 端请求层已切换为原生 `fetch` 封装
- [x] 根目录已新增独立 `app` 微信小程序骨架
- [x] VS Code `docker-dev` 双模式已补齐：`external` 直连外部 PG/Redis，`internal` 内置 PG/Redis
- [x] `backend` Maven 聚合编译、`frontend` 构建、`python-ai` 语法校验已通过
- [x] `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/`
- 部门当前先按“年级、学科等组织维度”建模，不在首版细化更复杂教学组织规则