docs: 用户/开发手册 HTML 版、db-schema 补 license_purchases、CLAUDE.md 文档地图、pay 对接指南
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JJ1g8XV1YhhmHRzhwWEW7o
This commit is contained in:
wangjia
+19
-43
@@ -107,9 +107,10 @@ inventories: # 库存批次：每行 = 某 product 在某仓库的一批
|
||||
# production_date/batch_no/supplier_name/warehouse_name —— 导入/审核时
|
||||
# 从源/product 拷贝，作历史保真 + 显示兜底
|
||||
stock_in_orders: # 入库单（status: draft→pending→approved/rejected；可由本人/管理员 withdraw 回 draft）
|
||||
stock_in_items: # 入库明细（product_id + 快照列 + quantity/unit_price/total_price/batch_no/production_date）
|
||||
stock_out_orders: # 出库单（同状态机）
|
||||
stock_out_items: # 出库明细（同上）
|
||||
stock_in_items: # 入库明细（product_id + 快照列 + quantity + cost_price 进价·单瓶 + cost_amount 总进价 + batch_no/production_date）
|
||||
stock_out_orders: # 出库单（同状态机；sale_total 应收合计 + profit_total 总利润，建单落库、确认售价/进价联动重算）
|
||||
stock_out_items: # 出库明细（cost_price 成本快照 + sale_price 售价 + cost_amount/sale_amount 两侧小计；成本/利润仅管理员可见，operator 响应被服务端抹零）
|
||||
# ※ 2026-07 定价消歧：旧列 unit_price/total_price/total_amount 弃用（详见 CLAUDE.md「定价字段口径」）
|
||||
inventory_logs: # 库存流水（每次变动自动记录 in/out + qty_before/after）
|
||||
inventory_checks / inventory_check_items: # 盘点单 / 盘点明细（FIFO 盘盈盘亏）
|
||||
```
|
||||
@@ -319,44 +320,15 @@ flutter build web --dart-define=BASE_URL=https://api.example.com
|
||||
|
||||
**规则**：所有硬编码 `localhost:8080` 的 URL 必须改用 `AppConfig` 对应属性，不得直接拼接字符串。
|
||||
|
||||
## 前端表格 UI 规范
|
||||
## 前端表格 UI 规范（ds 真相源，2026-07 起）
|
||||
|
||||
所有数据表格使用 `DataTableCard` widget，遵循以下规范：
|
||||
|
||||
### 行 Hover 效果
|
||||
`data_table_card.dart` 用 `Table` + `MouseRegion` + `ValueNotifier<int>` 实现行级 hover：
|
||||
- hover 时行背景色：`Color(0xFFF5F7FF)`
|
||||
- 列头背景色：`Color(0xFFF0F4FF)`
|
||||
|
||||
### 列头内嵌筛选（FilterableColumnHeader）
|
||||
可筛选的列头使用 `FilterableColumnHeader`，作为 `DataColumn.label` 传入：
|
||||
```dart
|
||||
DataColumn(
|
||||
label: FilterableColumnHeader(
|
||||
text: '仓库',
|
||||
options: warehouseOptions,
|
||||
selected: _filterWarehouse,
|
||||
onChanged: (v) => setState(() => _filterWarehouse = v),
|
||||
),
|
||||
)
|
||||
```
|
||||
- 鼠标 hover 时显示筛选图标（`filter_alt_outlined`，16px，右对齐）
|
||||
- 已激活筛选时图标常驻（`filter_alt`，蓝色）+ 取消 icon
|
||||
- 点击图标弹出多选对话框
|
||||
|
||||
### 客户端筛选模式
|
||||
部分表格（库存、商品、批次追踪、财务）采用客户端筛选：加载全量数据，在内存中过滤，派生 options：
|
||||
```dart
|
||||
final warehouseOptions = _records
|
||||
.map((r) => r.warehouseName ?? '')
|
||||
.where((s) => s.isNotEmpty)
|
||||
.toSet().toList()..sort();
|
||||
```
|
||||
|
||||
### 列显示/隐藏（ColDef + ColumnToggleButton）
|
||||
使用 `ColDef` 定义列，支持：
|
||||
- `required: true` — 不可隐藏
|
||||
- `minWidth: 1000` — 屏幕宽度不足时自动隐藏
|
||||
列表屏统一 `DsTable`（`client/lib/widgets/ds/ds_table.dart`）：toolbar + 表格 + pager 连成一卡，
|
||||
镜像原型 `.toolbar/.table/.pager`。列定义 `DsColumn`；可筛选列走列头漏斗（filtered 态主色高亮）；
|
||||
可隐藏列走列设置菜单；分页 `total` 带控件 / `pagerInfoText` 仅文案。行 hover、表头底色等
|
||||
全部来自 `context.tokens`（禁硬编码色，闸：`node client/tool/check_ds_code.mjs`）。
|
||||
其余原子（按钮/输入/徽章/chip/分段/KPI/菜单/toast/柱状图）见 `client/lib/widgets/ds/`，
|
||||
一对一镜像 `.superpowers/prototype/atoms.css`。旧 `DataTableCard`/`FilterableColumnHeader`
|
||||
体系已废弃（2026-07-03），勿在新屏使用。
|
||||
|
||||
## 移动端 / 响应式 UI 规范
|
||||
|
||||
@@ -408,11 +380,11 @@ DataTableCard(
|
||||
| **site** | `web/` Eleventy 营销宣传站（不含 Web 版 app） | `site-v*` | `CHANGELOG-site.md` | `deploy-site.yml` |
|
||||
| **server** | `backend/` Go 服务 + 共享基建(nginx/systemd) | `server-v*` | `CHANGELOG-server.md` | `deploy-server.yml` |
|
||||
|
||||
用 `/release <part> [version]` slash command：本地 build→test→更新 CHANGELOG→commit→tag→push；CI(Forgejo) 按 tag 前缀触发对应 workflow 自动编译/测试/发 Release/部署 EC2/Telegram 通知。**测试未过禁止发版**。
|
||||
用 `/release <part> [version]` slash command：本地 build→test→更新 CHANGELOG→commit→tag→push；CI(Forgejo) 按 tag 前缀触发对应 workflow 自动编译/测试/发 Release/部署 ali/Telegram 通知。**测试未过禁止发版**。
|
||||
|
||||
### 生产环境与运维
|
||||
|
||||
- 生产：EC2（`ec2-user@18.136.60.128`），jiu 为宿主 systemd 服务，MySQL 在容器 `jiu_mysql`（映射 127.0.0.1:3306）。配置 `/opt/jiu/config/production.env`（DATABASE_DSN）。
|
||||
- 生产：阿里云 ECS（`ssh ali`，北京；2026-07-02 从 EC2 割接）。入口 `https://jiu.51yanmei.com`（nginx 443 ssl+http2，certbot webroot 自动续期），反代 `127.0.0.1:8081` 的 systemd `jiu.service`；MySQL 在容器 `jiu_mysql`（127.0.0.1:3306）。配置 `/opt/jiu/config/production.env`（DATABASE_DSN、SERVER_PORT=8081、STORAGE_PUBLIC_URL）。每日 DB 备份 → 开发机 `~/jiu-db-backups`。
|
||||
- CI runner：mac runner=开发者本机（launchd + relay 绕 Shadowrocket，有看门狗自愈）、windows runner=另一台机（nssm 服务 `forgejo-runner`）、ubuntu=NAS docker。Forgejo 在 NAS（`git.51yanmei.com`）。
|
||||
- 一次性数据工具：`cmd/import-history`（旧系统进销存批量导入）、`cmd/fix-inventory-products`（修复历史库存 product_id 错指）。
|
||||
|
||||
@@ -425,7 +397,11 @@ DataTableCard(
|
||||
| Schema | backend/schema/schema.sql | 完整数据库建表 SQL |
|
||||
| S001 种子 | backend/seeds/S001.sql | 门店 S001 测试数据（含完整入库/出库/库存历史） |
|
||||
| S002 种子 | backend/seeds/S002.sql | 门店 S002 测试数据（基础数据相同，无库存/单据，模拟新门店） |
|
||||
| 用户手册 | docs/user-manual.md | 酒行员工操作手册（登录/入库/出库/库存/财务/设置） |
|
||||
| 文档索引 | docs/index.html | 全部文档单一入口 |
|
||||
| 用户手册 | docs/manual/user-manual.html | 酒行员工操作手册（HTML 主版本；官网帮助页源=web/content/docs.md） |
|
||||
| 开发手册 | docs/manual/dev-manual.html | 架构/后端/前端/数据库/API/运维/发版 全景 |
|
||||
| DB 列级文档 | docs/db-schema.html | 数据库 Schema 可视化 |
|
||||
| 用户手册(旧) | docs/user-manual.md | 已迁移至 HTML 版，停止更新 |
|
||||
| Android 签名 | docs/android-signing.md | 生成 keystore + 配置 Forgejo secrets，CI 给 APK 正式签名 |
|
||||
| iOS 分发 | docs/ios-signing.md | 证书/Profile/API Key + secrets，CI 构建并上传 TestFlight |
|
||||
| 部署（NAS/Gitea） | docs/deployment-nas-gitea.md | 自建 Forgejo + runner 部署说明 |
|
||||
|
||||
Reference in New Issue
Block a user