contract-manager/.trae/rules/project_rules.md

# 项目规则

## 技术栈规范

### server 模块
- Java 21
- Spring Boot 3.3.7
- Spring Data JPA 3.3.7
- MySQL 8.0.33
- Lombok 1.18.32
- POI 5.2.5
- PDFBox 3.0.1
- Redis

### client 模块
- Java 21
- JavaFX 21
- ControlsFX 11.1.2
- Lombok 1.18.32
- caffeine 3.1.8
- .fxml 界面UI, 放置于 /client/src/main/resources/ui/ 目录下
- websocket 与 server 模块通信
- StringConverter 创建规则与实现逻辑 `docs/task/string_converter_implementation_guide.md`
- TableCell 规则与逻辑 `docs/task/table_cell_implementation_guide.md`
- Service 规则与逻辑 `docs/task/serservice_layer_rules.md`
- 客户端 Tasker 至 服务器端 Tasker 通信规则与逻辑 `docs/task/client_server_tasker_communication_rules.md`

### common 模块
- Java 21
- Lombok 1.18.32

## 文件命名规范
- Java类名：使用驼峰命名法，首字母大写，如 `ContractService.java`
- 接口名：使用驼峰命名法，首字母大写，以I开头，如 `IContractService.java`
- 控制器类名：以Controller结尾，如 `ContractController.java`
- 服务类名：以Service结尾，如 `ContractService.java`
- 实体类名：使用驼峰命名法，首字母大写，如 `Contract.java`
- FXML文件：使用小写字母和下划线，如 `contract_view.fxml`
- SQL文件：表名使用大写和下划线，如 `CONTRACT_TYPE_LOCAL.sql`

## 目录结构规范
### 项目整体结构
- `client/`: 客户端模块，基于JavaFX实现的桌面应用
- `server/`: 服务端模块，基于Spring Boot实现的后端服务
- `common/`: 公共模块，包含客户端和服务端共享的代码
- `docs/`: 项目文档和数据库脚本目录
- `.trae/`: Trae IDE相关配置和规则
- `.mvn/`: Maven包装器配置
- 根目录下包含Maven构建文件和配置文件

### server 模块目录结构
- `src/main/java/com/ecep/contract/`: 主包路径
  - `api/`: API接口定义
  - `cloud/`: 云服务集成相关代码
  - `config/`: Spring Boot配置类
  - `controller/`: Web控制器
  - `ds/`: 数据访问层，按业务领域组织
    - `company/`: 公司相关业务
    - `contract/`: 合同相关业务
    - `customer/`: 客户相关业务
    - `project/`: 项目相关业务
    - `vendor/`: 供应商相关业务
    - 每个业务领域包含：`model/`(实体类)、`repository/`(数据访问接口)、`service/`(业务逻辑)、`vo/`(视图对象)
  - `handler/`: WebSocket处理器
  - `service/`: 服务层，包含一些通用服务和任务处理器
  - `ui/`: UI相关组件
  - `util/`: 工具类
  - 核心服务接口和基类文件直接位于contract包下
- `src/main/resources/`: 资源文件目录
- `src/test/`: 测试代码目录

### client 模块目录结构
- `src/main/java/com/ecep/contract/`: 主包路径
  - `controller/`: JavaFX控制器，按业务领域组织, 详细规范见 .trae\rules\client_controller_rules.md
    - 包含各种业务窗口控制器和Tab皮肤控制器
  - `converter/`: 类型转换器，详细规范见 .trae\rules\client_converter_rules.md
  - `serializer/`: 序列化相关类
  - `service/`: 客户端服务层，与服务端交互, 详细规范见 .trae\rules\client_service_rules.md
  - `task/`: 客户端任务类, 详细规范见 .trae\rules\client_task_rules.md
  - `util/`: 工具类
  - `vm/`: 视图模型
- `src/main/resources/ui/`: FXML界面文件目录
- `src/test/`: 测试代码目录

### common 模块目录结构
- `src/main/java/ecep/contract/`: 包含客户端和服务端共享的代码
  - `constant/`: 常量类，按业务领域组织
  - `model/`: 实体类，按业务领域组织, 不包含Serializable接口和serialVersionUID字段， 详细规范见 .trae\rules\entity_rules.md
  - `vo/`: 视图对象，按业务领域组织, 包含Serializable接口和serialVersionUID字段, 详细规范见 .trae\rules\vo_rules.md
  - `util/`: 工具类

### 文档和资源目录
- `docs/db/`: 数据库脚本文件
- `docs/task/`: 任务相关文档和规范
- `docs/model/`: 数据模型文档
- 其他项目文档和资源

## 数据库规范
- 表名使用大写字母和下划线，如 `COMPANY_VENDOR_FILE_TYPE_LOCAL`
- 字段名使用大写字母和下划线，如 `CREATE_DATE`
- 主键命名为 `ID`
- 外键命名格式为 `[关联表名]_ID`
- 唯一约束命名格式为 `UK_[表名缩写]_[字段名]`

## 代码规范
- 使用Lombok注解简化代码，如 `@Data`、`@Slf4j` 等
- 类和方法应有适当的JavaDoc注释
- 变量命名应清晰表达其含义
- 避免魔法数字，使用常量替代
- 异常处理使用统一的异常处理机制

## 忽略文件
ignore:
  - .idea
  - target
  - *.iml
  - .gitignore
  - .gitattributes
  - out/
  - *.log
  - build/
  - .DS_Store
  - *.class

  
# 6A工作流执行规则
## 阶段1: Align (对齐阶段)
### 目标: 模糊需求 → 精确规范
### 执行步骤
1.  **项目上下文分析**
-   分析现有项目结构、技术栈、架构模式、依赖关系
-   分析现有代码模式、现有文档和约定
-   理解业务域和数据模型
2.  **需求理解确认**
-   创建 `docs/任务名/ALIGNMENT_[任务名].md`
-   包含项目和任务特性规范
-   包含原始需求、边界确认(明确任务范围)、需求理解(对现有项目的理解)、疑问澄清(存在歧义的地方)
3.  **智能决策策略**
-   自动识别歧义和不确定性
-   生成结构化问题清单（按优先级排序）
-   优先基于现有项目内容和查找类似工程和行业知识进行决策和在文档中回答
-   有人员倾向或不确定的问题主动中断并询问关键决策点
-   基于回答更新理解和规范
4.  **中断并询问关键决策点**
-   主动中断询问，迭代执行智能决策策略
5.  **最终共识**
-   生成 `docs/任务名/CONSENSUS_[任务名].md` 包含:
-   明确的需求描述和验收标准
-   技术实现方案和技术约束和集成方案
-   任务边界限制和验收标准
-   确认所有不确定性已解决
### 质量门控
-   需求边界清晰无歧义
-   技术方案与现有架构对齐
-   验收标准具体可测试
-   所有关键假设已确认
-   项目特性规范已对齐
## 阶段2: Architect (架构阶段)
### 目标: 共识文档 → 系统架构 → 模块设计 → 接口规范
### 执行步骤
1.  **系统分层设计**
-   基于CONSENSUS、ALIGNMENT文档设计架构
-   生成 `docs/任务名/DESIGN_[任务名].md` 包含:
-   整体架构图(mermaid绘制)
-   分层设计和核心组件
-   模块依赖关系图
-   接口契约定义
-   数据流向图
-   异常处理策略
2.  **设计原则**
-   严格按照任务范围，避免过度设计
-   确保与现有系统架构一致
-   复用现有组件和模式
### 质量门控
-   架构图清晰准确
-   接口定义完整
-   与现有系统无冲突
-   设计可行性验证
## 阶段3: Atomize (原子化阶段)
### 目标: 架构设计 → 拆分任务 → 明确接口 → 依赖关系
### 执行步骤
1.  **子任务拆分**
-   基于DESIGN文档生成 `docs/任务名/TASK_[任务名].md`
-   每个原子任务包含:
-   输入契约(前置依赖、输入数据、环境依赖)
-   输出契约(输出数据、交付物、验收标准)
-   实现约束(技术栈、接口规范、质量要求)
-   依赖关系(后置任务、并行任务)
2.  **拆分原则**
-   复杂度可控，便于AI高成功率交付
-   按功能模块分解，确保任务原子性和独立性
-   有明确的验收标准，尽量可以独立编译和测试
-   依赖关系清晰
3.  **生成任务依赖图**(使用mermaid)
### 质量门控
-   任务覆盖完整需求
-   依赖关系无循环
-   每个任务都可独立验证
-   复杂度评估合理
## 阶段4: Approve (审批阶段)
### 目标: 原子任务 → 人工审查 → 迭代修改 → 按文档执行
### 执行步骤
1.  **执行检查清单**
-   完整性：任务计划覆盖所有需求
-   一致性：与前期文档保持一致
-   可行性：技术方案确实可行
-   可控性：风险在可接受范围，复杂度是否可控
-   可测性：验收标准明确可执行
2.  **最终确认清单**
-   明确的实现需求(无歧义)
-   明确的子任务定义
-   明确的边界和限制
-   明确的验收标准
-   代码、测试、文档质量标准
## 阶段5: Automate (自动化执行)
### 目标: 按节点执行 → 编写测试 → 实现代码 → 文档同步
### 执行步骤
1.  **逐步实施子任务**
-   创建 `docs/任务名/ACCEPTANCE_[任务名].md` 记录完成情况
2.  **代码质量要求**
-   严格遵循项目现有代码规范
-   保持与现有代码风格一致
-   使用项目现有的工具和库
-   复用项目现有组件
-   代码尽量精简易读
-   API KEY放到.env文件中并且不要提交git
3.  **异常处理**
-   遇到不确定问题立刻中断执行
-   在TASK文档中记录问题详细信息和位置
-   寻求人工澄清后继续
4.  **逐步实施流程** 按任务依赖顺序执行，对每个子任务执行:
-   执行前检查(验证输入契约、环境准备、依赖满足)
-   实现核心逻辑(按设计文档编写代码)
-   编写单元测试(边界条件、异常情况)
-   运行验证测试
-   更新相关文档
-   每完成一个任务立即验证
## 阶段6: Assess (评估阶段)
### 目标: 执行结果 → 质量评估 → 文档更新 → 交付确认
### 执行步骤
1.  **验证执行结果**
-   更新 `docs/任务名/ACCEPTANCE_[任务名].md`
-   整体验收检查:
-   所有需求已实现
-   验收标准全部满足
-   项目编译通过
-   所有测试通过
-   功能完整性验证
-   实现与设计文档一致
2.  **质量评估指标**
-   代码质量(规范、可读性、复杂度)
-   测试质量(覆盖率、用例有效性)
-   文档质量(完整性、准确性、一致性)
-   现有系统集成良好
-   未引入技术债务
3.  **最终交付物**
-   生成 `docs/任务名/FINAL_[任务名].md`(项目总结报告)
-   生成 `docs/任务名/TODO_[任务名].md`(精简明确哪些待办的事宜和哪些缺少的配置等，我方便直接寻找支持)
4.  **TODO询问** 询问用户TODO的解决方式，精简明确哪些待办的事宜和哪些缺少的配置等，同时提供有用的操作指引
# 技术执行规范
## 安全规范
-   API密钥等敏感信息使用.env文件管理
## 文档同步
-   代码变更同时更新相关文档
## 测试策略
-   测试优先：先写测试，后写实现
-   边界覆盖：覆盖正常流程、边界条件、异常情况
## 交互体验优化
### 进度反馈
-   显示当前执行阶段
-   提供详细的执行步骤
-   标示完成情况
-   突出需要关注的问题
### 异常处理机制
#### 中断条件
-   遇到无法自主决策的问题
-   觉得需要询问用户的问题
-   技术实现出现阻塞
-   文档不一致需要确认修正
#### 恢复策略
-   保存当前执行状态
-   记录问题详细信息
-   询问并等待人工干预
-   从中断点任务继续执行