auto(11bf28807ce8): session end @ 2026-07-03T16:10:49 (+1f)

This commit is contained in:
ssw committed 2026-07-03 16:10:49 +08:00
1 parent 395d6534e1
commit 47769f3de3
1 file changed
+142 -14
+142 -14
View File
@@ -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 镜像架构.
>