tomevault-io Code-Nest 项目规范
1. 目标
在本仓库内进行任何开发时，先用本规范完成三件事：
- 快速定位改动应该落在哪个模块。
- 按既有约定实现，避免破坏统一风格。
- 用最小必要命令验证改动可编译、可运行、可联调。
- 在我给需求后，你可以调用一些已经有的skill 来帮助你完善这些功能，更好的规范你
2. 仓库全景
- 后端是 Maven 多模块工程，根
pom.xml管理版本与子模块。 - 后端启动入口在
xiaou-application，统一上下文路径是/api。 - 前端分为两套：
vue3-admin-front（管理端，默认端口3000）vue3-user-front（用户端，默认端口3001）
- 每个前端同时支持 Electron 打包，入口在各自
electron/。 - 数据库脚本在
sql/，采用“基线 + 版本增量”结构。 - PRD 与技术文档在
docs/。
3. 目录速查
- 后端聚合入口：
xiaou-application/src/main/java/com/xiaou/CodeNestApplication.java - 全局配置：
xiaou-application/src/main/resources/application.yml - 公共能力：
xiaou-common/ - 用户端 API 封装：
vue3-user-front/src/api/ - 管理端 API 封装：
vue3-admin-front/src/api/ - 用户端路由：
vue3-user-front/src/router/index.js - 管理端路由：
vue3-admin-front/src/router/index.js - SQL 版本脚本：
sql/v*/ - 需求文档：
AI-DOCS/PRD/
4. 模块映射（后端）
优先按业务模块改，不要在 xiaou-application 塞业务逻辑。
| 模块 | 主要职责 |
|---|---|
xiaou-common |
统一返回体、异常处理、鉴权配置、通用工具、公共 Mapper |
xiaou-system |
管理员认证、系统日志、系统管理能力 |
xiaou-user |
用户注册登录与用户资料 |
xiaou-interview |
面试题库、题单、学习记录与掌握度 |
xiaou-community |
社区帖子、评论、标签、分类、用户态社区能力 |
xiaou-moment |
动态广场与互动 |
xiaou-blog |
博客文章、分类、标签 |
xiaou-codepen |
代码作品、模板、收藏/评论/Fork |
xiaou-resume |
在线简历、模板、分析与导出相关 |
xiaou-filestorage |
文件上传、存储配置、迁移 |
xiaou-notification |
通知中心 |
xiaou-chat |
聊天室与实时消息管理 |
xiaou-sensitive |
敏感词词库、策略、统计、检测接口实现 |
xiaou-knowledge |
知识图谱管理与展示 |
xiaou-version |
版本历史 |
xiaou-moyu |
摸鱼工具（日历、热榜、Bug 商店等） |
xiaou-points |
积分与抽奖 |
xiaou-plan |
计划打卡 |
xiaou-mock-interview |
AI 模拟面试流程 |
xiaou-flashcard |
闪卡学习 |
xiaou-oj |
在线判题、提交、题解、评论、排行 |
xiaou-sql-optimizer |
慢 SQL 分析与历史记录 |
xiaou-ai |
统一 AI 服务（LangChain4j + LangGraph4j + LlamaIndex） |
xiaou-user-api |
用户跨模块 API 契约（接口与 DTO） |
xiaou-sensitive-api |
敏感词跨模块 API 契约（接口与 DTO） |
5. 路由与鉴权约定（强约束）
按 SaTokenConfig 的现有规则组织接口路径：
- 管理端接口通常走
/auth/**或/admin/** - 用户端接口通常走
/user/** - 公共接口按业务定义（如
/oj/**、/community/**、/version/**） - 验证码：
/captcha/**（免登录） - Swagger：
/v3/api-docs/**、/swagger-ui/**（免登录）
鉴权工具类必须复用：
- 管理员：
StpAdminUtil - 用户：
StpUserUtil
需要管理员权限的方法优先使用 @RequireAdmin。
6. 返回体与错误码约定（强约束）
后端接口统一返回 Result<T>，定义在：
xiaou-common/src/main/java/com/xiaou/common/core/domain/Result.javaxiaou-common/src/main/java/com/xiaou/common/core/domain/ResultCode.java
关键业务码：
200：成功701：Token 无效702：Token 过期703：权限不足704：账号禁用
前端拦截器已按上述业务码处理跳转与提示，不要随意改语义。
7. 后端开发落地步骤
- 先确认业务归属模块，再改对应模块下
controller/service/mapper。 - 新增接口时，保持现有路径风格（admin/user/pub）。
- DTO、枚举、domain 放在当前业务模块，不要塞到
xiaou-application。 - 公共逻辑先考虑放
xiaou-common，避免复制代码。 - 跨模块调用先复用 API 契约模块（
xiaou-user-api、xiaou-sensitive-api）。 - MyBatis XML 一般在
src/main/resources/mapper。 - OJ 模块是特例，Mapper XML 在
xiaou-oj/src/main/java/com/xiaou/oj/mapper/。 - 需要新增模块时，同时更新根
pom.xml的<modules>与xiaou-application/pom.xml依赖。
8. 前端开发落地步骤
- 先看路由文件定位页面：
src/router/index.js。 - 再看 API 封装：
src/api/*.js。 - 最后改
src/views/**与src/components/**。 - 两端都用
@指向src，按现有别名写法保持一致。 - 请求统一走
src/utils/request.js，不要重复造 axios 实例。 - 用户端与管理端 token key 不同：
- 用户端常用
user_token - 管理端常用
token - 用户端主要页面在
vue3-user-front/src/views/： interview、oj、mock-interviewresume、community、momentsblog、codepen、flashcardpoints、plan、team、knowledge- 管理端主要页面在
vue3-admin-front/src/views/： user、interview、ojcommunity、moments、chatblog、codepen、resumesensitive、filestorage、logs、system
9. SQL 与数据变更约定
- 结构变更优先写版本增量脚本到
sql/vX.Y.Z/。 - 脚本命名使用业务语义，例如
oj_tables.sql、flashcard.sql。 - 表与字段命名沿用
snake_case。 - 保持
utf8mb4与合适索引策略。 - 涉及线上兼容时，避免直接破坏性
DROP，优先可回滚的增量迁移。 - 若功能需要初始化数据，提供
INSERT示例并注明执行顺序。
10. 配置与安全约定
- 主配置在
xiaou-application/src/main/resources/application*.yml。 - 私密配置放
application-sec.yml，不要把真实密钥写入公开文档。 - AI 相关配置统一走
xiaou.ai.*配置树，Prompt 规范与运行时设计参考AI-DOCS/Archive/历史版本/2026-04-20-ai-prompt-governance.md。 - 监控相关配置与文档：
management.*在application.ymlAI-DOCS/Deployment/监控告警/Prometheus监控部署指南.mddocker/monitoring/
11. 不要手改的内容
pom-xml-flattened（由 flatten 插件生成）。target/、dist/、out/（构建产物）。node_modules/（依赖目录）。
12. 改动后验证清单
后端最小验证：
mvn -pl xiaou-application -am clean package -DskipTests
后端本地启动：
mvn -pl xiaou-application -am spring-boot:run
管理端本地启动：
cd vue3-admin-front
npm run dev
用户端本地启动：
cd vue3-user-front
npm run dev2
按需补充：
cd vue3-admin-front && npm run lint
cd vue3-user-front && npm run lint
13. 需求分析优先级
收到需求后按以下顺序判断：
- 这是管理端需求、用户端需求，还是双端需求。
- 是否需要后端接口变更。
- 是否需要 SQL 结构变更。
- 是否影响鉴权、错误码、日志、监控。
- 是否需要同步 PRD 或部署文档。
14. 文档使用建议
需求细节不明确时，优先查：
README.md（整体能力、启动方式、版本历史）。AI-DOCS/PRD/*.md（模块级产品规则）。AI-DOCS/Archive/历史版本/**（专项升级方案）。AI-DOCS/Archive/coze/*.md（历史 AI 工作流配置归档）。
优先复用现有模块与路径约定，避免“新建平行体系”。
Source: xiaou61/Code-Nest — distributed by TomeVault.