sql更新、架构更新
This commit is contained in:
@@ -1,205 +0,0 @@
|
||||
# K12Study 首版项目框架规划
|
||||
|
||||
## Progress
|
||||
|
||||
- [x] 根目录骨架已创建：`backend`、`frontend`、`app`、`init/pg`
|
||||
- [x] `backend` Maven 多模块目录与基础 POM 已落地
|
||||
- [x] `gateway`、`auth`、`upms`、`boot-dev`、`python-ai` 首版占位代码已创建
|
||||
- [x] `init/pg` 已按模块拆分，并接入根目录 `tb_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
|
||||
|
||||
- 系统是“总校 -> 省级分校 -> 市区分校”的多层级租户结构
|
||||
- 每个校区下再有部门，当前部门维度至少支持“年级、学科”等业务组织
|
||||
- 区域是分库分表的核心路由维度：
|
||||
- 以“省份区域”作为首要分片依据
|
||||
- 业务表设计时必须显式保留区域路由字段
|
||||
- `tb_sys_area.sql` 视为区域基础数据来源约束：
|
||||
- 首版必须预留 `tb_sys_area` 基础表和初始化脚本接入位
|
||||
- 区域编码、层级、父子关系以 `tb_sys_area.sql` 为准
|
||||
- 首版数据模型明确区分两棵树：
|
||||
- 区域树：省 / 市 / 区县
|
||||
- 组织树：总校 / 分校 / 校区 / 部门
|
||||
- 首版 `upms` 基础对象固定包含：
|
||||
- `SysArea`
|
||||
- `SysTenant`
|
||||
- `SysDept`
|
||||
- `SysUser`
|
||||
- `SysRole`
|
||||
- 所有租户级业务主表统一预留字段：
|
||||
- `adcode`
|
||||
- `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/tb_sys_area.sql`
|
||||
- `init/pg/auth/*.sql`
|
||||
- `init/pg/upms/*.sql`
|
||||
- `init/pg/ai/*.sql`
|
||||
- 原则固定：
|
||||
- 每个模块维护自己的建表 SQL、索引 SQL、初始化数据 SQL
|
||||
- 不把所有表混在一个超大 SQL 文件中
|
||||
- 公共基础表单独归 `sys` 或 `common` 目录
|
||||
- `tb_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` 下脚本可按顺序执行
|
||||
- `tb_sys_area.sql` 可独立导入
|
||||
- `auth`、`upms` 模块脚本可独立维护且组合执行无冲突
|
||||
- 区域与租户模型最小验证必须覆盖：
|
||||
- 区域树可查询
|
||||
- 学校租户树可查询
|
||||
- 部门树可挂接到学校租户下
|
||||
- 带不同 `adcode` 的数据写入与查询能走统一路由键封装
|
||||
|
||||
## Assumptions
|
||||
|
||||
- 不使用 `Dubbo`
|
||||
- 首版不做真实业务页面、不做学生端真实业务、不做真实 AI 推理
|
||||
- `upms` 继续承担首版系统管理中心职责
|
||||
- `tb_sys_area.sql` 是必须接入的区域基础数据脚本，且归档在 `init/pg/sys/`
|
||||
- 部门当前先按“年级、学科等组织维度”建模，不在首版细化更复杂教学组织规则
|
||||
@@ -1,44 +0,0 @@
|
||||
# 课程学习-习题-批改ER与对象类数据流图实施计划
|
||||
问题陈述
|
||||
基于现有《AI智能学习系统功能清单》与现有架构图，在不纳入 AI 实现细节的前提下，先完成“课程学习、习题、批改”三条主链路的抽象建模，产出可直接指导后续代码与数据库落地的模块化 ER 图与对象类数据流图（每模块一个目录、两个 drawio 文件）。
|
||||
## 当前状态（已核实）
|
||||
* 现有 `docs/architecture/数据流图（多角色）.drawio (1-158)` 已定义 P1-P7 过程与 D1-D6 数据存储，但把 AI 处理作为主链路节点之一，需要按新范围裁剪为“无 AI 依赖的批改主链路”。
|
||||
* 现有 `docs/architecture/系统架构与代码架构.drawio (1-260)` 已给出分层和目标服务域（如 homework-content、grading-orchestrator 等），但仓库当前可运行模块仍以骨架为主。
|
||||
* 后端现有聚合模块为 `common/apis/ai-client/auth/upms/gateway/boot-dev`（`backend/pom.xml (13-21)`），尚未落地课程/习题/批改独立业务模块。
|
||||
* 数据库当前已落地的核心表主要是组织权限与认证、AI占位：`init/pg/upms/10_create_upms_tables.sql (1-153)`、`init/pg/auth/10_create_auth_tables.sql (1-56)`、`init/pg/ai/10_create_ai_tables.sql (1-47)`；尚无课程、题库、作业、提交、批改结果等业务实体。
|
||||
* `auth`/`upms` 服务当前仍以示例返回为主（`backend/auth/src/main/java/com/k12study/auth/service/AuthService.java (1-66)`、`backend/upms/src/main/java/com/k12study/upms/service/UpmsQueryService.java (1-111)`），说明本次需要先补齐领域建模图，再推进代码实现。
|
||||
## 目标范围与输出目录
|
||||
* 范围仅覆盖：课程学习、习题（题库/作业/提交）、批改（规则批改+教师复核+结果反馈）。
|
||||
* 明确不纳入：AI 子系统实现细节（OCR/LLM/ASR/模型编排）。
|
||||
* 统一输出根目录：`docs/architecture/modules/`
|
||||
* 每模块目录固定包含：`er图.drawio`、`数据流图.drawio`
|
||||
* 模块目录规划：
|
||||
* `docs/architecture/modules/00-组织与权限上下文/`
|
||||
* `docs/architecture/modules/01-课程学习/`
|
||||
* `docs/architecture/modules/02-习题与作业/`
|
||||
* `docs/architecture/modules/03-批改与反馈/`
|
||||
## 方案设计（ER + 对象类数据流图）
|
||||
* 00-组织与权限上下文（复用现有 upms/auth）
|
||||
* ER 聚焦租户、部门、用户、角色、权限、登录态对业务域的外键约束与数据隔离键（`adcode/tenant_id/tenant_path/dept_id/dept_path`）。
|
||||
* 数据流图仅保留“身份鉴权、租户路由、权限校验”对象类交互，作为其它模块前置边界。
|
||||
* 01-课程学习
|
||||
* ER 规划课程主数据与学习行为：课程、章节、课时、知识点、课程资源、标签、课程-标签关联、学习会话、学习进度。
|
||||
* 数据流图采用“学生/教师/机构管理员 -> Boundary(前端/API) -> Control(课程编排/进度服务) -> Entity(课程与进度聚合)”表达。
|
||||
* 02-习题与作业
|
||||
* ER 规划题库与作业域：题目、题目版本、题目-知识点关联、试卷、试卷题目、作业、作业发布对象、作业提交、题目作答明细。
|
||||
* 数据流图区分教师发布链路与学生作答链路，明确命令流（发布/提交）与查询流（拉题/看作业）。
|
||||
* 03-批改与反馈
|
||||
* ER 规划批改闭环：批改任务、批改规则、客观题判分、主观题复核、评分明细、错因标签、错题沉淀、复习任务。
|
||||
* 数据流图体现“自动规则判分 + 教师复核”双通道，不依赖 AI；预留抽象接口节点（GradingEnginePort）用于未来替换实现。
|
||||
## 采用的设计方法与原因
|
||||
* DDD 限界上下文：将课程、习题作业、批改反馈分域，避免单一大模型导致职责耦合与演进困难。
|
||||
* 聚合根与不变量建模：以“作业、提交、批改任务”为聚合根，保证状态转换与评分一致性在事务边界内成立。
|
||||
* 状态机建模：对作业（草稿/已发布/已截止）与批改任务（待处理/处理中/待复核/已完成）建状态流，减少流程分支歧义。
|
||||
* CQRS（读写分离）思路：发布、提交、批改等写操作与学情统计、作业列表等读模型分离，适配高并发查询场景。
|
||||
* 事件驱动与Outbox预留：提交后触发批改、批改后触发错题沉淀/复习任务，降低模块同步耦合并提高可扩展性。
|
||||
* 多租户路由键统一：所有核心业务实体强制带租户/组织路径字段，保持与现有 upms 路由策略一致。
|
||||
## 实施阶段与验收标准
|
||||
* 第一阶段：建立统一 drawio 模板（图例、命名规范、主键/外键/基数标注规范、同步/异步箭头规范）。
|
||||
* 第二阶段：完成 4 个模块目录与 8 个 drawio 文件，先 ER 后对象类数据流图，确保跨模块实体引用一致。
|
||||
* 第三阶段：做跨图一致性校验（实体命名、状态枚举、事件名、租户字段、API对象名），并补充“代码落地映射”注释（对应未来 backend 模块与 init/pg 子目录）。
|
||||
* 验收标准：每个模块必须同时具备 ER 与对象类数据流图；ER 图必须标明主外键、基数、关键索引与租户字段；数据流图必须标明 Actor/Boundary/Control/Entity 与关键输入输出对象。
|
||||
Reference in New Issue
Block a user