# reusable

**Repository Path**: lssjzmn/reusable

## Basic Information

- **Project Name**: reusable
- **Description**: 可复用规范包（从 eams_project 抽取）
这里把 eams_project（EAMS 资产管理系统）里与业务无关、只与"怎么做事"有关的约定抽成了可直接搬运的形式。 新项目开工时把本目录的东西拷过去，AI 助手（CodeBuddy）会自动按同一套风格协作，不必每次口头交代。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-06
- **Last Updated**: 2026-10-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 可复用规范包（从 `eams_project` 抽取）

这里把 `eams_project`（EAMS 资产管理系统）里**与业务无关、只与"怎么做事"有关**的约定抽成了可直接搬运的形式。
新项目开工时把本目录的东西拷过去，AI 助手（CodeBuddy）会自动按同一套风格协作，不必每次口头交代。

## 目录

```
reusable/
├── README.md                    # 本文件：怎么用、怎么维护
├── CODEBUDDY.md                 # 模板：放新项目根目录（全文默认进上下文，保持精简）
├── rules/                       # 项目规则：拷到新项目 .codebuddy/rules/ 下
│   ├── backend/RULE.mdc         # 后端规范（alwaysApply: true）
│   ├── frontend/RULE.mdc        # 前端规范（alwaysApply: true）
│   └── docs/RULE.mdc            # 文档与变更管理（alwaysApply: false，按需加载）
└── 新项目起步清单.md             # 开工动作清单（放新项目的 docs/ 或仓库根）
```

## 怎么用（3 步）

1. **拷规则**：把 `rules/` 下的三个文件夹原样复制到新项目根目录的 `.codebuddy/rules/`。
   规则名（目录名）可改，但**一条规则 = 一个文件夹 + 其中的 `RULE.mdc`**，这是 CodeBuddy 的约定。
2. **拷项目速览**：把 `CODEBUDDY.md` 放到新项目**根目录**，按占位符填好（它没有 frontmatter、全文会进上下文，所以保持精简）。
3. **拷清单**：把 `新项目起步清单.md` 放到新项目仓库里（建议 `docs/`），照着从第 0 节往下勾。

### 生效时机（容易忽略）

- 规则在**新建对话会话时**才加载 —— 复制完规则后**要新开一轮对话**才生效，当前会话不会自动加载。
- 想确认有没有生效，直接在对话里问：**"当前应用了哪些规则？"**

### 三种加载方式的取舍（本包的默认设置）

| 本包文件 | 设置 | 适用 | 什么时候改 |
| --- | --- | --- | --- |
| `backend/RULE.mdc` | `alwaysApply: true` | 后端是主力开发对象 | 纯前端项目 → 改成 `false`（变按需加载） |
| `frontend/RULE.mdc` | `alwaysApply: true` | 前端是主力开发对象 | 后端项目 → 改成 `false` |
| `docs/RULE.mdc` | `alwaysApply: false` | 只在写/改文档时用得上，按 `description` 相关性自动引入 | 团队文档规范很严时 → 改成 `true` |

> 官方建议：`alwaysApply: true` 的核心规则控制在 **3~5 条**；规则太长（> 500 行）要拆分。
> 上下文吃紧时，优先把 `frontend` 改成 `false`（按需加载仍然会在写 Vue 时被引入）。

## 维护

- **规则是活文档**：在新项目里调整了约定，就改对应 `RULE.mdc` 并更新它的 `updatedAt`（ISO 8601，含毫秒与 `Z`）。
- **不要让规则与 README 打架**：规则写"怎么做"，README 写"这个项目有什么"，两者冲突时以代码现状为准，并回头修文档。
- 本包是从 EAMS 抽取的**通用层**；EAMS 专有内容（业务表、权限码清单、打印方案）**没有**放进来 —— 见下节。

## 刻意没有抽进来的东西（别照搬）

| 没有抽 | 原因 |
| --- | --- |
| 业务表结构与字段（资产/调拨/维修/报废/盘点） | 强绑 EAMS 业务；新项目只借用**分层与命名**方式 |
| 41 个权限码清单与 RBAC 矩阵 | 是 EAMS 的授权设计；新项目要按自己的角色重新划 |
| `db/alter/` 历史增量脚本 | 只需保留**命名与幂等约定**，脚本本身不通用 |
| 打印链路的**项目特定代码**（机型参数、字体渲染、某套标签的字段与尺寸） | 强绑现场，不通用。**通用部分已沉淀进 `template`**（后端排版引擎 + 前端内容源 / WS 客户端 / 预览），新项目默认不启用即可；**架构约定见下节** |
| `.codebuddy/memory/` 与 `plans/` 里的过程记录 | 那是"某次怎么做"的流水，不是规范；规范已提炼进 `rules/` |
| 具体中间件实现细节（打印服务 TSPL、ECharts 图表配置等） | 规则只保留"若用到则怎么用"的约定；**骨架模板已内置 MinIO / XXL-JOB / EasyExcel**（连同配置与示例用法），不需要的直接删依赖与配置即可 |

## 如果新项目要打标签（抄这五条，别抄代码）

代码不通用（协议实现、字体渲染、机型参数都强绑现场），但下面几条是**踩过坑才定下来的架构约定**：

1. **后端只出指令片段**：产出 `{"functions_inorder":[…]}` 里的**单张标签部分**并回传**最终生效版面坐标**，**不含 `openport`/`closeport`**；后端不连打印服务、不碰打印机 IO。
2. **落地在客户端**：浏览器（或独立桌面客户端）直连**本机 TSC PrintServer**；报文是函数调用列表，收尾是**纯文本 `Finished`**，失败回 `{"Function_Failed":"函数名"}`（由客户端翻成中文原因）。
3. **页面必须保持 HTTP**：浏览器要用 `ws://127.0.0.1:8888` 直连本机服务，上 HTTPS 会被混合内容拦截 —— 要写进部署检查清单。
4. **端口不互相占用**：8888 归打印服务，业务侧一律做**客户端**，**不要自建监听**（否则同机只能跑一个）。
5. **口径单一来源 + 同步义务**：二维码正文在前端、版面算法在后端，改一处必须两侧同步；若还有第二个构造指令的客户端（独立打印工具），要再同步一次，并把**刻意差异**（如标题粗体、`DIRECTION` 默认值）显式写进文档。

落点：已沉淀为 `rules/backend/RULE.mdc` §11 与 `rules/frontend/RULE.mdc` §4 的 REQ 条目；骨架侧的可选能力说明见 `../template/backend/README.md` §八、`../template/frontend/README.md` §七；完整指令契约见业务项目 `../eams-print-server/docs/PROTOCOL.md`。

## 来源对照（便于回溯核实）

| 本包内容 | 主要来源 |
| --- | --- |
| 后端规范 §1~§13 | `eams-control/README.md`（§1.3 代码结构、§2 技术栈、§4 API/权限、§6 DDL 变更、§7 构建部署）、`EAMS系统设计与开发计划.md`（§2 选型理由、§3 架构、§4 工程结构、§13 文档与变更管理）、`eams-control/CHANGELOG.md`（写法） |
| 前端规范 §1~§11 | `eams-ui/README.md`（§5 目录结构、§6 接口与交互约定）、`EAMS系统设计与开发计划.md`（§4.2 前端结构）、实际代码约定（`api/request.ts`、`composables/`、`directives/`） |
| 文档规范 §1~§7 | `EAMS系统设计与开发计划.md`（§13）、各 README 的「差异说明」表与「部署前检查清单」、三份 CHANGELOG |
| 起步清单 §1~§6 | 上述文档 + 实施中踩过的坑（权限码分层、只读角色越权、DDL 双写、超时提示、无真机验收方式） |
| 打印/硬件链路的架构约定（上节五条） | 三工程现状：`eams-control` 的 `service/LabelPrintService.java`（只出片段 + 回传坐标）、`eams-ui` 的 `src/utils/tscPrintServer.ts`（浏览器直连 + 两级探活 + 失败中文化）与 `labelPreview.ts`（照抄坐标预览）、`eams-print-server/`（**打印客户端**：自构造指令、默认 USB 免驱动、**不再监听端口**）、`eams-print-server/docs/PROTOCOL.md`（指令契约冻结版） |