02 architecture and tech stack

架构与技术栈

适用对象

• 开发与运维人员：部署、排障、接口联调。
• 技术负责人：评估扩展点与安全边界。

前置条件

• 已阅读仓库根目录 README.md 中的环境与端口说明。
• 了解本系统为 前后端分离，浏览器只与前端静态资源及经 Nginx 反代的 API 交互。

页面入口（架构视角）

前端 路由 由 frontend/src/router/index.ts 聚合各模块子路由：

• 公共路由：/login。
• 主应用：/ → MainLayout，子路由包含 dashboard、system、project、entrustment、sample、equipment、staff、environment、quality、consumable、testing、reports 等。
• 通配：未匹配路径重定向至 /dashboard（非登录页）。

权限：router.beforeEach 中调用 getRoutePermission + canAccessRoutePermission；无权限时提示并跳回 /dashboard。

层级	路径/组件	说明
布局	MainLayout.vue	侧栏 Sidebar.vue + 顶栏 + <router-view>
菜单	Sidebar.vue 中 rawMenuItems	与业务路由一致，按权限过滤
API	frontend/src/utils/request.ts	baseURL: '/api'，统一处理 { code, message, data } 信封

字段说明

架构文档不定义业务字段；API 响应普遍采用：

{
  "code": 200,
  "message": "success",
  "data": { }
}

前端对 code 兼容数字与纯数字字符串（如 "200"），避免网关改写类型导致不解包 data。

标准操作步骤（SOP）

本地开发

1. 后端：DJANGO_SETTINGS_MODULE=limis.settings.dev，migrations 后 runserver（默认 8000）。
2. 前端：Vite 开发服务器，将 /api 代理至后端（见 frontend/vite.config.ts）。
3. 鉴权：登录获取 JWT，请求头 Authorization: Bearer <token>；401 时清除 token 并跳转 /login。

部署（Docker 概览）

1. 按 README 使用 docker compose 构建并启动。
2. 对外通常 80 为前端，API 同域 /api/；数据库、Redis、MinIO 等端口以 docker-compose.yml 为准。

排查接口问题

1. 浏览器 Network 查看响应体是否为信封格式。
2. 若前端拿不到业务数据，核对 code 类型与 data 嵌套（见 apiField / unwrapCrawlPayload 等业务规则）。
3. 后端模块权限：LimsModulePermission 与路由 lims_module 配置需一致。

常见错误

现象	可能原因	处理
前端列表为空但 Network 200	code 为字符串 "200" 旧逻辑未解包	已统一在 request.ts 处理，确认未使用绕过封装的请求
403/无权访问	用户角色未包含路由 meta.permission	在系统管理配置角色权限
重复提交	写操作带 Idempotency-Key	幂等设计，避免重复点击导致重复创建

数据核对清单

• 生产环境 VITE_* 或构建产物中 API 基路径与 Nginx /api/ 一致。
• JWT 过期策略与前端 handleUnauthorized 行为符合安全要求。
• 后端 StandardPagination 分页返回 data.results 与前端列表解析一致。

与上下游模块关系

后端应用结构（概念）

• apps/projects：工程项目、参建单位、分部分项、合同、见证人。
• apps/commissions：委托单、委托项目行、合同评审。
• apps/samples：样品、样品组、处置。
• apps/testing：检测分类/方法/参数、任务 TestTask、原始记录 OriginalRecord、结果 TestResult、判定规则等。
• apps/reports：报告模板、报告、审批与发放。
• apps/standards：标准规范等（前端列表在 /quality/standards）。
• apps/quality：内审、管评、不符合项等。
• apps/system：用户、角色、审计日志等。

请求链路

浏览器 → Nginx（静态 + /api 反代）→ Gunicorn/Django → PostgreSQL
                              ↓
                         JWT 中间件 / 权限

与前端路由的映射关系

每个业务模块的 页面路由（如 /project）通过 API 客户端（frontend/src/api/*）调用对应 ViewSet；权限字符串在路由 meta.permission 与后端模块权限中成对出现，部署与发版时需同步变更。