wangys/K12Study
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity

更新+mock部分

Browse Source
This commit is contained in:
wangys
2026-04-16 18:12:09 +08:00
parent d5c06eca28
commit adadb3bf1d
40 changed files with 884 additions and 174 deletions
Download Patch File Download Diff File Expand all files Collapse all files

BIN
docs/MAXHUBShareSetup_6.7.8.27_108.exe Normal file
View File

Binary file not shown.

269
docs/apijson/upms.api.json Normal file
View File

@@ -0,0 +1,269 @@
{
"_meta": {
"module": "upms",
"prefix": "/api/upms",
"responseEnvelope": {
"code": "int, 0=成功, 非0=业务失败",
"message": "string, 业务描述",
"data": "T, 业务数据",
"traceId": "string, 链路追踪ID"
},
"errorExample": {
"code": 500,
"message": "系统异常",
"data": null,
"traceId": "abc123"
}
},
"apis": [
{
"id": "upms-routes",
"method": "GET",
"path": "/api/upms/routes",
"summary": "获取当前用户的动态路由/菜单树",
"sqlSource": "upms.tb_sys_menu + upms.tb_sys_role_menu",
"request": {
"headers": { "Authorization": "Bearer {accessToken}" },
"params": null,
"body": null
},
"response": {
"code": 0,
"message": "OK",
"data": [
{
"id": "dashboard",
"path": "/",
"name": "dashboard",
"component": "dashboard",
"layout": "SIDEBAR",
"meta": {
"title": "控制台",
"icon": "layout-dashboard",
"permissionCodes": ["dashboard:view"],
"hidden": false
},
"children": []
},
{
"id": "tenant-management",
"path": "/tenant",
"name": "tenant-management",
"component": "tenant",
"layout": "SIDEBAR",
"meta": {
"title": "租户组织",
"icon": "building-2",
"permissionCodes": ["tenant:view"],
"hidden": false
},
"children": []
}
],
"traceId": "trace-001"
},
"fieldMapping": {
"id": "tb_sys_menu.route_id",
"path": "tb_sys_menu.route_path",
"name": "tb_sys_menu.route_name",
"component": "tb_sys_menu.component_key",
"layout": "tb_sys_menu.layout_type",
"meta.title": "tb_sys_menu.title",
"meta.icon": "tb_sys_menu.icon",
"meta.permissionCodes": "tb_sys_menu.permission_code (拆分为数组)",
"meta.hidden": "tb_sys_menu.hidden",
"children": "通过 parent_route_id 递归组装"
},
"backendDto": "com.k12study.api.upms.dto.RouteNodeDto",
"frontendType": "UpmsRouteNode (types/upms.ts)"
},
{
"id": "upms-users-current",
"method": "GET",
"path": "/api/upms/users/current",
"summary": "获取当前登录用户信息（含权限编码）",
"sqlSource": "upms.tb_sys_user + upms.tb_sys_role + upms.tb_sys_role_menu",
"request": {
"headers": { "Authorization": "Bearer {accessToken}" },
"params": null,
"body": null
},
"response": {
"code": 0,
"message": "OK",
"data": {
"userId": "U10001",
"username": "admin",
"displayName": "K12Study 管理员",
"adcode": "330100",
"tenantId": "SCH-HQ",
"tenantPath": "/SCH-HQ/",
"deptId": "DEPT-HQ-ADMIN",
"deptPath": "/DEPT-HQ/DEPT-HQ-ADMIN/",
"permissionCodes": ["dashboard:view", "tenant:view", "dept:view"]
},
"traceId": "trace-002"
},
"fieldMapping": {
"userId": "tb_sys_user.user_id",
"username": "tb_sys_user.username",
"displayName": "tb_sys_user.display_name",
"adcode": "tb_sys_user.adcode",
"tenantId": "tb_sys_user.tenant_id",
"tenantPath": "tb_sys_user.tenant_path",
"deptId": "tb_sys_user.dept_id",
"deptPath": "tb_sys_user.dept_path",
"permissionCodes": "通过 role->role_menu->menu.permission_code 聚合"
},
"backendDto": "com.k12study.api.upms.dto.CurrentRouteUserDto",
"frontendType": "UpmsCurrentUser (types/upms.ts)"
},
{
"id": "upms-areas",
"method": "GET",
"path": "/api/upms/areas",
"summary": "获取行政区划树",
"sqlSource": "upms.tb_sys_area",
"request": {
"headers": { "Authorization": "Bearer {accessToken}" },
"params": null,
"body": null
},
"response": {
"code": 0,
"message": "OK",
"data": [
{
"areaCode": "330000",
"parentCode": "100000",
"areaName": "浙江省",
"areaLevel": "PROVINCE",
"children": [
{
"areaCode": "330100",
"parentCode": "330000",
"areaName": "杭州市",
"areaLevel": "CITY",
"children": []
}
]
}
],
"traceId": "trace-003"
},
"fieldMapping": {
"areaCode": "tb_sys_area.adcode (转为字符串)",
"parentCode": "tb_sys_area.pid (转为字符串)",
"areaName": "tb_sys_area.name",
"areaLevel": "tb_sys_area.area_type (映射: 0->COUNTRY, 1->PROVINCE, 2->CITY)",
"children": "通过 pid 递归组装"
},
"backendDto": "com.k12study.api.upms.dto.AreaNodeDto",
"frontendType": "UpmsAreaNode (types/upms.ts)"
},
{
"id": "upms-tenants",
"method": "GET",
"path": "/api/upms/tenants",
"summary": "获取租户树",
"sqlSource": "upms.tb_sys_tenant",
"request": {
"headers": { "Authorization": "Bearer {accessToken}" },
"params": null,
"body": null
},
"response": {
"code": 0,
"message": "OK",
"data": [
{
"tenantId": "SCH-HQ",
"parentTenantId": null,
"tenantName": "K12Study 总校",
"tenantType": "HEAD_SCHOOL",
"adcode": "330100",
"tenantPath": "/SCH-HQ/",
"children": [
{
"tenantId": "SCH-ZJ-HZ-01",
"parentTenantId": "SCH-HQ",
"tenantName": "杭州分校",
"tenantType": "CITY_SCHOOL",
"adcode": "330100",
"tenantPath": "/SCH-HQ/SCH-ZJ-HZ-01/",
"children": []
}
]
}
],
"traceId": "trace-004"
},
"fieldMapping": {
"tenantId": "tb_sys_tenant.tenant_id",
"parentTenantId": "tb_sys_tenant.parent_tenant_id",
"tenantName": "tb_sys_tenant.tenant_name",
"tenantType": "tb_sys_tenant.tenant_type",
"adcode": "tb_sys_tenant.adcode",
"tenantPath": "tb_sys_tenant.tenant_path",
"children": "通过 parent_tenant_id 递归组装"
},
"backendDto": "com.k12study.api.upms.dto.TenantNodeDto",
"frontendType": "UpmsTenantNode (types/upms.ts)"
},
{
"id": "upms-departments",
"method": "GET",
"path": "/api/upms/departments",
"summary": "获取部门/组织树",
"sqlSource": "upms.tb_sys_dept",
"request": {
"headers": { "Authorization": "Bearer {accessToken}" },
"params": null,
"body": null
},
"response": {
"code": 0,
"message": "OK",
"data": [
{
"deptId": "DEPT-HQ",
"parentDeptId": null,
"deptName": "总校教学部",
"deptType": "GRADE",
"tenantId": "SCH-HQ",
"adcode": "330100",
"tenantPath": "/SCH-HQ/",
"deptPath": "/DEPT-HQ/",
"children": [
{
"deptId": "DEPT-HQ-MATH",
"parentDeptId": "DEPT-HQ",
"deptName": "数学学科组",
"deptType": "SUBJECT",
"tenantId": "SCH-HQ",
"adcode": "330100",
"tenantPath": "/SCH-HQ/",
"deptPath": "/DEPT-HQ/DEPT-HQ-MATH/",
"children": []
}
]
}
],
"traceId": "trace-005"
},
"fieldMapping": {
"deptId": "tb_sys_dept.dept_id",
"parentDeptId": "tb_sys_dept.parent_dept_id",
"deptName": "tb_sys_dept.dept_name",
"deptType": "tb_sys_dept.dept_type",
"tenantId": "tb_sys_dept.tenant_id",
"adcode": "tb_sys_dept.adcode",
"tenantPath": "tb_sys_dept.tenant_path",
"deptPath": "tb_sys_dept.dept_path",
"children": "通过 parent_dept_id 递归组装"
},
"backendDto": "com.k12study.api.upms.dto.DeptNodeDto",
"frontendType": "UpmsDeptNode (types/upms.ts)"
}
]
}

16
docs/architecture/api-design.md
View File

@@ -1,7 +1,7 @@
# API 设计（基础架构 + 业务功能）
## 1. API 设计原则
- 对外统一前缀：`/api/*`。
- 统一响应结构：`code/message/data/traceId`。
- 统一响应结构：`code/message/data/traceId`，其中 `code=0` 表示成功，非 0 表示业务失败。
- 认证策略：JWT + RBAC，网关做统一鉴权透传。
- API 冻结点：
- 基础架构 API 在 M3 冻结。
@@ -9,16 +9,16 @@
## 2. 基础架构 API（M3）
### 2.1 认证域（auth）
- `POST /api/auth/login`
- `POST /api/auth/refresh`
- `GET /api/auth/current-user`
- `POST /api/auth/tokens`（登录）
- `POST /api/auth/tokens/refresh`（刷新）
- `GET /api/auth/users/current`（当前用户）
### 2.2 权限与组织域（upms）
- `GET /api/upms/routes`
- `GET /api/upms/current-user`
- `GET /api/upms/areas/tree`
- `GET /api/upms/tenants/tree`
- `GET /api/upms/depts/tree`
- `GET /api/upms/users/current`
- `GET /api/upms/areas`
- `GET /api/upms/tenants`
- `GET /api/upms/departments`
### 2.3 基础扩展 API（建议补充）
- 文件域

4
docs/architecture/logical-view.md
View File

@@ -55,9 +55,9 @@ graph TD
## 3. 主链路视角
### 3.1 基础架构链路
- 登录：`frontend/app -> /api/auth/login -> auth -> token`
- 登录：`frontend/app -> /api/auth/tokens -> auth -> token`
- 权限与路由：`frontend/app -> /api/upms/routes -> upms`
- 组织数据：`/api/upms/areas/tree|tenants/tree|depts/tree`
- 组织数据：`/api/upms/areas|tenants|departments`
### 3.2 教学业务链路
- 教师发作业：题库/试卷/作业配置 -> 投放班级。

8
docs/architecture/完整业务流程图.drawio
View File

@@ -1,6 +1,6 @@
<mxfile host="65bd71144e">
<diagram id="full-business-flow-v3" name="完整业务流程图">
<mxGraphModel dx="1312" dy="773" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="5600" pageHeight="2300" math="0" shadow="0">
<mxGraphModel dx="1658" dy="703" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="5600" pageHeight="2300" math="0" shadow="0">
<root>
<mxCell id="0"/>
<mxCell id="1" parent="0"/>
@@ -35,13 +35,13 @@
<mxGeometry x="30" y="110" width="5400" height="220" as="geometry"/>
</mxCell>
<mxCell id="11" value="学生主线" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#f8f9fa;strokeColor=#b7c3d0;fontSize=13;fontStyle=1;align=left;spacingLeft=10;" parent="1" vertex="1">
<mxGeometry x="30" y="360" width="5400" height="260" as="geometry"/>
<mxGeometry x="20" y="370" width="5400" height="260" as="geometry"/>
</mxCell>
<mxCell id="12" value="AI/系统主线" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#f8f9fa;strokeColor=#b7c3d0;fontSize=13;fontStyle=1;align=left;spacingLeft=10;" parent="1" vertex="1">
<mxGeometry x="30" y="660" width="5400" height="620" as="geometry"/>
<mxGeometry x="50" y="670" width="5400" height="620" as="geometry"/>
</mxCell>
<mxCell id="13" value="管理运营主线" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#f8f9fa;strokeColor=#b7c3d0;fontSize=13;fontStyle=1;align=left;spacingLeft=10;" parent="1" vertex="1">
<mxGeometry x="30" y="1320" width="5400" height="300" as="geometry"/>
<mxGeometry y="1330" width="5400" height="300" as="geometry"/>
</mxCell>
<mxCell id="20" value="开始" style="ellipse;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;fontSize=12;" parent="1" vertex="1">
<mxGeometry x="70" y="470" width="110" height="64" as="geometry"/>