# MEMORY.md —— 长期记忆

## 🌐 语言要求
- **所有交互一律使用中文**
- 技术术语可保留原文（API、SQL、DTO 等），但解释、对话、回复用中文

## Java 注释规范（统一约定）

1. 所有公共接口和类必须包含 Javadoc
2. 注释语言：中文描述业务背景，技术术语保留英文（如 NPE）
3. 禁止生成 "Gets the value of X" 这类无意义的 getter/setter 注释
4. 复杂算法必须在代码块上方解释核心逻辑
5. 禁止使用 HTML 标签

## 物料近似查询 searchSimilar() 优先级（2026-05-29 产品决策，不查规格）

产品决定**不查询规格字段**，物料近似查询 `searchSimilar()` 按以下优先级分步：

1. **名称精确匹配** (`material_name = keyword`) — 优先级最高
2. **名称前缀匹配** (`material_name LIKE 'keyword%'`)
3. **名称模糊匹配** (`material_name LIKE '%keyword%'`)
4. **编码模糊匹配** (`material_code LIKE '%keyword%'`) — 兜底

去重原则：已在前置层级匹配的物料不再在后置层级重复出现。
保留旧 `searchByNameLike()` 不动。

## 开发注意事项（统一约定）

1. **复用优先**：逻辑雷同时提取公共方法复用，避免重复代码
2. **业务表仅存物料id**：物料相关字段仅存 `material_id`，其他数据（编码、名称、规格、单位等）通过关联查询填充，防止名称/编码变动后数据不一致
3. **填充在 Service 层**：关联数据的填充逻辑统一在 Service 层处理，不放在 Controller 或 Mapper
4. **首个版本直接改 DDL**：2026年5月为 v1.0，脚本直接修改建表语句，不需要写 ALTER TABLE 迁移
5. **字典优先用 DictService**：字典取值优先使用 `DictService` 公共方法，不手写字典查询逻辑
6. **禁止 List.of()**：Java 8 不兼容，统一用 `Collections.emptyList()` 替代

## Git 提交约定

1. **禁止 commit** — 不做任何 commit 操作，只允许查看、修改代码
2. **提示 commit 时必须附带 commit message** — 让用户可直接复制运行
3. 如需提交代码，由用户手动执行 commit
4. **`application.yml` / `application-local.yml` 由用户自行提交** — Agent 绝不碰这两个配置文件的版本管理

## 部署约定

1. **禁止自动部署测试环境** — 不做任何自动部署操作
2. 代码修改后由用户手动决定何时部署

## 数据库脚本执行状态（截至 2026-05-29）

### 本地库 (localhost:31983) 和 测试库 (Docker db:5432) 均已执行：

**基础脚本：**
- ✅ 00-init.sql - 基础表结构
- ✅ 10-system.sql - 系统数据
- ✅ 20-master-data-init.sql - 基础数据
- ✅ 22-material-type-dict.sql - 物料类型字典
- ✅ 30-sales.sql - 销售模块
- ✅ 40-purchase.sql - 采购模块
- ✅ 50-inventory.sql - 库存模块
- ✅ 99-default-warehouse.sql - 默认仓库

**序列脚本：**
- ✅ 23-stocktake-sequence.sql - 盘点单号序列 (`seq_im_stocktake_no`)
- ✅ 24-customer-sequence.sql - 客户编码序列 (`seq_md_customer_code`)
- ✅ 25-supplier-sequence.sql - 供应商编码序列 (`seq_md_supplier_code`)

**字段变更脚本：**
- ✅ 26-material-last-price.sql - 物料表添加 `last_inbound_price`、`last_outbound_price`
- ✅ fix-fin-add-order-date.sql - 财务表添加 `order_date`
- ✅ fix-write-off-add-updater.sql - 核销表添加 `updater`、`update_time`
- ✅ fix-write-off-remove-receipt-payment-id.sql - 删除 `fin_ar_write_off.receipt_id`、`fin_ap_write_off.payment_id`
- ✅ fix-ai-oper-log.sql - sys_oper_log 添加 AI 字段（`ai_session_id`, `ai_model`, `prompt_tokens`, `completion_tokens`, `total_tokens`）

**双库状态：** 本地库和测试库结构已同步，所有脚本均已执行完毕。