wurenzhi/makemd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 初始化项目结构并添加核心功能模块

Browse Source 
- 新增文档模板和导航结构
- 实现服务器基础API路由和控制器
- 添加扩展插件配置和前端框架
- 引入多租户和权限管理模块
- 集成日志和数据库配置
- 添加核心业务模型和类型定义
This commit is contained in:
wurenzhi
2026-03-17 22:07:19 +08:00
parent c0870dce50
commit 136c2fa579
728 changed files with 107690 additions and 5614 deletions
Download Patch File Download Diff File Expand all files Collapse all files

886
archive/handover/00.md Normal file
View File

@@ -0,0 +1,886 @@
我先给你一份比较完整的模板，然后再告诉你 **还有哪些文件能进一步优化 AI 编程体验**。
---
# PROJECT_MAP.md
# Project Map
This document provides a high-level map of the entire repository.
It is intended for both developers and AI systems to quickly understand the project structure.
---
# 1. Project Overview
Project Name: <PROJECT_NAME>
Purpose:
Describe the main goal of this project.
Example:
* Web backend service
* AI processing pipeline
* SaaS platform
Primary technologies:
* Language: <Python / Node / Go / etc>
* Framework: <FastAPI / Express / Spring / etc>
* Database: <PostgreSQL / MongoDB>
---
# 2. Repository Structure
Top-level structure:
```
project
├─ api
├─ service
├─ repository
├─ models
├─ utils
├─ config
├─ tests
└─ scripts
```
---
# 3. Key Modules
## api
Handles external requests.
Responsibilities:
* routing
* validation
* response formatting
---
## service
Contains core business logic.
Responsibilities:
* orchestration
* domain rules
* transaction control
---
## repository
Handles data persistence.
Responsibilities:
* database queries
* ORM interactions
* caching layer
---
## models
Defines domain entities.
Examples:
* User
* Order
* Session
---
## utils
Shared helper functions.
Examples:
* date helpers
* logging
* validation utilities
---
# 4. Request Flow
Typical request lifecycle:
```
Client
↓
API Layer
↓
Service Layer
↓
Repository Layer
↓
Database
```
---
# 5. Important Entry Points
Main entry points:
```
main.py
app.ts
server.go
```
Startup flow:
1. load configuration
2. initialize services
3. register routes
4. start server
---
# 6. Configuration
Configuration files are located in:
```
config/
```
Types:
* environment variables
* database configuration
* feature flags
---
# 7. Testing Strategy
Tests are located in:
```
tests/
```
Structure mirrors source code.
Example:
```
service/user_service.py
tests/service/test_user_service.py
```
---
# 8. Coding Rules
See:
```
project_rules.md
```
---
# 9. Dependency Rules
See:
```
DEPENDENCY_MAP.md
```
---
# 10. AI Notes
Guidelines for AI tools:
* Keep files under 2000 lines
* Avoid circular dependencies
* Follow modular architecture
* Prefer small reusable functions
---
# 除了这些文件，还有哪些 AI 项目文件？
完整的 **AI-native 项目结构**通常会有这些：
```
AI_CONTEXT.md
PROJECT_MAP.md
MODULE_INDEX.md
DEPENDENCY_MAP.md
project_rules.md
```
但实际上还可以再加几个更高级的。
---
# 1️⃣ CODE_STYLE.md
专门给 AI 的代码风格。
例如：
```
indent: 4 spaces
naming: snake_case
class naming: PascalCase
error handling: explicit
```
AI生成代码会更一致。
---
# 2️⃣ API_MAP.md
如果项目有 API。
例如：
```
GET /users
POST /login
DELETE /session
```
AI可以直接知道接口结构。
---
# 3️⃣ DATA_SCHEMA.md
数据库结构说明。
例如：
```
User
- id
- email
- password_hash
```
AI生成 SQL / ORM 会更准。
---
# 4️⃣ WORKFLOW.md
业务流程。
例如：
```
user register
↓
email verification
↓
account activation
```
AI理解业务逻辑会更快。
---
# 最完整的 AI 项目结构（推荐）
```
project
├─ api
├─ service
├─ repository
├─ models
├─ utils
├─ tests
├─ project_rules.md
├─ PROJECT_MAP.md
├─ AI_CONTEXT.md
├─ MODULE_INDEX.md
├─ DEPENDENCY_MAP.md
├─ CODE_STYLE.md
├─ API_MAP.md
└─ DATA_SCHEMA.md
```
---
# 一个很多人不知道的关键点
真正提升 AI 理解能力最大的文件其实不是这些，而是：
```
REPO_PROMPT.md
```
这是 **专门给 AI 的系统提示词**，告诉 AI：
* 如何修改代码
* 如何写模块
* 如何重构项目
下面是一套 **“AI 时代项目模板仓库结构（2026版）”**。
目标：**让 AI IDE、代码助手和人类开发者都能快速理解、导航和重构项目。**
---
# 一、完整仓库结构（推荐模板）
```text
project
├─ api/ # 外部接口层（HTTP / RPC / CLI）
│
├─ service/ # 核心业务逻辑
│
├─ repository/ # 数据访问层
│
├─ models/ # 数据模型 / schema
│
├─ components/ # 可复用组件（前端或服务模块）
│
├─ utils/ # 工具函数
│
├─ config/ # 配置文件
│
├─ scripts/ # 自动化脚本
│
├─ tests/ # 单元测试
│
├─ docs/ # 人类文档
│
├─ prompts/ # AI Prompt 模板
│
├─ embeddings/ # 向量索引配置
│
├─ project_rules.md
├─ AI_CONTEXT.md
├─ PROJECT_MAP.md
├─ MODULE_INDEX.md
├─ DEPENDENCY_MAP.md
├─ CODE_STYLE.md
├─ API_MAP.md
├─ DATA_SCHEMA.md
├─ WORKFLOW.md
├─ REPO_PROMPT.md
├─ README.md
└─ CHANGELOG.md
```
---
# 二、AI核心文件（最关键）
这些是 **AI理解项目的核心入口**。
### 1️⃣ AI_CONTEXT.md
作用：
* 项目总体介绍
* 技术栈
* 架构思想
AI第一时间读取。
---
### 2️⃣ PROJECT_MAP.md
作用：
* 仓库结构地图
* 入口文件
* 模块概览
让AI快速定位代码。
---
### 3️⃣ MODULE_INDEX.md
作用：
说明每个模块职责：
```text
api → 接口
service → 业务逻辑
repository → 数据访问
```
---
### 4️⃣ DEPENDENCY_MAP.md
定义 **依赖规则**：
```text
api → service
service → repository
repository → models
```
避免循环依赖。
---
### 5️⃣ project_rules.md
代码规范：
* 文件大小
* 模块拆分
* 命名规则
---
# 三、AI增强文件（提升 AI 代码能力）
### CODE_STYLE.md
代码风格：
```text
indent: 4 spaces
naming: snake_case
classes: PascalCase
comments: concise
```
AI生成代码更统一。
---
### REPO_PROMPT.md
**最重要的 AI 提示词文件**。
告诉 AI：
```text
如何修改代码
如何重构
如何写模块
```
例如：
```text
When modifying code:
- preserve architecture layers
- avoid circular dependencies
- keep files under 2000 lines
```
---
### prompts/
存放 AI prompt 模板：
```text
prompts/
refactor.md
bugfix.md
feature.md
```
---
# 四、业务理解文件
这些帮助 AI **理解业务逻辑**。
### API_MAP.md
```text
GET /users
POST /login
DELETE /session
```
---
### DATA_SCHEMA.md
数据库结构：
```text
User
- id
- email
- password_hash
```
---
### WORKFLOW.md
业务流程：
```text
register
↓
email verification
↓
account activation
```
---
# 五、代码目录规范
推荐代码目录：
```text
api/
user_controller
auth_controller
service/
user_service
auth_service
repository/
user_repository
```
调用链：
```text
API
↓
Service
↓
Repository
↓
Database
```
---
# 六、AI检索优化目录
为了让 AI IDE 更好检索代码：
```text
embeddings/
```
存储：
* 向量索引
* 代码摘要
一些 AI 工具会自动生成。
---
# 七、docs目录
给人类开发者：
```text
docs/
architecture.md
deployment.md
dev_setup.md
```
---
# 八、文件大小建议
AI-friendly 项目规则：
```text
单文件 ≤ 2000 行
函数 ≤ 100 行
模块 ≤ 10 文件
```
---
# 九、典型调用链
```text
Client
↓
API
↓
Service
↓
Repository
↓
Database
```
AI最容易理解这种结构。
---
# 十、为什么这个结构重要
这种仓库结构可以：
* 降低 AI 上下文需求
* 提升代码生成质量
* 提升自动重构能力
* 提升项目可维护性
很多开发者用这种结构后：
```text
7B–13B 模型
```
就能处理 **大型项目重构**。
---
# 十一、最关键的三个文件
如果只选三个：
```text
AI_CONTEXT.md
PROJECT_MAP.md
REPO_PROMPT.md
```
这三个可以让 AI **30 秒理解项目**。
---
下面是一份 **增强版 `REPO_PROMPT.md`** 模板。它的定位是：为 AI 助手（如 Cursor、Windsurf、GitHub Copilot）提供**仓库级系统提示**，统一其改代码、加功能、重构时的行为准则。把它放在仓库根目录即可。
# REPO_PROMPT.md
## Purpose
This file defines how AI assistants should interact with this repository.
Follow these rules when reading, modifying, or generating code.
---
## 1. Architectural Principles
1. Respect the layered architecture:
* api → service → repository → models
2. Never introduce circular dependencies.
3. Keep modules loosely coupled and cohesive.
4. Prefer composition over inheritance.
---
## 2. File and Function Limits
* Single file ≤ 2000 lines.
* Function ≤ 100 lines.
* Prefer splitting large logic into smaller modules.
If modifying a file that exceeds limits, propose a refactor.
---
## 3. Code Style
* Use descriptive variable and function names.
* Follow language conventions (snake_case or camelCase).
* Avoid abbreviations unless common (id, url, api).
* Add short comments only when logic is non-obvious.
Example:
Good:
```
createUserAccount
validateToken
fetchUserProfile
```
Bad:
```
handle
doTask
runLogic
```
---
## 4. Dependency Rules
Allowed:
```
api → service
service → repository
service → models
repository → models
utils → used by all
```
Forbidden:
```
repository → service
models → repository
api → repository
```
If a change would break these rules, refactor instead.
---
## 5. Refactoring Guidelines
When refactoring:
1. Preserve existing public interfaces.
2. Avoid unnecessary changes across unrelated modules.
3. Extract shared logic into utils if reused.
4. Ensure unit tests remain valid.
Prefer incremental refactoring over large rewrites.
---
## 6. Feature Development
When implementing a new feature:
1. Determine affected modules.
2. Add or modify models if needed.
3. Implement business logic in service layer.
4. Expose endpoints in api layer.
Never place business logic directly in api controllers.
---
## 7. Bug Fixing
When fixing bugs:
1. Identify root cause.
2. Modify the minimal number of files.
3. Avoid introducing new dependencies.
4. Add tests if possible.
---
## 8. Code Generation Behavior
When generating code:
* Follow existing project patterns.
* Reuse existing utilities and helpers.
* Avoid duplicating functionality.
* Maintain consistent naming conventions.
---
## 9. AI Context Strategy
To understand the project:
1. Read PROJECT_MAP.md.
2. Read MODULE_INDEX.md.
3. Check DEPENDENCY_MAP.md.
4. Then inspect relevant modules.
Do not assume knowledge of the entire repository.
---
## 10. Documentation Updates
If architectural changes occur:
Update the following files:
* PROJECT_MAP.md
* MODULE_INDEX.md
* DEPENDENCY_MAP.md
---
## 11. Testing Expectations
When adding new logic:
* Add unit tests in the tests directory.
* Mirror source directory structure.
* Ensure test coverage for critical paths.
---
## 12. Safety Rules
Do NOT:
* rewrite large parts of the codebase unnecessarily
* introduce breaking API changes
* add new external dependencies without justification
Prefer minimal, safe modifications.
---
## 13. AI Interaction Summary
AI assistants should:
* understand the architecture first
* make minimal targeted changes
* keep code modular and readable
* follow project conventions
---
## 使用建议
1. 将 `REPO_PROMPT.md` 放在仓库根目录，与 `PROJECT_MAP.md`、`AI_CONTEXT.md` 同级。
2. 在 IDE 的 AI 设置中，如果支持 **repo rules / system prompt**，可指向此文件。
3. 当项目架构变化时，及时同步更新。
## 搭配文件（推荐最小组合）
最实用的一组是：
```
AI_CONTEXT.md
PROJECT_MAP.md
MODULE_INDEX.md
DEPENDENCY_MAP.md
project_rules.md
REPO_PROMPT.md
```
这 6 个文件通常就足以让 AI 在中大型仓库里保持较稳定的改动质量。