diff --git a/docs/尚数网基本开发规范v3.0.md b/docs/尚数网基本开发规范v3.0.md index 6534c6e..380ce37 100644 --- a/docs/尚数网基本开发规范v3.0.md +++ b/docs/尚数网基本开发规范v3.0.md @@ -823,9 +823,138 @@ public class SswMapperConfig {} **检测**: `python3 .claude/skills/backend-dev/scripts/check_ssw_pack.py {app_code}` → BS-14 PASS +### 11.5 ssw-common 扩展层使用规范 (v3.0+ 新增, BS-新30) + +> **核心原则**: 遇到 jnpf 硬编码问题/平台限制时,走 ssw-common 扩展层,**不动 jnpf 源码**。 +> +> **合规性**: ssw-common 是 JNPF 官方预留的扩展点,升级不会被覆盖。 + +#### 11.5.1 何时用 ssw-common 扩展层 + +| 场景 | jnpf 问题 | ssw-common 方案 | +|------|----------|----------------| +| **硬编码限制** | `maxTokens=1500`(SendAiMessage.java:148) | `SswLLMClient` 可注入 maxTokens | +| **输出格式不修复** | LLM 输出含注释/截断/fieldOptions 错 | `JsonRepairUtil` 修复层 | +| **数据库方言限制** | 只支持 MySQL | `DbClearService` 支持 PG/MySQL 双方言 | +| **API 端点缺失** | 无数据库清理聚合端点 | `DbClearController` 暴露新端点 | +| **功能不完整** | workflow --ai 超长截断无 fallback | `repairWorkflow()` 修复方法 | + +**判断标准**: 如果 jnpf 平台限制阻碍业务开发,且该限制通过扩展层可绕过,则走 ssw-common。 + +#### 11.5.2 架构模式(三件套) + +``` +ssw-common-biz/service/ → 接口定义 +ssw-common-biz/service/impl/ → 业务实现 +ssw-common-controller/ → 端点暴露 +``` + +**三件套模板**: + +```java +// 1. 接口 (ssw-common-biz/service/) +public interface XxxService { + ResultType doSomething(params); +} + +// 2. 实现 (ssw-common-biz/service/impl/) +@Service +public class XxxServiceImpl implements XxxService { + @Autowired private YyyUtil yyyUtil; + public ResultType doSomething(params) { + // 业务逻辑(调用工具类/数据库) + } +} + +// 3. Controller (ssw-common-controller/) +@RestController +@RequestMapping("/api/ssw") +public class XxxController { + @Autowired private XxxService xxxService; + @PostMapping("/xxx") + public ResultType doXxx(@RequestBody Params params) { + return xxxService.doSomething(params); + } +} +``` + +**关键约束**: +- ✅ 完全独立,不依赖 jnpf 源码 +- ✅ 走自己的数据库连接(或主库) +- ✅ 端点路径 `/api/ssw/*`,不与 jnpf 冲突 +- ✅ Java 8 only(禁 var/records/text blocks) + +#### 11.5.3 实战案例索引(详查源码) + +| 案例 | 提交 | 核心组件 | 用途 | 端点 | +|------|------|---------|------|------| +| **AI 修复层** | `038bd98` (v0.14) | `JsonRepairUtil` + `SswLLMClient` + `AIRepairService` | 修复 LLM 输出格式问题(`--ai` fallback) | `/api/ssw/ai/repair` | +| **Workflow AI 修复** | `6f96c93` (v0.15) | `AIRepairService.repairWorkflow()` | 修复 workflow --ai 超长截断 | `/api/ssw/ai/repair-workflow` | +| **DB clear 端点** | `e525be4` | `DbClearService` + `DbClearController` | 数据库清理聚合端点(PG/MySQL 双方言) | `/api/ssw/db/clear` | + +**查看源码**: `boot/ssw-common-biz/` + `boot/ssw-common-controller/` + +#### 11.5.4 代码规范 + +| 维度 | 规范 | +|------|------| +| **Java 版本** | Java 8 only(禁 `var` / `records` / `text blocks`) | +| **包名规范** | `ssw.common.{util\|service\|service.impl\|controller}` | +| **依赖共享** | 业务包只需加 `ssw-common-biz` 依赖,零配置 | +| **端点规范** | `/api/ssw/{功能}`,不与 jnpf 冲突 | +| **日志规范** | 用 `@Slf4j`,不记录敏感信息(密码/token/手机号) | +| **异常处理** | 用 `Result` 包装,不抛原始异常 | + +#### 11.5.5 开发流程 + +```bash +# 1. 在 ssw-common-biz 创建 Service 接口 + 实现 +# 路径: boot/ssw-common-biz/service/ + service/impl/ + +# 2. 在 ssw-common-controller 创建 Controller +# 路径: boot/ssw-common-controller/ + +# 3. 在业务包 pom.xml 加依赖: +# +# com.ssw +# ssw-common-biz +# ${project.version} +# + +# 4. 编译重启 +cd $ccWorkDir/boot && mvn clean package -DskipTests +java -jar jnpf-admin/target/jnpf-admin-*.jar --spring.profiles.active=dev + +# 5. 验证端点 +curl -X POST http://127.0.0.1:30000/api/ssw/xxx \ + -H "Content-Type: application/json" \ + -d '{"key": "value"}' +``` + +#### 11.5.6 检测清单 + +- [ ] Java 8 兼容(无 var/records/text blocks) +- [ ] 包名符合 `ssw.common.*` 规范 +- [ ] 不依赖 jnpf 源码(完全独立) +- [ ] 端点路径不与 jnpf 冲突(`/api/ssw/*`) +- [ ] 日志无敏感信息 +- [ ] 编译通过 + 重启成功 +- [ ] 端点可访问(curl 测试) +- [ ] 业务包加 `ssw-common-biz` 依赖 + +#### 11.5.7 反模式 + +| 反模式 | 后果 | 修复 | +|--------|------|------| +| ❌ 直接改 jnpf 源码 | 升级覆盖丢失 | 移到 ssw-common | +| ❌ 用 Java 11+ 特性 | jnpf-admin 不兼容 | 改回 Java 8 语法 | +| ❌ 端点路径与 jnpf 冲突 | 路由冲突报错 | 改 `/api/ssw/*` | +| ❌ 依赖 jnpf 内部包 | 升级连锁失败 | 完全独立实现 | +| ❌ 不写单元测试 | 扩展层质量失控 | 走 `ssw-e2e-test` 验证 | + --- -## 十二、skill 索引 (v3.0 新增, 13 个) +## 十三、skill 索引 (v3.0 新增, 13 个) > **v2.0 → v3.0 关键变化**: 19 个独立 skill → **v0.11+ 收纳 12 个到 dacli-ts + 1 个合并, 剩 13 个核心 skill**. @@ -892,7 +1021,7 @@ public class SswMapperConfig {} --- -## 十三、文档格式约定 (v3.0 新增, 替代 v2.0 单一 HTML) +## 十四、文档格式约定 (v3.0 新增, 替代 v2.0 单一 HTML) > **v2.0 → v3.0 关键变化**: 文档 = HTML only → **3 HTML + 4 MD (v0.12+, 6 判据驱动)**. @@ -961,7 +1090,7 @@ dacli doc get --file=docs//design.html --from=200 --lines=50 --- -## 十四、git 提交策略 (v3.0 新增) +## 十五、git 提交策略 (v3.0 新增) ### 14.1 一轮一提交 (CLAUDE.md §14) @@ -1001,7 +1130,7 @@ feat(): (vX.Y+) --- -## 十五、反模式 (v3.0 必查, 替代 v2.0 文档约定) +## 十六、反模式 (v3.0 必查, 替代 v2.0 文档约定) > **v2.0 → v3.0 关键变化**: 文档软约定 → **CI 关卡硬强制**. @@ -1023,7 +1152,7 @@ feat(): (vX.Y+) --- -## 十六、AI 协作原则 (v3.0 新增, 来自 MEMORY 6 条通用洞察) +## 十七、AI 协作原则 (v3.0 新增, 来自 MEMORY 6 条通用洞察) > **来源**: `~/.claude/projects/-home-ubuntu-ccWorkDir/memory/MEMORY.md` (2026-06-27 审计 60→6 文件). @@ -1076,7 +1205,7 @@ feat(): (vX.Y+) --- -## 十七、代码审查清单 (v3.0 更新) +## 十八、代码审查清单 (v3.0 更新) ### 17.1 表单开发审查 @@ -1143,7 +1272,7 @@ feat(): (vX.Y+) --- -## 十八、附录: 权威源速查 +## 十九、附录: 权威源速查 ### 18.1 项目级文档 @@ -1195,16 +1324,15 @@ feat(): (vX.Y+) --- -## 十九、版本历史 +## 二十、版本历史 | 版本 | 日期 | 关键变化 | 作者 | |------|------|----------|------| | v1.0 | 2025 | JNPF 手动, AI 不参与 | (基础) | | v2.0 | 2026-03 | + AIBridge (Python), 19 个独立 skill | aibridge 团队 | | **v3.0** | **2026-06-29** | **+ dacli (TS) + webapi 镜像 + 13 skill 收纳 + 7 阶段流程 + 4 关卡 CI + 3 HTML+4 MD 文档** | **Claude Code + dacli 团队** | -| **v3.0+** | **2026-06-29** | **+ 应用隔离方案 (§四 新增, 9 维度隔离全景 + 数据库 + 目录 + 10 条反模式 + 审查清单, 含 BS-47 jxcj P1-5 字典 enCode 加 appCode 前缀修复)** | **Claude Code + dacli 团队** | -| **v3.0+** | **2026-06-29** | **+ CI 关卡 G (§二十 新增, webapi 镜像架构自动防御 + git pre-commit hook + 故意 FAIL 白名单) + 回归审计方法论 (§二十一, docs/cmd-review/regression-2026-06-29.md, 381 行报告)** | **Claude Code + dacli 团队** | -| **v3.0+** | **2026-06-29** | **+ webpatches 强制流程 (§二十二 新增, 改 web 端必跑 CI 关卡 G + patch 文档必含 CI 关卡 G 截图 + 升级后必跑, 闭环防御)** | **Claude Code + dacli 团队** | +| **v3.0+** | **2026-06-29** | **+ 应用隔离方案 + CI 关卡 G + 回归审计 + webpatches 强制流程** | **Claude Code + dacli 团队** | +| **v3.0+** | **2026-07-03** | **+ ssw-common 扩展层使用规范 (§11.5, BS-新30 AI修复层/Workflow AI修复/DB clear 端点)** | **Claude Code + dacli 团队** | ### v3.0 vs v2.0 关键变化 @@ -1227,7 +1355,7 @@ feat(): (vX.Y+) --- -## 二十、CI 关卡 G (v3.0+ 新增, webapi 镜像架构自动防御) +## 二十一、CI 关卡 G (v3.0+ 新增, webapi 镜像架构自动防御) > **核心**: 防止新代码继续走"经验复刻"老路, 自动检查 dacli 代码的 webapi 镜像质量, git pre-commit hook 自动集成. > @@ -1297,7 +1425,7 @@ git config dacli.gate.enabled false --- -## 二十一、回归审计方法论 (v3.0+ 新增, cmd-review/regression-2026-06-29) +## 二十二、回归审计方法论 (v3.0+ 新增, cmd-review/regression-2026-06-29) > **核心**: 当 dacli 出现"过度依赖经验构建代码, 忽视 web 源码引用"症状时, 用四步法系统化审计修复. > @@ -1365,7 +1493,7 @@ git config dacli.gate.enabled false --- -## 二十二、webpatches 强制流程 (v3.0+ 新增, 改 web 端必跑 CI 关卡 G) +## 二十三、webpatches 强制流程 (v3.0+ 新增, 改 web 端必跑 CI 关卡 G) > **核心**: 改 web 端源码前 + 后**必跑 CI 关卡 G**, 防止 web 端修改破坏 dacli webapi 镜像架构. >