code-nest-project-spec

name	code-nest-project-spec
description	Code-Nest 多模块全栈项目协作规范与落点导航。Use when modifying this repository for feature development, bug fixing, refactor, API change, SQL migration, or frontend-backend联调 so changes land in the correct module with consistent conventions.

Code-Nest 项目规范

1. 目标

在本仓库内进行任何开发时，先用本规范完成三件事：

1. 快速定位改动应该落在哪个模块。
2. 按既有约定实现，避免破坏统一风格。
3. 用最小必要命令验证改动可编译、可运行、可联调。
4. 在我给需求后，你可以调用一些已经有的skill 来帮助你完善这些功能，更好的规范你

2. 仓库全景

• 后端是 Maven 多模块工程，根 pom.xml 管理版本与子模块。
• 后端启动入口在 xiaou-application，统一上下文路径是 /api。
• 前端分为两套：

1. vue3-admin-front（管理端，默认端口 3000）
2. 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.java
• xiaou-common/src/main/java/com/xiaou/common/core/domain/ResultCode.java

关键业务码：

• 200：成功
• 701：Token 无效
• 702：Token 过期
• 703：权限不足
• 704：账号禁用

前端拦截器已按上述业务码处理跳转与提示，不要随意改语义。

7. 后端开发落地步骤

1. 先确认业务归属模块，再改对应模块下 controller/service/mapper。
2. 新增接口时，保持现有路径风格（admin/user/pub）。
3. DTO、枚举、domain 放在当前业务模块，不要塞到 xiaou-application。
4. 公共逻辑先考虑放 xiaou-common，避免复制代码。
5. 跨模块调用先复用 API 契约模块（xiaou-user-api、xiaou-sensitive-api）。
6. MyBatis XML 一般在 src/main/resources/mapper。
7. OJ 模块是特例，Mapper XML 在 xiaou-oj/src/main/java/com/xiaou/oj/mapper/。
8. 需要新增模块时，同时更新根 pom.xml 的 <modules> 与 xiaou-application/pom.xml 依赖。

8. 前端开发落地步骤

1. 先看路由文件定位页面：src/router/index.js。
2. 再看 API 封装：src/api/*.js。
3. 最后改 src/views/** 与 src/components/**。
4. 两端都用 @ 指向 src，按现有别名写法保持一致。
5. 请求统一走 src/utils/request.js，不要重复造 axios 实例。
6. 用户端与管理端 token key 不同：
7. 用户端常用 user_token
8. 管理端常用 token
9. 用户端主要页面在 vue3-user-front/src/views/：
10. interview、oj、mock-interview
11. resume、community、moments
12. blog、codepen、flashcard
13. points、plan、team、knowledge
14. 管理端主要页面在 vue3-admin-front/src/views/：
15. user、interview、oj
16. community、moments、chat
17. blog、codepen、resume
18. sensitive、filestorage、logs、system

9. SQL 与数据变更约定

1. 结构变更优先写版本增量脚本到 sql/vX.Y.Z/。
2. 脚本命名使用业务语义，例如 oj_tables.sql、flashcard.sql。
3. 表与字段命名沿用 snake_case。
4. 保持 utf8mb4 与合适索引策略。
5. 涉及线上兼容时，避免直接破坏性 DROP，优先可回滚的增量迁移。
6. 若功能需要初始化数据，提供 INSERT 示例并注明执行顺序。

10. 配置与安全约定

1. 主配置在 xiaou-application/src/main/resources/application*.yml。
2. 私密配置放 application-sec.yml，不要把真实密钥写入公开文档。
3. AI 相关配置统一走 xiaou.ai.* 配置树，Prompt 规范与运行时设计参考 AI-DOCS/Archive/历史版本/2026-04-20-ai-prompt-governance.md。
4. 监控相关配置与文档：
5. management.* 在 application.yml
6. AI-DOCS/Deployment/监控告警/Prometheus监控部署指南.md
7. docker/monitoring/

11. 不要手改的内容

1. pom-xml-flattened（由 flatten 插件生成）。
2. target/、dist/、out/（构建产物）。
3. 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. 需求分析优先级

收到需求后按以下顺序判断：

1. 这是管理端需求、用户端需求，还是双端需求。
2. 是否需要后端接口变更。
3. 是否需要 SQL 结构变更。
4. 是否影响鉴权、错误码、日志、监控。
5. 是否需要同步 PRD 或部署文档。

14. 文档使用建议

需求细节不明确时，优先查：

1. README.md（整体能力、启动方式、版本历史）。
2. AI-DOCS/PRD/*.md（模块级产品规则）。
3. AI-DOCS/Archive/历史版本/**（专项升级方案）。
4. AI-DOCS/Archive/coze/*.md（历史 AI 工作流配置归档）。

优先复用现有模块与路径约定，避免“新建平行体系”。