更新开发文档并调整开发环境配置

2026-04-20 14:32:44 +08:00
parent 49118a4418
commit 60a7906eb3
5 changed files with 102 additions and 20 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -88,3 +88,5 @@ ruoyi-ui/vue.config.js
 .pytest_cache/

 tests/
+
+tongweb_62318.properties
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -15,21 +15,58 @@

 ---

-## 协作约定
+## 高优先级规则

 - 使用简体中文进行思考和对话
- Git 提交说明使用中文
- Git 提交前必须检查暂存区，仅允许包含本次任务相关文件
- 若暂存区存在无关文件，必须先移出暂存或与用户确认，禁止顺带提交
- 根据设计文档产出实施计划时，默认输出两份文档：
-  - 后端实施计划放 `docs/plans/backend/`
-  - 前端实施计划放 `docs/plans/frontend/`
+- Git 提交说明必须使用中文
+- 忽略 `.DS_Store` 文件，不将其视为本次任务需要处理或提交的有效变更
+- 仅当用户明确声明调用 `using-superpowers` 时才允许启用；未明确声明时按普通流程直接处理需求
+- Git 提交前必须检查暂存区，仅允许包含本次任务相关文件；若存在无关文件，必须先移出暂存或与用户确认
+- 每一次改动都需要留下实施文档，记录修改内容、影响范围与验证情况
+- 功能设计同时涉及前端和后端改动时，必须分别输出后端与前端两份实施计划；若仅涉及单侧，则只输出对应实施计划
+- 新增或修改设计文档、实施计划、实施记录前，必须先确认保存路径是否正确
+- 前端相关安装、构建、调试、测试命令执行前，必须先通过 `nvm` 切换并确认 Node 版本
+- 测试结束后，自动关闭测试过程中启动的前后端进程
+- 重启后端时，必须优先使用 `bin/restart_java_backend.sh`
+
+---
+
+## 协作约定
+
+### 基础协作
+
 - 前端开发直接在当前分支进行，不需要额外创建 git worktree
+- 给出方案时，必须保持最短路径实现，不允许提供兼容性、补丁性或过度设计的方案
+- 不允许自行扩展出用户需求之外的兜底、降级或变体方案，避免业务逻辑偏移
+- 输出方案前必须完成全链路逻辑校验，确保方案逻辑正确、链路闭环
+
+### Git 与变更管理
+
+- Git 提交前必须检查暂存区，仅保留本次任务相关文件
+- 若暂存区存在无关文件，必须先移出暂存或与用户确认，禁止顺带提交
+- `.DS_Store` 默认忽略，不纳入任务变更范围
+
+### 文档产出
+
+- 若需求来自设计文档，默认同时沉淀后端与前端两份实施计划
+- 功能设计同时涉及前端和后端改动时，实施计划分别放在 `docs/plans/backend/` 与 `docs/plans/frontend/`
+- 功能修改只涉及前端或只涉及后端时，只输出对应的实施计划
+- 非前后端架构项目不强制拆分两份实施计划
+- 每一次改动都需要留下实施文档，实施记录优先放在 `docs/reports/implementation/`
+- 每次新增或修改设计文档、实施计划、实施记录前，都要先确认保存路径是否正确
+
+### 测试与运行
+
 - 测试结束后，自动关闭测试过程中启动的前后端进程
 - 重启后端时，必须优先使用 `bin/restart_java_backend.sh`，不要直接手工执行 `java -jar` 替代正式重启流程
+- 前端相关安装、构建、调试、测试命令执行前，必须先通过 `nvm` 切换并确认 Node 版本
+
+### 数据库与编码
+
 - 遇到 MCP 数据库操作时，使用项目配置文件中的数据库连接信息
- 执行包含中文内容的 MySQL SQL 脚本或数据库导入时，禁止直接手写 `mysql -e` 或普通重定向执行；必须优先使用 `bin/mysql_utf8_exec.sh <sql-file>`，确保会话字符集为 `utf8mb4`，避免导入或写入乱码
- 数据库字符集与排序规则统一要求：所有业务表、系统表新增或修改时，必须显式使用 `utf8mb4` 字符集与 `utf8mb4_general_ci` 排序规则；禁止引入 `utf8mb4_0900_ai_ci`、`utf8mb4_unicode_ci` 或其他混用排序规则
+- 执行包含中文内容的 MySQL SQL 脚本或数据库导入时，禁止直接手写 `mysql -e` 或普通重定向执行；必须优先使用 `bin/mysql_utf8_exec.sh <sql-file>`，确保会话字符集为 `utf8mb4`
+- 所有业务表、系统表新增或修改时，必须显式使用 `utf8mb4` 字符集与 `utf8mb4_general_ci` 排序规则
+- 禁止引入 `utf8mb4_0900_ai_ci`、`utf8mb4_unicode_ci` 或其他混用排序规则
 - 银行流水打标相关规则与参数编码需要统一使用全大写；新增或修改 `rule_code`、`indicator_code`、`param_code` 时，禁止混用大小写风格

 ---
@@ -63,6 +100,9 @@ mvn clean package -DskipTests
 ```bash
 cd ruoyi-ui

+# 使用 nvm 切换到项目所需 Node 版本
+nvm use
+
 # 安装依赖
 npm install --registry=https://registry.npmmirror.com

@@ -166,8 +206,10 @@ return AjaxResult.success(result);
 - 非业务字段如 `create_by`、`create_time` 由后端自动维护
 - 前端表单不要暴露通用审计字段
 - 新增菜单、字典、初始化数据时，同步补充 SQL 脚本
- 执行数据库脚本或导入数据库前，需确认客户端会话字符集为 `utf8mb4`；涉及中文插入、更新、导入时默认使用 `bin/mysql_utf8_exec.sh`
- 所有系统表和业务表的表级、字符字段级排序规则统一为 `utf8mb4_general_ci`；新增建表 SQL、字段追加 SQL、表结构修复 SQL 必须显式声明，避免因默认排序规则漂移导致联表或条件查询报错
+- 执行数据库脚本或导入数据库前，需确认客户端会话字符集为 `utf8mb4`
+- 涉及中文插入、更新、导入时默认使用 `bin/mysql_utf8_exec.sh`
+- 所有系统表和业务表的表级、字符字段级排序规则统一为 `utf8mb4_general_ci`
+- 新增建表 SQL、字段追加 SQL、表结构修复 SQL 必须显式声明字符集与排序规则，避免因默认排序规则漂移导致联表或条件查询报错

 ### 前端规范

@@ -228,15 +270,10 @@ ccdi/
 ### 主要业务代码分布

 - `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/`
-  - 含 `controller`、`domain`、`mapper`、`service`、`annotation`、`validation` 等目录
 - `ccdi-project/src/main/java/com/ruoyi/ccdi/project/`
-  - 含 `config`、`controller`、`domain`、`mapper`、`service`
 - `ccdi-lsfx/src/main/java/com/ruoyi/lsfx/`
-  - 含 `client`、`config`、`constants`、`controller`、`domain/request`、`domain/response`
 - `ruoyi-ui/src/views/`
-  - 当前包含 `ccdi`、`ccdiBaseStaff`、`ccdiProject`、`ccdiPurchaseTransaction`、`ccdiIntermediary`、亲属关系、员工调动、招聘等业务页面
 - `ruoyi-ui/src/api/ccdi/`
-  - 放置纪检初核业务 API 封装

 ### 添加新后端模块时

@@ -297,6 +334,9 @@ ccdi/
 - 只有历史资料或外部原始材料才放入 `assets/`
 - 如果移动了文档，需同步修正文档内引用路径
 - 若需求来自设计文档，默认同时沉淀后端与前端两份实施计划
+- 功能设计同时涉及前端和后端改动时，必须分别输出后端与前端两份实施计划；若仅涉及前端或仅涉及后端，则只输出对应实施计划；非前后端架构项目不强制拆分双文档
+- 每一次改动都需要留下实施文档，记录本次修改内容、影响范围与验证情况，实施记录优先放在 `docs/reports/implementation/`
+- 每次新增或修改设计文档、实施计划、实施记录前，都要先确认保存路径是否正确

 ---

@@ -307,3 +347,5 @@ ccdi/
 - `docker/backend`、`docker/frontend`、`docker/mock` 分别对应三类运行时镜像
 - `sql/migration/` 用于增量迁移脚本，新增修复脚本优先按日期或功能命名
 - 启动前后端或 Mock 服务做验证后，结束测试时要主动停止进程，避免残留占用端口
+- 前端相关安装、构建、调试、测试命令执行前，必须先通过 `nvm` 切换并确认 Node 版本
+
--- a/docs/reports/implementation/2026-04-20-agents-global-rules-sync-record.md
+++ b/docs/reports/implementation/2026-04-20-agents-global-rules-sync-record.md
@@ -0,0 +1,19 @@
+# AGENTS 全局规则同步实施记录
+
+## 本次改动
+
+- 更新根目录 `AGENTS.md` 的协作约定，补充 `.DS_Store` 忽略要求，以及 `using-superpowers` 只能在用户明确声明时启用的限制
+- 更新根目录 `AGENTS.md` 的前端命令与开发测试提醒，明确前端相关命令执行前必须先通过 `nvm` 切换并确认 Node 版本
+- 更新根目录 `AGENTS.md` 的文档维护要求，补充“每次改动均需留下实施文档”“前后端联动设计需拆分前后端实施计划”“写文档前先确认保存路径正确”等规则
+- 在根目录 `AGENTS.md` 新增“方案规范”章节，约束方案输出必须走最短实现路径，不得擅自扩展兼容、补丁、兜底或降级方案，并要求完成全链路逻辑校验
+
+## 影响范围
+
+- 影响文件仅限仓库根目录 `AGENTS.md`
+- 本次为项目协作规范更新，不涉及业务代码、数据库脚本、前端页面或后端接口变更
+
+## 验证说明
+
+- 已确认实施记录保存路径为 `docs/reports/implementation/`
+- 已人工核对新增规则与本次提供的全局 `AGENTS.md` 要求一致，且未覆盖或破坏仓库原有约束
+- 本次仅修改文档，无需运行代码测试
--- a/docs/reports/implementation/2026-04-20-agents-structure-optimization-record.md
+++ b/docs/reports/implementation/2026-04-20-agents-structure-optimization-record.md
@@ -0,0 +1,19 @@
+# AGENTS 文档结构优化实施记录
+
+## 本次改动
+
+- 重构根目录 `AGENTS.md` 的章节结构，新增“高优先级规则”章节，将高频且强约束的协作规则前置
+- 将原有分散在多个章节中的规则重新归类到“基础协作”“Git 与变更管理”“文档产出”“测试与运行”“数据库与编码”等小节
+- 保留原有核心约束不变，仅优化文档层次、阅读顺序与检索效率
+- 精简重复表达，例如将前后端实施计划拆分、实施记录留痕、`nvm` 使用、测试后关闭进程等规则统一收口到更明确的章节
+
+## 影响范围
+
+- 影响文件仅限仓库根目录 `AGENTS.md`
+- 本次为项目协作规范文档优化，不涉及业务代码、数据库脚本、前端页面或后端接口变更
+
+## 验证说明
+
+- 已确认实施记录保存路径位于 `docs/reports/implementation/`
+- 已人工检查优化后的 `AGENTS.md`，确认原有关键规则仍然保留，且文档结构更清晰
+- 本次仅修改文档，无需运行代码测试
--- a/ruoyi-admin/src/main/resources/application-dev.yml
+++ b/ruoyi-admin/src/main/resources/application-dev.yml
@@ -89,11 +89,11 @@ spring:
            # 地址
            host: 116.62.17.81
            # 端口，默认为6379
-            port: 6379
+            port: 56379
            # 数据库索引
-            database: 0
+            database: 9
            # 密码
-            password: Kfcx@1234
+            password: N0f3d12c4a927eee1+
            # 连接超时时间
            timeout: 10s
            lettuce: