日常开发流程

典型工作流

text

1. 拉最新代码 → pnpm install
2. docker compose up -d（若 DB 未起）
3. 启动后端（Java 单体 / micro-java / Python 选一）
4. build 变更过的 shared 包
5. pnpm --filter web dev（或 desktop / mobile）
6. 改代码 → 浏览器/窗口热更新

改不同模块时的注意点

改 contracts（OpenAPI / SQL）

先改 contracts/openapi/rbac-api.yaml 或 contracts/sql/schema.sql
同步 Java Controller（server-java 或 micro-java 对应服务）/ Python router
同步 packages/shared/types 与 api-client
再改前端页面

改 shared 包

包	构建命令	消费方
types	`pnpm --filter @xichen-full-stack/types build`	api-client、auth、admin
auth	`pnpm --filter @xichen-full-stack/auth build`	admin
api-client	`pnpm --filter @xichen-full-stack/api-client build`	admin、mobile
admin	源码直引，无需 build	web、desktop
components	`pnpm --filter @xichen-full-stack/components build`	web、desktop 模板组件
utils	`pnpm --filter @xichen-full-stack/utils build`	web、desktop、mobile
instrument	`pnpm --filter @xichen-full-stack/instrument build`	desktop 仪器设备可选插件

admin 包通过 Vite 源码引用，改完保存后 web/desktop dev 会自动热更新。

改 device-agent（C#）

步骤	说明
驱动	在 `packages/device-agent/src/` 新建 `DeviceAgent.Drivers.*`，实现 `IDeviceDriver`
注册	`DeviceAgent.Host/Program.cs` 中 `AddSingleton<IDeviceDriver, ...>()`
验证	`pnpm device-agent:dev`；或 `DEVICE_AGENT_AUTO_START=true` + `desktop dev`
前端	改 `@xichen-full-stack/instrument` 类型/客户端后需 `instrument build`

C# 项目不纳入 Turbo pipeline，使用 dotnet build / 根目录 pnpm device-agent:build。

改后端

Java 单体：packages/server-java，pnpm --filter @xichen-full-stack/server-java dev，端口 8080
Java 微服务：packages/micro-java，先 mvn install，再启动 auth / system / monitor / gateway（4 服务 + 网关），对外 8080；改业务后可跑 scripts/sync-from-server-java.ps1 与单体同步
Python：packages/server-python，改 .env 后重启 uvicorn

详见 micro-java 本地启动。

改前端应用

Web：packages/web/src/main.ts 仅为薄入口，业务在 @xichen-full-stack/admin
Desktop：同上；仪器设备为可选插件（Desktop）
Mobile：packages/mobile，uni-app；App 打包见 Mobile — Android

依赖升级

外部 npm 包版本在 pnpm-workspace.yaml 的 catalog / catalogs.mobile 中统一维护，子包 package.json 使用 "catalog:" 引用。升级步骤：

修改 pnpm-workspace.yaml 中对应版本
根目录执行 pnpm install

详见 Monorepo — Catalog。

Turbo 命令

bash

pnpm dev      # 并行启动各包 dev（含所有子包，慎用）
pnpm build    # 按依赖顺序构建（shared 先于 app）
pnpm lint     # 全仓 lint
pnpm run clean   # 仅删除各包 dist，不删 node_modules

单独启动某个包更安全：

bash

pnpm --filter web dev
pnpm --filter desktop dev
pnpm --filter @xichen-full-stack/server-java dev
pnpm device-agent:dev

Git 提交建议

契约变更与实现变更放在同一 PR，便于 review
不要提交 .env、.env.production（含 API 地址、数据库密码）
shared 包若改了 types，确保 api-client build 通过

日常开发流程 ​

典型工作流 ​

改不同模块时的注意点 ​

改 contracts（OpenAPI / SQL） ​

改 shared 包 ​

改 device-agent（C#） ​

改后端 ​

改前端应用 ​

依赖升级 ​

Turbo 命令 ​

Git 提交建议 ​

相关文档 ​