EvoCode 数据字典（字段级）¶

16 张表全部字段：类型 / 必填 / 默认 / 说明 / 示例版本：v1.0 · 2026-08-10 · 与《开发指导》§5 DDL（V001-V007）一一对应

使用说明：实现实体类、DTO 映射、前端类型时的查表工具。字段"来源"列标注该字段由谁写入（用户/后端/analyzer/AI）。

1. 通用约定¶

项	约定
主键	`BIGSERIAL` 自增，命名 `id`
时间	`TIMESTAMPTZ`；实体统一 `LocalDateTime`（UTC 存储，展示层转本地）
逻辑删除	仅 `project` / `analysis` 含 `deleted SMALLINT DEFAULT 0`（MyBatis Plus 全局逻辑删除）；其余快照/明细表按 analysis_id 重建或随项目级联删除，无 deleted 列
枚举	`VARCHAR(20)` 存短码，全大写；前端展示映射在组件层
JSONB	MyBatis Plus 用 `JacksonTypeHandler` + `autoResultMap = true`
命名	snake_case 字段 ↔ camelCase 实体（map-underscore 开启）
审计	`created_at` 自动填充（MetaObjectHandler），`updated_at` 更新时间

2. 表清单¶

表	版本	用途	关键索引
project	V001	项目档案	(deleted),(status)
analysis	V001	分析任务（状态机）	(project_id, id DESC)
file_node	V001	扫描快照/项目地图	(project_id, analysis_id)
dependency	V009	依赖与版本风险	(project_id, analysis_id)
analysis_report	V010	报告拆表（health_score/level/summary 列化 + report_json 完整保留）	(analysis_id) UNIQUE, (health_score)
quality_issue	V002	质量 issue + AI 解释	(project_id, analysis_id)
architecture_node	V003	架构节点	(project_id, analysis_id)
architecture_edge	V003	调用/依赖关系	(source_node_id, target_node_id)
arch_violation	V003	架构违规	(project_id, analysis_id)
commit_stat	V004	git 提交明细	(project_id, analysis_id)
file_change_stat	V004	文件变更聚合/热点	(project_id, analysis_id)
tech_debt	V005	技术债 issue	(project_id, status)
generated_doc	V005	生成文档	(project_id)
chat_session	V006	会话	(project_id, created_at DESC)
chat_message	V006	消息	(session_id, id)
knowledge_chunk	V006	RAG 知识块（向量）	(project_id, analysis_id) + HNSW
hotspot	V007	演化热点落库	(project_id, analysis_id)

3. 逐表字段¶

3.1 project（项目）¶

字段	类型	必填	默认	说明	来源	示例
id	bigint	✓	—	主键	系统	1
name	varchar(100)	✓	—	项目名	用户	Chatez
description	text		null	描述	用户	null
source_type	varchar(10)	✓	—	ZIP / GIT	系统	GIT
repo_url	varchar(500)		null	仓库地址	用户	https://github.com/…
storage_path	varchar(500)	✓	—	磁盘目录 data/projects/{id}	系统	data/projects/1
status	varchar(20)	✓	CREATED	CREATED/ANALYZING/READY/FAILED	系统	READY
lang_stats	jsonb		null	语言占比 {"Java":61.2}	analyzer	{"Java":61.2,"JavaScript":30.4}
framework_tags	varchar(100)[]		null	框架标签数组	analyzer	{Spring Boot,Vue}
loc_total	bigint		null	代码总行数	analyzer	20431
file_count	int		null	文件数	analyzer	412
ignored_count	int		null	被忽略文件数	analyzer	88
last_analyzed_at	timestamptz		null	最近成功分析时间	系统	2026-08-10T10:00:00Z
created_at	timestamptz	✓	now()	创建时间	系统	—
updated_at	timestamptz	✓	now()	更新时间	系统	—
deleted	smallint	✓	0	逻辑删除	系统	0

3.2 analysis（分析任务）¶

字段	类型	必填	默认	说明	来源	示例
id	bigint	✓	—	主键	系统	10
project_id	bigint	✓	—	FK→project	系统	1
type	varchar(20)	✓	FULL	FULL/QUALITY/ARCH/EVOLUTION	用户	FULL
status	varchar(20)	✓	PENDING	PENDING/RUNNING/SUCCEEDED/FAILED/CANCELLED	系统	SUCCEEDED
progress	int	✓	0	0-100	系统	100
stage	varchar(30)		null	QUEUED/SCAN/SCAN_DONE/REPORT/DONE	系统	DONE
error_code	varchar(10)		null	3xxx 细分（SCAN_TIMEOUT 等）	系统	null
error_message	text		null	失败原因	系统	null
report_json	jsonb		null	报告全文（LLM/RULES）——SPI-6 拆表后新报告写入 analysis_report，本列仅存量兼容	analyzer	见 §5.2
report_source	varchar(10)		null	报告来源 LLM/RULES（与 data.source 一致，V001）	系统	RULES
prompt_version	varchar(20)		null	生成报告所用 prompt 版本（V001）	系统	report-1.2
analyzer_version	varchar(20)		null	生成报告的分析器版本	系统	0.1.0
regenerated_at	timestamptz		null	最近一次重新生成时间	系统	null
started_at	timestamptz		null	开始时间	系统	—
finished_at	timestamptz		null	结束时间	系统	—
created_at	timestamptz	✓	now()	创建时间	系统	—
deleted	smallint	✓	0	逻辑删除	系统	0

3.3 file_node（文件快照）¶

字段	类型	必填	默认	说明	来源
id	bigint	✓	—	主键	系统
project_id	bigint	✓	—	FK→project	系统
analysis_id	bigint	✓	—	FK→analysis	系统
path	text	✓	—	相对项目根路径	analyzer
language	varchar(30)		null	语言（OTHER=未识别）	analyzer
loc	int		null	代码行数	analyzer
size_bytes	int		null	文件大小	analyzer
created_at	timestamptz	✓	now()	创建时间	系统

无 deleted 字段（快照数据，随 analysis 重建）；示例：("src/main/java/com/chatez/service/UserService.java","Java",180,4210)

3.4 dependency（依赖）¶

字段	类型	必填	默认	说明	来源
id	bigint	✓	—	主键	系统
project_id	bigint	✓	—	FK→project	系统
analysis_id	bigint	✓	—	FK→analysis	系统
ecosystem	varchar(20)	✓	—	maven/npm/pip/go	analyzer
name	varchar(200)	✓	—	组件名	analyzer
version	varchar(50)		null	当前版本	analyzer
latest_version	varchar(50)		null	最新版本	analyzer/规则
risk_level	varchar(10)		null	LOW/MEDIUM/HIGH；null=未命中规则（未知版本，不误报）	analyzer
risk_reason	text		null	风险原因（EOL 等）	analyzer
suggestion	text		null	升级建议	analyzer
file	varchar(100)		null	来源文件（pom.xml / package.json）	analyzer
is_eol	boolean	✓	FALSE	是否 EOL	analyzer
ai_advice	jsonb		null	AI 升级建议 {impact,steps,risks,estimate}	AI
ai_status	varchar(10)	✓	NONE	NONE/PENDING/DONE/FAILED	系统
created_at	timestamptz	✓	now()	—	系统

3.5 quality_issue（质量 issue）¶

字段	类型	必填	默认	说明	来源
id	bigint	✓	—	主键	系统
project_id	bigint	✓	—	FK→project	系统
analysis_id	bigint	✓	—	FK→analysis	系统
source	varchar(20)	✓	—	SONAR	analyzer
severity	varchar(10)	✓	—	BLOCKER/CRITICAL/MAJOR/MINOR/INFO	analyzer
kind	varchar(20)	✓	—	BUG/VULNERABILITY/SMELL	analyzer
rule_key	varchar(100)		null	Sonar 规则键	analyzer
file_path	text		null	文件路径	analyzer
line	int		null	行号	analyzer
message	text		null	原始消息	analyzer
ai_explanation	text		null	AI 解释"为什么是问题"	AI
ai_suggestion	text		null	AI 建议"怎么改"	AI
ai_status	varchar(10)	✓	PENDING	PENDING/DONE/FAILED	系统
status	varchar(10)	✓	OPEN	OPEN/IGNORED/FIXED	用户/系统
created_at	timestamptz	✓	now()	—	系统

3.6 architecture_node（架构节点）¶

字段	类型	必填	默认	说明	来源
id	bigint	✓	—	主键	系统
project_id	bigint	✓	—	FK→project	系统
analysis_id	bigint	✓	—	FK→analysis	系统
node_key	varchar(300)	✓	—	唯一标识（如全限定类名）	analyzer
name	varchar(200)	✓	—	短名	analyzer
node_type	varchar(20)	✓	—	CONTROLLER/SERVICE/REPOSITORY/ENTITY/UTIL/MODULE/OTHER	analyzer
file_path	text		null	所在文件	analyzer
metrics	jsonb		null	{inDegree,outDegree,depCount}	analyzer
created_at	timestamptz	✓	now()	—	系统

3.7 architecture_edge（关系）¶

字段	类型	必填	默认	说明	来源
id	bigint	✓	—	主键	系统
project_id	bigint	✓	—	FK→project	系统
analysis_id	bigint	✓	—	FK→analysis	系统
source_node_id	bigint	✓	—	FK→architecture_node	系统
target_node_id	bigint	✓	—	FK→architecture_node	系统
relation	varchar(20)	✓	—	CALL/IMPORT/DEPEND	analyzer
created_at	timestamptz	✓	now()	—	系统

3.8 arch_violation（架构违规）¶

字段	类型	必填	默认	说明	来源
id	bigint	✓	—	主键	系统
project_id	bigint	✓	—	FK→project	系统
analysis_id	bigint	✓	—	FK→analysis	系统
violation_type	varchar(40)	✓	—	LAYER_VIOLATION/CYCLE/GOD_CLASS/…	analyzer
description	text		null	违规说明	analyzer
source_node_id	bigint		null	FK→node	系统
target_node_id	bigint		null	FK→node	系统
severity	varchar(10)	✓	—	HIGH/MEDIUM/LOW	analyzer
suggestion	text		null	建议	analyzer
created_at	timestamptz	✓	now()	—	系统

3.9 commit_stat（提交明细）¶

字段	类型	必填	默认	说明	来源
id	bigint	✓	—	主键	系统
project_id	bigint	✓	—	FK→project	系统
analysis_id	bigint	✓	—	FK→analysis（P5 实现维度，同 arch_*）	系统
commit_hash	varchar(40)	✓	—	git 哈希（实际存 %h 短哈希）	analyzer
author_name	varchar(100)		null	作者名	analyzer
author_email	varchar(200)		null	作者邮箱	analyzer
committed_at	timestamptz	✓	—	提交时间	analyzer
lines_added	int	✓	0	新增行	analyzer
lines_removed	int	✓	0	删除行	analyzer
files_changed	int	✓	0	变更文件数	analyzer
message	text		null	提交信息	analyzer
created_at	timestamptz	✓	now()	—	系统

3.10 file_change_stat（文件变更聚合）¶

P5 实现注：以 analysis_id 维度落库（同 arch_* 先例）；仅聚合 commit_count/lines_added/lines_removed，未实现 first/last_changed_at 与 risk_score（热点判定在 analyzer 规则侧，risk_score 留待 v1.0 演化）。

字段	类型	必填	默认	说明	来源
id	bigint	✓	—	主键	系统
project_id	bigint	✓	—	FK→project	系统
analysis_id	bigint	✓	—	FK→analysis	系统
file_path	text	✓	—	文件路径（UNIQUE with analysis_id）	analyzer
commit_count	int	✓	0	变更次数	analyzer
lines_added	int	✓	0	累计新增	analyzer
lines_removed	int	✓	0	累计删除	analyzer
created_at	timestamptz	✓	now()	—	系统

3.11 tech_debt（技术债）¶

字段	类型	必填	默认	说明	来源
id	bigint	✓	—	主键	系统
project_id	bigint	✓	—	FK→project	系统
source	varchar(30)	✓	—	ARCH/QUALITY/DEPEND/EVOLUTION/AI_DOCTOR/MANUAL	系统/用户
title	varchar(200)	✓	—	标题	系统
level	varchar(10)	✓	—	HIGH/MEDIUM/LOW	系统
description	text		null	详情	系统
suggestion	text		null	建议	系统
status	varchar(10)	✓	OPEN	OPEN/DOING/DONE/WONTFIX	用户
ref_analysis_id	bigint		null	关联分析	系统
resolve_note	text		null	DONE 验证说明	用户
wonfix_reason	text		null	WONTFIX 必填原因	用户
created_at	timestamptz	✓	now()	—	系统
resolved_at	timestamptz		null	关闭时间	系统

3.12 generated_doc（生成文档）¶

字段	类型	必填	默认	说明	来源
id	bigint	✓	—	主键	系统
project_id	bigint	✓	—	FK→project	系统
doc_type	varchar(20)	✓	—	README/ARCH/API	系统
title	varchar(200)	✓	—	标题	AI/用户
content	text	✓	—	Markdown 内容	AI/用户
version	int	✓	1	编辑版本递增	系统
edited	boolean	✓	FALSE	是否人工修改过	系统
created_at	timestamptz	✓	now()	—	系统

3.13 chat_session（会话）¶

字段	类型	必填	默认	说明	来源
id	bigint	✓	—	主键	系统
project_id	bigint	✓	—	FK→project	系统
title	varchar(200)	✓	新会话	标题（首条消息后 AI 自动生成）	AI
created_at	timestamptz	✓	now()	—	系统
deleted	smallint	✓	0	逻辑删除（@TableLogic）	系统

3.14 chat_message（消息）¶

字段	类型	必填	默认	说明	来源
id	bigint	✓	—	主键	系统
session_id	bigint	✓	—	FK→chat_session	系统
role	varchar(10)	✓	—	USER/ASSISTANT	系统
content	text	✓	—	内容	用户/AI
citations	jsonb		null	[{file,line,excerpt}]（ASSISTANT 才有）	AI/系统
created_at	timestamptz	✓	now()	—	系统
deleted	smallint	✓	0	逻辑删除（@TableLogic）	系统

3.15 knowledge_chunk（RAG 知识块）¶

字段	类型	必填	默认	说明	来源
id	bigint	✓	—	主键	系统
project_id	bigint	✓	—	FK→project	系统
analysis_id	bigint	✓	—	FK→analysis（随分析全量重建）	系统
file_path	text	✓	—	源文件	analyzer
chunk_index	int	✓	—	块序号	analyzer
content	text	✓	—	切片内容（≤800 token）	analyzer
meta	jsonb		null	{symbol,lang}	analyzer
embedding	vector(1024)		null	向量（维数随模型）	AI
created_at	timestamptz	✓	now()	—	系统

3.16 hotspot（演化热点）¶

字段	类型	必填	默认	说明	来源
id	bigint	✓	—	主键	系统
project_id	bigint	✓	—	FK→project	系统
analysis_id	bigint	✓	—	FK→analysis	系统
module	varchar(200)	✓	—	热点模块/文件	analyzer
risk_level	varchar(10)	✓	—	HIGH/MEDIUM	analyzer
evidence	jsonb		null	证据数组 ["变更45次",…]	analyzer
ai_conclusion	text		null	AI 风险中心判断	AI
created_at	timestamptz	✓	now()	—	系统

4. 枚举字典¶

枚举	值	说明
ProjectSourceType	ZIP / GIT	项目来源
ProjectStatus	CREATED / ANALYZING / READY / FAILED	建档状态
AnalysisStatus	PENDING / RUNNING / SUCCEEDED / FAILED / CANCELLED	任务状态机
AnalysisType	FULL / QUALITY / ARCH / EVOLUTION	分析类型
Stage	QUEUED / SCAN / SCAN_DONE / REPORT / DONE	阶段（进度文案）
RiskLevel	LOW / MEDIUM / HIGH	风险等级
Ecosystem	maven / npm / pip / go	依赖生态
IssueKind	BUG / VULNERABILITY / SMELL	质量 issue 类型
Severity	BLOCKER / CRITICAL / MAJOR / MINOR / INFO	严重度
AiStatus	NONE / PENDING / DONE / FAILED	AI 生成状态
IssueStatus	OPEN / IGNORED / FIXED	质量 issue 处理状态
NodeType	CONTROLLER / SERVICE / REPOSITORY / ENTITY / UTIL / MODULE / OTHER	架构节点类型
EdgeRelation	CALL / IMPORT / DEPEND	关系类型
ViolationType	LAYER_VIOLATION / CYCLE / GOD_CLASS / DUPLICATE_RESPONSIBILITY	违规类型
TechDebtSource	ARCH / QUALITY / DEPEND / EVOLUTION / AI_DOCTOR / MANUAL	技术债来源
TechDebtStatus	OPEN / DOING / DONE / WONTFIX	技术债状态
DocType	README / ARCH / API	文档类型
ChatRole	USER / ASSISTANT	消息角色
ReportSource	LLM / RULES	报告来源
HotspotLevel	HIGH / MEDIUM	热点等级

错误码（1001-1003 / 2001-2009 / 3001-3003 / 5001-5003）不属于表枚举，唯一来源 docs/06-API契约.md §2.2，三端共用，此处不重复登记。

5. JSONB 内部结构（实现时必须一致）¶

5.1 project.lang_stats¶

{ "Java": 61.2, "JavaScript": 30.4, "OTHER": 8.4 }

5.2 analysis.report_json¶

{ "healthScore": 82, "level": "GOOD", "summary": "...",
  "techStack": { "languages": {...}, "frameworks": ["Spring Boot"] },
  "dimensions": [ { "key": "quality", "score": 76, "stars": 4, "summary": "..." } ],
  "risks": [ { "level": "HIGH", "title": "...", "detail": "...",
               "suggestion": "...", "references": [ { "file": "...", "line": 12 } ] } ],
  "recommendations": [ { "phase": "第一阶段", "items": ["..."] } ] }

source 与 promptVersion 不在 report_json 内：落库时写入 analysis 的 report_source / prompt_version 列（V001，见 §3.2），对外响应在 data 层返回（06 §3.7）。

SPI-6（V010）拆表后：report_json 落 analysis_report 表（analysis_id UNIQUE），health_score / level / summary 提为列（列表排序与历史摘要直接读列，不再解析 JSONB 子查询）；本 JSONB 结构保持不变，详情/导出从 analysis_report.report_json 读取。

5.3 dependency.ai_advice¶

{ "impact": "升级影响面", "steps": ["..."], "risks": ["..."], "estimate": "0.5 人日" }

5.4 architecture_node.metrics¶

{ "inDegree": 0, "outDegree": 3, "depCount": 2 }

5.5 chat_message.citations¶

[ { "file": "pom.xml", "line": 3, "excerpt": "<parent>…2.5.14…" } ]

5.6 hotspot.evidence¶

[ "变更 45 次", "新增 12000 行", "耦合度全项目最高" ]

6. 迁移与命名规则¶

新迁移：db/migration/V0NN__desc.sql，编号递增，禁止修改已执行文件（新增列走新版本）
新字段：snake_case；时间类以 _at 结尾；枚举类以状态语义命名（status/level/type）
删除字段：先停用（注释）一个版本，再删（单人项目可简化，但记录在变更日志）
字段口径变更（如健康分算法）必须同步：07 数据字典 + 06 契约 + 03 规范测试