# shiguang-miniprogram

**Repository Path**: yasinh/shiguang-miniprogram

## Basic Information

- **Project Name**: shiguang-miniprogram
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-08
- **Last Updated**: 2026-09-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 拾光 · 微信小程序

面向小学教师的学生成长记录工具。语音是主入口，低频录入收进「＋」，多位老师的具体事实共同形成学生档案。

当前工程承接已确认的极简手绘设计，采用原生 JavaScript / WXML / WXSS，无运行时 npm 依赖。

## 打开工程

1. 用微信开发者工具导入当前目录（不是 `miniprogram/` 子目录）。
2. 已配置用户确认的正式小程序 AppID：`wx044e977f146a9930`，源码目录 `miniprogram/`。
3. 点击「编译」。小程序无需 npm 构建；真实联调默认连接 https://momoget.com 后端，设计演示使用独立 Mock 空间。
4. 编译模式选择「设计系统」，可查看统一颜色、文字层级、图标和真实组件。

`project.private.config.json` 是开发者工具生成的个人设置，不入版本管理。当前本机基础库为 3.17.2。正式发布前须核验当前 AppID 的发布权限，并配置可达的 HTTPS 服务、合法域名和隐私声明。

## 目录

- `miniprogram/`：原生小程序。
- `miniprogram/styles/tokens.wxss`：从设计源文件生成的语义变量。
- `miniprogram/components/`：图标、记录卡片、面板、班级/日期选择器。
- `miniprogram/services/`：业务规则、本地存储、原生录音适配。
- `design/tokens.json`：设计变量唯一来源。
- `design/design-system.md`：设计语言与组件规范。
- `design/references/`：选定稿与最新界面截图。
- `design/prototype/`：本次迁移前的浏览器原型核心源码快照，仅用于设计对照。
- `docs/`：架构、能力边界和验收结果。
- `tests/`：规则与原生页面控制器测试。

## 当前可体验

- 首页按屏幕空间适配完整卡片、放不下的叠放，班级切换。
- 建班、导入名单、文字记录、成绩 CSV 选择/粘贴。
- 录入时独立选择目标班级；日期默认今天，原生日期选择器按需修改。
- 语音结束即生成处理卡；原音上传后由后台完成转写与整理，无法确定学生时保留待确认卡；私人/班级可见、学生校准与纠正。
- 学生档案、日期范围、依据事实整理沟通稿/学期总结、编辑、复制正文、出处追溯和旧稿失效。
- 真实后端教师会话与邀请接受；设计演示仍显式标记 Mock。
- 微信录音 API 已接线。真机录音仍需麦克风授权和实测，开发工具模拟器的能力依版本而异。

真实后端位于相邻的 `polly-pronounce-pro` 项目，共用 Better Auth、班级和学生名单。文字整理、回顾与报告直连 DeepSeek 官方 API，语音转写独立使用百炼；均由服务端调用，小程序不持有模型密钥。回顾先展示原始记录，再补后台摘要；语音待确认、原音重试和人工纠正保留来源。提醒保存已接入，微信订阅推送尚未接入。真实微信手机号登录仍须配置对应 AppID 凭据与平台权限，本地联调会话不能替代真机认证。

## 验证

```sh
npm run design:build
npm run check
npm run check:native
npm test
```

无需先执行 `npm install`。WXML/WXSS 原生编译及验收状态见 `docs/verification.md`。

## 后端技术方案

后端已经实现并完成本机真实接口评测；当前变更和剩余验收范围见 [DeepSeek 切换与修复复测](docs/backend/deepseek-fixes-2026-09-10.md)。架构背景见 [Polly 与拾光共用后端：简化方案 v2](docs/backend/shared-backend-v2.md)，复用 Polly 的 Next.js / Drizzle / PostgreSQL，共享教师身份、班级和名单。[旧版独立后端方案](docs/backend/technical-design.md)、[接口索引](docs/backend/api-index.md)与[OpenAPI契约](docs/backend/openapi.yaml)保留为历史参考，需按 v2 修订后再用于联调。

语音交互、状态机、Mock边界与后端接口预留见 [语音记录协议 v3](docs/backend/voice-records-v3.md)，其「无记录草稿、说完即成卡」规则覆盖旧方案中的手动语音归档流程。


## 新版原型对齐（2026-09-09）

首页保留手绘Logo、学生插画、语音主入口；全部/班级只是查看范围，不切换角色。右下进入统一回顾，支持时间轴、线索搜索、原始记录、多对象纠错与撤销、事项语音续记、摘录分享和自用提醒。新语音默认仅自己可见。

微信开发者工具打开项目后，可进入 `pages/design-system/index`，点击“打开新版原型演示”体验完整流程。演示数据独立保存；“退出演示，回到原有记录”恢复原数据。新页面为 `pages/journal/index`，沿用共享组件与原生导航、录音和picker。

此原型演示模式中的 AI 整理、分享和提醒均为 Mock，不发送消息或推送；与真实后端空间隔离。接口、修订、来源与权限约束见 [journal-v5.md](docs/backend/journal-v5.md)。远端接入替换 `services/api.js` 的transport；录音上传需使用assets适配，不直接传本地路径。

## 游客浏览与登录（2026-09-09）

首次打开直接进入首页，未登录可浏览学生、回顾等页面；没有内容时展示空状态，不展示上一账号记录。游客可先录音；结束后保留原音，再由“登录并继续”进入欢迎与登录合并页。登录成功自动生成处理卡；取消登录可返回、播放原音或下次继续，不强制先建班。

设计演示提供明确标注的 Mock 登录。本机真实联调使用独立开发会话；原生手机号按钮及服务端登录路径已接线，真实微信认证仍待平台凭据和真机验收，见 [登录协议](docs/backend/account-login-v1.md)。首次空数据库不注入示例学生；已有本机记录保留。新版原型演示空间中的记录也需先通过 Mock 登录后查看。

### 服务端连接

开发工具、体验版和正式版默认连接 `https://momoget.com`，服务配置位于 `miniprogram/services/config.js`。微信后台的 request 与 uploadFile 合法域名需包含此域名；原音下载域名以服务端返回的地址为准。