docs: 更新TRA编程培训课程材料、课件与AI技能交付包
- 新增全套考试卷、评估卷、参考答案与考试培训包模板 - 修正slidev培训课件:调整模块标题、链路图缩放,替换工单示例为通用业务对象 - 修正课堂红线表述为证据红线,将小组作业调整为个人作业要求 - 新增权限、状态流转、审计日志、看板指标四类可复用业务规则块 - 整理AI工程技能交付包,迁移旧资产至客户专属交付包并统一术语 - 新增考试输出模板与TRAE使用记录文档
This commit is contained in:
+135
@@ -0,0 +1,135 @@
|
||||
# 项目知识库输出契约
|
||||
|
||||
生成完整代码库知识库时使用本参考。
|
||||
|
||||
## 语言策略
|
||||
|
||||
人类阅读的叙述文档应匹配用户语言。如果用户使用中文或要求中文,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 营销文案复制成架构文档。
|
||||
- 没有来源路径就声称某接口、表、权限或运行模式存在。
|
||||
- 隐藏未知问题,而不是列出来。
|
||||
Reference in New Issue
Block a user