# KnowledgeInsight_Manager **Repository Path**: CmbTestWorker/knowledge-insight-manager ## Basic Information - **Project Name**: KnowledgeInsight_Manager - **Description**: No description available - **Primary Language**: Java - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-11-17 - **Last Updated**: 2026-11-18 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # knowledge-insight-manager 知识数据中台的 Java 平台管理服务(platform-admin):空间、成员、产品、文档版本、发布指针、任务调度、对象凭证、配额与审计,首版为模块化单体。 ## 设计文档 服务设计文档已归入本仓库 [`docs/`](docs/README.md): | 文档 | 内容 | | --- | --- | | [00-实现方案](docs/00-实现方案.md) | 单 Maven 工程、DDD 四层、业务包、事务边界、实施步骤与验收 | | [07-平台管理服务](docs/07-平台管理服务.md) | 资源与 API、文档生命周期、发布事务、任务调度、对象存储凭证、配额审计(配额二期)、内部接口与测试 | 上游文档:[01-总体设计与原则](../knowledge-insight-core/docs/01-总体设计与原则.md)、[02-数据模型](../knowledge-insight-core/docs/02-数据模型.md)、[09-工程规范与测试](../knowledge-insight-core/docs/09-工程规范与测试.md);对外入口见 [06-网关服务](../knowledge-insight-gateway/docs/06-网关服务.md)。 ## 技术栈 - JDK 21 + Spring Boot 4(MVC + 虚拟线程) - MySQL 8.4(唯一业务状态权威)、内网 COS(endpoint/AK/SK/bucket 可配)、outbox + 轮询调度 - 任务模型:`processing_job` 租约领取、回调校验、失败回收 ## 状态 **P0–P4 核心已落地;P5 外部接入/治理第一批已落地**: - Spring Boot 4 MVC + Java 21 虚拟线程、MyBatis、MySQL 初始 schema; - 统一错误模型、`request_id`、健康检查、Maven Wrapper、ArchUnit; - 空间、成员、产品、`documents:batch`、scope 文档查询; - 文档创建、pending revision、上传凭证、上传确认、原始文件下载、ingest job 创建; - job payload / attempt start、完成回调、构建 ready、发布指针、outbox 与审计; - 过期租约回收(60s 扫描,最多 3 次); - 文档改名、下架、任务列表/重试; - 图 scope 水位更新、graph job 调度、generation 启停、active generation 切换; - API Key 创建/列表/撤销/校验、审计查询、用量汇总、Outbox 拉取/确认、可配置 webhook 自动投递; - 外部 `/api/**` 与内部 `/internal/admin/**` 可选 HMAC 验签。 > 当前身份可用开发态 `X-Principal-Id`;Manager 已实现可选外部 HMAC(`MANAGER_HMAC_ENABLED`)和内部服务 HMAC(`MANAGER_INTERNAL_AUTH_ENABLED`),默认关闭。Gateway/Worker 侧签名尚未接入,`/internal/dev/**` 仍未保护。对象存储是本地 dev 实现,真实内网 COS adapter 尚未接入;尚未与真实 Core Worker 联调。P4 的真实 ES/COS 清理执行、P5 的 Gateway API Key 认证接入、压测和交付演练仍未完成。当前只用于本地/受控联调,禁止直接暴露到不可信网络;G1 接入网关签名后再替换。 ### 本地运行 1. 准备 MySQL 8.4,执行 [schema.sql](src/main/resources/db/schema.sql)。 2. 至少插入一个 `principal`;空间创建者会自动成为该空间 ADMIN。 3. 设置 `DB_URL`、`DB_USERNAME`、`DB_PASSWORD`,启动: ```bash ./mvnw spring-boot:run curl http://127.0.0.1:8081/health/live curl http://127.0.0.1:8081/health/ready # P1 API(X-Principal-Id 仅本地开发态使用) curl -H 'X-Principal-Id: 1' http://127.0.0.1:8081/api/v1/namespaces # P2:创建文档,返回 upload.url / fields / revisionId curl -X POST -H 'Content-Type: application/json' -H 'X-Principal-Id: 1' \ -d '{"productId":1,"title":"示例文档"}' \ http://127.0.0.1:8081/api/v1/namespaces/demo/documents # 本地 dev 存储:把文件 PUT 到返回的 upload.url curl -X PUT -H 'Content-Type: text/markdown' \ --data-binary @README.md '' # 上传确认(sha256/sizeBytes 由客户端计算,服务端与对象存储校验) curl -X POST -H 'Content-Type: application/json' -H 'X-Principal-Id: 1' \ -d '{"revisionId":1,"sha256":"","sizeBytes":1234}' \ http://127.0.0.1:8081/api/v1/namespaces/demo/documents/1/upload-complete ``` 测试: ```bash ./mvnw test ``` Testcontainers 集成测试需要可用的 Docker socket;本机没有 Docker socket 时会自动跳过,单元测试与架构测试仍会执行。P0–P5 已另用本地 MySQL 做 schema 与 HTTP 冒烟。 DDL 以 [02-数据模型 §2](../knowledge-insight-core/docs/02-数据模型.md) 为唯一事实来源,发布与任务规则见 [07 §4–5](docs/07-平台管理服务.md)。