ops2/.workbuddy/memory/MEMORY.md

MEMORY.md - 长效记忆

最后更新: 2026-04-29

---

项目概览

项目名称: OPS 运营管理系统 技术栈: Vue 3 + Vite (前端 Web) / uni-app (移动端) / Go + Gin + GORM (后端)

ops2/
├── backend/my_work/          # Go 后端（端口由 config.yaml 决定，默认 8080）
├── frontend/
│   ├── ops_vue_js/           # Vue 3 Web 前端
│   └── ops2_uniapp/          # uni-app 移动端
└── DOC/

---

后端架构

启动流程 (main.go)

1. 检查 ./data/config.yaml，不存在则复制 ./defConfig/configTemp.yaml
2. configed 必须为 true 才能启动
3. 初始化顺序：ReturnInit → ApiUserInit → ApiFilesInit → ApiScheduleInit → ApiPurchaseInit → ApiWorkOrderInit → ApiWarehouseInit → BindsInit
4. 静态文件服务 ./dist，所有非 /api 请求转发给前端 HTML
5. 支持 TLS（证书路径在 config 中配置）
6. 版本信息通过 -ldflags -X 编译注入（GitVersion / GitCommit / BuildTime）

路由根 (api.go)

/api
├── /static      → ApiStatic
├── /users       → ApiUser
├── /files       → ApiFiles
├── /purchase    → ApiPurchase
├── /schedule    → ApiSchedule
├── /work_order  → ApiWorkOrder
├── /warehouse   → ApiWarehouse
└── /admin       → ApiSysAdmin

请求/响应格式

// 请求体
{ "userCookieValue": "xxx", "data": { ...业务参数 } }

// 响应体
{ "err_code": 0, "err_msg": "apiOK", "return": { ... } }

错误码从 ./defConfig/errorCodes.json 读取，常用：apiOK=0，userNoLogin=-44，permission_denied，parameErr，dbErr

认证机制

• 登录成功返回 Cookie 对象（存 TabUserCookie 表）
• 后续请求通过 JSON body 中 userCookieValue 传递
• Cookie 过期后端返回 err_code=-44，前端拦截器自动处理
• AuthenticationAuthority(ctx) → 分离 cookie 和 data，验证返回 (isAuth bool, user TabUser, data map)

---

用户认证模块 (apiUsers.go)

数据表

表	说明
TabUser	用户（Name 唯一索引）
TabUserGroups	用户组
TabUserGroupBinds	用户-组绑定
TabUserInfo	用户详情（头像/昵称/性别/生日/语言等）
TabUserCookie	登录 Cookie（ExpiresAt，Remember 字段）
TabUserLoginFailLog	登录失败日志（24小时内聚合，累计 Count）

初始化

• 自动创建 admins 组 + admin 用户（默认密码 adminpassword）
• 密码：加盐哈希，支持 text / md5 / md5salt（config 指定）

权限缓存（内存）

各模块维护各自的管理员 ID 列表：

变量	所属模块	刷新函数
sysAdmins []uint	apiUsers.go	updateSysAdminsCash()
scheduleAdmins []uint	apiSchedule.go	ScheduleUpdateAdminsCash()
purchaseAdmins []uint	apiPurchase.go	PurchaseUpdateAdminsCash()
workOrderAdmins []uint	apiWorkOrder.go	WorkOrderUpdateAdminsCash()
warehouseAdmins []uint	apiWarehouse.go	WarehouseUpdateAdminsCash()

修改用户组时自动刷新缓存（apiSysAdmin.go 的 add_group_member 和 remove_group_member）：

switch group.Name {
case "admins":         updateSysAdminsCash()
case "schedule_admin": ScheduleUpdateAdminsCash()
case "purchase_admin": PurchaseUpdateAdminsCash()
case "work_order_admin": WorkOrderUpdateAdminsCash()
case "warehouse_admin":  WarehouseUpdateAdminsCash()
}

API 路由 (/api/users/*)

路由	用途
POST /login	登录（返回 Cookie 对象，含 Remember）
POST /register	注册
POST /getinfo	获取当前用户信息（含 isSysAdmin 字段）
POST /changePassword	修改密码（oldpass/newpass）
POST /changeEmail	修改邮箱
POST /updateAvatar	更新头像（FormData）
POST /updateInfo	更新详情（firstName/username/birthdate/gender/region/language）
GET /getuserinfo/:id	获取指定用户信息

---

系统管理模块 (apiSysAdmin.go)

路由前缀: /api/admin/*，全部要求 SysAdminCheck

路由	用途
POST /sysadmins	获取系统管理员 ID 列表
POST /users	用户列表（分页+搜索，返回含头像路径）
POST /groups	用户组列表（含成员数 + 前5个成员ID）
POST /group_members	指定组的成员列表（分页）
POST /user_detail	用户详情（基本信息 + userinfo）
POST /reset_user_password	重置密码（同时注销该用户所有 cookie）
POST /add_group_member	添加用户到组（含缓存刷新）
POST /remove_group_member	从组移除用户（含缓存刷新）
POST /login_fail_logs	登录失败日志（分页+搜索 username/IP）

SysAdminCheck(userID) 直接查内存 sysAdmins 列表。

---

文件管理模块 (api_Files.go)

数据表 TabFileInfo

字段	说明
Sha256	唯一标识，去重键
Name	原始文件名
Path	存储路径
Mime	MIME 类型
Type	image/video/pdf 等
Const	引用计数

存储结构

data/
├── static/avatar/        # 用户头像（/api/static/avatar/:filename）
└── upload/
    ├── image/            # 以 SHA256 命名
    ├── video/
    ├── music/
    └── pdf/

API (/api/files/*)

路由	用途
POST /upload/image	上传图片（FormData + SHA256 去重）
GET /:mode/:hash	get=下载（带文件名），download=预览

---

日程模块 (apiSchedule.go)

数据表

• TabSchedule（软删除）：Title / StartDate / EndDate / BgColor(默认#3788d9) / Remark
• TabScheduleLog：操作日志

API (/api/schedule/*)

路由	用途
POST /getevents	按日期范围查询（start_date <= end AND end_date >= start）
POST /addevent	新增
POST /editevent	编辑
POST /deleevent	软删除

---

采购模块 (apiPurchase.go)

数据表

表	用途
TabPurchaseOrder	采购订单（软删除）
TabPurchaseCosts	费用明细（单价/运费，多币种）
TabPurchaseFileBind	图片关联
TabPurchaseCommit	状态变更记录
TabPurchaseLog	操作日志

状态流

pending → ordered → arrived → received
                    ↓
               lost / returned

货币：1-CNY / 2-MOP / 3-HKD / 4-USD

API (/api/purchase/*)

路由	用途
POST /getorder	订单详情（含费用/图片/状态记录/关联工单）
POST /getorders	列表（搜索/分页/状态筛选）
POST /addorder	新增
POST /updateorder	编辑（费用/图片重建）
POST /deleteorder	删除
POST /updatestatus	更新状态（可附评论/图片）
POST /delete_commit	删除状态记录
POST /getordercount	各状态数量统计
POST /search_work_orders	搜索工单（用于关联）

---

工单模块 (apiWorkOrder.go)

数据表

表	用途
TabWorkOrder	工单（软删除）
TabWorkOrderFileBind	工单图片关联
TabWorkOrderCommit	进度记录
TabWorkOrderCommitFileBind	进度关联图片
TabWorkOrderPurchaseOrderBind	工单-采购订单关联（含 CommitID）
TabWorkOrderLog	操作日志

状态流

pending → checked → parts_ordered → repaired → returned
                          ↓
                    unrepairable

特殊逻辑

• 状态变为 returned 时，自动移除物品的容器绑定（ContainerID = nil）
• 工单 ↔ 物品：TabWarehouseItemWorkOrderBind
• 工单 ↔ 采购：TabWorkOrderPurchaseOrderBind

API (/api/work_order/*)

路由	用途
POST /add	新增（可关联物品）
POST /update	编辑
POST /list	列表
POST /get	详情（含图片/进度/关联物品/采购）
POST /commit	提交进度（更新状态，可关联采购）
POST /delete	删除
POST /delete_commit	删除进度
POST /count	各状态统计
POST /search_purchase_orders	搜索采购订单（用于关联）

---

仓库模块 (apiWarehouse.go)

数据表

表	用途
TabWarehouseContainer	容器（树形，最多5层，ParentID=nil为顶级）
TabWarehouseItem	物品（ContainerID=nil表示未入库）
TabWarehouseItemCommit	物品移动记录
TabWarehouseLog	操作日志

跨模块绑定表 (binds.go)

表	用途
TabWarehouseItemWorkOrderBind	物品-工单
TabWarehouseItemFileBind	物品-图片
TabWarehouseContainerFileBind	容器-图片
TabPurchaseFileBind	采购-图片
TabWorkOrderFileBind	工单-图片
TabWorkOrderCommitFileBind	工单进度-图片
TabWorkOrderPurchaseOrderBind	工单-采购

---

Web 前端架构 (frontend/ops_vue_js/)

技术栈: Vue 3 + Vite 7 + Pinia + Vue Router (hash 模式) + Vue I18n + Tailwind CSS v4 + Tabler Icons

目录结构

src/
├── api/
│   ├── index.js        # Axios 实例，基础 URL /api，请求拦截注入 cookie，响应拦截处理 -44
│   ├── auth.js         # 认证 + sysadmin 管理 API
│   ├── purchase.js     # 采购 API
│   ├── warehouse.js    # 仓库 API
│   ├── work_order.js   # 工单 API
│   ├── schedule.js     # 日程 API
│   └── users.js        # 其他用户信息 API（按需加载头像/用户名）
├── components/
│   ├── AppHeader.vue          # 导航栏（含系统管理入口，权限判断 isSysAdmin）
│   ├── AppFooter.vue
│   ├── AppToast.vue
│   ├── ConfirmDialog.vue
│   ├── PurchaseOrderForm.vue
│   ├── SettingNav.vue
│   ├── tagadder.vue
│   ├── useDropzone.vue        # 文件拖拽上传
│   ├── imageCropper.vue       # 图片裁剪
│   ├── datePicker.vue
│   ├── dateTimePicker.vue
│   └── datatimePickerForFullCalendar.vue
├── composables/
├── i18n/
│   ├── en.json                # 英文翻译
│   └── zh-CN.json             # 中文翻译
├── layouts/
│   ├── DefaultLayout.vue      # 需要登录的页面布局
│   └── AuthLayout.vue         # 认证页面全屏布局
├── router/index.js
├── stores/
│   ├── user.js        # 当前用户（isLoggedIn / isSysAdmin / cookie / avatarUrl）
│   ├── users.js       # 其他用户信息缓存（按需拉取，防重复请求）
│   └── toast.js       # 全局 Toast
└── views/
    ├── HomeView.vue
    ├── ScheduleView.vue       # FullCalendar
    ├── SysAdminView.vue       # 系统管理（仅 sysAdmin 可访问，meta.requireSysAdmin）
    ├── AdminView.vue
    ├── purchase/              # PurchaseList / addorder / ShowOrder / editorder
    ├── work_order/            # WorkOrderList / AddEditWorkOrder / ShowWorkOrder
    ├── warehouse/             # WarehouseOverview / ContainerList / ContainerDetail / ItemList / ItemDetail / AddItem / ItemEdit
    └── settings/              # AccountView / ContactView / SecurityView

路由说明

• 公开页：/ /login /register /forgot_password /schedule /404
• /sysadmin 需要 meta.requireSysAdmin，不满足跳回首页
• 未登录跳转 /login?redirect=原路径

状态管理 (stores/user.js)

• Cookie 持久化：Remember=true 存 localStorage，否则只存 sessionStorage
• isSysAdmin 由 /users/getinfo 返回的 isSysAdmin 字段驱动
• fetchUserInfo() 在 login() 后自动调用

i18n 翻译节点

week / errorpage / appname / tagadder / dropzone / cropper / purchase / work_order / warehouse / purchase_addorder / schedule / home / message / settings / button / footer / cost_type / order_status / sysadmin

构建配置

• 输出目录: ../../backend/my_work/dist（后端直接 serve）
• 开发代理: /api → http://127.0.0.1:8080
• 路径别名: @ → ./src

---

移动端 (frontend/ops2_uniapp/)

技术栈: uni-app + Vue 3 + Pinia

当前完成度: ~40%

页面	完成度
login	85%（表单/验证/请求/Toast）
settings	90%（API 地址配置/连接测试）
index/order/message	5%（占位）
user	20%（登录入口）

待完成:

• 完善 api/index.js（Cookie 认证，参照 Web 前端）
• 实现各功能页面（仓库/工单/采购等）

---

开发注意事项

1. 后端 JSON 字段命名: 结构体字段为 PascalCase（如 UserID / AvatarPath），前端需对应
2. 头像: usersStore.getAvatarUrlFromUserID(id) 返回 /api/static/avatar/{path} 或默认 /ava.svg
3. i18n 修改: 同时修改 en.json 和 zh-CN.json 两个文件
4. 同源部署: 后端 serve ./dist 静态资源，前端 build 直接输出到后端目录
5. API 封装: api/index.js 统一返回 { errCode, data, raw }

---

更新记录

• 2026-04-24: 首次梳理
• 2026-04-28: 修复 SysAdminView 中 <img .../> 误删 bug；添加 message.sysadmin 英文翻译
• 2026-04-29: 全面重新分析代码，更新并精简记忆文档