link-skills

Link 产品全链路开发技能

技能概述

本技能为 link CRM+AI 企业级微服务系统提供全生命周期开发指导。link 系统基于 Java 8 + Spring Boot 2.1 + Spring Cloud Greenwich 构建，包含 8 个微服务模块，覆盖 CRM 业务、AI 助手、认证授权、API 网关等核心能力。

适用场景

• 为 link 系统开发新功能模块（CRM 业务、AI 助手、知识库等）
• 设计新接口或修改现有接口
• 数据库表设计与变更
• 代码编写与审查（需遵循 link 编码规范）
• 测试验证与部署上线
• 线上问题排查与运维操作
• 企微/微信集成开发
• AI 能力集成（Coze、火山引擎 HiAgent）

项目快速索引

全链路工作流

收到 link 开发需求后，按以下五阶段顺序执行。每个阶段产出作为下一阶段输入。

阶段一：需求分析

目标：明确需求边界、验收标准和影响范围。

执行步骤：

1. 解析需求，确定涉及的模块（link-ai / link-base / link-gateway 等）
2. 识别需求类型：
   • 新功能开发 → 需完整走五阶段
   • 接口新增/修改 → 重点关注阶段二、三
   • Bug 修复 → 跳至阶段三（定位+修复），再走阶段四验证
   • 运维操作 → 直接走阶段五
3. 确认验收标准（功能点清单、接口契约、性能要求）
4. 评估影响范围（涉及哪些模块、表、接口、配置）
5. 识别约束条件（link-core 框架限制、Checkstyle 规范、签名过滤器等）

产出：需求分析摘要（需求描述 + 验收标准 + 影响范围 + 约束条件）

参考文档：加载 references/project-architecture.md 了解模块划分和技术栈

阶段二：方案设计

目标：完成技术方案、数据库设计和接口设计。

2.1 技术方案设计

1. 确定功能归属模块（按业务域划分）
2. 设计分层架构：Controller → Service → DAO(MyBatis) → Model
3. 识别跨服务调用需求（Feign 客户端）
4. 评估是否需要消息队列（Kafka）、缓存（Redis）、搜索（ES）
5. 确定配置项（Apollo namespace 规划）

参考文档：加载 references/project-architecture.md 了解架构细节

2.2 数据库设计

1. 表命名：LNK_ 前缀 + 大写下划线（如 LNK_KB_DOCUMENT）
2. 字段命名：大写下划线（如 DOCUMENT_NAME、CREATE_TIME）
3. 必备字段：ID（主键）、CREATED_BY、CREATION_DATE、LAST_UPDATED_BY、LAST_UPDATE_DATE、OBJECT_VERSION_NUMBER（乐观锁）
4. 设计 MyBatis Mapper 接口（继承 BasicMapper）和 XML 映射文件
5. 多数据源考量：业务数据 → linkbase，管理数据 → linkadmin，分析数据 → ClickHouse

特殊模式 — 数据中转：link-ai 知识库模块不落本地库，Service 层直接代理第三方 API。如需求涉及知识库，参考此模式。

参考文档：加载 references/database-guide.md 了解数据库设计规范和 MyBatis 模式

2.3 接口设计

1. 路由设计：
   • 服务内：/link/{module}/{resource}/{action}（如 /link/aiAssistant/kbDocument/queryPage）
   • 网关层：/linkcrm/{module}/{resource}/{action}（网关 StripPrefix=1）
2. 请求方式：统一 @RequestMapping（不限定 method），参数用 @JsonParam 接收 JSON 请求体
3. 响应格式：统一信封

   {
     "success": true,
     "code": "200",
     "result": {},
     "rows": [],
     "total": 100,
     "detailMessage": ""
   }
   

4. 错误码设计：参考 references/api-design-guide.md 中的错误码体系
5. Swagger 文档：Controller 使用 @Api(tags={"xxx接口"}) 注解

参考文档：加载 references/api-design-guide.md 了解完整接口设计规范

产出：方案设计文档（技术方案 + 表结构 DDL + 接口契约 + 文件清单）

阶段三：编码开发

目标：基于 link 标准编写代码，通过 Checkstyle 校验。

3.1 创建文件结构

每个业务域严格三层分包：

src/main/java/com/link/{module}/{domain}/
├── controller/        # XxxController extends BasicController
├── service/           # XxxService(接口) + XxxServiceImpl extends BasicServiceImpl
├── dao/mybatis/
│   ├── mapper/        # XxxMapper extends BasicMapper
│   └── sqlMap/        # XxxMapper.xml + XxxMapperMySql.xml
└── model/             # Xxx extends BasicModel

3.2 代码模板

使用 assets/templates/ 下的模板创建新文件：

• Controller.java → 复制为 {Name}Controller.java
• Service.java → 复制为 {Name}Service.java
• ServiceImpl.java → 复制为 {Name}ServiceImpl.java
• Mapper.java → 复制为 {Name}Mapper.java
• MapperMySql.xml → 复制为 {Name}MapperMySql.xml
• Model.java → 复制为 {Name}.java

模板中使用 {Name}、{name}、{module}、{domain}、{table} 作为占位符，替换为实际值。

3.3 编码规范要点

加载 references/coding-standards.md 获取完整规范。关键红线：

3.4 特殊开发场景

AI 对话集成（Coze）：

• 参考 com.link.coze 包结构
• 非流式：直接调用 Coze API
• 流式：使用 WebFlux + SSE

火山引擎 HiAgent：

• 参考 com.link.hiagent 包结构
• 含工作流调用、ASR 语音识别

WebSocket 实时通信：

• 路径：/websocket/ai
• 基于 Netty + link-websocket-starter

企微集成：

• 参考 com.link.base.tencent.corpwx 包结构
• 通讯录同步、外部联系人、应用消息

知识库数据中转：

• 参考 com.link.base.knowledge 包结构
• Service 层代理第三方 API，不落本地库
• Token 通过 RSA 公钥加密自动注入

参考文档：加载 references/coding-standards.md 获取完整编码规范和代码模式

3.5 一致性自检

代码编写完成后执行以下检查：

1. Checkstyle 合规：逐条对照 references/coding-standards.md 中的 Checkstyle 规则
2. 分层完整性：Controller → Service → Mapper → Model 四层是否齐全
3. 命名一致性：类名、表名、路由路径是否对应
4. XML 映射：Mapper 接口方法与 XML SQL ID 是否一一对应
5. 依赖注入：@Resource 注入 Service，禁止 @Autowired（link 约定）
6. 异常处理：Controller 层 try-catch BasicServiceException + Exception 双层
7. Swagger 注解：@Api + @ApiOperation 完整

产出：代码文件清单 + 一致性自检报告

阶段四：测试部署上线

目标：验证功能正确性，完成部署上线。

4.1 测试验证

link 项目测试现状：单元测试极少（maven-surefire-plugin skip=true），主要依赖手动测试。

测试策略：

1. 接口冒烟测试：使用 curl 命令测试每个接口
   • 注意：link 框架入站签名过滤器会导致直接 curl 返回 475
   • 解决方案：通过网关访问，或参考 references/testing-guide.md 中的签名头配置
2. 数据库验证：执行 SQL 确认数据正确性
3. 日志检查：查看 logs/ 目录下的应用日志
4. Swagger 验证：访问 /swagger-ui.html 确认接口注册

参考文档：加载 references/testing-guide.md 了解测试方法和签名绕过方案

4.2 构建打包

# 进入对应模块目录
cd D:\develop\code\cdfai\link-ai  # 或其他模块

# Maven 打包（跳过测试）
mvn clean package -DskipTests

注意：需要配置 settings.xml（阿里云镜像 + 内部 Nexus 仓库认证），link-core 等私有依赖从内部 Nexus 拉取。

4.3 Docker 镜像构建

# 多阶段构建
docker build -f Dockerfile -t cdfai/link-{module}:{version} .

Dockerfile 模式：Stage 1 Maven 构建 → Stage 2 运行时（基于 choerodon-tools/javabase:0.8.0）

4.4 K8s 部署

1. 更新 Helm Chart values（charts/link-{module}/values.yaml）
2. 配置项：
   • 副本数、资源限制（requests/limits）
   • JVM 参数（G1GC，Xms/Xmx）
   • 数据库/Redis/Kafka 连接配置
   • Apollo 配置中心 namespace
3. 部署命令：

   helm upgrade --install link-{module} ./charts/link-{module} -n {namespace}
   

4. 健康检查：startupProbe / readinessProbe / livenessProbe（TCP 探针）

参考文档：加载 references/deployment-guide.md 了解完整部署流程

4.5 上线验证

1. 服务注册确认（Eureka 注册成功）
2. 网关路由可达性验证
3. 接口功能冒烟测试
4. 日志无异常 ERROR
5. 监控告警配置确认

产出：测试报告 + 部署确认 + 上线验证清单

阶段五：运维与后续

目标：保障系统稳定运行，快速响应线上问题。

5.1 日常运维

1. 日志监控：Log4j2 + Graylog GELF，关注 ERROR 级别日志
2. 配置变更：通过 Apollo 配置中心热更新（namespaces: ops / biz / stability）
3. 定时任务：XXL-JOB 管理（端口 8025），关注任务执行状态
4. 数据库运维：MySQL 主从同步、Redis 集群健康、ES 索引状态

5.2 故障排查

加载 references/troubleshooting.md 获取已知问题和解决方案。

常见问题快速索引：

5.3 性能优化

1. 数据库：EXPLAIN 分析慢查询，索引优化
2. 缓存：Redis 缓存热点数据，注意缓存一致性
3. JVM：G1GC 调优，关注 GC 日志
4. 连接池：Druid 监控（gateway），MyBatis 连接池配置
5. K8s：HPA 自动扩缩容，资源限制调优

5.4 安全检查

1. SQL 注入：检查 MyBatis XML 中 ${} 使用
2. 敏感信息泄露：异常信息不返回前端
3. Fastjson 漏洞：评估 AutoType 配置
4. 签名校验：确保入站请求签名有效
5. 权限控制：接口鉴权（link-auth 服务）

产出：运维操作记录 + 故障排查报告 + 优化建议

参考文档索引

代码模板索引

使用建议

1. 新功能开发：从阶段一开始，依次走完五阶段
2. 接口开发：重点参考阶段二（接口设计）和阶段三（编码），使用代码模板
3. Bug 修复：直接进入阶段三（定位修复）→ 阶段四（验证）
4. 部署上线：重点参考阶段四的构建打包和 K8s 部署
5. 运维排查：直接进入阶段五，参考故障排查文档
6. 每次使用时：根据当前阶段加载对应的 references/ 文档，避免一次性加载所有文档