smart
67837df8d0
- 新增全套考试卷、评估卷、参考答案与考试培训包模板 - 修正slidev培训课件：调整模块标题、链路图缩放，替换工单示例为通用业务对象 - 修正课堂红线表述为证据红线，将小组作业调整为个人作业要求 - 新增权限、状态流转、审计日志、看板指标四类可复用业务规则块 - 整理AI工程技能交付包，迁移旧资产至客户专属交付包并统一术语 - 新增考试输出模板与TRAE使用记录文档
136 lines
5.0 KiB
Markdown
136 lines
5.0 KiB
Markdown
# 项目知识库输出契约
|
|
|
|
生成完整代码库知识库时使用本参考。
|
|
|
|
## 语言策略
|
|
|
|
人类阅读的叙述文档应匹配用户语言。如果用户使用中文或要求中文，README、上下文、架构、运行、后端、前端、数据、认证/权限、扩展、排障、RAG 指南和 ADR 都应使用中文。
|
|
|
|
技术锚点保持原样：源码路径、命令、类名、方法名、API 路径、配置键、表名、权限码、JSON key 和元数据枚举值。
|
|
|
|
生成索引可以保持技术化和接近源码。不要为了翻译而破坏可刷新性。
|
|
|
|
## 文档职责
|
|
|
|
| 文件 | 用途 |
|
|
| --- | --- |
|
|
| `README.md` | 入口、阅读顺序、高价值链接、新鲜度说明。中文输出时标题和使用说明应为中文。 |
|
|
| `CONTEXT.md` | 领域语言、业务能力、用户角色、核心名词、不变量。 |
|
|
| `CONTEXT-MAP.md` | 限界上下文、模块归属、上下游依赖、运行边界。 |
|
|
| `01-architecture.md` | 系统形态、模块图、请求/数据/控制流、扩展点。 |
|
|
| `02-runtime.md` | 本地运行、构建、环境变量、Docker、部署模式、进程拓扑。存在时必须识别本地、Docker standalone 和云端模式。 |
|
|
| `03-backend.md` | 后端模块、入口点、API 约定、service/mapper/entity 模式。 |
|
|
| `04-frontend.md` | 前端启动、路由、状态、API client、组件/页面约定。 |
|
|
| `05-data-and-migrations.md` | 数据库、迁移、schema 来源、种子数据、表族。 |
|
|
| `06-auth-permissions.md` | 认证、授权、token/session 流、权限码生命周期。仓库存在后端驱动菜单时，必须解释菜单/按钮权限流。 |
|
|
| `07-extension-guide.md` | 如何端到端新增功能，并给出有来源依据的示例。适用时必须覆盖后端 CRUD、前端页面和权限/菜单数据变更。 |
|
|
| `08-troubleshooting.md` | 面向症状的排障手册，包含命令、文件和可能原因。 |
|
|
| `09-rag-indexing.md` | 切块、元数据、排除规则、刷新频率、过期数据策略。 |
|
|
| `adr/*.md` | 当前代码已经体现的架构决策。 |
|
|
| `generated/*.md` | 可重新生成的数据索引。 |
|
|
|
|
## 必要章节
|
|
|
|
每份叙述文档应包含：
|
|
|
|
- **已观察来源**：使用过的具体文件或命令。
|
|
- **核心事实**：简洁、有来源依据的陈述。
|
|
- **操作影响**：开发者因这些事实需要采取的不同做法。
|
|
- **未知与风险**：需要运行权限、数据库导出、产品负责人输入或外部文档才能确认的缺口。
|
|
|
|
## 新人可用性门禁
|
|
|
|
认为知识库可交接前，确认新维护者能回答：
|
|
|
|
1. 这个产品/项目是什么，哪些目录最重要？
|
|
2. 如何启动，或如何识别当前运行模式？
|
|
3. 后端接口、前端路由/页面、配置、数据表、权限码在哪里索引？
|
|
4. 菜单、按钮和后端权限校验如何连接？
|
|
5. 新增普通功能时，通常会改哪些后端、前端、数据库和权限产物？
|
|
|
|
如果 README 加叙述文档无法明显回答这些问题，先补充或修改人类阅读指南。不要通过加长生成索引来解决。
|
|
|
|
## 生成索引
|
|
|
|
### `project-inventory.md`
|
|
|
|
包含：
|
|
|
|
- 仓库根路径
|
|
- 构建/包管理清单
|
|
- 主要语言
|
|
- 主要目录
|
|
- scripts
|
|
- Docker/compose 文件
|
|
- env 文件
|
|
- 测试文件
|
|
|
|
### `backend-endpoints.md`
|
|
|
|
包含路由方法、路径、类/文件、近似行号、认证注解和备注。不要在 class-level 与 method-level mapping 需要 Java 表达式解析时编造完整路径；展示已观察片段，并标记组合限制。
|
|
|
|
### `frontend-routes.md`
|
|
|
|
包含静态路由文件、动态路由加载器、`src/views` 索引、路由守卫文件和外部路由包加载器。
|
|
|
|
### `config-reference.md`
|
|
|
|
包含 env 文件、YAML/properties 文件、相关 key、默认值和风险说明。敏感信息必须脱敏。
|
|
|
|
### `database-dictionary.md`
|
|
|
|
包含 SQL 文件、迁移文件、表名、表族，以及表是初始化、迁移还是推断得出。不要把巨大 SQL 写进正文；摘要并链接来源。
|
|
|
|
### `permission-codes.md`
|
|
|
|
包含后端注解、前端权限 helper/usage、菜单/权限 SQL 命中和认证生命周期说明。
|
|
|
|
## ADR 模板
|
|
|
|
```markdown
|
|
# ADR NNNN: 标题
|
|
|
|
Date: YYYY-MM-DD
|
|
Status: Observed
|
|
|
|
## Context
|
|
|
|
说明该决策已经存在的来源事实。
|
|
|
|
## Decision
|
|
|
|
当前代码体现的架构决策。
|
|
|
|
## Consequences
|
|
|
|
收益、取舍、操作约束和迁移风险。
|
|
|
|
## Sources
|
|
|
|
- `path/to/file`
|
|
```
|
|
|
|
## RAG 元数据
|
|
|
|
推荐每个 chunk 使用：
|
|
|
|
```json
|
|
{
|
|
"project": "name",
|
|
"snapshot_date": "YYYY-MM-DD",
|
|
"source_path": "path",
|
|
"doc_type": "architecture|runtime|generated|adr|runbook",
|
|
"domain": "backend|frontend|data|auth|deploy",
|
|
"freshness": "manual|generated",
|
|
"confidence": "observed|inferred|unknown"
|
|
}
|
|
```
|
|
|
|
## 反模式
|
|
|
|
- 只有长篇说明，没有生成索引。
|
|
- 写与仓库无关的“最佳实践”建议。
|
|
- 把 README 营销文案复制成架构文档。
|
|
- 没有来源路径就声称某接口、表、权限或运行模式存在。
|
|
- 隐藏未知问题，而不是列出来。
|