feat: 初始化考培练系统项目
- 从服务器拉取完整代码 - 按框架规范整理项目结构 - 配置 Drone CI 测试环境部署 - 包含后端(FastAPI)、前端(Vue3)、管理端 技术栈: Vue3 + TypeScript + FastAPI + MySQL
This commit is contained in:
98
docs/规划/后端开发拆分策略/子agent/00-通用基础/essential_docs.md
Normal file
98
docs/规划/后端开发拆分策略/子agent/00-通用基础/essential_docs.md
Normal file
@@ -0,0 +1,98 @@
|
||||
# 必读文档清单
|
||||
|
||||
## 核心规划文档
|
||||
|
||||
这些文档包含了项目的重要设计决策,所有Agent都应该了解:
|
||||
|
||||
### 1. 架构设计文档
|
||||
|
||||
- `../../协作机制设计.md` - **必读** - 模块间协作机制、全局上下文、错误处理
|
||||
- `../../项目脚手架结构.md` - **必读** - 详细的目录结构和文件组织
|
||||
- `../../模块分工指南.md` - **必读** - 各模块的职责边界和接口定义
|
||||
- `../../开发规范文档.md` - **必读** - 详细的编码规范和最佳实践
|
||||
|
||||
### 2. 业务理解文档
|
||||
|
||||
- `../../../README.md` - 项目整体介绍
|
||||
- `../../../../kaopeilian-frontend/页面与按钮速查.md` - 前端页面框架和功能
|
||||
- `../../../../kaopeilian-frontend/前后端接口约定.md` - 前后端接口约定
|
||||
|
||||
### 3. 质量保证文档
|
||||
|
||||
- `../../质量保证机制.md` - 代码审查和测试要求
|
||||
- `../../统一基础代码.md` - 可复用的代码模板
|
||||
|
||||
### 4. 配置管理文档
|
||||
|
||||
- `../../配置一致性检查清单.md` - **必读** - 所有需要保持一致的配置项清单
|
||||
- `../../配置管理使用说明.md` - **必读** - 配置管理工具使用指南和最佳实践
|
||||
|
||||
## 使用建议
|
||||
|
||||
### 对于每个Agent
|
||||
|
||||
1. **开发前必读**:
|
||||
|
||||
- 本目录的 `base_prompt.md`
|
||||
- 本目录的 `project_structure.md`
|
||||
- `../../协作机制设计.md`
|
||||
- `../../模块分工指南.md`
|
||||
- `../../配置一致性检查清单.md`
|
||||
|
||||
2. **开发中参考**:
|
||||
|
||||
- `../../开发规范文档.md`
|
||||
- `../../统一基础代码.md`
|
||||
- `../../配置管理使用说明.md`
|
||||
- 相关模块的接口定义
|
||||
|
||||
3. **遇到问题时**:
|
||||
|
||||
- 先运行配置检查脚本:`../../../../../check-config.sh`
|
||||
- 查看 `../../配置一致性检查清单.md`
|
||||
- 参考 `../../配置管理使用说明.md`
|
||||
|
||||
4. **集成时查看**:
|
||||
|
||||
- 依赖模块的API契约
|
||||
- `../../质量保证机制.md`
|
||||
|
||||
### 文档引用示例
|
||||
|
||||
```markdown
|
||||
# 在对话中引用
|
||||
@考培练系统规划/后端开发拆分策略/协作机制设计.md
|
||||
@考培练系统规划/后端开发拆分策略/模块分工指南.md
|
||||
@子agent/01-Agent-Auth/prompt.md
|
||||
|
||||
我已了解项目的协作机制和模块分工,开始开发Auth模块。
|
||||
```
|
||||
|
||||
## 重要提醒
|
||||
|
||||
- 这些文档包含了项目的核心设计理念
|
||||
- 遵循这些文档可以确保代码的一致性
|
||||
- 有疑问时优先查阅这些文档而不是自行决定
|
||||
- 禁止在各模块文档中重复粘贴通用规范,统一通过本目录进行引用,避免信息漂移
|
||||
|
||||
## 可复用资产索引(Coze 并入)
|
||||
- 代码位置
|
||||
- 后端(完整可并入):`/Users/nongjun/Desktop/Ai公司/本地开发与测试/coze-chat-backend/`
|
||||
- 关键文件:`auth.py`(OAuth/JWT 优先,PAT 回退,直连 *.coze.cn)、`main.py`(SSE/卡片/会话/上传/中断)、`config.py`/`local_config.py`(本地/环境配置)。
|
||||
- 目标映射:
|
||||
- → `kaopeilian-backend/app/services/ai/coze/{client.py,service.py,exceptions.py,models.py}`
|
||||
- → `kaopeilian-backend/app/api/v1/coze_gateway.py`
|
||||
- 前端(可快速接入或重写):`/Users/nongjun/Desktop/Ai公司/本地开发与测试/coze-chat-frontend/`
|
||||
- 页面:`src/pages/{NewChat,Exam,Training}`
|
||||
- Store:`src/stores/{NewChatStore,ExamStore,TrainingStore}.ts`
|
||||
- API:`src/server/{api.ts,global.ts}`(SSE/中断/上传)
|
||||
- 目标策略:
|
||||
- 快速:以子应用挂载 `/ai-chat/*`;
|
||||
- 稳定:迁移为 Vue3 + Pinia,复用 SSE/卡片渲染逻辑。
|
||||
- 配置项(本地/环境变量)
|
||||
- `COZE_API_BASE`、`COZE_WORKSPACE_ID`、`COZE_API_TOKEN`
|
||||
- `COZE_OAUTH_CLIENT_ID`、`COZE_OAUTH_PUBLIC_KEY_ID`、`COZE_OAUTH_PRIVATE_KEY_PATH`
|
||||
- 建议:生产关闭“开发用 PAT 获取”,统一 `Bearer` 鉴权,设置 `NO_PROXY=localhost,127.0.0.1,api.coze.cn,.coze.cn`。
|
||||
- 参考说明
|
||||
- 根目录:`配置说明.md`、`README.md`(已含运行与映射说明)
|
||||
- 并入后务必以各模块 `api_contract.yaml` 为准,旧路由通过网关短期兼容,按里程碑收敛。
|
||||
Reference in New Issue
Block a user