yunzerwebsiteallinone/.trae/documents/小程序端OA功能实现计划.md

小程序端 OA 功能实现计划

Context

Web 管理端（backend/）已具备完整的 OA 四大功能（通知公告、文档库、薪酬工资单、员工档案）， 但移动端（uniapp/）目前只有统一 webview 兜底，OA 子系统里除「日程提醒/记事本」外均无原生页面。 本次目标：参照 backend/ 对应功能，在小程序端提供 OA 四大功能的原生体验。

已确认的范围与约束

• 四大功能：通知公告（只读浏览）、文档库（浏览+下载+收藏）、薪酬工资单（仅本人）、员工档案（仅本人、只读）。
• 后端管理端 OA 接口均为 /backend/oa/* 且强制 user_type=backend，移动端令牌调不到 → 必须新增面向客户端的 /app/oa/* 只读接口。
• 写操作（发布公告、上传文档、编辑工资单、维护档案）继续留在 Web 端。
• 仅本人数据通过「登录账号 → 员工」映射解析（与 backend_auth.go 一致）。
• 微信小程序为主端，兼容 H5/APK；沿用既有 Sub*/工具页的卡片风格与 FaIcon 图标。

现状关键参考

用途	位置
移动端控制器鉴权/响应范式	app_reminder.go
移动端路由注册	app.go
公告控制器/模型	backend_oa_notice.go / oa_notice.go
文档控制器/服务/模型	backend_oa_document.go / oa_document.go / oa_document.go
薪酬控制器/模型	backend_oa_compensation.go / backend_oa_compensation.go
员工档案控制器/模型	backend_employee_file.go / backend_employee_file.go
账号→员工映射范式	backend_auth.go
前端请求封装	request.js
前端 API 封装范式	schedule.js
列表/详情页样式范式	schedule/index.vue
菜单跳转分发	nav.js
OA 概览页组件	SubHome.vue

一、后端：新增客户端 OA 只读接口

1. 新增 go/controllers/app_oa.go

AppOaController + 复用式辅助方法：

• oaClaims()：允许 backend/app/platform（与 AppReminderController.appClaims 同口径）。
• oaOk/oaErr()：统一 {code,msg,data} 响应。
• oaTenantUID(claims)：services.ResolveTenantUID(tid, claims.UserID)。
• oaMyEmployee(tid, userID) (*models.BackendEmployee, bool)：查 SystemTenantUser（uid+tid）取 account，再按 tid + account 查 BackendEmployee（对齐 backend_auth.go L266-289）。

2. 接口清单

方法	路由	说明	复用
GET	/app/oa/notice/list	仅 status=1、is_deleted=0、tid；is_top 优先 + publish_time 倒序；keyword/page/pageSize	models.OaNotice
GET	/app/oa/notice/:id	详情，read_count+1（沿用 Raw UPDATE 写法）	同上
GET	/app/oa/document/categories	scope=shared/personal/all 分类树	services.OaDocCategoryTree
GET	/app/oa/document/list	文档分页（scope/category_id/uncategorized/keyword/mine/star/doc_type）	services.OaDocList
GET	/app/oa/document/:id	文档详情（累加查看数）	services.OaDocView
GET	/app/oa/document/download/:id	记录下载数并返回下载地址	services.OaDocDownload
POST	/app/oa/document/:id/star	收藏/取消收藏	services.OaDocToggleStar
GET	/app/oa/compensation/payrolls	仅本人薪资单，employee_id = 我的员工ID + is_deleted=0；payroll_month 可选	payrollMap()（包级函数，可直接复用）
GET	/app/oa/compensation/payrolls/:id	明细 + 自定义增减项，二次校验 employee_id == 我的员工ID	models.BackendOaPayrollItem
GET	/app/oa/employee-file	仅本人档案 + 子记录（教育/工作/合同/证照）	(&BackendEmployeeFileController{}).efAssembleDTOList、efFileCompleteness、efOrgNameMap（均只依赖 models.Orm，零值控制器可安全调用）

3. 路由注册（go/routers/app/app.go）

追加 // OA 协同办公 段。注意 beego 按注册顺序匹配：字面量路由必须排在 :id 通配之前 （如 document/categories、document/list、document/download/:id 先于 document/:id）。

二、前端：API 封装与页面

1. 新增 uniapp/api/oa.js

依据 schedule.js 范式封装： fetchNotices/getNotice、fetchDocCategories/fetchDocs/getDoc/downloadDoc/toggleDocStar、 fetchPayrolls/getPayroll、getMyEmployeeFile，并导出展示用枚举标签 （公告类型/级别、文档类型、薪资单状态、在职状态、婚姻状况）。

2. 新增页面（统一沿用卡片 + FaIcon + page-common.scss）

页面	文件	内容
公告列表	pages/oa/notice/index.vue	搜索、置顶/重要标记、发布人+时间+阅读数，点击进详情
公告详情	pages/oa/notice/detail.vue	标题、类型/级别标签、发布信息、正文
文档库	pages/oa/document/index.vue	共享/私密空间切换、分类横向筛选、搜索、文档列表（类型图标+大小+分类）
文档详情	pages/oa/document/detail.vue	元信息、摘要、下载（uni.downloadFile+uni.openDocument，失败降级复制链接）、收藏切换
我的工资单	pages/oa/compensation/index.vue	月份筛选、实发金额高亮、发放状态，点击进明细
工资单明细	pages/oa/compensation/detail.vue	应发/扣款分项、社保公积金个税、自定义增减项、实发合计
我的档案	pages/oa/employeefile/index.vue	基本信息、在岗状态、完整度、教育/工作/合同经历列表（只读）

3. 注册路由（uniapp/pages.json）

pages 数组追加上述 7 个页面，navigationBarTitleText 分别为 「通知公告 / 公告详情 / 文档库 / 文档详情 / 我的工资单 / 工资单明细 / 我的档案」， 背景统一 #F8FAFC。

4. 菜单跳转映射（uniapp/utils/nav.js）

在 NATIVE_RULES 中补充 OA 原生路由（顺序放在既有规则之后，模式从具体到宽泛）：

• 通知公告：「通知公告|公告|notice」
• 文档库：「文档库|文档管理|文档图谱|document」
• 薪酬工资单：「薪酬|工资|薪资|compensation|payroll」
• 员工档案：「员工档案|人事档案|档案|employeefile|employeeFile」

5. OA 概览页新增「最新公告」卡片（SubHome.vue）

在「日程待办」区块后新增一个 v-if="sub.module === 'oa'" 的区块： 调用 /app/oa/notice/list（pageSize=3）展示标题 + 发布时间，「全部」跳转公告列表页。 仅对 OA 生效，不影响 crm/erp/cms/tools 概览。

三、验证

1. 后端编译：cd go && go build ./... 通过。
2. 前端编译：cd uniapp && npm run dev:mp-weixin，确认产物 dist/dev/mp-weixin 无报错。
3. 接口自测（若可连库）：以 app 令牌请求 /app/oa/notice/list、/app/oa/document/list?scope=shared、 /app/oa/compensation/payrolls、/app/oa/employee-file，确认鉴权、租户隔离与本人限制生效。
4. 端上验证：微信开发者工具打开 OA 子系统，从菜单进入四个功能页，检查列表/详情/下载/收藏与公告卡片。 （注：数据库当前连接超时，接口数据验证受限于环境，必要时由用户提供实际层级/菜单信息。）