# 项目知识库输出契约

生成完整代码库知识库时使用本参考。

## 语言策略

人类阅读的叙述文档应匹配用户语言。如果用户使用中文或要求中文，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 营销文案复制成架构文档。
- 没有来源路径就声称某接口、表、权限或运行模式存在。
- 隐藏未知问题，而不是列出来。