# aPaaS + Bitable Configuration Files
This directory contains all configuration files and documentation needed to set up aPaaS native chart components with Bitable data connector.
## 📁 Files Overview
### Configuration Files
| File | Purpose | Use When |
|------|---------|----------|
| `apaas-data-request.json` | Complete data request configuration | Importing into aPaaS Data Request |
| `QUICK_START.md` | 15-minute setup guide | First-time setup |
| `INTEGRATION_GUIDE.md` | Detailed step-by-step instructions | Comprehensive implementation |
### Documentation
| File | Purpose | Audience |
|------|---------|----------|
| `../APAAS_CHART_CONFIG.md` | Complete reference guide | Developers & Power Users |
## 🚀 Getting Started
### Choose Your Path
**New to aPaaS?** → Start with `QUICK_START.md`
- Get running in 15 minutes
- Minimal configuration
- Basic dashboard setup
**Need Full Setup?** → Follow `INTEGRATION_GUIDE.md`
- Complete step-by-step guide
- All features included
- Production-ready
**Reference/Customization?** → Use `../APAAS_CHART_CONFIG.md`
- All chart types documented
- Advanced configurations
- Troubleshooting guide
## 📋 Project Information
### Your Configuration
```yaml
aPaaS:
app_id: Dffwb10dwaz6UZs6c4HlWyV3g7c
page_id: pgeEOroex4nCBQxc
Bitable:
app_token: C8kmbTsqoa6rBesTKRpl8nV8gHd
table_id: tblG4uuUvbwfvI9Z
Data Fields:
- Date
- Views
- Likes
- Comments
- Shares
- Followers
- Engagement_Rate
```
## 🔧 Using the Configuration Files
### 1. Import JSON Configuration
**Option A: Direct Import**
```bash
# Copy the JSON file
cat apaas-data-request.json
# Paste into aPaaS Data Request configuration panel
```
**Option B: Manual Configuration**
1. Open `apaas-data-request.json`
2. Copy sections as needed
3. Paste into aPaaS interface
### 2. Customize for Your Use Case
**Change Bitable Source**:
```json
{
"url": "https://open.feishu.cn/open-apis/bitable/v1/apps/YOUR_APP_TOKEN/tables/YOUR_TABLE_ID/records/search"
}
```
**Add/Remove Fields**:
```json
{
"field_names": [
"Date",
"Your_Field_1",
"Your_Field_2"
]
}
```
**Modify Filters**:
```json
{
"filter": {
"conditions": [
{
"field_name": "Status",
"operator": "is",
"value": ["Active"]
}
]
}
}
```
## 📊 Dashboard Components
The configuration supports these chart types:
### Metric Cards
- Total Views
- Total Likes
- Average Engagement Rate
- Total Followers
### Charts
- **Line Chart**: Dual-axis trend (Views + Engagement Rate)
- **Bar Chart**: Stacked engagement breakdown
- **Pie Chart**: Total engagement distribution
### Interactive Features
- Date range filtering
- Click events
- Real-time updates
- Responsive design
## 🔐 Authentication Setup
### Required Credentials
You need **one** of these:
**Option A: Tenant Access Token (Recommended)**
```json
{
"app_id": "cli_xxxxxxxxx",
"app_secret": "xxxxxxxxxxxxx"
}
```
**Option B: Personal Base Token**
```json
{
"personal_base_token": "pat_xxxxxxxxx"
}
```
### How to Get Credentials
1. **Tenant Access Token**:
- Visit: https://open.feishu.cn/app
- Create/select your app
- Copy App ID and App Secret
- Configure in `apaas-data-request.json`
2. **Personal Base Token**:
- Open your Bitable
- Settings → Advanced → API Access
- Generate Personal Base Token
- Use in Authorization header
## 📖 Documentation Structure
```
lark-dashboard-sdk/
├── APAAS_CHART_CONFIG.md # Complete reference guide
└── config/
├── README.md # This file
├── QUICK_START.md # 15-min setup guide
├── INTEGRATION_GUIDE.md # Detailed step-by-step
└── apaas-data-request.json # Data request config
```
## ✅ Setup Checklist
Use this checklist to track your progress:
### Prerequisites
- [ ] Feishu/Lark account access
- [ ] Bitable with TikTok data
- [ ] aPaaS app created
- [ ] App credentials obtained
### Configuration
- [ ] Data request created
- [ ] Authentication configured
- [ ] Connection tested successfully
- [ ] Field mapping verified
### Components
- [ ] Metric cards added (4)
- [ ] Line chart configured
- [ ] Bar chart configured
- [ ] Pie chart configured (optional)
### Interactions
- [ ] Date range filter added
- [ ] Filter connected to data
- [ ] Click events configured
- [ ] Tooltips enabled
### Testing
- [ ] Preview mode tested
- [ ] All components load data
- [ ] Filters work correctly
- [ ] No console errors
### Deployment
- [ ] Performance optimized
- [ ] Caching enabled
- [ ] Page published
- [ ] Users can access
## 🎯 Quick Reference
### Data Request Basics
**Fetch all data**:
```json
{
"method": "POST",
"url": "https://open.feishu.cn/open-apis/bitable/v1/apps/{app_token}/tables/{table_id}/records/search",
"body": {
"page_size": 500
}
}
```
**With filtering**:
```json
{
"body": {
"filter": {
"conjunction": "and",
"conditions": [
{
"field_name": "Date",
"operator": "isGreaterEqual",
"value": ["2023-11-01"]
}
]
}
}
}
```
**With sorting**:
```json
{
"body": {
"sort": [
{
"field_name": "Date",
"desc": false
}
]
}
}
```
### Data Binding Expressions
**Sum values**:
```javascript
{{getTikTokData.data.items.reduce((sum, i) => sum + i.fields.Views, 0)}}
```
**Average**:
```javascript
{{getTikTokData.data.items.reduce((sum, i) => sum + i.fields.Engagement_Rate, 0) / getTikTokData.data.items.length}}
```
**Map to array**:
```javascript
{{getTikTokData.data.items.map(i => i.fields.Views)}}
```
**Format date**:
```javascript
{{getTikTokData.data.items.map(i => new Date(i.fields.Date).toLocaleDateString())}}
```
## 🔍 Troubleshooting
### Common Issues
| Issue | Solution | Reference |
|-------|----------|-----------|
| 401 Unauthorized | Check App ID/Secret | INTEGRATION_GUIDE.md → Troubleshooting |
| No data in charts | Verify field names | APAAS_CHART_CONFIG.md → Troubleshooting |
| Filter not working | Check event binding | INTEGRATION_GUIDE.md → Phase 5 |
| Slow performance | Enable caching | APAAS_CHART_CONFIG.md → Best Practices |
### Debug Checklist
When something doesn't work:
1. ✅ Check browser console (F12) for errors
2. ✅ Test data request independently
3. ✅ Verify field names are exact (case-sensitive)
4. ✅ Confirm authentication is working
5. ✅ Check data binding expressions
6. ✅ Review INTEGRATION_GUIDE.md troubleshooting
## 📚 API Documentation
### Bitable API
**List Records**:
```
POST https://open.feishu.cn/open-apis/bitable/v1/apps/{app_token}/tables/{table_id}/records/search
```
**Authentication**:
```
GET https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal
```
### Official Docs
- [Bitable API Reference](https://open.feishu.cn/document/server-docs/docs/bitable-v1/app-table-record/list)
- [Authentication Guide](https://open.feishu.cn/document/server-docs/api-call-guide/calling-process/get-access-token)
- [aPaaS Platform Docs](https://apaas.feishu.cn/docs)
## 🛠️ Customization Examples
### Add New Metric Card
```javascript
{
"title": "Total Shares",
"value": "{{getTikTokData.data.items.reduce((sum, i) => sum + i.fields.Shares, 0)}}",
"format": "compact",
"icon": "🔄",
"color": "#8A5CD1"
}
```
### Add Custom Filter
```json
{
"name": "statusFilter",
"type": "dropdown",
"options": ["All", "Active", "Archived"],
"default": "All"
}
```
### Add Calculated Field
```json
{
"calculatedFields": [
{
"name": "engagement_per_view",
"expression": "{{(likes + comments + shares) / views * 100}}",
"type": "percentage"
}
]
}
```
## 🚢 Deployment Guide
### Pre-Deployment
1. Test in preview mode
2. Verify all data loads
3. Check mobile responsiveness
4. Test all interactions
### Performance Optimization
```json
{
"caching": {
"enabled": true,
"ttl": 300
},
"pagination": {
"enabled": true,
"pageSize": 100
}
}
```
### Go Live
1. Save all changes
2. Click "Publish"
3. Set permissions
4. Share with users
## 📞 Support & Resources
### Official Support
- Feishu Community: https://open.feishu.cn/community/
- Developer Portal: https://open.larksuite.com/
- API Explorer: https://open.feishu.cn/api-explorer/
### This Project
- Issues: Check INTEGRATION_GUIDE.md troubleshooting
- Questions: Review APAAS_CHART_CONFIG.md
- Examples: See apaas-data-request.json
## 📝 Version History
| Version | Date | Changes |
|---------|------|---------|
| 1.0 | 2025-12-09 | Initial release |
## 🤝 Contributing
Found an issue or have improvements? Update the documentation:
1. Edit the relevant .md file
2. Test your changes
3. Document the improvement
4. Share with team
## 📄 License
This configuration is part of the lark-dashboard-sdk project.
---
**Ready to get started?** → Open `QUICK_START.md`
**Need detailed setup?** → Follow `INTEGRATION_GUIDE.md`
**Looking for reference?** → Check `../APAAS_CHART_CONFIG.md`
