2026Technology-Competition/_DEVELOPMENT_GUIDE.md

指摘管理系统 · 开发指南

1. 当前已完成（master 骨架）

后端

组件	状态	说明
Maven 多模块结构	✅	ims-common / ims-api / ims-service / ims-web
数据库表 & Flyway 迁移	✅	22 张表，7 个迁移脚本
JPA Entity + Repository	✅	22 Entity + 22 Repository
Spring Security + JWT	✅	登录接口真实实现
所有 Controller 定义	✅	11 个 Controller，接口签名已定义
统一返回结构	✅	ApiResponse / PageResult / 全局异常处理
CRUD DTO 类	✅	26 个请求/响应类
docker-compose	✅	PostgreSQL+pgvector / Redis / MinIO
配置文件	✅	application.yml / dev / prod

前端

组件	状态	说明
Vite + React + TypeScript	✅	项目初始化
Ant Design 主题	✅	品牌色、圆角已配置
路由表	✅	全部 13 个页面路由 + 懒加载 + 路由守卫
登录页	✅	表单 + API 调用 + token 存储 + 跳转
全局 Layout	✅	侧边栏菜单树 + 顶栏（用户/通知）
axios 封装	✅	请求拦截器（自动带 token）+ 响应拦截器（401 跳登录）
Redux Store	✅	auth slice + 各模块 slice 空壳

---

2. 开发流程

两阶段

Phase 1（你 ─ 当前阶段）
  master
  └── 实现知识库模块（后端 Service + 前端页面）
      完成后合并到 master，通知其他组

Phase 2（各组 ─ 知识库完成后）
  master（含知识库模块）
  ├── feature/group1   指摘 CRUD + 工作台 + 驾驶舱
  ├── feature/group2   批量录入 + 系统管理
  └── feature/group3   AI 分析 + Prompt + Agent
      各组从 master 拉分支 → 独立开发 → PR → 合入 master

分支策略

master ── 骨架 + 知识库模块，各组以此为基线
  ├── feature/group1
  ├── feature/group2
  └── feature/group3

合并规则

阶段	操作
日常开发	各组在自己分支上提交，不往 master 推
功能完成	发起 Pull Request，指定 reviewer 审核
审核通过	通过 PR 合入 master，禁止直接 push

不冲突保障

各组修改范围完全不重叠：

backend/ims-api/src/main/java/com/ims/api/controller/
  ├── IssueController.java          ← 一组
  ├── UserController.java           ← 二组
  ├── KnowledgeController.java      ← 你
  ├── AiAnalysisController.java     ← 三组
  └── ...其余 Controller 同理       ← 各组对应

frontend/src/pages/
  ├── issues/          ← 一组
  ├── dashboard/       ← 一组
  ├── batch-input/     ← 二组
  ├── ai-analysis/     ← 三组
  ├── knowledge-base/  ← 你
  └── system/          ← 二组

backend/ims-service/src/main/java/com/ims/service/
  ├── entity/          ← 仅 master 改，各组不能动
  ├── repository/      ← 仅 master 改，各组不能动
  └── security/        ← 仅 master 改，各组不能动

核心原则：Entity 和 Repository 是共享契约，任何人不得修改 master 上的 Entity 字段和 Repository 方法签名。

---

3. 各组分工

高优先级功能定义

优先级	功能	说明
P0	批量上传	历史评审数据与新增数据的快速录入
P0	AI 自动分析	针对上传数据实时提取风险点、改进项
P1	问题一览管理	对 AI 分析结果统一管理，支持进度追踪
P1	基础仪表盘	图表展示质量趋势与风险分布
P1	对策状况登记	针对问题登记解决方案，含负责人与期限

优先级 vs 现有模块映射

优先级	对应模块	归属
P0 批量上传	批次录入 + 导入导出	二组
P0 AI 自动分析	AI 智能分析	三组
P1 问题一览管理	指摘列表 + 详情	一组
P1 基础仪表盘	工作台	一组
P1 对策状况登记	指摘状态流转 + 编辑	一组

你 — 知识库模块（Phase 1 实施人）

前置依赖：无

#	任务	涉及文件	说明
1	文档上传 API	KnowledgeController + KnowledgeService	接收文件，存入 MinIO，记录到 knowledge_documents
2	文档解析 + 切片	DocumentParserService	使用 Apache Tika 解析 PDF/Word/TXT，按 500 Token 切片
3	向量化 + 写入 pgvector	VectorizationService	调用 Ollama nomic-embed-text 向量化，写入 knowledge_chunks
4	语义检索	SearchService	向量化 → pgvector 余弦相似度检索 → 重排序
5	检索审计	SearchLogService	记录每次检索的 query、耗时、命中数
6	知识库管理页面	frontend/pages/knowledge-base/	文档列表、上传、删除、重新向量化
7	EmbeddingService 接口	ims-service 新增	供三组调用

EmbeddingService 接口契约（供三组调用）：

public interface EmbeddingService {
    List<Float> embed(String text);
    List<SearchResult> search(String query, int topK);
}

一组 — 指摘 CRUD + 工作台 + 驾驶舱

前置依赖：等 master 含知识库后拉分支

#	任务	前端页面	后端接口
1	指摘列表查询	issues/list.tsx	GET /api/v1/issues
2	创建指摘	issues/new.tsx	POST /api/v1/issues
3	指摘详情	issues/detail.tsx	GET /api/v1/issues/{id}
4	编辑指摘	issues/edit.tsx	PUT /api/v1/issues/{id}
5	状态流转	详情页内	PATCH /api/v1/issues/{id}/status
6	附件管理	详情页内	POST /issues/{id}/attachments
7	工作台仪表盘	dashboard/index.tsx	GET /api/v1/dashboard/stats
8	通知	顶栏铃铛	GET /api/v1/notifications
9	Agent 指令	工作台 + 详情页	POST /api/v1/agent/execute
10	Agent 审批	详情页	POST /api/v1/agent/approval/*

二组 — 批量录入 + 系统管理

前置依赖：等 master 含知识库后拉分支

#	任务	前端页面	后端接口
1	批量导入 Excel	batch-input/index.tsx	POST /api/v1/import/excel
2	模板下载	批量录入页	GET /api/v1/import/template
3	用户管理	system/users.tsx	GET/POST /api/v1/users
4	部门树	用户管理页	GET /api/v1/departments
5	角色权限	system/roles.tsx	GET/POST /api/v1/roles
6	系统日志	system/logs.tsx	GET /api/v1/logs
7	Agent 管理	system/agent-admin.tsx	GET/PUT /api/v1/agent/config
8	Prompt 模板管理	Agent 管理页内	GET/POST /api/v1/prompts
9	AI 配置管理	Agent 管理页内	GET/PUT /api/v1/ai/config

三组 — AI 分析 + Prompt 引擎 + Agent 核心

前置依赖：

• 等知识库模块的 EmbeddingService 接口就绪后对接
• 可以先写 Mock 实现，不阻塞开发

#	任务	前端页面	后端实现
1	AI 分析列表	ai-analysis/index.tsx	GET /api/v1/ai/records
2	批量生成分析	AI 分析页	POST /api/v1/ai/batch-generate
3	分析反馈	分析详情	POST /api/v1/ai/records/{id}/feedback
4	Prompt 模板引擎	—	PromptTemplateEngine
5	Prompt 格式适配	—	PromptFormatter
6	Spring AI 集成	—	AiProviderConfig
7	模型切换 + 容错	—	ModelRoutingService
8	Agent ReAct 循环	—	AgentOrchestrator
9	Agent 长期记忆	—	MemoryService
10	工具注册中心	—	ToolRegistry

---

4. 开发约定

后端

• Service 类放在 com.ims.service.{模块名}，接口在 ims-api，实现在 ims-service
• 类名格式：{模块名}Service
• API 路径（已定义，不要修改）：

  /api/v1/issues       ← 一组
  /api/v1/users        ← 二组
  /api/v1/knowledge    ← 你
  /api/v1/ai           ← 三组
  /api/v1/agent        ← 一组
  /api/v1/prompts      ← 三组
  

前端

• 统一使用 src/request.ts 的 axios 实例
• 组件 PascalCase 命名

数据库

• Entity 字段任何人不得修改
• 如需新增字段，加 Flyway 迁移脚本（版本号格式 V{版本}__{说明}.sql），通知其他组

代码风格

• Java：Lombok @Data / @Builder，不写注释
• TypeScript：使用类型定义，避免 any

---

5. 启动指南

# 1. 启动数据库
docker compose up -d

# 2. 编译后端
cd backend
mvn install -DskipTests

# 3. 启动后端（端口 8080）
mvn spring-boot:run -pl ims-web -am

# 4. 启动前端（新开终端）
cd frontend
npm install && npm run dev

# 5. 浏览器打开 http://localhost:5173，用 admin / Admin@2026 登录

---

6. 知识库模块详细设计

6.1 数据流

用户上传文档 (PDF/Word/TXT/MD)
    ↓
KnowledgeController.upload()
    ↓
MinIO 存储源文件 → knowledge_documents 记录
    ↓
DocumentParserService 解析文本 (Tika)
    ↓
TextSplitter 切片 (500 Token, 10% 重叠)
    ↓
VectorizationService
    ├── Ollama nomic-embed-text 向量化
    └→ 每个切片写入 knowledge_chunks (content + embedding)
    ↓
knowledge_documents.status = 'completed'

6.2 检索流程

用户输入 query
    ↓
SearchService.search(query, topK)
    ├── EmbeddingModel.embed() 将 query 转为向量
    ├── pgvector 余弦相似度检索 (IVFFlat)
    └→ 返回 Top K 结果
    ↓
SearchLogService 记录审计日志

---

7. 常见问题

Q: 我改了 Entity 字段，别人不知道怎么办？ A: 不要改。如需加字段，在群里通知所有人后各自 rebase。

Q: 前端页面路由冲突怎么办？ A: 路由表已按路径隔离，各组只关心自己的页面路径。

Q: 后端编译报错怎么办？ A: 先 mvn clean compile 检查。确认是 master 问题则在群里反馈。