Files

T

smart 67837df8d0 docs: 更新TRA编程培训课程材料、课件与AI技能交付包

- 新增全套考试卷、评估卷、参考答案与考试培训包模板
- 修正slidev培训课件：调整模块标题、链路图缩放，替换工单示例为通用业务对象
- 修正课堂红线表述为证据红线，将小组作业调整为个人作业要求
- 新增权限、状态流转、审计日志、看板指标四类可复用业务规则块
- 整理AI工程技能交付包，迁移旧资产至客户专属交付包并统一术语
- 新增考试输出模板与TRAE使用记录文档

2026-08-08 11:00:36 +08:00

5.0 KiB

Raw Permalink Blame History

项目知识库输出契约

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

语言策略

人类阅读的叙述文档应匹配用户语言。如果用户使用中文或要求中文，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`	可重新生成的数据索引。

必要章节

每份叙述文档应包含：

已观察来源：使用过的具体文件或命令。
核心事实：简洁、有来源依据的陈述。
操作影响：开发者因这些事实需要采取的不同做法。
未知与风险：需要运行权限、数据库导出、产品负责人输入或外部文档才能确认的缺口。

新人可用性门禁

认为知识库可交接前，确认新维护者能回答：

这个产品/项目是什么，哪些目录最重要？
如何启动，或如何识别当前运行模式？
后端接口、前端路由/页面、配置、数据表、权限码在哪里索引？
菜单、按钮和后端权限校验如何连接？
新增普通功能时，通常会改哪些后端、前端、数据库和权限产物？

如果 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 模板

# ADR NNNN: 标题

Date: YYYY-MM-DD
Status: Observed

## Context

说明该决策已经存在的来源事实。

## Decision

当前代码体现的架构决策。

## Consequences

收益、取舍、操作约束和迁移风险。

## Sources

- `path/to/file`

RAG 元数据

推荐每个 chunk 使用：

{
  "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 营销文案复制成架构文档。
没有来源路径就声称某接口、表、权限或运行模式存在。
隐藏未知问题，而不是列出来。

5.0 KiB Raw Permalink Blame History