auto(11bf28807ce8): session end @ 2026-07-03T16:10:49 (+1f)
This commit is contained in:
1 parent
395d6534e1
commit
47769f3de3
1 file changed
+142
-14
+142
-14
@@ -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 加依赖:
|
||||
# <dependency>
|
||||
# <groupId>com.ssw</groupId>
|
||||
# <artifactId>ssw-common-biz</artifactId>
|
||||
# <version>${project.version}</version>
|
||||
# </dependency>
|
||||
|
||||
# 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/<app>/design.html --from=200 --lines=50
|
||||
|
||||
---
|
||||
|
||||
## 十四、git 提交策略 (v3.0 新增)
|
||||
## 十五、git 提交策略 (v3.0 新增)
|
||||
|
||||
### 14.1 一轮一提交 (CLAUDE.md §14)
|
||||
|
||||
@@ -1001,7 +1130,7 @@ feat(<scope>): <description> (vX.Y+)
|
||||
|
||||
---
|
||||
|
||||
## 十五、反模式 (v3.0 必查, 替代 v2.0 文档约定)
|
||||
## 十六、反模式 (v3.0 必查, 替代 v2.0 文档约定)
|
||||
|
||||
> **v2.0 → v3.0 关键变化**: 文档软约定 → **CI 关卡硬强制**.
|
||||
|
||||
@@ -1023,7 +1152,7 @@ feat(<scope>): <description> (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(<scope>): <description> (vX.Y+)
|
||||
|
||||
---
|
||||
|
||||
## 十七、代码审查清单 (v3.0 更新)
|
||||
## 十八、代码审查清单 (v3.0 更新)
|
||||
|
||||
### 17.1 表单开发审查
|
||||
|
||||
@@ -1143,7 +1272,7 @@ feat(<scope>): <description> (vX.Y+)
|
||||
|
||||
---
|
||||
|
||||
## 十八、附录: 权威源速查
|
||||
## 十九、附录: 权威源速查
|
||||
|
||||
### 18.1 项目级文档
|
||||
|
||||
@@ -1195,16 +1324,15 @@ feat(<scope>): <description> (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(<scope>): <description> (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 镜像架构.
|
||||
>
|
||||
|
||||
Reference in new issue
Block a user