docs(wiki): sync CommonShelf/CAS master data documentation with current implementation (#25)

Author: Copilot

wiki/backend/api-reference.md

@@ -7,6 +7,8 @@
 - `announcements.router` -> `/api`
 - `cart_sync.router` -> `/api`
 - `chemical_info.router` -> `/api`
+- `chemical_name_map.router` -> `/api`
+- `common_shelf.router` -> `/api`
 - `consumable_orders.router` -> `/api`
 - `error_logs.router` -> `/api`
 - `events.router` -> `/api`
@@ -15,7 +17,7 @@
 - `user_logs.router` -> `/api`
 - `user_sessions.router` -> `/api/users/me`
 - `users.router` -> `/api`
-- `inventory_extended_routes` 与 `common_shelf` 通过 `register_*` 动态挂到 `inventory.router`，最终前缀为 `/api/inventory`。
+- `inventory_extended_routes` 通过 `register_*` 动态挂到 `inventory.router`，最终前缀为 `/api/inventory`。
 - `reagent_orders_workflow` 通过 `register_*` 动态挂到 `reagent_orders.router`，最终前缀为 `/api/reagent-orders`。
 
 ## 权限判定
@@ -102,12 +104,28 @@
 
 | 方法 | 路径 | 函数 | 权限 | 关键参数（path/query/body/file） | 返回模型 | 状态码 | 代码 |
 | --- | --- | --- | --- | --- | --- | --- | --- |
-| `GET` | `/api/inventory/common-shelf` | `list_common_shelf` | 已登录用户 | query: `search` | `—` | `200` | <InlineCodeRef href="https://github.com/hzb666/LabStorageManager/blob/main/app/api/common_shelf.py#L591" /> |
-| `POST` | `/api/inventory/common-shelf/consume-one` | `consume_one_common_shelf_item` | 管理员 | body: `CommonShelfConsumeRequest` | `—` | `200` | <InlineCodeRef href="https://github.com/hzb666/LabStorageManager/blob/main/app/api/common_shelf.py#L679" /> |
-| `GET` | `/api/inventory/common-shelf/export` | `export_common_shelf` | 已登录用户 | — | `—` | `200` | <InlineCodeRef href="https://github.com/hzb666/LabStorageManager/blob/main/app/api/common_shelf.py#L895" /> |
-| `DELETE` | `/api/inventory/common-shelf/group/{sample_inventory_id}` | `delete_common_shelf_group` | 已登录用户 | path: `sample_inventory_id` | `dict` | `200` | <InlineCodeRef href="https://github.com/hzb666/LabStorageManager/blob/main/app/api/common_shelf.py#L862" /> |
-| `PUT` | `/api/inventory/common-shelf/group/{sample_inventory_id}` | `update_common_shelf_group` | 已登录用户 | path: `sample_inventory_id`；body: `InventoryUpdate` | `dict` | `200` | <InlineCodeRef href="https://github.com/hzb666/LabStorageManager/blob/main/app/api/common_shelf.py#L783" /> |
-| `POST` | `/api/inventory/common-shelf/manual-add` | `manual_add_common_shelf_inventory` | 已登录用户 | body: `ManualInventoryCreate` | `dict` | `200` | <InlineCodeRef href="https://github.com/hzb666/LabStorageManager/blob/main/app/api/common_shelf.py#L757" /> |
+| `GET` | `/api/common-shelf/groups` | `list_common_shelf_groups` | 已登录用户 | query: `search`、`search_field`、`fuzzy`、`sort_by`、`sort_order` | `CommonShelfGroupListResponse` | `200` | <InlineCodeRef href="https://github.com/hzb666/LabStorageManager/blob/main/app/api/common_shelf.py#L131" /> |
+| `POST` | `/api/common-shelf/manual-add` | `manual_add_common_shelf` | 已登录用户 | body: `CommonShelfManualCreate` | `dict` | `200` | <InlineCodeRef href="https://github.com/hzb666/LabStorageManager/blob/main/app/api/common_shelf.py#L206" /> |
+| `GET` | `/api/common-shelf/groups/{group_key}/locations` | `get_common_shelf_group_locations` | 已登录用户 | path: `group_key` | `list[CommonShelfLocationSummaryResponse]` | `200` | <InlineCodeRef href="https://github.com/hzb666/LabStorageManager/blob/main/app/api/common_shelf.py#L155" /> |
+| `GET` | `/api/common-shelf/groups/{group_key}/location-suggestions` | `get_common_shelf_group_location_suggestions` | 已登录用户 | path: `group_key` | `list[str]` | `200` | <InlineCodeRef href="https://github.com/hzb666/LabStorageManager/blob/main/app/api/common_shelf.py#L164" /> |
+| `GET` | `/api/common-shelf/location-suggestions` | `get_common_shelf_location_suggestions_by_fields` | 已登录用户 | query: `cas_number`、`brand`、`specification` | `list[str]` | `200` | <InlineCodeRef href="https://github.com/hzb666/LabStorageManager/blob/main/app/api/common_shelf.py#L169" /> |
+| `GET` | `/api/common-shelf/groups/{group_key}/items` | `get_common_shelf_group_items` | 已登录用户 | path: `group_key` | `list[CommonShelfGroupItemResponse]` | `200` | <InlineCodeRef href="https://github.com/hzb666/LabStorageManager/blob/main/app/api/common_shelf.py#L187" /> |
+| `PUT` | `/api/common-shelf/groups/{group_key}` | `update_common_shelf_group` | 已登录用户 | path: `group_key`；body: `CommonShelfGroupEditRequest` | `dict` | `200` | <InlineCodeRef href="https://github.com/hzb666/LabStorageManager/blob/main/app/api/common_shelf.py#L229" /> |
+| `PUT` | `/api/common-shelf/groups/{group_key}/items/{item_id}` | `update_common_shelf_item` | 已登录用户 | path: `group_key`、`item_id`；body: `CommonShelfGroupItemUpdateRequest` | `dict` | `200` | <InlineCodeRef href="https://github.com/hzb666/LabStorageManager/blob/main/app/api/common_shelf.py#L312" /> |
+| `POST` | `/api/common-shelf/groups/{group_key}/add-bottles` | `add_common_shelf_bottles` | 已登录用户 | path: `group_key`；body: `CommonShelfAddBottlesRequest` | `dict` | `200` | <InlineCodeRef href="https://github.com/hzb666/LabStorageManager/blob/main/app/api/common_shelf.py#L357" /> |
+| `POST` | `/api/common-shelf/groups/{group_key}/remove-one` | `remove_one_common_shelf` | 已登录用户 | path: `group_key`；body: `CommonShelfRemoveOneRequest` | `dict` | `200` | <InlineCodeRef href="https://github.com/hzb666/LabStorageManager/blob/main/app/api/common_shelf.py#L399" /> |
+| `DELETE` | `/api/common-shelf/groups/{group_key}/items/{item_id}` | `delete_common_shelf_item` | 已登录用户 | path: `group_key`、`item_id` | `dict` | `200` | <InlineCodeRef href="https://github.com/hzb666/LabStorageManager/blob/main/app/api/common_shelf.py#L439" /> |
+| `DELETE` | `/api/common-shelf/groups/{group_key}` | `delete_common_shelf_group` | 管理员 | path: `group_key` | `dict` | `200` | <InlineCodeRef href="https://github.com/hzb666/LabStorageManager/blob/main/app/api/common_shelf.py#L473" /> |
+| `GET` | `/api/common-shelf/export` | `export_common_shelf` | 已登录用户 | — | `—` | `200` | <InlineCodeRef href="https://github.com/hzb666/LabStorageManager/blob/main/app/api/common_shelf.py#L506" /> |
+
+### CAS 主数据接口 (`chemical_name_map`)
+
+| 方法 | 路径 | 函数 | 权限 | 关键参数（path/query/body/file） | 返回模型 | 状态码 | 代码 |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| `GET` | `/api/chemical-name-map` | `list_chemical_name_map` | 已登录用户 | query: `search`、`search_field`、`fuzzy`、`skip`、`limit` | `dict` | `200` | <InlineCodeRef href="https://github.com/hzb666/LabStorageManager/blob/main/app/api/chemical_name_map.py#L85" /> |
+| `POST` | `/api/chemical-name-map` | `create_chemical_name_map` | 已登录用户 | body: `ChemicalNameMapCreate` | `ChemicalNameMapResponse` | `200` | <InlineCodeRef href="https://github.com/hzb666/LabStorageManager/blob/main/app/api/chemical_name_map.py#L123" /> |
+| `PUT` | `/api/chemical-name-map/{item_id}` | `update_chemical_name_map` | 已登录用户 | path: `item_id`；body: `ChemicalNameMapUpdate` | `ChemicalNameMapResponse` | `200` | <InlineCodeRef href="https://github.com/hzb666/LabStorageManager/blob/main/app/api/chemical_name_map.py#L149" /> |
+| `DELETE` | `/api/chemical-name-map/{item_id}` | `delete_chemical_name_map` | 已登录用户 | path: `item_id` | `dict` | `200` | <InlineCodeRef href="https://github.com/hzb666/LabStorageManager/blob/main/app/api/chemical_name_map.py#L173" /> |
 
 ### 试剂订单基础接口 (`reagent_orders`)
 
@@ -211,4 +229,3 @@
 - [app/main.py](https://github.com/hzb666/LabStorageManager/blob/main/app/main.py)（行370，382，396）
 - [app/services/chemical_info.py](https://github.com/hzb666/LabStorageManager/blob/main/app/services/chemical_info.py)（行442）
 
-

wiki/backend/api-workflows.md

@@ -13,6 +13,7 @@
 - [app/api/reagent_orders_workflow.py](https://github.com/hzb666/LabStorageManager/blob/main/app/api/reagent_orders_workflow.py) 负责审批、到货、入库和删除。
 - [app/api/consumable_orders.py](https://github.com/hzb666/LabStorageManager/blob/main/app/api/consumable_orders.py) 同时承担耗材订单 CRUD 与状态流转。
 - [app/api/announcements.py](https://github.com/hzb666/LabStorageManager/blob/main/app/api/announcements.py)、[app/api/error_logs.py](https://github.com/hzb666/LabStorageManager/blob/main/app/api/error_logs.py)、[app/api/user_logs.py](https://github.com/hzb666/LabStorageManager/blob/main/app/api/user_logs.py)、[app/api/cart_sync.py](https://github.com/hzb666/LabStorageManager/blob/main/app/api/cart_sync.py)、[app/api/events.py](https://github.com/hzb666/LabStorageManager/blob/main/app/api/events.py) 则处理外围能力。
+- [app/api/common_shelf.py](https://github.com/hzb666/LabStorageManager/blob/main/app/api/common_shelf.py)、[app/api/chemical_name_map.py](https://github.com/hzb666/LabStorageManager/blob/main/app/api/chemical_name_map.py) 负责常用货架分组与 CAS 主数据维护。
 
 ## 试剂工作流
 
@@ -45,14 +46,15 @@
 - `borrow` 和 `return` 会修改状态、写借还历史，并通过 SSE 通知前端。
 - `dashboard/my-borrows` 和 `dashboard/pending-stockin` 为首页和仪表盘聚合数据。
 - `import/template` 与 `import` 组成 Excel 导入链路。
-- 常用货架不单独建表，而是同 `inventory` 共表，通过 `is_common` 语义和专用路由完成分组维护。
+- 常用货架由独立的 `common_shelf` 表（`CommonShelf` 模型）维护，按 `CAS + 品牌 + 规格` 形成分组键 `group_key`，并由 `/api/common-shelf/*` 提供分组级与瓶级操作。
+- 手动加瓶前会校验 CAS 主数据；若缺失主数据，需要先走 `/api/chemical-name-map` 完成补录，避免常用货架出现无法稳定展示名称的脏数据。
 
 ## 事件驱动补充层
 
 路由不是唯一的更新出口。很多接口在数据库提交后还会广播 SSE：
 
 - 库存创建、编辑、删除、借用、归还
-- 常用货架创建、编辑、删除、消耗
+- 常用货架创建、编辑、删除、加瓶、扣减 1 瓶
 - 试剂订单与耗材订单的创建、更新、删除
 - 仪表盘聚合数据更新
 

wiki/changelog.md

@@ -2,6 +2,13 @@
 
 本页按版本概括项目的主要演进，用于帮助开发者快速判断能力边界、理解历史改动背景，并辅助阅读不同阶段的代码与文档。
 
+## 0.9.1
+
+- 重构常用货架为“分组 + 瓶级条目”模型，新增分组定位、位置建议、加瓶/扣减与条目级维护接口。
+- 分组逻辑：按 `CAS + 品牌（标准化）+ 规格（标准化）` 生成 `group_key`；只要三者之一变化，就会进入新分组或触发分组合并确认。
+- 新增 CAS 主数据维护能力（`/api/chemical-name-map`），支持在常用货架补录链路中先补主数据再续写加瓶操作。
+- 前端常用货架页新增 CAS 主数据管理入口，手动添加流程与主数据校验联动，减少名称缺失导致的展示不一致。
+
 ## 0.9.0
 
 - 引入 SSE 实时推送、常用货架管理和 FTS 全文搜索，补齐库存检索、状态感知与实时刷新能力。

wiki/frontend/page-map.md

@@ -40,7 +40,7 @@
 | `ReagentOrders` | `reagentOrderAPI` | `reagent_orders` |
 | `ConsumableOrders` | `consumableOrderAPI` | `consumable_orders` |
 | `Inventory` | `inventoryAPI` | `inventory` |
-| `CommonShelf` | `commonShelfAPI` | `common_shelf` |
+| `CommonShelf` | `commonShelfAPI`、`chemicalNameMapAPI` | `common_shelf` |
 | `CartImport` | `cartSyncAPI` | 以 HTTP 为主，提交后触发相关房间刷新 |
 
 ## 改动入口
@@ -50,6 +50,7 @@
 - 表单页优先接入 `BaseForm` 和 `validationSchemas`
 - 需要实时数据时，优先补齐 `useSSE` 或 `useListSSE`
 - 页面级导航变化时，同步更新本页和 [应用骨架](/frontend/app-shell)
+- 涉及常用货架补录时，同步考虑 CAS 主数据管理入口和 `chemicalNameMapAPI` 的联动
 
 ## 验证建议
 
@@ -64,4 +65,3 @@
 - [frontend/src/pages/Layout.tsx](https://github.com/hzb666/LabStorageManager/blob/main/frontend/src/pages/Layout.tsx)
 - [frontend/src/pages/ReagentOrders.tsx](https://github.com/hzb666/LabStorageManager/blob/main/frontend/src/pages/ReagentOrders.tsx)
 
-

wiki/user-guide/inventory-and-borrowing.md

@@ -126,10 +126,6 @@
 
 当某组还有可用瓶时，页面可能会出现 **拿一瓶**。
 
-### 这个操作有什么限制
-
-这个操作只有管理员可以用。普通用户点了也会提示权限不够。
-
 ### 它和借用有什么不同
 
 “拿一瓶”不是借用，它更像是把一瓶常用试剂直接记为消耗掉了。执行后，这瓶会被标记为已耗尽，剩余量清零，也会留下相应记录。
@@ -142,11 +138,12 @@
 
 - 查看常用货架
 - 新增常用货架条目
+- 补录或维护 CAS 主数据（名称、英文名、别名）
 - 编辑分组
-- 删除分组
+- 删除整组（仅管理员）
 - 导出分组
 
-其中“拿一瓶”仍然只有管理员可用。
+“拿一瓶”（扣减 1 瓶）登录用户即可操作。
 
 ## 手动补录怎么分
 
@@ -165,6 +162,8 @@
 - 公共试剂补录
 - 需要按组展示、按瓶消耗的常用品
 
+如果系统提示“该 CAS 还未录入主数据”，先在常用货架页点 **CAS 主数据管理** 补齐名称信息，再继续本次手动添加。
+
 ### 这两种方式的共同点
 
 - 都会检查 CAS 信息。