跳转到内容
GitHub

技术架构与项目结构

第一次打开这个仓库,最快的读法是跟着一次请求走一遍。这一页以用户列表(后台的「系统管理 → 用户管理」,接口是 GET /api/v1/sys/users)为例,列出它依次经过的文件,再给一张「想改什么去哪找」的表。要从头写一个新模块,看从零加一个业务模块。

浏览器 · apps/web + packages/platform + packages/api
  1. 路由文件声明 URL 参数与守卫,不渲染
  2. 页面注册表路由 → 页面组件
  3. 页面的 api.ts拼查询串,发请求
  4. 请求客户端带令牌 · 判定成败

GET /api/v1/sys/users · Authorization: Bearer <token>

服务端 · apps/api/backend
  1. JWT 中间件解出当前用户
  2. 权限依赖核对权限码
  3. api收参数,调 service
  4. service业务规则 · 分页
  5. crud自动追加数据范围

SQL · 已带上数据范围条件

数据库
  1. PostgreSQL · SQL Server · MySQL三选一,同一套代码
箭头是请求方向。高亮的那一环:行级数据范围由 crud 的基类自动加进查询,不用在每个方法里手写

一个 pnpm + turbo 的 monorepo,后端、三个客户端和文档站都在里面。

apps/
├─ api/ 后端(FastAPI,Python,uv 管理),代码在 apps/api/backend/
├─ web/ Web 后台:路由文件 + 页面注册表,不写页面本身
├─ desktop/ Electron 桌面端模板,加载 web 的构建产物
├─ mobile/ Expo 移动端模板,原生界面
├─ worker/ 只有一个启动 Celery 的 dev 脚本
└─ docs/ 这个文档站
packages/
├─ api/ 后端契约:请求客户端、成败判定、生成的 schema.d.ts
├─ i18n/ 语言包与校验脚本
├─ ui/ 通用组件,不含业务
└─ platform/ 页面、登录与权限、外壳(多页签、侧边栏)

包之间的依赖是单向的,写在各自 package.json 的 dependencies 里:

包直接依赖的 workspace 包
apps/web@admin/platform · @admin/ui · @admin/i18n
packages/platform@admin/api · @admin/ui · @admin/i18n
apps/mobile@admin/api · @admin/i18n
packages/api · packages/i18n · packages/ui无

方向反了(比如 ui 去 import platform)pnpm arch:check 会报错,CI 里也跑这一条。

十个环节,前四个在浏览器里,后六个在服务端。

#文件这一环做什么
1apps/web/src/routes/_auth/system/user.tsx路由文件。用 zod 声明 URL 上有哪些参数(页码、筛选项),挂权限守卫 requirePerm;component: () => null,自己不渲染页面
2apps/web/src/lib/page-registry.tsx页面注册表。"/_auth/system/user": UserPage 这一行把路由对到页面组件,由多页签的 TabOutlet 挂载
3packages/platform/src/pages/user/api.tsusersQuery 把参数拼成查询串,发 GET /api/v1/sys/users。页面 index.tsx 用 useQuery 调它
4packages/api/src/client.ts · envelope.ts请求客户端。加上 Authorization: Bearer 和 Accept-Language;遇到 401 刷新一次令牌后重放。resolveEnvelope 判定成败:HTTP 状态不对,或者 HTTP 200 但信封里的 code 不是 200,都算失败
5apps/api/backend/middleware/jwt_auth_middleware.pyJWT 中间件。解令牌、填 request.user,并把当前用户放进上下文(第 9 环要用)
6apps/api/backend/app/admin/api/v1/sys/user.py接口函数 get_users_paginated。装饰器上的 dependencies 声明三件事:RequestPermission('sys:user:list')(要哪个权限码)、DependsRBAC(核对)、DependsPagination(分页参数)
7apps/api/backend/common/security/rbac.pyrbac_verify 核对权限:超级管理员放行,其余用户看他的角色勾选的菜单里有没有这个权限码
8apps/api/backend/app/admin/service/user_service.pyget_list。向 crud 要一条查询,交给 paging_data 分页,再给每个用户补上角色
9apps/api/backend/app/admin/crud/crud_user.py · common/security/data_scope.pyCRUDUser 继承 DataScopedCRUD。基类改写了 select / select_model / count,每次查询自动追加当前用户的数据范围条件 —— 部门经理因此只查得到本部门及以下的用户,分页总数也是过滤后的
10apps/api/backend/common/response/response_schema.py · utils/serializers.py返回。所有接口都包在 { code, msg, data } 信封里;stringify_unsafe_ints 把超过 JS 安全整数范围的 ID 转成字符串,所以前端拿到的 ID 一律是 string

三处容易看漏的地方:

  • 路由文件不渲染页面。 多页签要同时保留所有打开的页面,所以页面由 TabOutlet 按注册表挂载,路由文件只管 URL 参数和守卫。页面组件里也不能直接读路由,参数走 props。原因见多页签。
  • 数据范围不用手写。 第 9 环是基类自动做的。确实要绕开时(比如后台任务要查全量)用 bypass_data_scope()。规则怎么配见数据权限。
  • 成败判定不在页面里。 HTTP 200 不代表成功,要看信封里的 code;这个判断集中在 packages/api,页面只处理成功的数据和抛出来的 ApiError。

内置功能在 apps/api/backend/app/admin/,按层分目录,调用方向是 api → service → crud:

apps/api/backend/app/admin/
├─ api/v1/ 接口函数:收参数、声明权限码,调 service
├─ service/ 业务规则、事务
├─ crud/ 查询(继承 DataScopedCRUD)
├─ model/ SQLAlchemy 模型,一个类一张表
├─ schema/ 请求和响应的字段(Pydantic)
└─ tests/ 这个模块的测试

可拆卸的功能做成插件,放在 apps/api/backend/plugin/ 下:同样的五层,外加一个 plugin.toml 和自己的 sql/ 种子。详见插件机制。

页面在 packages/platform/src/pages/ 下,一个页面一个目录。用户管理是这几个文件:

文件内容
api.ts这个页面用到的接口函数、类型和查询 key
columns.tsx列表的列定义和行内操作
form.tsx新增 / 编辑表单(react-hook-form + zod)
index.tsx页面本身:查询区、表格、分页,把筛选条件写进 URL
table-features.ts这张表启用了哪些表格功能
要改什么去哪找
表单字段和校验页面目录的 form.tsx
列表的列页面目录的 columns.tsx
筛选条件三处要一起改:路由文件的 searchSchema、页面 index.tsx 的查询区字段、api.ts 里拼查询串的函数
接口的请求 / 响应字段后端 app/admin/schema/(插件在 plugin/<名字>/schema/)。改完跑 pnpm --filter @admin/api gen:api 重新生成 packages/api/src/schema.d.ts;页面 api.ts 里手写的类型也要跟着改
业务规则app/admin/service/
查询怎么写app/admin/crud/
表结构改 app/admin/model/ 里的模型,再 pnpm db:revision '说明' 生成迁移、pnpm db:upgrade 升级。迁移文件在 apps/api/backend/alembic/versions/
菜单和按钮权限码种子在 apps/api/backend/sql/ 下三种数据库各一份的 init_snowflake_test_data.sql;种子只在初始化时执行,已经在跑的库要再写一条数据迁移。后端用 RequestPermission('…') 声明,前端用 requirePerm(…) 守卫
界面文案和翻译packages/i18n/src/locales/ 的 zh-CN.json 和 en-US.json,改完跑 pnpm i18n:check。后端的报错文案另在 apps/api/backend/locale/
环境变量apps/api/backend/.env.example 和 core/conf.py
能在界面上改的参数参数配置插件 apps/api/backend/plugin/config/,见参数配置与数据字典
定时任务apps/api/backend/app/task/,见定时任务
加一个侧边栏里看得见的页面路由文件、页面注册表、页面目录、sys_menu 的菜单记录、语言包,五处都要有。逐步做法见从零加一个业务模块

给编码代理的约定写在仓库里,不在这个文档站上:根目录的 CLAUDE.md 放跨模块的硬纪律,各模块目录下的 AGENTS.md 放那一层实测出来的坑。Claude Code 读到某个目录的文件时会自动加载那一份。

文档站这边,每一页都有 Markdown 原文(页面标题下的「复制 Markdown」,或者把地址结尾的 / 换成 .md),全站索引在 llms.txt。