@nebula-skills/nebula-code-standards 0.1.0

package/README.md

@@ -0,0 +1,45 @@
+# @nebula-skills/nebula-code-standards
+
+Nebula 企业级框架代码规范 skill。安装后会自动落到本机所有受支持的工具目录：
+
+- `~/.claude/skills/nebula-code-standards/`
+- `~/.cursor/skills/nebula-code-standards/`
+- `~/.codex/skills/nebula-code-standards/`
+
+## 安装
+
+```bash
+# 装最新版
+npm install -g @nebula-skills/nebula-code-standards
+
+# 显式装 latest
+npm install -g @nebula-skills/nebula-code-standards@latest
+
+# 装指定版本
+npm install -g @nebula-skills/nebula-code-standards@0.1.0
+```
+
+`postinstall` 会自动把 skill 内容拷到本机检测到的工具目录。
+
+## 兜底命令（postinstall 没生效时）
+
+```bash
+# 重装到所有检测到的目标
+npx nebula-skill-standards install
+
+# 限定目标工具
+npx nebula-skill-standards install --targets claude,cursor
+
+# 内部开发：symlink 模式，npm 包内 md 改了立刻生效
+npx nebula-skill-standards install --mode symlink
+
+# 卸载
+npx nebula-skill-standards uninstall
+
+# 状态
+npx nebula-skill-standards status
+```
+
+## 内容
+
+参考 [`skill/SKILL.md`](skill/SKILL.md)。

package/bin/cli.cjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+"use strict";
+
+const path = require("node:path");
+
+const SKILL_NAME = "nebula-code-standards";
+const SKILL_DIR = path.join(__dirname, "..", "skill");
+
+process.env.NEBULA_SKILL_DEFAULT_NAME = SKILL_NAME;
+process.env.NEBULA_SKILL_DEFAULT_DIR = SKILL_DIR;
+
+const argv = process.argv.slice(2);
+const sub = argv[0];
+
+if (!sub || sub === "help" || sub === "--help" || sub === "-h") {
+  console.log(`Usage: nebula-skill-standards <command> [options]
+
+Commands:
+  install                              Install this skill into ~/.claude /~/.cursor /~/.codex (detected ones).
+    [--mode copy|symlink]              copy (default) or symlink (dev mode).
+    [--targets claude,cursor,codex]    Restrict to specific tools.
+  uninstall                            Remove this skill from tool directories.
+  status                               Show where this skill is currently installed.
+  list                                 List all skills installed across detected tools.
+
+Equivalent to:
+  nebula-skill <command> ${SKILL_NAME} --dir ${SKILL_DIR} [options]
+`);
+  process.exit(0);
+}
+
+const allowed = new Set(["install", "uninstall", "status", "list"]);
+if (!allowed.has(sub)) {
+  console.error(`Unknown command: ${sub}. Run \`nebula-skill-standards help\` for usage.`);
+  process.exit(2);
+}
+
+const forwarded = [sub];
+
+if (sub === "install") {
+  forwarded.push(SKILL_NAME, "--dir", SKILL_DIR, ...argv.slice(1));
+} else if (sub === "uninstall" || sub === "status") {
+  forwarded.push(SKILL_NAME, ...argv.slice(1));
+} else if (sub === "list") {
+  forwarded.push(...argv.slice(1));
+}
+
+const cliPath = require.resolve("@nebula-skills/installer/cli");
+process.argv = [process.argv[0], cliPath, ...forwarded];
+require(cliPath);

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@nebula-skills/nebula-code-standards",
+  "version": "0.1.0",
+  "description": "Nebula 企业级框架代码规范 skill（Claude Code / Cursor / Codex 通用）。",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lucky-finder/nebula-skills.git",
+    "directory": "packages/nebula-code-standards"
+  },
+  "homepage": "https://github.com/lucky-finder/nebula-skills/tree/main/packages/nebula-code-standards#readme",
+  "files": [
+    "skill/",
+    "bin/",
+    "scripts/",
+    "README.md"
+  ],
+  "bin": {
+    "nebula-skill-standards": "./bin/cli.cjs"
+  },
+  "dependencies": {
+    "@nebula-skills/installer": "^0.1.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "nebula",
+    "skill",
+    "cursor",
+    "claude-code",
+    "codex",
+    "code-standards",
+    "java",
+    "vue",
+    "mybatis-plus"
+  ],
+  "scripts": {
+    "build": "node -e \"process.exit(0)\"",
+    "postinstall": "node scripts/postinstall.cjs"
+  }
+}

package/scripts/postinstall.cjs

@@ -0,0 +1,18 @@
+"use strict";
+
+const path = require("node:path");
+
+try {
+  const { run } = require("@nebula-skills/installer/postinstall");
+  run({
+    name: "nebula-code-standards",
+    skillDir: path.join(__dirname, "..", "skill"),
+  });
+} catch (err) {
+  const msg = err && err.message ? err.message : String(err);
+  console.warn(
+    "[nebula-skill] nebula-code-standards postinstall skipped:",
+    msg,
+    "\n  Run `npx nebula-skill-standards install` later to retry."
+  );
+}

package/skill/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: nebula-code-standards
+description: >-
+  Nebula 企业级框架代码规范。生成 Java Controller、Service、Entity、VO、Mapper 代码时必须参考。
+  生成前端 Vue/TypeScript API 函数、路由配置时必须参考。进行数据库建表、Flyway 脚本编写时必须参考。
+  开发 CRUD 功能、新业务模块时必须参考。涉及分页查询、统一返回值 R<T>、MapStruct 对象转换、
+  多租户隔离、IceStark 微前端子应用开发时必须参考。
+  使用 JSON 工具、分布式锁、Redis 工具（NebulaCacheHelper）时必须参考。
+  新增第三方依赖、管理依赖版本时必须参考。
+  涉及框架层与 Starter 层分层依赖、泛型参数使用、Service/impl 目录规范时必须参考。
+  开发跨服务 RPC 接口（Feign Client）、编写 Constants 常量类、实现 LocalStub 时必须参考。
+  处理文件流下载、IO 异常、StreamUtils 使用场景时必须参考。
+  Mapper @Select 注解与多租户安全、LambdaQueryWrapper 放置规范时必须参考。
+  跨模块 Service 协作、多表联动写操作事务规范、引用计数延迟删除模式时必须参考。
+  设计对外 VO/DTO 时（不暴露存储内部细节）、DDL 建表校验 BaseEntity 11 字段完整性时必须参考。
+  配置 Log4j2 日志格式、多环境日志配置（dev/uat/prod）、ELK JSON 日志接入时必须参考。
+  配置 traceId 链路追踪日志打印、HTTP/定时任务/@Scheduled/MQ 消费等场景 traceId 传播时必须参考。
+  涉及 nebula 五大仓库（support/boot/auth/system/web）职责边界、需求落点决策时必须参考。
+  在 nebula-boot 中查找已封装的工具/组件/注解、判断是否需要造轮子时必须参考。
+  调用 nebula-auth 或 nebula-system 跨服务 RPC、查询 RpcService DTO 字段含义时必须参考。
+  评估是否需要在 nebula-boot 中下沉新能力、判断在 boot 升级还是业务自实现时必须参考。
+  开发独立仓库形态的微前端业务子应用、接入 nebula-web 主应用、双仓库本地联调时必须参考。
+  初始化新 nebula 项目（前端/后端/前后端一起）、需要一条指令本地跑起来时必须参考。
+  编写代码前进行避坑自检、code review、问题排查时必须参考。
+---
+
+# Nebula 代码规范
+
+Nebula 是企业级 SaaS 框架，核心特性：**多租户（行级隔离）**、**微前端（IceStark）**、**MyBatis-Plus CRUD 基类**、**统一 JWT 认证**。
+
+## 核心原则
+
+- Controller：只做参数接收与响应封装，不写 `if` 业务判断
+- Service：只写业务逻辑，不写 `LambdaQueryWrapper` 条件拼装
+- MapperExt：只做 SQL 构建与执行，不含业务判断
+- DO：只映射数据库字段，不含前端展示逻辑
+
+## 框架基类速查
+
+| 基类 | 模块 | 用途 |
+|------|------|------|
+| `BaseEntity` | `nebula-framework-mybatis` | 实体基类，含 11 个公共字段及自动填充 |
+| `BaseMapper<T>` | `nebula-framework-mybatis` | Mapper 基类，开箱即用单表 CRUD |
+| `BaseService<T>` | `nebula-framework-mybatis` | Service 接口基类 |
+| `BaseServiceImpl<M, T>` | `nebula-framework-mybatis` | Service 实现基类，含 `getByIdOrThrow` |
+| `PageParam` | `nebula-framework-core` | 分页入参：`pageNo`（默认1）、`pageSize`（默认10）、`sorts` |
+| `PageResult<T>` | `nebula-framework-core` | 分页响应：`total`、`records`、`convert()` 批量转换 |
+| `R<T>` | `nebula-framework-core` | HTTP 响应包装：`R.ok(data)` / `R.ok()` |
+| `BusinessException` | `nebula-framework-core` | 业务异常，含错误码和提示 |
+| `GlobalErrorCode` | `nebula-framework-core` | 错误码：`PARAM_INVALID`、`DATA_NOT_FOUND` 等 |
+| `BaseMapperConfig` | `nebula-framework-core` | MapStruct 全局配置（忽略未映射字段） |
+| `JsonUtils` | `nebula-framework-core` | **JSON 工具**，禁止 `new ObjectMapper()`，统一用此类 |
+| `NebulaLockHelper` | `nebula-boot-starter-redis` | **分布式锁**，禁止 `StringRedisTemplate.setIfAbsent` |
+| `NebulaCacheHelper` | `nebula-boot-starter-redis` | **Redis 缓存工具**，封装 Key 前缀/JSON/Hash/Set/过期，禁止直接用 `StringRedisTemplate` |
+| `SystemException` | `nebula-framework-core` | **系统级异常**（IO/外部调用失败），区别于业务异常 `BusinessException` |
+| `StreamUtils` | `spring-core` | 文件流复制，用 `StreamUtils.copy(in, out)` 替代手动 byte[] 循环 |
+| `TraceContextHolder` | `nebula-framework-trace` | 取当前 traceId / runWithContext 切换上下文 |
+| `TenantContextHolder` | `nebula-framework-tenant` | `getTenantCode()` / `runAsTenant` / `runWithoutTenant` |
+| `SecurityContextHolder` | `nebula-framework-security` | 当前登录用户信息 |
+| `@DistributedLock` | `nebula-boot-starter-redis` | 声明式分布式锁（SpEL Key） |
+| `@RepeatSubmit` | `nebula-framework-web` | 防 HTTP 重复提交（body hash + 用户身份） |
+| `@Idempotent` | `nebula-framework-idempotent` | 业务幂等（SpEL Key + Redis 后端） |
+| `@Desensitize` | `nebula-framework-web` | 响应字段脱敏（手机/邮箱/身份证等） |
+| `@RequiresPermission` | `nebula-framework-security` | 权限校验，支持 AND/OR 与 SpEL |
+| `@TenantSwitch` / `@TenantIgnore` | `nebula-framework-tenant` | 方法级切换租户 / 忽略租户过滤 |
+| `@AuditLog` | `nebula-boot-starter-log` | 审计日志（含 `#_DIFF` 等内置 SpEL 函数） |
+| `IdGenRpcService` | `nebula-system-api` | 业务号发号（订单号、工单号等），**不要** 拿 `IdUtils` 当业务号 |
+| `TenantRpcService` | `nebula-system-api` | 跨服务查租户（推荐用 `tenantCode` 而非 `tenantId`） |
+
+## 命名规范速查
+
+| 层次 | 规则 | 示例 |
+|------|------|------|
+| 数据库表 | `t_{业务名蛇形}` | `t_demo` |
+| 实体类 | `{业务名}DO` | `DemoDO` |
+| Mapper 接口 | `{业务名}Mapper` | `DemoMapper` |
+| 动态查询类 | `{业务名}MapperExt` | `DemoMapperExt` |
+| Service 接口 | `I{业务名}Service` | `IDemoService` |
+| Service 实现 | `{业务名}ServiceImpl` | `DemoServiceImpl` |
+| Controller | `{业务名}Controller` | `DemoController` |
+| 分页入参 VO | `{业务名}PageParamVO` | `DemoPageParamVO` |
+| 新增/修改入参 | `{业务名}SaveParamVO` | `DemoSaveParamVO` |
+| 列表响应 VO | `{业务名}RespVO` | `DemoRespVO` |
+| 详情响应 VO | `{业务名}DetailVO` | `DemoDetailVO` |
+| 对象转换 | `{业务名}Convert` | `DemoConvert` |
+
+## REST 接口设计速查
+
+| HTTP 方法 | 路径 | 说明 | 入参 | 响应 |
+|-----------|------|------|------|------|
+| `POST` | `/{域}/{资源}/page` | 分页查询 | `@RequestBody XxxPageParamVO` | `R<PageResult<XxxRespVO>>` |
+| `GET` | `/{域}/{资源}/{id}` | 查询详情 | `@PathVariable Long id` | `R<XxxDetailVO>` |
+| `POST` | `/{域}/{资源}` | 新增 | `@Valid @RequestBody XxxSaveParamVO` | `R<Long>`（返回新id） |
+| `PUT` | `/{域}/{资源}` | 修改 | `@Validated(UpdateGroup.class) @RequestBody` | `R<Void>` |
+| `DELETE` | `/{域}/{资源}` | 批量逻辑删除 | `@RequestBody List<Long> ids` | `R<Void>` |
+| `PATCH` | `/{域}/{资源}/{id}/v` | 启用 | `@PathVariable Long id` | `R<Void>` |
+| `PATCH` | `/{域}/{资源}/{id}/x` | 禁用 | `@PathVariable Long id` | `R<Void>` |
+
+> 路径前缀约定：`/{业务域}/{资源名}`，例如 `/mes/demo`
+
+## 方法命名约定
+
+| 操作 | Service 方法名 | Controller 方法名 |
+|------|--------------|----------------|
+| 分页查询 | `page{业务名}` | `page{业务名}` |
+| 详情查询 | `get{业务名}ById` | `get{业务名}ById` |
+| 新增 | `create{业务名}` | `create{业务名}` |
+| 修改 | `update{业务名}` | `update{业务名}` |
+| 逻辑删除 | `delete{业务名}` | `delete{业务名}` |
+| 启用 | `enable{业务名}` | `enable{业务名}` |
+| 禁用 | `disable{业务名}` | `disable{业务名}` |
+
+## 详细规范文档
+
+### 写代码层（按层次/技术分）
+- 后端规范（分层、DO/VO/MapperExt/Service/Controller）：[backend-standards.md](backend-standards.md)
+- 前端规范（技术栈、API封装、路由、共享包）：[frontend-standards.md](frontend-standards.md)
+- 数据库规范（DDL建表、Flyway、字段映射）：[db-standards.md](db-standards.md)
+- 完整 CRUD 代码示例：[full-crud-example.md](full-crud-example.md)
+- **框架工具使用规范**（JsonUtils/分布式锁/依赖版本/分层约束）：[framework-standards.md](framework-standards.md)
+
+### 工作区/架构层（按仓库/能力分）
+- **工作区总览**（五仓库职责、依赖链、需求落点决策）：[workspace-overview.md](workspace-overview.md)
+- **boot 组件目录**（framework/starter 全清单 + 速查矩阵）：[boot-components-catalog.md](boot-components-catalog.md)
+- **auth/system RPC 字典**（接口签名 + DTO 字段含义）：[rpc-api-reference.md](rpc-api-reference.md)
+- **独立仓库子应用接入**（vite 双入口、命名一致性、部署）：[microapp-guide.md](microapp-guide.md)
+
+### 工作流层（按场景分）
+- **新项目初始化向导**（前后端骨架 + 连通性检测 + Demo CRUD）：[init-new-project.md](init-new-project.md)
+- **boot 升级 vs 自实现 决策**（缺口分析 + 强制询问流程）：[upgrade-decision.md](upgrade-decision.md)
+- **避坑清单**（10 大类 80+ 条反模式）：[pitfalls-checklist.md](pitfalls-checklist.md)
+
+> 不确定从哪开始？先翻 [workspace-overview.md](workspace-overview.md) §三需求落点决策表。