@nebula-skills/nebula-code-standards 0.1.0

package/skill/workspace-overview.md

@@ -0,0 +1,194 @@
+# Nebula 工作区总览
+
+> 在动手写代码前，先用本文判断「这个需求该落在哪个仓库」。判断错了，后面所有规范都白搭。
+
+---
+
+## 一、五个仓库的定位
+
+| 仓库 | 定位 | 判断关键词 | 当前推荐版本 |
+|------|------|----------|---------|
+| `nebula-support` | 三方依赖 BOM + Gradle 构建插件中心 | 「升版本」「换三方库」「构建/发布脚本」 | `0.1.22-SNAPSHOT` |
+| `nebula-boot` | Spring Boot 框架库（framework + starter + tools 三层） | 「通用工具」「自动装配」「全公司复用」 | `0.1.22-SNAPSHOT` |
+| `nebula-auth` | 统一认证授权服务（登录 / Token / OAuth2） | 「登录」「Token」「账号密码」「OAuth2」 | `0.1.8-SNAPSHOT`，默认端口 `9010` |
+| `nebula-system` | 平台公共服务（用户/角色/菜单/字典/租户/组织/IdGen/Region） | 「字典」「组织」「员工」「主键发号」「行政区划」 | `0.2.47-SNAPSHOT`，默认端口 `8081` |
+| `nebula-web` | 前端微前端 monorepo（主应用 + 内置子应用） | 「主应用」「微前端」「IceStark」 | 主应用 `:3000`，子应用 `:3001+` 递增 |
+
+> 实际版本以各仓库 `gradle.properties` 为准；本文档给出的是当前推荐基线，可按需修改 [[init-new-project]] 的派生默认值。
+
+---
+
+## 二、依赖链路
+
+```
+            ┌─────────────────────────────┐
+            │ nebula-support (BOM + 构建)  │  ← 所有三方版本号在此
+            └──────────────┬──────────────┘
+                           │
+            ┌──────────────▼──────────────┐
+            │ nebula-boot                  │
+            │  ├─ framework (无 AutoConfig)│  ← 工具/契约/SPI
+            │  └─ starter   (自动装配)     │  ← Spring Boot 集成
+            └──────────────┬──────────────┘
+                           │
+        ┌──────────────────┼──────────────────┐
+        ▼                  ▼                  ▼
+  ┌──────────┐      ┌─────────────┐    ┌────────────────┐
+  │nebula-auth│      │nebula-system │    │ 业务服务         │
+  │ -api      │      │ -api         │    │ (-api/-core/   │
+  │ -core     │      │ -core        │    │  -starter/     │
+  │ -starter  │      │ -starter     │    │  -server)      │
+  │ -server   │      │ -server      │    └───────┬─────────┘
+  └─────┬─────┘      └─────┬────────┘            │
+        │                  │                     │
+        └──── Feign RPC ───┴─────────────────────┘
+              (路径前缀 /rpc/nebula/{domain}/{resource})
+
+                                                  ▲
+  ┌──────────────────────────────────────────────┘
+  │
+  ▼
+┌────────────────────────────────────────────────┐
+│ nebula-web (Vite + IceStark monorepo)          │
+│  ├─ apps/nebula-web-main      (主应用 :3000)    │
+│  ├─ apps/nebula-web-auth      (子应用 :3001)    │
+│  ├─ apps/nebula-web-system    (子应用 :3002)    │
+│  └─ packages/{types,utils,components}           │
+└────────────────────────────────────────────────┘
+                       ▲
+                       │ IceStark 加载
+                       │
+┌────────────────────────────────────────────────┐
+│ 业务前端独立仓库                                  │
+│  - `private:true` 的单 app                      │
+│  - `@nebula-web/*` 走 GitLab Package Registry   │
+│  - 自带 `deploy/build-deploy.sh`                │
+└────────────────────────────────────────────────┘
+```
+
+---
+
+## 三、需求落点决策
+
+收到任何 nebula 相关需求时，按下表先判断落点，再翻对应文档：
+
+| 需求关键词 | 落点 | 第一份要看的文档 |
+|----------|------|----------------|
+| 登录 / 退出 / Token 刷新 / OAuth2 客户端 / 验证码 | 调用 `nebula-auth` | [[rpc-api-reference]] §二 |
+| 查字典 / 查组织 / 查员工 / 查行政区划 / 查租户 / 主键发号 | 调用 `nebula-system` | [[rpc-api-reference]] §三 |
+| 通用工具（JSON、加密、ID、Excel、限流、缓存、锁、幂等、审计、脱敏...） | 先查 `nebula-boot` 是否已有 | [[boot-components-catalog]] §C 速查矩阵 |
+| boot 不存在的通用能力 | 评估「下沉 boot vs 业务自实现」 | [[upgrade-decision]] |
+| 写业务 CRUD（增删改查、分页、批量） | 在业务 server 模块内 | [[backend-standards]] + [[full-crud-example]] |
+| 写数据库迁移 / 建表 / 公共字段 | 业务 server 的 db/migration | [[db-standards]] |
+| 写跨服务 Feign 接口（自己服务对外暴露） | 业务 api 模块的 Constants + provider + LocalStub 三件套 | [[framework-standards]] §三-C |
+| 前端新业务子模块 | 决策：内置 `nebula-web/apps/` 或 独立仓库 | [[microapp-guide]] §一 |
+| 前端独立仓库子应用接入主应用 | 套独立仓库样板 | [[microapp-guide]] |
+| 主应用配菜单 / 路由 / 鉴权 / 全局请求 | 改 `nebula-web/apps/nebula-web-main` | [[frontend-standards]] |
+| 「从零起一个新 nebula 项目」 | 进入对话式向导 | [[init-new-project]] |
+| 三方依赖升级 / 新增第三方库 | 改 `nebula-support` BOM | [[framework-standards]] §五 |
+| 写代码前 30 秒自检 | 扫一遍避坑清单 | [[pitfalls-checklist]] |
+
+---
+
+## 四、Maven 仓库与网络约束
+
+业务项目引入 nebula 各包时，**只走公司内网 Nexus**：
+
+```
+http://10.10.1.130:8081/repository/nebula-public/
+```
+
+- ⚠️ **必须连公司内网 / VPN** 才能访问。
+- 拉取失败常见症状：`Connection refused` / `Read timed out` / HTTP `503 Service Unavailable`。
+- 出现这些症状时，先告诉用户：**「请确认已连接公司内网或 VPN，然后重试」**，不要去找其他镜像源。
+
+详见 [[init-new-project]] §依赖拉取异常处理。
+
+---
+
+## 五、跨仓库版本对齐
+
+业务项目引入 boot/auth/system 时，按下表对齐版本号（实际以最新发布版为准）：
+
+```properties
+# 业务项目 gradle.properties
+projectGroup=com.huida.{domain}
+projectVersion=0.1.0-SNAPSHOT
+nebulaSupportVersion=0.1.22-SNAPSHOT
+nebulaBootVersion=0.1.22-SNAPSHOT
+nebulaAuthVersion=0.1.8-SNAPSHOT
+nebulaSystemVersion=0.2.47-SNAPSHOT
+```
+
+```gradle
+// 业务项目 build.gradle 依赖
+api platform("com.huida.nebula:nebula-support-dependencies:${nebulaSupportVersion}")
+api platform("com.huida.nebula.boot:nebula-boot-dependencies:${nebulaBootVersion}")
+api "com.huida.nebula.boot:nebula-boot-starter:${nebulaBootVersion}"
+api "com.huida.nebula:nebula-auth-api:${nebulaAuthVersion}"
+api "com.huida.nebula:nebula-system-api:${nebulaSystemVersion}"
+```
+
+**Group 速记：**
+
+| 模块前缀 | Maven Group |
+|---------|------------|
+| `nebula-framework-*` | `com.huida.nebula` |
+| `nebula-boot-starter-*` | `com.huida.nebula.boot` |
+| `nebula-tools-*` | `com.huida.nebula.tools` |
+| `nebula-auth-*` | `com.huida.nebula` |
+| `nebula-system-*` | `com.huida.nebula` |
+
+---
+
+## 六、后端项目标准四层结构
+
+所有 nebula 后端业务项目都按四层组织：
+
+```
+nebula-{domain}/
+├── nebula-{domain}-api      ← RPC 接口 + DTO + Constants（其他服务通过它调你）
+├── nebula-{domain}-core     ← Entity + Mapper + Service + Controller + Convert + feign/local
+├── nebula-{domain}-starter  ← AutoConfiguration + ComponentScan（其他服务通过它启用你的能力）
+└── nebula-{domain}-server   ← Application + application.yml + db/migration + log4j2.xml
+```
+
+**依赖方向：** `server → starter → core → api`。`api` 模块只能依赖 boot 与第三方库，**不可** 引用本项目其他模块。
+
+---
+
+## 七、关键技术栈版本基线
+
+| 技术 | 版本 |
+|------|------|
+| JDK | `17`（强制） |
+| Spring Boot | `3.5.9` |
+| Gradle | `8.12`（通过 Wrapper） |
+| MyBatis-Plus | `3.5.9` |
+| Spring Cloud | `2025.0.0` |
+| Vue | `3.5.x` |
+| Vite | `5.x` |
+| TypeScript | `5.x` |
+| pnpm | `>= 9` |
+| Node.js | `>= 22` |
+
+详细技术栈与 IntelliJ 配置见 [[init-new-project]] §一-技术栈基线。
+
+---
+
+## 八、本文档与其他文档的关系
+
+本文档是「索引层」。具体规范请翻：
+
+- [SKILL.md](SKILL.md) — Skill 元数据与速查表
+- [backend-standards.md](backend-standards.md) — 后端分层 / 包结构 / DO/VO/Mapper/Service/Controller
+- [frontend-standards.md](frontend-standards.md) — 前端技术栈 / API 封装 / 路由 / 共享包
+- [framework-standards.md](framework-standards.md) — 工具类使用 / 分层依赖 / 链路追踪 / RPC 三件套
+- [db-standards.md](db-standards.md) — DDL / Flyway / 11 公共字段
+- [full-crud-example.md](full-crud-example.md) — 完整 CRUD 后端 + 前端代码
+- [boot-components-catalog.md](boot-components-catalog.md) — boot 全部组件能力目录
+- [rpc-api-reference.md](rpc-api-reference.md) — auth/system RPC 字典
+- [microapp-guide.md](microapp-guide.md) — 独立仓库子应用接入规范
+- [init-new-project.md](init-new-project.md) — 新项目初始化向导
+- [upgrade-decision.md](upgrade-decision.md) — boot 升级 vs 自实现 决策
+- [pitfalls-checklist.md](pitfalls-checklist.md) — 一页式避坑清单