跳转至

二次开发指南（接管与扩展 step-by-step）

目标：新人/接管团队读完本指南 + README 即可本地跑通、理解结构、按需扩展。 设计原则与命名规范见架构方案 2.3 / 2.4 节；本文是操作级说明。

1. 环境准备（版本见 README 清单）

  1. 安装 JDK 21、Maven 3.9+、Node 20+（npm 11+）；MySQL 8（仅生产/集成测试需要，dev 用 H2）
  2. 克隆仓库后按 README「快速开始」跑通前后端（后端 dev 档位 H2，无需任何外部依赖）

2. 后端结构速览

velasim-server/
├── pom.xml                    # 父 pom：版本统一管理（revision + 第三方版本）
├── vela-common/               # 只能放纯 POJO/常量/枚举，禁止依赖任何业务模块
├── vela-framework/            # 横切能力：Web/安全/缓存/MyBatis-Plus/TraceId/存储/异步
├── vela-module-system/        # 系统域（已实施：操作日志、站内信框架）
├── vela-module-*/             # 其余业务域（待各里程碑实施）
└── vela-boot/                 # 启动 + 配置 + Flyway 迁移（db/migration）

依赖规则（架构防腐，违反会在 Code Review 被拒）： - 业务模块只允许依赖 vela-common / vela-framework，禁止模块间相互依赖 - 模块间协作一律走 Spring 事件（事件类放 framework，发布方事务内 ApplicationEventPublisher.publishEvent， 消费方 @TransactionalEventListener(phase = AFTER_COMMIT)——保证回滚不同步。首例：UserPasswordChangedEvent （system 发布、desktop 监听做 Samba/Windows/挂载三层同步，2026-09-13）；携带明文的事件类必须隐去 toString 并禁止落日志） - 新增模块：父 pom <modules> 加一行 + 业务模块照 vela-module-system/pom.xml 复制

落库待办约定（外呼类操作专用，防生命周期事务被不可达目标阻塞）： - 需在"事件/生命周期"后执行的对外调用（host-agent/Samba/云厂商），一律先入待办表（如 desktop_host_op）再异步派发： 入队侧同事务只写 DB（快路径），执行侧 CAS 抢占 + 组内 seq 有序门 + 指数退避 + 超限告警，扫掠器定时兜底 （模板：DesktopHostSyncService/DesktopHostOpDispatcher/DesktopHostOpSweeperTask） - 待办行存密码只允许 AES 密文（secret_enc），终态清空；错误消息落库前必须 scrub 明文 - 三层账号/密码规范统一走 SyncAccountPolicy / PasswordPolicy（framework/security），与 host-agent 正则逐字一致，改动三处同步

3. 新增一个业务功能（以"新增 XX 管理"为例）

  1. 建表：vela-boot/src/main/resources/db/migration/ 新增 V{N}__xx.sql
  2. 命名：域前缀 + 小写蛇形（job_、netdisk_、desktop_...）；表/字段注释即文档
  3. 兼容写法放 db/migration（H2 MySQL 模式与 MySQL 都要能跑），MySQL 专有 DDL 放 db/migration/mysql/（同名版本号）
  4. 实体/Mapper：对应模块 entity/、mapper/（@Mapper + 继承 BaseMapper）
  5. Service：接口 + impl；业务规则校验抛 BusinessException（错误码先查 ErrorCode 手册，缺失再新增并补测试）
  6. Controller：返回 Result<T> / PageResult<T>；入参继承 PageQuery；危险操作加 @OperLog
  7. 测试：Service 核心逻辑单测（Mockito）+ 需要数据库的用 Testcontainers MySQL

4. 接入一个可插拔扩展点（架构方案 2.3 的 8 类接口）

以"新增调度器 X"为例（P2 实施后可用）：

  1. 实现 SchedulerProvider 接口（submit/query/stop/queryAccount）
  2. 注册 Bean 时带类型标识（如 @Component("scheduler-x")）
  3. sys_cluster 台账配置 scheduler_type=x —— 不改任何既有代码

同理适用于：云厂商 CloudProvider、短信 SmsSender、执行通道 JobExecutor、存储 StorageService、通知渠道 Notifier、认证提供者。（计费策略 CostStrategy 已随 V36 商业化下线移除）

5. 前端扩展

  • 页面一律套用布局模板（layouts/ 与后续 components/layouts/ 的 7 类模板，架构方案 7.4），同类页面同骨架
  • 主题/颜色只用 token 变量（assets/styles/tokens.css），禁止硬编码色值
  • 文案全部走 locales/zh-CN.ts + en-US.ts（键名一致），禁止硬编码中文
  • 响应式断点用 useBreakpoint()（xl/lg/md/sm），列表/看板/门户按模板的响应式规则适配

5.5 H2 控制台（dev 档位调试）

dev 档位（--spring.profiles.active=dev）内置 H2 内存库（MySQL 模式），启动后可直接查看表与数据：

  • 地址：http://localhost:8080/h2-console
  • JDBC URL：jdbc:h2:mem:velasim（注意与 dev 配置一致），用户 sa、密码留空
  • 内存库每次重启清空并由 Flyway 重新迁移 + 种子数据（V1-V9 + 管理员账号/演示数据自动重建）

注意：登录后访问需先通过 /api/v1/auth/login 获取 token；H2 控制台在白名单内可直接打开。

6. 日常开发命令

# 后端
mvn -B install -DskipTests                      # 全量构建
mvn -B -pl vela-common test                     # 单模块测试
java -jar vela-boot/target/velasim.jar --spring.profiles.active=dev   # 运行（H2）
# 前端
npm run dev / npm run build / npm run type-check

7. 常见问题

问题 处置
H2 启动报 DDL 语法错误 检查迁移脚本是否用了 MySQL 专有语法；专有语法移至 db/migration/mysql/
雪花 ID 前端精度丢失 后端已全局 Long→String 序列化，禁止绕过（不要用 @JsonFormat 覆盖成数字）
新增错误码 先查 ErrorCode 手册避免重复；补 ErrorCodeTest 唯一性测试自动保护
缓存使用 只用 CacheConstants 已注册的缓存名；必须设 TTL/容量（架构方案 10 节资源利用率条款）
平台密码/账号报"不满足三层同步要求" 有意收紧（2026-09-13）：账号 ^[a-z][a-z0-9_]{2,31}$、密码 8-64 位 ^[A-Za-z0-9!@#$*()_+-=.,/?~:;\[\]{}]$ 且四类字符（大小写/数字/特殊）至少三类——字符集与 Windows 主机代理逐字一致（含 cmd 元字符 % & 引号 空白 的密码无法安全传给 net user/net use），复杂度与 Windows 默认密码策略对齐（平台为超集，默认策略主机必可接受）；改动正则必须平台+Java 代理+C# 代理三处同步（SyncAccountPolicyTest 有字面量一致断言）
迁移已部署过又要改 无生产环境（全新项目），已应用迁移可直接改（H2 与 MariaDB 双方言验证：mvn test + 真机）；有生产后改用新增迁移